ultra-ui

name	ultra-ui
description	Ultra UI skill - human-centered UI pipeline plus Google's DESIGN.md spec, ui-ux-pro-max knowledge base, source relevance filtering, and Uncodixfy anti-generic reasoning gate. Generates source relevance, UX, concept, composition, 2D/3D scene, motion, state, implementation, QA, and lint-clean DESIGN.md artifacts before coding.
layer	domain
category	design
triggers	["/design-pipeline","/ui-pipeline","SaaS dashboard","UI review","UX improvement","WCAG compliance","accessibility audit","add styles","admin panel","ai design","award-winning","beautify","build UI","build a dashboard","build a form","build a landing page","build component","color scheme","complex layout","component design","create a website","create dialog","create screen","create table","create the UI for","create ui","css variables","dark mode","design a","design a component","design a page","design card","design from scratch","design guideline","design guidelines","design modal","design navigation","design review","design screen","design sidebar","design system","design this screen","design to code","design with stitch","elevate ui","fix ui","generate design","generate ui","improve ui","interface design","landing page design","looks bad","looks ugly","make a page","make it look better","make it look good","make it pretty","mockup","needs polish","pen file","pencil design","pixel perfect","polish the ui","premium UI","professional design","redesign","responsive design","shadcn","stitch","style component","style it","style this","tailwind","theme","ui","ui components","ui design","ui guidelines","user interface","web design","wireframe to code","DESIGN.md","design tokens","design.md","follow Design.md","follow design.md","docs path","source relevance","design lint","design diff","tailwind tokens","design token export"]
linksTo	["uncodixfy","ux-compiler","ui-polish","design-kit","accessibility"]

ultra-ui

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:

pnpm ultra-ui pipeline \
  --brief "premium learning knowledge graph for serious self-learners" \
  --surface "dashboard + landing" \
  --audience "serious learners and researchers" \
  --emotion "calm confidence with visible progress" \
  --density "medium-high" \
  --scene hybrid \
  --stack nextjs \
  --out docs/ui/4learner

Docs Location Rule

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
Architecture/codebase docs	Routes, APIs, data, runtime constraints, implementation limits	User-facing copy, landing narrative, visual mood, proof points
Generic guideline/reference	Checklist, accessibility, QA, process rules	Product-specific content or layout
Stale/irrelevant source	Ignore or cite as rejected	Any UI or implementation decision

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".
typography	map of token to typography object	Supports fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation.
rounded	map of scale token to dimension	Use none, sm, md, lg, xl, full unless a domain needs more.
spacing	map of scale token to dimension or number	Use 4px/8px-derived rhythm.
components	map of component token to property tokens	Use references for backgroundColor, textColor, typography, rounded, padding, size, height, width.

Section Order

Order	Section	When To Include
1	## Overview	Always; product fit, personality, density, audience.
2	## Colors	Always when colors exist; explain role and contrast.
3	## Typography	Always when typography exists; explain hierarchy and loading.
4	## Layout	Grid, spacing, breakpoints, safe areas.
5	## Elevation & Depth	Shadows, borders, tonal layering, blur policy.
6	## Shapes	Radius scale and shape language.
7	## Components	Buttons, cards, forms, nav, states.
8	## Do's and Don'ts	Guardrails and anti-patterns.

Read references/design-md-spec.md for the condensed normative spec and references/design-md-format.md for authoring examples.

Data Assets

