---
name: ui-design
effort: medium
description: "UI design workflow. Generates context-aware mockups with GAN-inspired generator/evaluator separation, visual verification via Playwright, and structured sprint contracts. Use when: (1) designing new pages or components, (2) the /prd skill reaches its UI design phase (Step 3), (3) redesigning existing pages, (4) creating design options for user review, (5) any task involving 'design UI', 'mockup', 'opzioni di design', 'progetta interfaccia', '3 opzioni', 'design page', 'UI design'. Not for: bug fixes, small tweaks, copy-only changes, or implementing an already-chosen design."
---

# UI Design Skill

Design workflow that produces context-aware mockup options, evaluates them with
separated generator/evaluator agents (GAN pattern), and delivers an approved
design with a structured UI Element Inventory.

**Architecture principle:** The generator never evaluates its own output.
Evaluation is always performed by a separate agent with fresh context.
[DESIGN-CHOICE: a fresh-context evaluator avoids the generator rationalizing its
own mockups — separating generation from scoring keeps the quality gate honest.]

## Project Context

**Reads from `baldart.config.yml`:**
`paths.design_system`, `paths.ui_guidelines`, `paths.components_primitives`,
`paths.components_root`, `paths.global_styles`, `paths.prd_dir`,
`identity.design_philosophy`, `identity.language`, `identity.audience_segments`,
`stack.charting.canonical`, `stack.charting.forbidden`, `stack.charting.wrappers_root`.

**Gated by features:**
`features.has_design_system` (when `true`, design-system reads are BLOCKING; when `false`, skip step 1 of Prerequisites and rely on `paths.ui_guidelines` alone).

**Overlay:** loads `.baldart/overlays/ui-design.md` if present — extends base by default; sections marked `## [OVERRIDE] <topic>` replace base sections. See `framework/agents/project-context.md` § 5.

**On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.

## Effort

**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
reasoning depth for this run — detect it once at kickoff and strip the token
before consuming user input. Level→behavior mapping, parsing contract, and
precedence caveats: `framework/agents/effort-protocol.md`.


## Working Directory (MANDATORY when invoked from `/prd`, since v3.22.0)

When `/prd` Step 3 invokes this skill, the caller passes (or sets as cwd) an
absolute **`WORKING_DIRECTORY`** that points to the PRD's docs worktree
(e.g. `/Users/alice/proj/.worktrees/prd-menu-info`). All persistent design
artefacts produced by this skill — most notably the `design.html` saved in
Step G — MUST be written inside that directory, NOT into the consumer's main
checkout. Without this, the design lands on the main repo, the `/prd` Step 7
stage list at `$WORKTREE_PATH/${paths.prd_dir}/<slug>/design.html` finds
nothing, and the PRD merged into `develop` ships without its design asset.

**Rule:** every `${paths.prd_dir}/...` reference in this document — including
Step G's "Copy approved HTML to `${paths.prd_dir}/<slug>/design.html`" — is
relative to `WORKING_DIRECTORY` when invoked from `/prd`. Construct the
absolute target path as `<WORKING_DIRECTORY>/<paths.prd_dir>/<slug>/design.html`
before any `Write`.

**Standalone invocations** (when the user runs `/ui-design` directly, no PRD
worktree): fall back to the consumer root. No prefix needed.

---

## Prerequisites — BLOCKING reads before ANY design work

The registry-first cascade below is the consumer view of the SSOT in
[`framework/agents/design-system-protocol.md`](../../../agents/design-system-protocol.md).
When the cascade rules diverge between this file and the protocol module,
the protocol module wins.

These reads are BLOCKING. Resolve paths from `baldart.config.yml` before opening files. If `features.has_design_system: true`, item 1 is the mandatory entry point and skipping it is a protocol violation.

