opencode-boilerplate/docs/design

Design Specification (docs/design/)

This directory holds the project's UI/UX design specification. It is created and maintained by the /define-design and /update-design commands and consumed by /generate-app and /add-feature.

Source of truth

docs/design/ui-blueprint.json   ← THE source of truth for UI generation

SVG files are visual references only. If an SVG and the blueprint disagree, the blueprint wins and the SVG must be regenerated.

Generated UI must follow design-tokens.json — no hard-coded values.

Structure

docs/design/
├── design-brief.md         # UI/UX direction (human-readable, concrete)
├── design-tokens.json      # Styling values (color, type, spacing, radius, …)
├── ui-blueprint.json        # Source of truth: screens, components, routes, actions
├── platform-mapping.md      # How the design maps to Web / Flutter / WinUI 3
└── screens/                 # SVG wireframes (one per blueprint screen)
    ├── home.svg
    ├── settings.svg
    └── [screen-id].svg

File purposes

design-brief.md

Overall UI/UX direction: target users, design concept, visual mood, layout/navigation principles, accessibility, platform-specific notes, preferred styles, and styles to avoid.

design-tokens.json

Design tokens in a Design Tokens Community Group–inspired JSON format ($type / $value). Covers color, typography, spacing, radius, shadow, motion, and breakpoints. Platform code reads from these tokens and never hard-codes values.

ui-blueprint.json

The source of truth for UI generation. Describes the app name, target platforms, routes, screens (each with a layout and component tree), reusable components (variants and states), and user actions/navigation.

platform-mapping.md

Documents how design-tokens.json and ui-blueprint.json are converted to each target platform:

• Web: tokens → CSS variables / Tailwind theme; blueprint → pages, routes, components.
• Flutter: tokens → ThemeData / ColorScheme / constants; blueprint → widgets, routes.
• WinUI 3: tokens → ResourceDictionary; blueprint → XAML pages, UserControls, navigation.

screens/*.svg

Low-fidelity wireframes, one per screen in ui-blueprint.json, named <screen-id>.svg. Generated for human review only — never the source of truth.

Workflow

/setup-project   → product/architecture docs
/define-design   → creates the files above
/generate-app web | flutter | winui3   → scaffolds the app from these files
/update-design   → updates these files when a feature changes the UI
/add-feature     → reads these files before implementing; updates them first if the UI changes

Status

This directory is populated by running /define-design. Until then, the files above do not exist and /generate-app will ask you to run /define-design first.