UI Build

Precondition. Tool of dept-frontend. If that department skill is not loaded in this conversation, load it first and use its brief (what, why, where, how) as the input of this skill. Skip only for L0 edits.

Approach

New interface is a design decision before it is code. Decide on purpose and character first, then write code that carries that decision into every detail.

• The existing system wins. In a project with tokens, a component library or established screens, the "direction" is already chosen: match it so precisely that the new view looks like it was always there. Invention is reserved for greenfield work.
• Intent over intensity. A quiet, dense admin view and an expressive landing can both be excellent; what fails is a view with no point of view, assembled from defaults.
• Generic is a defect. Interchangeable layouts, a single flat type size, evenly spread color, cards wrapped around everything and decorative effects with no reason all read as "template". Each choice should be explainable by the product, the user or the content.
• Complete beats pretty. A view is not built until loading, empty, error, success, disabled and interaction states exist, it reflows on the narrowest screen and it works by keyboard.
• Questions before acting: who uses this and in what situation? What is the one primary action? What already exists that I can reuse? What would make this view clearly belong to this product?

Design system decision (mini-brief)

Write it before the first file, 4–6 lines, in the brief's language. It adapts to the project's situation.

Brownfield rule: if a field would require a new token, font or component variant, list it as a proposal for dept-ux-ui instead of silently adding it.

Avoid

• Inventing fonts, colors or radii in a project that already has a system.
• Shipping only the happy path; a spinner as the only non-success state.
• A modal where inline or progressive disclosure would serve the task.
• Several competing primary actions on one view.
• New breakpoints to patch a layout that fluid sizing would fix.
• Copying a generic template layout without adapting hierarchy to the content.

Inputs

Output contract

Always return to the department:

1. Design decision (mini-brief) and mode used.
2. Files created or changed, with placement rationale.
3. Reuse map: components and tokens reused; anything new and why.
4. States covered (checklist) and the responsive and theme checks done.
5. A11y basics verified (keyboard path, focus, labels, contrast).
6. Open risks / proposals for dept-ux-ui (new tokens, variants) or dept-backend (missing error shapes).

Pattern library (grows with use)

• Before building, list patterns/ and read the matching file, if any.
• After building something reusable that has no pattern yet (a modal, a data table, a stepper…), write patterns/<pattern>.md from ../waymark/templates/pattern.template.md: stack-agnostic intent, anatomy, states, a11y, pitfalls, and one short adapter per stack it was built in. Project-specific details go to project memory, not here.
• Update an existing pattern only with new, verified information (novelty check, waymark references/learning.md).

Modes

Read only the mode the task needs (one file); never load all modes.

• build — a new component, dialog, form, screen or dashboard is needed and no equivalent exists. → modes/build.md
• compose — the screen can be assembled mostly from existing components (library or shared layer) with little or no new styling. → modes/compose.md
• greenfield-direction — no tokens, theme or component library exist yet, or the user explicitly asks for a new visual identity. → modes/greenfield-direction.md

Stack adapters

Stack-specific notes → references/stack-adapters.md (read only the project's stack row).

Learned notes

Grows with use (waymark references/learning.md). Dated, non-obvious notes about using this tool. When there are more than ~10, fold them into the body above and clear this list.