1. **MANDATORY / BLOCKING when `features.has_design_system: true`** — read `${paths.design_system}/INDEX.md` (the design-system entry point: component index, authority matrix, token contract, any project-specific theming pairing rules and overlay decision tree).
2. **MANDATORY / BLOCKING** — read `${paths.ui_guidelines}` for canonical visual language, typography, accessibility, and brand voice. If the project has a `identity.design_philosophy` set, that philosophy is the lens through which the guidelines apply.
3. **MANDATORY when `features.has_design_system: true`** — read `${paths.design_system}/tokens-reference.md` (if present): token contract. Never hardcode values that bypass this SSOT.
4. **MANDATORY when `features.has_design_system: true`** — read the relevant `${paths.design_system}/components/<Name>.md` for every primitive you will touch, and the relevant `${paths.design_system}/patterns/*.md` for the pattern involved.
5. **MANDATORY for chart / data-viz tasks** — apply `stack.charting`:
   - Propose only libraries in `stack.charting.canonical`. Refuse libraries listed in `stack.charting.forbidden`.
   - If `stack.charting.wrappers_root` is set, propose those project wrappers over raw library usage.
   - If both lists are empty, ask the user which charting library to use before proposing one.
6. **MUST** run `ui-ux-pro-max` skill for design intelligence (bounded by the design-system SSOT above — advisory only).
7. **MUST** identify the audience segment for the work, using `identity.audience_segments` as the menu of valid choices. If segments are empty, treat the work as undifferentiated.
8. If brand inputs are missing (e.g. logo, accent palette), ask — never invent.

## Design System Alignment

- Token consumption follows the project's chosen mechanism (CSS custom properties in `${paths.global_styles}`, Tailwind config, theme provider, etc.). The base skill assumes nothing; defer to the design-system docs above for the project's mechanism.
- Canonical sources (resolve via `baldart.config.yml`):
  - `${paths.design_system}/INDEX.md` — component index + authority matrix (when `features.has_design_system: true`)
  - `${paths.design_system}/tokens-reference.md` — human-readable token contract
  - `${paths.design_system}/components/<Name>.md` — per-component specs
  - `${paths.design_system}/patterns/*.md` — pattern docs (e.g. theming, overlays, motion)
- NEVER hardcode hex colors, shadow tuples, or border-width values when the project has a token contract. Use the tokens listed in the contract.
- If the project uses multi-tenant theming (`features.multi_tenant_theming: true`), themed-surface text/bg pairing is mandatory per the project's theming pattern doc — consult `.baldart/overlays/ui-design.md` for the exact pairing rule.

---

## Workflow Steps

### Step A — Component Discovery

Read [references/component-discovery.md](references/component-discovery.md).

Before running the cascade, consult `${paths.design_system}/INDEX.md` (when present) and the relevant per-component doc in `${paths.design_system}/components/`. This is the authoritative inventory of tokens-compliant primitives.

Run the full cascade: design-system INDEX → project search (`${paths.components_primitives}/*`, `${paths.components_root}/shared/*` if applicable) → 21st.dev catalog → create from scratch. Document which existing components to reuse and which need creation. Any new component must consume the project's design tokens.

### Step B — Context Capture

Read [references/generation.md](references/generation.md) § Context Capture.

1. Identify 1-3 pages where the feature will live.
2. Capture screenshots via Playwright. Save to `/tmp/prd-design-<slug>/context/`.
3. Invoke `codebase-architect` to analyze adjacent UI components, layout patterns, and design tokens. Report file paths and rendered structure.

### Step C — Generate 3 Options (GENERATOR)

Read [references/generation.md](references/generation.md).

