ui-design

name

ui-design

description

Designs the screens — the presentation half of each feature's low-level design, sibling to detailed-design. Runs in three modes: anchor (right after ux-foundations, designing 2-3 key screens to validate the design system before features build on it), per-feature (the construction loop — after detailed-design, designing that feature's SCR screens against its contracts), and re-verification (after a design.md amendment). Resolves strategy per screen: picks up screens that already exist in a connected design tool (Figma, Claude Design, Figma Make, Open Design, or any design tool), otherwise falls back per project policy to code-native specs or generation. Emits one uniform contract — docs/design-manifest.json keyed on SCR IDs — that downstream implementation reads regardless of which tool or strategy produced each screen. Trigger on "design the screens", "design anchor screens", "design this feature's UI", "ui design for", or "register the Figma designs". Screens conform to design.md or escalate — never fork it.

UI Design

The presentation half of the feature's low-level design — detailed-design's conceptual sibling, but sequential in the loop: in per-feature mode this skill consumes the feature's technical-design.md (screens bind to its contracts — a screen displays what an endpoint returns), which is why detailed-design runs first. Only anchor mode, which precedes any feature, has no such dependency. It answers, per screen: what does it look like, what does it compose from, what states does it cover, where does its design authority live. Its defining characteristic is that it's an adapter: how screens get designed varies by project (an existing design file, a generation tool, straight to code), so this skill routes across strategies while emitting one uniform output contract — the design manifest — that everything downstream reads, whatever produced each screen. All design-tool variance is absorbed here; no downstream skill ever learns what a Figma node is.

Three principles govern it:

1. Strategy is resolved per screen, not per project. A project with a partial design file is "register" for the screens that exist and the project's fallback policy for the rest. The manifest lookup by SCR ID is always the first move.
2. Screens conform to the design system or escalate — never fork it. docs/design.md + tokens.json are the authority. A fetched or generated screen introducing an off-system color, component, or pattern is either corrected to the system, or the system is amended through ux-foundations' amendment path (the presentation analog of detailed-design's schema escalation). Local work never silently mutates upstream authority.
3. The manifest is the only registry. With per-screen routing, no design tool ever holds the complete picture — only docs/design-manifest.json does. This skill is its single writer.

Inputs

Defaults below; user paths win; source-gated citation throughout (SCR/FEAT/ FR/UC/NFR IDs only from documents that exist; never fabricate).

• Design system — docs/design.md + docs/tokens.json (from ux-foundations). The authority every screen conforms to. Also read design.md's structured design_provenance block (mode and fidelity drive the anchor recommendation) and ux-foundations.md's screen inventory (SCR IDs, purposes, states) and per-surface profiles.
• Feature context (per-feature mode) — the feature's technical-design.md (contracts the screens bind to: a screen displays what an endpoint returns) and its plan entry (SCR IDs, FR/UC trace).
• The manifest — docs/design-manifest.json, if it exists: what's already designed, by which strategy, and the project's routing policy.
• Connected design tools — whatever design-tool MCPs are connected. Treated capability-first (see references/design-tool-integrations.md): tools are interchangeable engines behind two capabilities — enumerate/export existing designs and generate from a system spec.

Outputs

1. docs/design-manifest.json — the global, SCR-keyed screen registry: one entry per screen with strategy, source locator, states coverage, contract bindings, conformance result, status. Single-writer; entries appended/updated by this skill only. Schema: references/manifest-guide.md.
2. docs/features/FEAT-NNN-<slug>/ui-design.md (per-feature mode) — the human-readable screen specs and decisions, beside technical-design.md. Anchor mode writes docs/anchor-screens.md instead (no feature folder exists yet).
3. RTM append (docs/rtm.md, if present; silent skip otherwise): the feature's ui-design ref appended into Design ref for the FRs whose screens it designs — append-only, that column only.
4. Escalations (when the authority rule trips): a proposed design-system amendment filed toward ux-foundations, recorded in the manifest entry — never a silent local fork.

Workflow

Phase 0 — Mode detection

Determine the mode from context and intent; confirm when ambiguous:

• Anchor — ux-foundations just completed, no features designed, or the user asks for anchor/key screens. Purpose: validate that the design system composes before features build on it.
• Per-feature — a feature's technical-design.md exists (or the user names a FEAT); the loop mode.
• Re-verification — design.md was amended; re-check the manifest entries whose screens the amendment affects (changed tokens/components), update conformance results, flag screens needing rework.

Anchor recommendation gradient (state it, let the user decide — anchors are recommended, never mandatory): strongly suggested when design.md's provenance is research mode or non-technical stakeholders must sign off; suggested for image-extraction or ingestion provenance (the translation was never visually validated); skip for tool-sourced systems (mode 4 — the key screens already exist) and framework-constrained projects. Cost framing: an anchor pass is hours; a system amendment discovered at feature 5 is not.

