Skip to main content

design-an-interface

When a feature needs UI but there's no Figma frame (greenfield / fast exploration β€” "Path B" of the Product↔R&D handoff), turn the requirement into a concrete composition built from the design system β€” so the result is the same kind of machine-consumable design reference Figma+Code-Connect would give, with zero invented components and zero raw hex.

The output is a spec a downstream agent can build from, not a picture. It feeds /plan-feature and PRD Β§7.2.

Inputs​

  • The requirement: the screen/flow and what the user must accomplish (from a PRD Β§1–7, a ClickUp task, or a described need).
  • The catalog: COMPONENTS.md + tokens (palette.ts) from @bewith-dev/design-system (ships with design-system PR #326; until then Storybook + src/components). These are the only building blocks.

Steps​

  1. Decompose the screen into regions (header, list, form, actions, empty/error surfaces).
  2. Map each region to catalog components by name β€” e.g. "summary row uses SummaryCard + Chip; primary action is Button variant=primary; list is DataTable". Never name a component that isn't in COMPONENTS.md.
  3. Reference tokens for color/spacing intent (semantic.success, the spacing scale) β€” never raw hex or px literals.
  4. Specify every state for each interactive element: default / loading / empty / error / success / disabled. RTL + mobile/desktop where in scope.
  5. Flag gaps explicitly. If the design needs something not in the catalog, that's a request to extend the design system β€” file an /add-component task; do not hand-roll it in the app.
  6. Emit the composition as a structured section (region β†’ components β†’ props/tokens β†’ states) ready to paste into the PRD Β§7.2 / Design Doc. A Mermaid layout sketch (mermaid-diagrams) is optional and supplementary β€” the component map is the contract.

Boundaries​

  • Catalog-only. Components from COMPONENTS.md, color/spacing from tokens. A needed-but-missing piece is an /add-component request, never a one-off.
  • Spec, not pixels. Produces a buildable composition; once a pattern stabilizes, promote shared pieces into the design system (Path A territory).
  • Component/library ownership is design-system; building the screen is frontend-developer. This skill produces the reference both consume; validated by /design-review.