Domain	Count	File	Example Keywords
Styles	91	data/styles.csv	glassmorphism, minimalism, bento grid, spatial design, calm UI
Color palettes	161	data/colors.csv	SaaS, ecommerce, healthcare, beauty, fintech
Font pairings	73	data/typography.csv	elegant, playful, professional, modern
Product types	161	data/products.csv	SaaS, e-commerce, portfolio, healthcare
UX guidelines	104	data/ux-guidelines.csv	animation, accessibility, view transitions, APCA, popover
Chart types	25	data/charts.csv	trend, comparison, timeline, funnel, pie
Google Fonts	1,923	data/google-fonts.csv	sans serif, monospace, japanese, variable
Icons	105	data/icons.csv	action icons, navigation icons, status icons
Landing patterns	34	data/landing.csv	hero, social proof, conversion, pricing
App interface rules	30	data/app-interface.csv	layout, state, interaction, accessibility
React performance	44	data/react-performance.csv	memoization, suspense, hydration, bundle
Stacks	16	data/stacks/*.csv	angular, astro, flutter, html-tailwind, jetpack-compose, laravel, nextjs, nuxt-ui, nuxtjs, react-native, react, shadcn, svelte, swiftui, threejs, vue

Quick Start

Generate Only DESIGN.md

cd .claude/skills/ultra-ui/lib
pnpm install
pnpm ultra-ui generate \
  --style "bento grid" \
  --palette "saas-blue" \
  --font "elegant" \
  --product "analytics dashboard" \
  --out ./DESIGN.md

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.

python3 .claude/skills/ultra-ui/scripts/search.py "<product industry tone>" --design-system
python3 .claude/skills/ultra-ui/scripts/search.py "bento" --domain style
python3 .claude/skills/ultra-ui/scripts/search.py "saas-blue" --domain color
python3 .claude/skills/ultra-ui/scripts/search.py "elegant" --domain typography
python3 .claude/skills/ultra-ui/scripts/search.py "dashboard" --domain product
python3 .claude/skills/ultra-ui/scripts/search.py "keyboard focus" --domain ux
python3 .claude/skills/ultra-ui/scripts/search.py "trend comparison" --domain chart

Use multi-dimensional queries: product + industry + tone. Example: "fintech compliance dense operator console".

Token Reference Resolution Rules

• Write references as {group.token} such as {colors.primary} or {spacing.md}.
• Hyphenated token names are valid: {colors.on-primary}.
• References must resolve inside the YAML tree; broken references are lint errors.
• Most references should point to primitive values. Component typography may point to a composite typography object.
• Frontmatter wins when prose and tokens disagree.
• If a requested token is missing, search the data assets first, then add the token and rerun lint.
• Unknown section headings should be preserved. Unknown component properties can warn, so prefer spec properties.

WCAG Contrast Notes

• The linter checks component backgroundColor and textColor pairs when both resolve to colors.
• Normal text target: 4.5:1 or better.
• UI graphics and large text: 3:1 minimum; generated systems should still prefer 4.5:1.
• Define on-* foreground tokens for each saturated background token.
• Do not use decorative accents as text backgrounds unless an accessible on-accent token exists.
• Pair color state with text, icon semantics, or ARIA state; never rely on color alone.

Pre-Delivery Checklist

DESIGN.md

• Source relevance pass classified prompt/docs/design paths before using them.
• Architecture/codebase docs only constrained implementation; they did not drive page copy, layout, or product positioning.
• YAML frontmatter parses.
• name, colors.primary, typography, rounded, spacing, and representative component tokens exist.
• Token references resolve; no broken-ref errors.
• Sections follow canonical order.
• DESIGN.md lints clean or warnings are explicitly resolved.
• Contrast passes WCAG AA for text-bearing component pairs.
• Tailwind/DTCG exports are regenerated from DESIGN.md, not edited manually.

Visual Quality

• Uncodixfy smell pass completed: no glass/floating gradient shells, dashboard hero, decorative copy, fake KPI filler, badge spam, hover transforms, or oversized radii unless product-specific.
• Full-page UI includes a semantic global frame: labeled navbar, main, and footer with product-specific trust/help/next-action links.
• Existing product tokens/components were used before inventing new palette, typography, or layout rules.
• No emojis used as icons; use SVG or the target app's icon system.
• Consistent icon family and stroke style.
• Typography matches defined tokens; no ad-hoc sizes.
• Colors match semantic tokens; no random grays.
• Spacing follows the defined rhythm.
• Pressed states do not shift layout bounds.
• At least one distinctive design element makes the experience memorable.

Interaction And Accessibility

• Interactive elements have hover, focus-visible, active, disabled, loading, and error states as relevant.
• Touch targets are at least 44x44pt on iOS and 48x48dp on Android.
• Transitions are 150-300ms and respect reduced motion.
• Focus order matches visual order.
• Forms have visible labels and accessible error messages.
• Color is not the only state indicator.

Responsive

• Works at 375px, 768px, 1024px, and 1440px.
• Landscape orientation remains readable.
• Safe areas are respected.
• Content is not hidden behind fixed or sticky bars.
• Horizontal insets adapt by device size.

References Index

Reference	Read When
references/design-md-spec.md	Need the normative DESIGN.md schema and consumer behavior.
references/design-md-format.md	Need to write or repair DESIGN.md structure.
references/design-md-validation.md	Need lint rule meanings, WCAG notes, or diff review guidance.
references/ux-laws.md	Need UX laws, heuristics, and Gestalt principles.
references/design-languages.md	Need a named design language or style direction.
references/color-systems.md	Need OKLCH, semantic tokens, dark mode, or accessible palette strategy.
references/themes.md	Need ready-made theme palettes and exact hex values.
references/component-patterns.md	Need button/card/input/form implementation patterns.
references/stitch-workflow.md	Need Stitch or Pencil MCP design workflows.
references/font-pairings.md	Need curated type pairing options.
references/design-systems.md	Need examples from established design systems.
references/composition-rules.md	Need visual hierarchy, grid, balance, and composition rules.
references/illustration-backends.md	Need custom illustration generation backends.
references/modern-techniques.md	Need modern CSS, animation, token, APCA, or platform techniques.
references/modern-patterns.md	Need bento, kinetic, AI chat, command palette, or spatial UI patterns.
references/operator-console-style.md	Need dense control-plane/operator-console aesthetics.
references/ui-styling/shadcn-components.md	Need shadcn/ui component usage.
references/ui-styling/shadcn-theming.md	Need shadcn theme and CSS variable guidance.
references/ui-styling/shadcn-accessibility.md	Need shadcn ARIA, focus, and keyboard patterns.
references/ui-styling/tailwind-utilities.md	Need Tailwind utility class guidance.
references/ui-styling/tailwind-responsive.md	Need responsive Tailwind and container query patterns.
references/ui-styling/tailwind-customization.md	Need Tailwind theme customization and plugins.
references/ui-styling/canvas-design-system.md	Need canvas-based visual design philosophy.

Attribution

DESIGN.md spec and examples are from google-labs-code/design.md by Google LLC. See THIRD_PARTY_NOTICES.md for license and source details.