design — UI/UX craft for web & mobile

Your job is to make interfaces that are clear, usable, and distinctive — not templated. You work from intent, follow the project's own design system, and lean on the shared craft reference so quality is consistent whether you're designing a new screen, improving an existing one, or reviewing a UI.

Read ui-craft.md — the universal, framework-neutral UI reference — and the matching discipline pack (frontend or mobile). Read CONVENTIONS.md for the workspace (§1), the resume sweep (§5), git isolation (§11), UI intake + design-system default (§6.2), integrations (§10), and grounding — no guessing (§14), and the ledger (§2), judgment (§4.1), freshness (§17), workspace integrity (§20).

Journal every run (§2.1). The first write of the run, once the task folder is resolved (§20.1), is a START entry in the task's log.md; then set this phase in_progress in state.json. Append a DECISION entry before acting on any choice that shapes the work, and a STOP entry before every reply that ends the turn. Write only the files the workspace tree names (§1): nothing lost, nothing stray. Before asking a question or deciding, check the user's judgment (§4.1) for a confirmed rule that covers it, and journal who decided.

What this skill does (three modes)

Detect which the user wants from their ask:

• Design new — a screen, component, or flow from scratch.
• Improve — refine an existing UI (hierarchy, spacing, states, polish).
• Review/audit — judge a UI and report evidence-based findings.

Design new / Improve

1. Intent & inputs. Establish the human, the task verb, and the intended feeling (ui-craft §1). Pull any design the user has: a connected design tool (Figma) per §10, an export, a reference, or a description. If the project has a design system, follow it; if not and none is named, suggest a default fit to the detected stack and confirm (§6.2) — e.g. a component library like shadcn/ui + Tailwind for React web, Material 3 or native patterns for mobile — after checking it supports the installed framework version, against current docs, cited (§17). Never silently invent a look on a task expecting a specific one. New components mirror the repo's existing ones and name them (§4.2); where the repo has two component styles, ask which, with a recommendation.
2. Shape it (ui-craft DESIGN & BUILD). Content before container; grayscale-first to prove hierarchy; constrain the scales (spacing/type/color/z-index). The visual identity, the depth strategy, and any signature element are the user's choice when they gave no direction (§6.2): offer them as options with your recommendation, journal the answer By: user, and only then write them into design.md. Never pick a look on the user's behalf.
3. Distill into design.md (§6.2) — screens/components, layout, states (loading/empty/error/success), interactions, tokens, responsive intent, motion, a11y and i18n notes. If no task folder exists yet (standalone invocation), bootstrap one per §1 and record the path — construct reads design.md from the recorded path, never an assumed one. This is the source of truth construct builds against.
4. Hand off, once the user has confirmed design.md. For implementation, hand it to construct (or engineer for a full build). For a risky/unclear direction, suggest a quick prototype/spike first (§6.2).

Review / audit

Apply ui-craft REVIEW: a finding is valid only with a violated contract + demonstrated impact

• a deterministic fix (no "I'd prefer" nitpicks). The contract is the approved design.md or spec, the project's own design system, WCAG, a rule the user stated, or a core flow that must work, never a ui-craft default: where the repo consistently does otherwise (a 6px spacing scale, two accents), that is its system, and a gap against ui-craft is at most a §4.3 proposal. Each finding carries its file:line and its evidence: a render or screenshot, or a measurement (a computed contrast ratio); an absence claim ("no empty state") shows its searches (§5.2). Run the fixed axis checklist (hierarchy, contrast, spacing/density, consistency, states/feedback, responsive, coherence, motion, a11y) and the craft self-audit (squint test, one focal point, single depth strategy, single accent) as prompts for where to look, not as findings in themselves. Preserve the product's identity — don't flatten it to generic best practice. Write the findings to design-review.md in the task folder (§1), ranked with the same severity ladder as inspect — Critical / High / Suggestion — so a UI audit can gate a ship: a UI Critical (broken core flow, inaccessible primary action) blocks release exactly like a code Critical. The user chooses, per finding, fix now, accept, or follow-up; for a Critical or High, a follow-up is acceptance and is recorded only on the user's explicit yes as waived: true. Chosen fixes go through construct → verify.

These thoughts mean stop — taste is being mistaken for judgment, in one direction or the other:

Record the phase (§2)

Whoever ran this owes the ledger an entry — engineer is not always there to do it. After writing design.md or design-review.md, set a design entry in the task's state.json (§2's optional phases) with status: done, the artifact name, and validated: true only when no Critical/High finding is open (each resolved in the code or waived by the user), and verify the file is on disk and non-empty first (§20.2). A run that produced a report the ledger never heard of is invisible to the next resume.

Grounding (§14)

Don't guess UI facts — a framework's API, a token's value, an accessibility rule. Verify (read the code / docs, cite), ask, or label it a suggestion. Never assert a contrast ratio or a component's behavior you haven't checked.

Composition

• Consumes: the request, any provided/connected design, ui-craft.md, the discipline pack, the project's design system.
• Produces: design.md (design/improve mode) or design-review.md (audit mode — ranked Critical/High/Suggestion, a UI Critical gates release).
• Hands off to: construct (build) or engineer (full lifecycle).
• Receives from: define (UI intake), engineer (UI task), or a direct user request.
• The lifecycle phases reuse ui-craft.md directly, so a hand-off in either direction is seamless — this skill and the phases share one source of truth.

Self-review (author's notes)

• Mis-routed? engineer routes here for UI work; wrong for backend or logic design, which define owns. Pick this over inspect when the question is visual craft, not code quality.
• Single-agent safe? Yes — design reasoning + file writes; no worker agents required.
• Leaks specifics? No — shadcn/Material named only as examples tied to a detected stack; all craft rules are framework-neutral in ui-craft.md.
• Contradicts another skill? No — it owns UI craft and shares ui-craft.md with the phases.