ux-foundations

name

ux-foundations

description

Establishes the UX and design foundations for an application before feature work begins — the "architecture of the UI." Consumes the upstream SRS (docs/srs.md) and architecture document (docs/architecture.md) when present, then builds the design system from one of four user-chosen source modes: research a new direction, extract from reference images, ingest an existing design file, or pull from a connected design tool (e.g., Figma via MCP). Produces docs/ux-foundations.md (personas, IA, navigation, flows, screen inventory per surface), docs/design.md (agent-ready design system: tokens, components, states, layout and usage rules), and tokens.json (W3C DTCG). Use in the design phase, after architecture and before implementation planning, for any application with one or more UI surfaces. Trigger on "design the UX foundations", "set up the design system", "what should the UI look like", "plan the screens and navigation", or "create the design language".

UX Foundations

This skill defines the structure and design language of the UI before any feature is built — the counterpart to a software-architecture document, but for the experience layer. It produces the system screens are later assembled from, not pixel-perfect screens.

The governing idea, especially with several interfaces: one shared core, defined once, plus a per-surface layer for each interface. A single design language spans every surface so the product feels like one thing; each surface (admin portal, website, mobile app) gets its own profile because its users, navigation, components, and context genuinely differ.

Inputs

Two kinds of input with different consumption rules:

Pipeline documents — read silently, never ask. These are this pipeline's own upstream artifacts in their contracted locations; consuming them is the pipeline working as designed.

• SRS — default docs/srs.md. Read §2.3 (user classes & characteristics — the personas source; do not re-elicit them), §1.2 (vision/scope), the accessibility/usability NFRs in §3.3 (the accessibility bar comes from here and is non-negotiable — it overrides any ingested design), and any brand/compliance constraints in §2.5. Note NFR IDs for citation.
• Architecture — default docs/architecture.md. Read the UI surfaces (they appear as containers/building blocks), the context diagram's actors, and any frontend stack constraints.
• Use cases — docs/use-cases.md if present: key user flows often realize use cases; cite UC IDs where they do.

Source-gated traceability (same rule as the architecture skill): cite SRS NFR/FR IDs and UC IDs only when those documents exist; otherwise state drivers in prose. Never fabricate an ID.

Design source — always ask, never assume. Detection tells you what's possible; only the user can tell you what's wanted. A design.md in the folder may be stale; images may be leftovers; the user may want a fresh direction despite having sources. See Phase 1.

Fallback: if the pipeline documents are missing, say so and elicit surfaces and users directly (reduced mode) — the skill stays usable standalone.

Outputs

Three files, with a strict authority split:

1. docs/ux-foundations.md — the plan-time document: personas, per-surface IA and navigation, key user flows, screen inventories, cross-surface reconciliation. This is what implementation-planning consumes. It references design.md for anything design-system and never restates token values — design.md is the single source of truth for those.
2. docs/design.md — the render-time document a coding agent loads when building UI: tokens (with inline CSS-variable form), component specs with states and variants (including per-surface variants), layout/grid rules, accessibility rules, do/don'ts, agent quick-reference, provenance and known gaps. See references/design-md-guide.md.
3. docs/tokens.json — the canonical machine-readable tokens in W3C DTCG format (industry-standard interchange; transforms to CSS/Tailwind/native downstream). design.md's CSS block is derived from it — same values, one source of truth.

Workflow

Phase 1 — Ingest, detect, and ask the mode question

