| name | ux-scaffold |
| description | Template-aware mockup project creation with DESIGN.md-derived tokens. Supports html-lite (zero-install, navigable) and react-full (shadcn + Vite + Radix). Use when generating mockups from a PRD or spec. |
UX Scaffold
Purpose
Create mockup projects at the correct fidelity level, styled from DESIGN.md tokens via ux-theme-gen output, and structured as navigable screen sets rather than monolithic apps.
When to Use
ux-engineer invokes this after ux-theme-gen has produced theme artifacts.- User explicitly requests a mockup scaffold.
Templates
| Template | Fidelity | Output | Build step required |
|---|
html-lite | Low | Self-contained HTML per screen + index.html | No — opens from file:// |
react-full | High | Vite + React + shadcn/ui project | Yes — pnpm install && pnpm dev |
react-mid | — | Cut (decision 2) | — |
react-native | — | Reserved, not implemented | — |
Scripts
scaffold-lite.sh
Usage: ./scripts/scaffold-lite.sh <feature> <variant-num> <theme-css-path> <output-dir>
Generates:
<output-dir>/index.html — entry point listing all screens with nav<output-dir>/screen-<name>.html — one per enumerated screen<output-dir>/screen-map.md — Mermaid flowchart of screen navigation
scaffold-full.sh
Usage: ./scripts/scaffold-full.sh <feature> <variant-num> <output-dir>
Scaffolds a Vite + shadcn project. The script:
- Creates the Vite app via
npm create vite@latest.
- Runs
pnpm install.
- Runs
shadcn@4.18.0 init --base radix --preset nova --css-variables --yes --silent in the created dir.
- Copies
ux-theme-gen output (theme.css) into src/index.css, replacing the default token declarations.
Screen Enumeration
Before scaffolding, the agent enumerates screens from the source artifact:
| Screen type | Purpose |
|---|
happy | Primary flow, success state |
error-validation | Form validation failures |
error-server | Server/network error states |
error-permission | Permission denied, unauthorized |
empty | No data, first-use experience |
loading | Skeleton screens, spinners |
edge-overflow | Long text, many items |
edge-zero | Zero items, disabled states |
Each screen becomes a named file (screen-happy.html, screen-error-validation.html, etc.).
html-lite Navigation (Decision 2)
Lite output is a browsable prototype, not loose files:
index.html — lists every screen with its purpose and the AC/story it satisfies, plus the screen map rendered inline.- Inter-screen links — persistent nav strip on every screen: back to index, previous/next, and direct links to related states (e.g., happy → error-validation → empty).
- Relative links only — must work from
file:// with no server.
- Current-screen indication — highlighted in the nav strip.
Annotations
Every screen section carries a machine-readable reference to the AC or story it satisfies:
- HTML:
<section data-ac="AC-3"> or <!-- AC: AC-3 -->
- React:
{/* @ac AC-3 */} comment above the relevant JSX
Theme Integration
html-lite: reads theme.css and inlines the :root token values as a <style> block.react-full: theme.css replaces the shadcn-generated :root / @theme inline block in src/index.css.
Both templates must not contain hardcoded palette values. All styling derives from the theme output.
Palette Inputs — Removed
The palette parameter and the colorhunt.co fallback are removed. DESIGN.md is the sole palette source. If DESIGN.md is unfilled, the agent runs the filling procedure rather than inventing a palette.
Dependencies (react-full)
Pinned to the verified compatibility matrix:
| Package | Version | Notes |
|---|
vite | ^8 | via create vite |
@vitejs/plugin-react | ^6 | Vite 8 only |
@tailwindcss/vite | ^4 | replaces postcss + autoprefixer |
tailwindcss | ^4 | CSS-first, no config file |
shadcn | 4.18.0 | pinned exactly; never @latest |
radix-ui | ^1.6 | unified package |
tw-animate-css | ^1.4 | replaces tailwindcss-animate |
class-variance-authority | ^0.7 | |
clsx + tailwind-merge | latest | |
lucide-react | ^1.33 | icon library |
Node requirement: >= 24 (shadcn CLI needs >= 20.18.1; repo floor is >= 24).
Backward Compatibility
webapp-mockup has been removed. Use ux-scaffold directly with the appropriate template.
Acceptance Checklist
- Scripts run non-interactively with no TTY
- html-lite produces valid standalone HTML viewable from
file://
- index.html includes screen map + screen listing
- Inter-screen navigation works with relative links
- react-full uses shadcn CLI (pinned), not hand-rolled components
- No hardcoded palette in any scaffold output
- Every screen carries an AC/story annotation
- No
postcss, autoprefixer, tailwindcss-animate, or tailwindcss init -p
