Design Exploration & Comparison Kit
A local-first workspace for generating, comparing, and reviewing UI design directions before committing one to a real application.
DECK gives humans and AI agents a predictable place to explore several implementations of the same page. Agents create self-contained design files and shared mock data; DECK discovers them automatically. You browse the results, compare responsive behavior, record observations, and lift the winning direction into the real application.
No backend, account, API integration, or registry is required. The repository stays focused on one loop: generate → view → compare → note → choose.
- Automatic discovery — projects, pages, and
Design*.tsxfiles appear from a fixed folder convention. - True design isolation — every variation runs in its own iframe, preventing CSS and document state from leaking between designs.
- Meaningful comparison — single and side-by-side modes include independent widths, resizing, zoom, zoom sync, and window controls.
- Fair mock data — all variations of a page consume the same typed data source.
- Responsive review — inspect mobile, tablet, desktop, or custom widths without changing the design code.
- Theme-aware previews — projects and pages can expose light, dark, system, or custom themes.
- Observation notes — create, search, filter, sort, and copy notes while the designs remain visible.
- Keyboard-first workflow — navigation, view modes, preview windows, themes, panels, and comparison controls have shortcuts.
- Portable results — the winning component is deliberately easy to move into the real application.
- Node.js 22 or later
- npm 10 or later
git clone https://github.com/stevo1403/deck.git
cd deck
npm ci
npm run devOpen http://localhost:6174. Press ? in DECK to see all keyboard shortcuts.
To verify a production build locally:
npm run build
npm run preview
- Choose or create a project and page under
src/projects/. - Ask an AI agent to follow
DECK.mdandCONVENTIONS.md. - Generate multiple
DesignX.tsxvariations backed by one sharedmock-data.ts. - Refresh DECK, compare the variations, and record observations.
- Copy the chosen component into the real application and replace its mock data with real props or data sources.
DECK does not auto-export a winner. That final move is intentionally manual so experimental code never crosses into the real application unnoticed.
The filesystem is the registry:
src/projects/<project-slug>/
├── preferences.json
├── preferences.md
└── pages/
└── <page-slug>/
├── DesignA.tsx
├── DesignB.tsx
├── mock-data.ts
├── NOTES.md
├── preferences.json # optional page overrides
└── preferences.md # optional page guidance
Each design must default-export a React component with no required props. Designs for the same page use typed named exports from the same mock-data.ts, ensuring they differ in design—not in underlying content or behavior.
No shell registration is necessary. Vite discovers matching files through import.meta.glob. After adding an entirely new project or page, refresh the browser so Vite rescans the file tree.
The full agent-facing contract, including isolation and import rules, lives in CONVENTIONS.md.
| Compare variations | Navigate projects and pages |
|---|---|
 |
 |
Take observations without leaving the comparison
Each preview behaves like an independent window: resize, minimize, maximize, close, zoom, or change its viewport without disturbing the other designs.
Workspace choices such as the last project and page, selected designs, pane settings, theme, zoom, and notes are stored in the browser so a review can continue across sessions.
A fresh checkout includes three fictional products. Each has four pages, and each page has four functionally equivalent design directions.
| Product | Pages | Design directions |
|---|---|---|
| Northstar — product operations | Executive overview, project portfolio, team capacity, activity inbox | Classic product UI, contemporary bento, editorial, spatial/AI-forward |
| Meridian — personal finance | Money overview, send money, cards and controls, transaction history | Classic product UI, contemporary bento, editorial, spatial/AI-forward |
| Wayfinder — travel planning | Destination discovery, stay search, itinerary, booking checkout | Classic product UI, contemporary bento, editorial, spatial/AI-forward |
The examples are self-contained and use no external services or image assets. Their filtering, selection, fields, tabs, and primary actions remain consistent across variations so they demonstrate real comparison rather than a collection of static mockups.
Project and page preferences.json files are shallow-merged, with page values taking precedence. Markdown preferences remain separate and are shown as project and page guidance.
A project or page can declare its available themes in preferences.json. DECK passes the selected theme to the canvas, where designs can respond through document.documentElement.dataset.theme.
The floating notes tool stores review observations locally in the browser and can copy them as Markdown for an AI agent. A page's tracked NOTES.md remains the file-based design decision record.
Browser
├── Shell
│ ├── automatic project/page/design discovery
│ ├── comparison and responsive controls
│ └── preferences and observation tools
└── Canvas iframe (one isolated document per design)
└── DesignX.tsx + shared page mock-data.ts
The shell never renders a design component directly. It points each iframe to /canvas?project=...&page=...&design=..., isolating CSS, document state, and design-level behavior. The implementation uses Vite, React 19, TypeScript, Tailwind CSS 4, Radix UI, Recharts, and date-fns.
Build and run the production container with Docker Compose:
docker compose up --build -dOpen http://localhost:6174. Stop the container with:
docker compose downBecause generated designs are compiled into the production image, rebuild after adding or changing them.
DECK does not commit or upload anything by itself. Designs under src/projects/ are ordinary repository files, however, so Git will include them if you stage and push them. Use fictional or redistributable examples in a public checkout. Keep confidential explorations in a private fork, private repository, or a separate local copy with an appropriate ignore strategy.
Contributions are welcome when they improve the focused design-exploration workflow. Before opening a pull request, read the contributing guide and run:
npm run buildPlease use the repository's issue templates for bugs and feature proposals. By participating, you agree to follow the Code of Conduct. Security concerns should be reported privately according to the Security Policy.
See the Changelog for notable project changes.
DECK is available under the MIT License.