ux-design

Files (2)

• CHANNELS.md
• SKILL.md

SKILL.md (first lines)

# 03 — UX Design

## Overview

A design system that nobody decided is the average of the model's training data. This phase exists to make one human decision — **what this product looks like and what it deliberately is not** — and to write it down where restricted-context subagents can inherit it.

Three levels decide **who draws**. They never decide whether the decision gets made, nor whether the system is good: everything that raises quality is local, deterministic, and runs with no account and no network.

## When to use

- `stack.yml.frontend.framework` is set and not `none`, and `docs/03-ux-ui/navigation_map.md` **or** `design_system.md` is missing.
- The user says the design already exists in Claude Design and wants to start building pages.
- A project is adopted (`frontend.ui_defined: true`) and has no written design system.

## When NOT to use

- No frontend in `stack.yml` → go straight to `build`.
- Both deliverables exist and the user wants pages → that is `build`, not this phase. **Except** when `design_system.md` predates v2.0.0 and has no semantic token layer (`color.bg.*`, `color.text.*`, `color.border.*`, `color.focus.*`) — that is the content migration `2.0-design-system-layers`, this phase owns it, and bouncing to `build` leaves the contrast gate with nothing to compute. See Step 4.
- The user wants to change one token on a built system → that is a delta in `design_system.md` §7, not a re-run of this phase.

> **Antigravity:** if the session exposes `define_subagent`, register the agents this skill dispatches from `agents/<name>/AGENT.md` before the first dispatch — `architecture-validator` read-only (all flags `false`), any agent that writes with `enable_write_tools: true` (the flag defaults to `false`). In Claude Code they are registered by the plugin. The table of flags is in `build/SKILL.md` § "Cross-Platform Subagent Initialization".

## Required Inputs

- `.specture/stack.yml` — `frontend.framework`, `frontend.ui_library`, `frontend.styling`, `frontend.ui_defined`, `frontend.design_channel`.
- `.specture/conventions.md`.
- `docs/01-requirements/business_requirements.md` — actors, stories, and **§Identidad de Marca (`MK-nnn`)**, which is the only sanctioned source of brand.
- `docs/02-architecture/architecture.md`.
- The API contract declared in `stack.yml.api.contract_file` + its readable companion — the source of truth for what the UI consumes. The navigation map cites `operationId`s; it never invents URLs or response shapes.
- Templates: `BRAND_BRIEF_TEMPLATE.md`, `NAVIGATION_MAP_TEMPLATE.md`, `DESIGN_SYSTEM_TEMPLATE.md`, `COMPONENT_REFERENCE_TEMPLATE.md`.

## Hard Rules

<HARD-GATE>
- **NO code, NO snippets, NO HTML/JSX/CSS.** Even pseudo-code. Output is specification. *(Exception: throwaway direction comps — Step 2, deleted after the choice.)*
- **BRAND PROVENANCE GATE.** First, look for `## Identidad de Marca` in `business_requirements.md`. **If the section is absent, the gate fails immediately** — do not count anything. An absent section is not "zero undefined fields", it is the strongest form of *no brand*: nobody was ever asked. Say so, name the cause, and stop:
  > *"`business_requirements.md` no tiene `## Identidad de Marca` — es la migración de contenido `2.0-brand-brief`. Sin marca capturada no puedo escribir `design_system.md` sin inventarla. Corré `/specture:discover --marca` (cinco preguntas, no re-abre el cuestionario) y volvemos."*

  Only when the section **exists**, count the `MK-001`…`MK-005` fields that read `sin definir`. **If 2 or more, you may not author `design_system.md`.** Emit `docs/03-ux-ui/brief.md` from `BRAND_BRIEF_TEMPLATE.md`, run the refusal protocol of Step 2, and stop. `PROPUESTO_POR_EL_AGENTE` marks *individual fields the user could not answer* — **never a whole direction**. If the entire brand is proposed, there is no brand: there is your average.
- **Delegation is not authorization.** "Elegí vos", "confío en tu gusto", "no me preguntes" changes **who picks among options you present**. It never authorizes you to generate the options *and* pick. There is exactly one legal response: the refusal protocol.
- **An external design is not yours to author.** If `frontend.design_channel` is `claude-design`, or `.design-sync/config.json` exists, or `docs/03-ux-ui/handoff/` exists, the design system **already exists elsewhere**. You may not write `design_system.md` with values of your own — not as a draft, a scaffold, a placeholder, or "proposed". You ingest, or you stop.
- **Every number has provenance.** Every contrast ratio and every OKLCH ΔL in `design_system.md` comes from a run of `scripts/design-lint.js contrast`. Paste its `DESIGN_CHECK:` token in §6. Writing an estimated number is forbidden; write `sin verificar` instead.
- **NEVER decide a UI library on your own**, and never accept a declared one without the collision check of Step 1.
- **Violating the letter of a rule is violating its spirit.**
</HARD-GATE>

## The process

### Step 0 — Detect the level

Read `frontend.design_channel` from `stack.yml`, and look for `.design-sync/config.json` and `docs/03-ux-ui/handoff/`.

| Level | Condition | Who draws |
|---|---|---|
| **A — Claude Design** | `design_channel: claude-design`, or a pointer to a remote design project exists | The user, in claude.ai/design. Specture pulls per component, on demand, in `build`. |
| **B — native canvas** | `design_channel: canvas`, or the user asks for visual iteration and has no external project | Claude, via the `design` skill, inside this session. |
| **C — no external tool** | anything else, including other providers | Specture alone. The spine runs whole. |

**Adopt (`ui_defined: true`) is orthogonal to the level** — see Step 5.

The level never changes the deliverables, the gates, or the standard. If you cannot determine it, say so and ask; **never assume C to avoid asking**.

