Ultra UI turns UI/UX research, product fit, source relevance filtering, style selection, palette selection, font pairing, human workflow, concept direction, scene design, motion, states, and QA gates into a durable design bundle. Treat DESIGN.md as the token source of truth, but do not treat token generation as the whole design process or product intent.
Decision Tree
What does the user need?
|
+- "Generate a UI from scratch"
| +- Has a product brief -> lib/pipeline (default)
| +- Only needs token file -> lib/generate
| +- Needs exact DESIGN.md schema -> references/design-md-format.md
|
+- "Validate a DESIGN.md"
| +- Structural/token/WCAG lint -> lib/lint or lib/index validate
| +- Needs rule explanations -> references/design-md-validation.md
| +- Broken refs or contrast warnings -> fix tokens first, prose second
|
+- "Diff two DESIGN.md files"
| +- Version-over-version review -> lib/diff
| +- Regression found -> inspect removed/modified tokens and lint delta
|
+- "Convert DESIGN.md to Tailwind config"
| +- Tailwind v3 JSON -> lib/export --format tailwind
| +- Tailwind v4 CSS variables -> lib/export --format css-tailwind
| +- W3C design tokens -> lib/export --format tokens
|
+- "Choose style / color / font / theme"
| +- Full recommendation -> scripts/search.py "<query>" --design-system
| +- Deep dive by domain -> scripts/search.py "<query>" --domain <domain>
| +- Persist classic design-system docs -> scripts/search.py "<query>" --design-system --persist
|
+- "Build / design a page or component"
| +- From scratch, wants a good UI -> pipeline: source relevance -> uncodixfy -> UX -> concepts -> scene -> DESIGN.md -> implementation -> QA
| +- From scratch, wants only tokens -> generate DESIGN.md first
| +- From scratch, wants code -> use the pipeline bundle, then implement
| +- Has a .pen file to edit -> stitch workflow, then extract DESIGN.md
| +- Wants full pipeline -> inspire -> define DESIGN.md -> implement -> validate
|
+- "Review / audit existing UI"
| +- Quick check -> Pre-Delivery Checklist
| +- Token/system audit -> extract or write DESIGN.md, then lint
| +- Accessibility audit -> WCAG notes + ux-guidelines search
|
+- "Fix / improve existing UI"
| +- Broken or inconsistent -> normalize tokens into DESIGN.md
| +- Boring or generic -> run pipeline and enforce QA anti-generic gate
| +- Looks Codex/AI-generated -> run uncodixfy smell pass, then pipeline QA
| +- Pre-launch quality pass -> lint + checklist + responsive validation
|
+- "Match a real brand's style"
| +- Brand reference exists -> design-kit/getdesign, then translate to DESIGN.md
| +- Brand reference absent -> infer tokens, document rationale, lint
|
+- "Implement Stitch/Pencil design as code"
+- Extract design DNA -> DESIGN.md tokens + prose
+- Implement -> code from bundle, export Tailwind if useful
Default Human Pipeline
For new UI work, use the pipeline command before implementation:
All long-lived Ultra UI documentation artifacts belong under docs/ui/. Use docs/ui/<product-or-surface>/ for generated pipeline bundles and docs/ui/README.md as the external-agent entrypoint. Outside agents should read docs/ui/README.md before loading skill internals. Do not scatter durable UI docs under app folders, .claude/skills, or root scratch files. Test fixtures may keep fixture-local generated artifacts under tests/fixtures/** only when the test needs the full bundle.
The pipeline writes:
File
Purpose
SOURCE-RELEVANCE.md
Classifies prompt/docs/design sources before they can affect content, layout, or tokens.
DESIGN.md
Machine-readable tokens and core design rationale.
DESIGN-CONTRACT.md
Product intent, user understanding, IA, layout shell, states, accessibility, implementation constraints, and Codex/Uncodixfy rules.
UNCODIXFY.md
Start-gate smell pass that bans default Codex UI moves before layout/code.
UX.md
Audience, emotional target, jobs, and UX rules.
CONCEPTS.md
Concept variants and required signature moment.
COMPOSITION.md
Responsive composition and visual hierarchy.
SCENE.md
2D scenery layers and 3D concept plan.
MOTION.md
Motion role, timing, and interaction personality.
STATES.md
Empty, loading, streaming, success, error, offline, and reduced-motion states.
IMPLEMENTATION.md
Build order and stack-specific notes.
QA.md
Anti-generic gate and visual verification checklist.
tokens/selected-rows.json
Retrieved knowledge-base rows used by the pipeline.
Implementation starts from SOURCE-RELEVANCE.md, DESIGN-CONTRACT.md, UNCODIXFY.md, UX.md, and CONCEPTS.md, uses DESIGN.md for tokens, then passes QA.md. A UI that only changes color, radius, and font fails this skill.
Animation, Skeleton, Theme, And Styling Enforcement
Normal UI motion, skeletons, loaders, themes, and token-based styling are mandatory. Every implementation must include:
Motion for state changes, controls, menus, panels, route/content transitions, loaders, skeletons, and generated output.
Skeleton states for page, card, table/list, media, and generated-output loading regions when those regions exist.
Loader states for blocking actions, background sync, uploads, generation, and route/data transitions.
Semantic theme/styling coverage: surfaces, text, borders, focus rings, shadows, component states, and light/dark behavior or a documented single-theme exception.
Reduced-motion behavior that keeps the workflow usable.
Use CSS transitions/keyframes, existing framework motion utilities, and platform View Transitions first. Anime.js and Three.js are allowed only for graphic-heavy browser experiences where sequencing, canvas, 3D, or high-touch visual storytelling is central to the product. If the user did not explicitly request that level of graphics, ask before adding either dependency and record the answer in the task ledger or implementation notes.
DESIGN.md vs DESIGN-CONTRACT.md
Keep DESIGN.md narrow and tool-friendly: frontmatter tokens plus canonical visual-system sections. Put broad product/UX governance in DESIGN-CONTRACT.md: product intent, user mental model, IA, page shell, interaction logic, states, accessibility, implementation constraints, anti-patterns, and UI decision records. This avoids corrupting the DESIGN.md token contract while still giving Codex the stronger reasoning structure it needs.
Source Relevance Gate
Before using a user-mentioned document path such as DESIGN.md, design guideline, /docs, or a README, classify it:
Source Type
Allowed Use
Not Allowed
Product/page brief
Audience, product claims, page intent, content hierarchy, user journey
Build/runtime architecture unless stated
Brand/design system
Tokens, components, spacing, radius, typography, contrast, brand tone
Page sections, landing copy, product positioning by filename alone
Hard rule: architecture/codebase content must never appear on the frontend. Framework names, backend/API topology, database/runtime/provider details, schema terms, deployment notes, file paths, docs taxonomy, and implementation jargon are internal constraints only. They must not become nav labels, hero copy, cards, proof points, empty states, tooltips, metadata, alt text, errors, badges, or footer copy.
A file named DESIGN.md is not automatically relevant to a landing page/site. Use it as token/design-system evidence unless its content explicitly describes the current product, surface, audience, and page goal. Never leak docs paths, architecture terms, or guideline labels into user-facing UI.
Uncodixfy Reasoning Gate
Before writing UI code, identify the default AI/Codex moves you are tempted to make and choose the harder, cleaner product UI instead. This is a start gate, not only an end-of-run checklist.
Chain ux-compiler -> ultra-ui -> uncodixfy for non-trivial UI rework, redesign, dashboard, admin, editor, checkout, onboarding, or product workflow screens.
Use existing app structure, tokens, typography, density, and components before inventing a new visual system.
Prefer normal application IA over decorative shells: stable nav, clear work area, context rail only when useful, direct controls, and real state handling.
Fail the pass if the improvement is only gradients, glass, larger radius, fake KPI cards, ornamental labels, or generic "premium dashboard" decoration.
Write the anti-Codex smell pass in the task ledger or implementation notes when the work is substantial.
Canonical DESIGN.md Format
Use DESIGN.md for durable design-system handoff. The YAML frontmatter is machine-readable and normative. The markdown body is human-readable rationale.
Token Schema
Token Group
Shape
Notes
version
string
Optional; upstream alpha uses alpha.
name
string
Human-readable design system name.
description
string
Optional summary.
colors
map of token to hex color
Values must be sRGB hex strings such as "#2563EB".
The generator shells to ../scripts/search.py for the top style, color, font, and product matches, emits DESIGN.md frontmatter and Overview/Colors/Typography prose, then runs official lint.
Validate Existing DESIGN.md
cd .claude/skills/ultra-ui/lib
pnpm ultra-ui lint ../../examples/heritage/DESIGN.md
pnpm ultra-ui validate ../../examples/heritage/DESIGN.md
Fix error findings before export. Treat warning findings as review items, especially contrast and orphaned tokens.
Diff Two Versions
cd .claude/skills/ultra-ui/lib
pnpm ultra-ui diff ./DESIGN.md ./DESIGN.next.md
Review removed tokens, modified colors, modified typography, and lint regressions before accepting a design-system change.
CLI Search Workflow
Use the copied Python search when the user asks for design recommendation depth rather than a finished DESIGN.md file.