First-feature-as-implicit-anchor: in per-feature mode, if no anchor ever ran and the manifest is empty, treat this feature's screens with anchor-level scrutiny — the system's first compositional test is happening now; watch for system amendments, not just screen correctness.

Phase 1 — Gather the screen set

Anchor mode: pick 2–3 screens with the user — the most compositionally demanding and stakeholder-visible from the inventory (a dense data screen, a key flow screen), not the easiest.

Per-feature mode — first resolve which feature, deterministically: if the user named one (by FEAT ID or name), use it — explicit naming is the only legitimate off-sequence path. Otherwise compute the default: walk the plan's build sequence in order; the first feature whose folder has technical-design.md but no ui-design.md is next. Multiple eligible folders is not ambiguity — the sequence resolves it (earliest in build order wins); never present a menu, which invites accidental violation of the plan's dependency-and-risk ordering. Announce the resolution ("FEAT-004 is next per the plan's build sequence; designing its screens") so the user can redirect before work starts. Then gather: the feature's SCR IDs from its plan entry/technical-design.md; pull each screen's inventory entry (purpose, states) and the contracts it binds to. Re-verification: the affected entries computed from the amendment's changed tokens/components.

Phase 2 — Resolve strategy per screen

Read references/strategy-guide.md. For each SCR ID:

1. Manifest lookup — already designed (by an anchor or an earlier feature)? Reuse; verify its contract bindings still hold for this feature.
2. Source lookup — does the screen exist in a connected design tool (matched by SCR-ID naming or prior registration)? → Strategy A: register (fetch, verify conformance, fill missing states, register).
3. Not found → the project's routing policy: Strategy C: code-native spec (default) or Strategy B: generate via a connected design tool. The policy is asked once on first run, recorded in the manifest header, applied thereafter, overridable per screen.

When no design tool is connected but one is wanted (the user asked to register or generate, or the policy is "generate"): never silently downgrade to code-native — say so plainly, name what's needed (a design-tool MCP — e.g., Figma's official server), and point at the runtime's own connection mechanism, verifying the current steps against live docs rather than reciting remembered commands (connection mechanics are runtime-specific and drift — the same live-reality rule as scaffolding's generators). Then offer both paths: connect now and proceed tool-backed, or proceed code-native and register tool designs later (re-verification mode exists precisely for after-the-fact registration). A deferred integration beats a blocked pipeline; a silent downgrade beats neither.

Phase 3 — Execute strategies

Per strategy protocols in references/strategy-guide.md (tool specifics in references/design-tool-integrations.md). Every path ends the same way: the screen verified against design.md/tokens.json (conform-or-escalate), all key states covered (empty/loading/error — fill or record as gaps), contract bindings checked (per-feature mode: the screen shows what the endpoints return; UC alternate/exception flows have UI states), and the manifest entry written.

Phase 4 — Write the feature document

Read references/document-templates.md and follow its structures — the heading formats are load-bearing (manifest locators anchor on them). Per-feature mode: ui-design.md in the feature folder — per screen: the spec or source reference, composition (which design.md components), states, contract bindings, decisions, escalations. Anchor mode: anchor-screens.md opening with the verdict that is anchor mode's whole point — does the system compose? — with any system amendments proposed. Keep prose here; the manifest stays the machine index.

Phase 5 — Verify

Read references/verification.md: every screen in the set has a manifest entry; every entry's source resolves; conformance run per screen with escalations filed not forked; states coverage recorded honestly; contract bindings cited from technical-design.md; RTM appended; IDs source-gated. Fix failures; flag the unfixable.

Phase 6 — Deliver

Summarize per screen: strategy, source, states, escalations. Anchor mode additionally states plainly: "anchor designs are registered in design-manifest.json; the design system itself is unchanged" — or, when escalations were filed, "amendments proposed toward ux-foundations: " — so it's explicit that no ux-foundations document was written by this skill. Live-computed progress ("FEAT-004 screens designed — manifest now covers 9 of 27 inventory screens"; computed, never stored). Handoff: implementation consumes tasks.md + the manifest (+ ui-design.md for the specs); code-native screens are realized during feature implementation, optionally with a screenshot loop against the spec.

Scope boundaries

Does not: implement screens (implementation's job — including realizing code-native specs); design contracts/schema (detailed-design); amend the design system itself (files escalations to ux-foundations); write any RTM column but Design ref (append-only); let any downstream artifact depend on a tool's API — downstream reads the manifest only.

What good looks like

• Every screen in scope has exactly one manifest entry; SCR ID is a unique key; the manifest — not any tool — is the complete registry.
• Strategy was resolved per screen; existing designs were picked up, not regenerated; fallbacks followed the recorded policy.
• Zero silent forks: every off-system element was corrected or escalated.
• States coverage is honest — gaps recorded, not glossed.
• A fresh implementation session can build any screen from the manifest + specs without knowing which tool (if any) was involved.