**Run the capability probe of `ux-design/CHANNELS.md` before drawing or pulling anything** — it is the file that holds the mechanics of each level, and probing after the work is spent is how a user gets promised a round-trip that cannot happen. A channel is never reported absent without its reason.

### Step 1 — Library, and the collision check

Read `frontend.ui_library`. If unset, propose 2-3 options for the framework and let the user pick. If declared, confirm it briefly.

**Then, before authoring a single token** — and only when the library is not `none`/`tailwind-only` — write its **default gravity centre** on four axes: neutral palette, radius profile, type pairing, density. Compare against `MK-003` (attributes) and `MK-004` (anti-references).

If the library's factory look falls inside a declared anti-reference, **stop** and put two options to the user:

- **(a)** change `ui_library`; or
- **(b)** sign an **override budget** — the named list of the library's components that will have to be rewritten, with the axis forcing each rewrite. It goes in `design_system.md` §1 and the Phase 4 visual gate checks it.

> Resolving this by calling the library "headless", "unstyled" or "themeable" is forbidden. That describes **colour**, which is cheap to replace. The expensive part is radius, density, control heights and type metrics, which are wired into every copied component.

### Step 2 — The direction decision

This is the step the phase exists for. **The user chooses; you never choose for them.**

1. **Emit `docs/03-ux-ui/brief.md`** from `BRAND_BRIEF_TEMPLATE.md`. Part A comes from `MK-nnn`; you ask for what is missing. Part B you *propose* from Part A.
2. **Generate exactly three named directions.** Each declares: thesis in one sentence · type pairing (and its bucket) · seed hue · shape language · density · motion personality · signature element · **what it deliberately sacrifices**.
3. **Show them.** At level A or B, draw them (level B: in an **isolated working directory**, so the `design` skill's step 0 cannot lift a factory scaffold — `tailwind.config.js` defaults or `components.json` with `baseColor: slate` — and anchor all three to it). At level C, a 3-row Markdown table plus one throwaway self-contained `.html` comp per direction, marked non-importable and deleted after the choice. A direction chosen from adjectives is a vocabulary choice, not a design choice.
4. **Ask for a number.** One question, one character, ~20 seconds.

**Refusal protocol** — when the user delegates, refuses, or does not answer: present the three directions anyway and ask for the number. If the answer is still "cualquiera" or silence, the phase ends **`BLOQUEADA-MARCA`**. It is not complete. Do not announce "UX completo" and do not offer Phase 4.

**Validity rule (mechanical):** any two directions must differ on **≥2 axes computable from the artefact** — type bucket, hue family of the hex, radius profile, border treatment. A free-text label never counts toward the minimum. Three perturbations of one centre are one direction wearing three names; regenerate.

The chosen direction **and the two discarded ones** are recorded as an ADR in `.specture/decisions/` — that is the anti-regression artefact restricted-context subagents inherit instead of re-deriving an average. Emit it as `Proposed`; the Phase 4 visual gate promotes it to `Accepted`.

### Step 3 — Navigation map

Write `docs/03-ux-ui/navigation_map.md` from `NAVIGATION_MAP_TEMPLATE.md`. The five-column table of §1 is the machine-readable source: a screen that is not a row does not exist for the coverage gate.

- `operationId`s come from the contract. **Assigning one by name plausibility is forbidden** — that an id exists does not make it the right id, and the verifier cannot tell those apart. A screen whose operations you have not confirmed writes `por-confirmar`.
- If a screen needs data no operation exposes, that is a contract gap for §4 and Phase 2. Never invent an operation.

### Step 4 — Design system

**First, if `design_system.md` already exists, check whether it has a semantic token layer** (`color.bg.*`, `color.text.*`, `color.border.*`, `color.focus.*`). If it has none, this is the content migration `2.0-design-system-layers` and **this phase owns it**: say so before anything else, and re-run the token section *with the user* rather than authoring the layer from your own taste.

> *"`design_system.md` no declara capa semántica — es la migración `2.0-design-system-layers`. Sin ella el gate de contraste no tiene pares que computar y no puede garantizar nada. Reconstruimos la capa juntos sobre los primitivos que ya tenés."*

The primitives already in the file stay; what gets added is the semantic layer that names their **roles**. When the layer is written and `design-lint contrast` passes, record the migration as done:

```
node "${CLAUDE_PLUGIN_ROOT}/scripts/doctor.js" migrate --verify 2.0-design-system-layers --by "ux-design"
```

(Antigravity: `${PLUGIN_ROOT}`; manual `@import`: `$SPECTURE_ROOT`.) Commit `.specture/migrations.log` with the document — the log is tracked and append-only. If `--verify` fails, the layer is not done: fix it, never log it by hand.

Then, for a design system being written for the first time: write `docs/03-ux-ui/design_system.md` from `DESIGN_SYSTEM_TEMPLATE.md`. Brand fields come from `MK-nnn` and are **not re-invented**.

- **Tokens in three layers**, referenced one way only. Derive neutrals by desaturating the brand hue — never copy a factory scale.
- **The roster of §3 is written whole, in this phase**: one row per reusable component, including those of later milestones. **Lazy authoring applies only to `components/<Nombre>.md`, never to the roster row.** Merging components with different anatomy, props or states into one row is forbidden — `Table` and `Pagination` are two rows; `Input`, `Select` and `DatePicker` are three. If the roster exceeds 40 rows, that is the size of the product, not a problem with this phase.
- **`deferred` needs a destination that exists today** in `docs/04-roadmap/ROADMAP.md`. If the epic is not in the roadmap yet, the only legal value is `deferred → sin epic asignado`.

From FerEscobarDev/Specture, MIT.

More from FerEscobarDev/Specture