**OPTIONAL (graceful degradation):** `huashu-design` is a user-installed skill, NOT shipped with the
framework. If it is installed, invoke it before generating any HTML — it provides the HTML prototype
engine (React+Babel or vanilla+Tailwind CDN, Tweaks panel, App Prototype shell with AppPhone state
manager, Playwright click validation, animated output); follow its rules for the prototype type in
scope. If it is NOT installed, proceed without it: emit a one-line notice ("huashu-design not
installed — generating HTML mockups directly") and have `ui-expert` produce the HTML mockups using
the generation rules in `references/generation.md` plus a Tailwind CDN scaffold. Never block the
design run on huashu-design's absence.

**Filesystem rule (ABSOLUTE):** every HTML file MUST be written to disk with the `Write` tool at `/tmp/prd-design-<slug>/option-X.html` BEFORE opening in a browser. Outputting inline code blocks is not sufficient.

Invoke `ui-expert` agent with:
- Feature description and discovery answers
- Context screenshots (Read the image files)
- Codebase-architect findings
- 21st.dev catalog categories
- Full generation rules from the reference
- `huashu-design` prototype rules loaded above (only if the skill is installed; otherwise omit)
- `identity.design_philosophy` and `identity.language` to drive aesthetic and copy register

Output: 3 HTML files written to `/tmp/prd-design-<slug>/` via `Write` tool.

### Step D — Evaluate Options (EVALUATOR — separate agent)

Read [references/evaluation.md](references/evaluation.md).

Invoke a **separate, fresh-context `ui-expert` agent** (a NEW instance — NOT the `ui-expert` that
generated in Step C). `ui-expert` is the right evaluator because the rubric scores design-quality
criteria (visual hierarchy, information density, mobile-first layout) — a code-quality reviewer would
apply a code-correctness lens and miss the design criteria entirely. The GAN separation is preserved
by using a distinct instance with no memory of the generation pass.
- Pass the 3 HTML files
- Pass the context screenshots as reference
- Pass the evaluation rubric from [references/evaluation.md](references/evaluation.md) (7 criteria, scoring 1-5, hard thresholds) — the evaluator must read that reference, it does not know the rubric natively
- Request: produce evaluation report at `/tmp/prd-design-<slug>/evaluation-report.md`

**If any option FAIL:** send feedback to generator, re-generate, re-evaluate. Max 5 iterations per option.

**If PASS:** proceed to Step E.

### Step E — Present to User

1. **Open all 3 options in the user's default browser (MANDATORY):**
   ```bash
   open /tmp/prd-design-<slug>/option-a.html
   open /tmp/prd-design-<slug>/option-b.html
   open /tmp/prd-design-<slug>/option-c.html
   ```
   (On non-macOS hosts, substitute `xdg-open` / `start`.)
2. Show screenshots inline as supplement.
3. For each option: approach name, reused vs. new components. **DO NOT give evaluation scores, rankings, or recommendations on which to pick.**

**STOP.** Wait for user choice.

### Step F — Iterate on Feedback

1. User chooses option or requests changes.
2. Generator applies changes (with context screenshots as reference).
3. Evaluator re-evaluates (same rubric, fresh context).
4. Open updated HTML + show screenshot.
5. Repeat until explicit user approval.

### Step G — Save & Produce Inventory

Read [references/inventory.md](references/inventory.md).

1. Copy approved HTML to a deterministic canonical path so downstream steps can find it without asking:
   - `features.has_prd_workflow: true` → `${paths.prd_dir}/<slug>/design.html`.
   - `features.has_prd_workflow: false` → the framework default `.baldart/designs/<slug>/design.html`
     (create the directory if missing). Do NOT ask the user for an arbitrary runtime location — a
     non-recorded path breaks any downstream `/prd` / `/new` step that expects the design at a known
     location. (The user may override via an overlay-declared `paths.designs_dir`, but the default is
     deterministic.)
   **When invoked from `/prd` (since v3.22.0), prefix the chosen relative path with `WORKING_DIRECTORY` — see the "Working Directory" section near the top of this file.** Concrete absolute target (prd-workflow case): `<WORKING_DIRECTORY>/<paths.prd_dir>/<slug>/design.html`.
2. Extract UI Element Inventory (sprint contract).
3. Update state file with chosen option, design decisions, component lists.
4. Clean up `/tmp/prd-design-<slug>/`.

### Step H — Registry Coherence Reconciliation (BLOCKING completion gate)

When `features.has_design_system: true`, the design is not complete until the
component registry reflects every primitive the chosen design depends on. Run
the **Post-Intervention Coherence Check** defined in
[`framework/agents/design-system-protocol.md`](../../../agents/design-system-protocol.md)
§ "Post-Intervention Coherence Check".

Concretely, walk the UI Element Inventory from Step G and for each item:

1. **Registry-hit confirmed**: the primitive exists in `${paths.design_system}/INDEX.md`
   AND its `components/<Name>.md` spec matches the way the design uses it
   (props, variants, accessibility). If the design uses a variant not yet
   documented, update the spec inline.
2. **Source-tree-hit silent primitive**: the primitive exists under
   `${paths.components_primitives}` but not in `INDEX.md`. Add the INDEX entry
   inline (full spec or stub `status: needs-review`, see decision matrix in the
   protocol).
3. **New primitive proposed by the design**: it has no source implementation
   AND no spec. Either:
   - scaffold the spec + INDEX entry now as part of the inventory deliverable, OR
   - open a follow-up card and **flag the gap explicitly** in the inventory so
     downstream implementation work cannot proceed without resolution.
4. **Token additions**: the design introduces a color / spacing / shadow / motion
   value not present in `${paths.design_system}/tokens-reference.md`. Update the
   reference inline OR open a follow-up token-addition card before approval.

Surface every finding in the design handoff with the standard codes
(`DS_INDEX_DRIFT` / `DS_COMPONENT_STALE` / `DS_TOKENS_DRIFT`). Silent
reconciliation is forbidden — the user must see the drift that was found and
how it was resolved (inline vs. follow-up card).

This step exists because the design phase is where drift is **cheapest to
prevent**: catching a duplicate primitive at the mockup stage costs minutes,
catching it after implementation costs a refactor. The weekly `ds-drift`
routine is a safety net, not a substitute for this check.

---

## Design Principles (quick reference)

These are enforced — read `${paths.ui_guidelines}` for full spec.

- **Minimalism**: every control justifies its existence
- **Mobile-first**: 320px upward, 44px touch targets, 200% text scaling
- **Contrast**: every `bg-*` MUST have explicit `text-*` (WCAG 4.5:1)
- **Multi-tenant theming pairing**: when `features.multi_tenant_theming: true`, themed text-token paired with themed bg-token per the project's theming pattern doc
- **View State Trinity**: loading (skeletons), error (localized message + retry), empty (CTA). The error language follows `identity.language`.
- **Separation of concerns**: UI / business logic / data layers stay separate
- **Registry coherence (BLOCKING)**: when `has_design_system: true`, every primitive in the chosen design is reconciled with `INDEX.md` + `components/<Name>.md` + `tokens-reference.md` before sign-off (Step H). New primitive ⇒ new spec same change. Modified primitive ⇒ updated spec same change. Silent reuse of undocumented primitive ⇒ INDEX entry added now

---

## When This Skill is Called by /prd

The `/prd` skill invokes this skill for its Step 3 (UI Design Phase).
The flow maps directly:

| /prd Step | This skill Step |
|-----------|-----------------|
| 3a — UI Context Analysis | Steps A + B |
| 3b — 3 Design Options | Steps C + D + E |
| 3c — Design Iteration | Step F |
| 3d — Save & Inventory | Step G |

The `/prd` skill should invoke `ui-design` and follow its output rather than duplicating the design workflow internally.

---

## Delegation

### To `visual-designer` agent

For: hero illustrations, custom icons, empty state artwork, decorative backgrounds, onboarding visuals, campaign assets.

Provide: asset type, purpose, relevant section, style-guideline reference, brand colors, aspect ratio. Use `identity.design_philosophy` to set the aesthetic direction.

### To `motion-expert` agent

For: hover states, page transitions, expand/collapse motion, micro-interactions, reduced-motion-safe specs.

Provide: triggering action, affected element, desired feedback, accessibility requirements. If `stack.animation.canonical` is set, the motion-expert proposes specs targeting those libraries.

---

## Linked Skills

| Skill | When |
|-------|------|
| `huashu-design` | **OPTIONAL in Step C** (user-installed, not shipped) — HTML prototype engine, App Prototype shell, Tweaks, Playwright validation, MP4/GIF export. If installed, use it; else generate HTML mockups directly with a notice |
| `ui-ux-pro-max` | Before substantial design for design intelligence |
| `frontend-design` | To translate design into production code |
| `webapp-testing` | For browser verification with Playwright |
| `playwright-skill` | For quick screenshots and responsive checks |
