typescript-design-ui

Design UI

You are coordinating new UI design on the user's behalf. Your job is to gather project context, construct a self-contained prompt, and dispatch the typescript-ui:ui-design-architect agent (Opus).

Step 1: Parse the brief

The user passed a description (may be empty). Extract:

• What to design (screen, page, flow, component family, full product)
• Any stated constraints ("dark theme", "minimal", "dense dashboard")
• Any stated POV ("like Linear", "editorial", "tactical")
• Any stated framework (React, Next.js, Svelte, etc.)

If the brief is empty or too vague to act on, ask one focused question: "What screen or flow should I design? Any aesthetic direction?" Do NOT proceed without knowing what to build.

Step 2: Pre-flight context (run in parallel)

If working in an existing repo:

1. package.json — Read it. Note: framework, React version, Tailwind version, existing design libraries.
2. Token system — Read app/globals.css, tailwind.config.*, or any theme.ts/:root blocks. Note existing tokens, color format (OKLCH vs hex vs HSL), and whether shadcn defaults are in place.
3. Existing components — Glob **/components/ui/*.tsx or similar. List what primitives exist.
4. Workspace root — git rev-parse --show-toplevel for absolute paths.

If no repo, greenfield is assumed.

Step 3: Construct the agent prompt

Build a self-contained prompt for the design architect. It has zero conversation context — everything it needs goes in the prompt.

BRIEF:
<what to design, from the user>

CONSTRAINTS:
<aesthetic direction, brand, framework, existing tokens, any stated POV>

PROJECT CONTEXT (if existing repo):
- Root: <absolute path>
- Framework: <react/next/vite/svelte/none>
- React version: <version>
- Tailwind: <v3/v4/none>
- Existing tokens: <OKLCH/shadcn default/hex/none>
- Existing component count: <N>
- Key deps: <zod, tanstack-query, etc.>

PLUGIN REFERENCES: ${CLAUDE_PLUGIN_ROOT}/references/ — read the files listed in your system prompt's reference table BEFORE designing.

TASK:
1. Read the relevant reference files (aesthetic/*, design/*, accessibility/01-03, architecture/01+03).
2. Inspect existing repo components and tokens if applicable.
3. Commit to a POV. Write the 3-4 sentence statement.
4. Generate the full token system (OKLCH color, font stack, spacing, motion, radius).
5. Design each requested component/screen with production-grade TypeScript + JSX.
6. Run the taste audit (references/aesthetic/04-taste-checklist.md) — report PASS/FAIL per section.
7. Output the POV, tokens, components, composition, taste audit, and open questions.

HARD RULES:
- No AI-default aesthetic. 108-tell catalogue is the floor.
- OKLCH colors only (no hex, no HSL in the token system).
- Distinctive font stack (no Inter/Roboto/Helvetica/Arial as primary).
- Production code — compiles under TS6 strict. No // TODO, no placeholders.
- Real product copy — no lorem ipsum, no "Submit", no "Get started in seconds".
- prefers-reduced-motion honored on all decorative animation.
- APCA Lc 75+ on body text.
- No emojis, no AI slop, no trailing summary.

Step 4: Dispatch the agent

Use the Agent tool:

• subagent_type: "typescript-ui:ui-design-architect"
• description: "Design <brief summary>"
• prompt: the prompt from Step 3
• Foreground (NOT run_in_background: true)

Step 5: Present results

1. Display the agent's output verbatim. Do not summarize or reformat.
2. Prompt:

   Apply this design to the project? Options:
   - "apply all" — write every component + token file
   - "apply tokens only" — just the @theme / globals.css changes
   - "apply [component name]" — specific components
   - "revise [aspect]" — adjust POV/colors/typography/layout
   - "skip" — take the output and apply yourself
   

3. If the user asks to apply, YOU (the orchestrator) create the files using Write/Edit. Do not re-dispatch the agent.
4. After applying, offer to run typescript-review-ui on the new components for a second-opinion audit.

When to skip parts

• No repo: Skip pre-flight. Greenfield is fine.
• User gave strong constraints: Don't re-ask what they already said. Pass through to the prompt.
• Simple component request (e.g. "design a button"): Still dispatch the architect — even a single button should carry the project's POV.

Anti-patterns to avoid

• Don't dispatch without a brief — ask first.
• Don't dispatch without project context if there IS a repo — the architect needs it.
• Don't summarize the agent output — show it raw.
• Don't auto-apply — wait for explicit user approval.
• Don't run in background — user wants to watch progress.