1. Silently ingest pipeline documents (per Inputs): surfaces and actors from the architecture, user classes and the accessibility bar from the SRS.
2. Detect candidate design sources: a design file (design.md or similar) in the project, reference images in docs/design-refs/ only (the convention location — no design-refs folder or no images there means images are treated as not present; do not scan the wider project), connected design-tool MCPs (Figma etc.). User-provided paths or attached images always win over detection. Detection is for presenting options, not for deciding.
3. Always ask the mode question — even when nothing is found, and even when exactly one source is found. Report what was detected, then offer the full menu with detected sources as named concrete options:
   • Research — no design source; research and propose a direction (comparable products, current conventions, the SRS's audience) before tokenizing. Degrade gracefully to expertise-based proposal without web access.
   • Extract from images — reference images from docs/design-refs/ (if detected) or paths/attachments the user supplies; if the mode is chosen and no images are available, ask for them — never hunt the wider project. Extract palette, type feel, spacing, component shapes.
   • Ingest a design file — user provides (or confirms detected) an external design.md/brand document; map it onto our structure.
   • Connect a design tool — pull tokens/styles/components via MCP. Folded variants: brand guidelines (PDF brand book) → ingest variant; existing codebase (CSS/Tailwind config) → extract variant, highest fidelity; mandated component framework (Material, shadcn) → one elicitation question in any mode, constrains the component layer. The user's explicit choice also resolves multi-source conflicts; within the chosen source, references/source-modes.md governs. SRS accessibility NFRs override every mode's output.
4. Confirm the surface list from the architecture ("I see three UI surfaces: admin portal, public website, mobile app — correct?"). Surfaces are the spine of everything downstream.

Phase 2 — Elicit the UX specifics

Read references/elicitation-guide.md. Personas come from SRS §2.3 — confirm, don't re-elicit. Ask only what upstream doesn't answer: per-surface device and responsive targets, brand feel (research mode), voice/tone, i18n. Batch questions, state inferences, offer one-word defaults.

Phase 3 — Acquire the design direction (mode-specific)

Read references/source-modes.md and run the chosen mode's acquisition protocol. For connected tools, references/design-tool-integrations.md has per-tool guidance with a generic fallback. Every mode ends the same way: a proposed design direction played back for confirmation (extraction is approximation; ingestion has conflicts to surface; research is a proposal). Never assert — confirm.

Phase 4 — Establish the shared core (once)

Read references/design-system-guide.md. Codify the confirmed direction into the shared core: semantic role-based tokens, core component inventory with states, voice, and the accessibility standard (from the SRS NFRs, cited by ID).

Phase 5 — Profile each surface (loop)

Read references/surface-profile-guide.md. Per surface: assign the surface code (confirm with the user), then users and jobs (from SRS user classes), IA and navigation, key flows (cite UC IDs where flows realize use cases), the screen inventory with stable SCR-<CODE>-<NNN> IDs per screen (same never-renumber rules as requirement IDs — downstream slices reference them), surface-specific components, token overrides.

Phase 6 — Reconcile across surfaces

Shared vs. surface-specific components, flows that span surfaces, consistency rules.

Phase 7 — Generate the three outputs

1. docs/tokens.json — DTCG format, per the design-system guide.
2. docs/design.md — per references/design-md-guide.md, deriving the CSS block from tokens.json.
3. docs/ux-foundations.md — per references/document-template.md, with embedded Mermaid sitemaps and flow diagrams (see references/diagram-guide.md), referencing design.md rather than restating it.

Phase 8 — Deliver

Summarize the design direction, the surface set, and the three outputs. Note the handoffs: the screen inventory feeds implementation-planning; **design.md

• tokens.json** feed every UI-building session downstream (suggest referencing design.md from CLAUDE.md). Offer next steps: anchor screen mockups, or proceed to implementation-planning.

Scope boundaries

Does not produce pixel-perfect per-feature screens (per-slice detailed design, downstream) or frontend component code (build). System and structure only — which is exactly what lets one core span web and native surfaces.

What good looks like

• Personas trace to SRS user classes; the accessibility bar cites its NFR IDs; flows cite the UC IDs they realize (all source-gated, never fabricated).
• Every screen has a stable SCR-<CODE>-<NNN> ID; no duplicates, no renumbering — the inventory is the reference downstream slices and ui-design cite.
• The mode question was asked explicitly; the chosen source's provenance and known gaps are recorded in design.md.
• design.md is agent-ready: concrete values, states, usage rules — no vagueness.
• tokens.json, design.md's CSS block, and ux-foundations.md never disagree, because value authority lives in tokens.json/design.md alone.
• One coherent core; per-surface layers diverge only where context demands.