| instructions | You are in FULLY AUTONOMOUS MODE. Zero questions. Just produce the spec.
TASK:
$ARGUMENTS
RULES:
- Do NOT ask the user anything. Decide and move.
- If you're unsure between two options, pick the one that is simpler and more conventional.
- Read the entire codebase before producing any output.
- If a design-spec.md already exists, read it and update it rather than replacing from scratch.
- Output is a single file: `design-spec.md` in the project root.
=== WHY THIS SKILL EXISTS ===
Every project without a locked design spec experienced cascading rework:
- ProjectA: 3 UI redesign waves hitting 20+ screen files, "old terminology" to "new terminology"
rename caused 149 test failures, branding change on Day 7 after features were built.
- ProjectB: No locked design spec led to reactive UI changes across the entire app.
- Confidence Coach: Design token consolidation required 6 separate commits to
standardize colors and spacing that should have been defined from Day 1.
This skill locks ALL design decisions into a single source of truth BEFORE any
implementation begins. Other skills (/iterate, /ship, /bootstrap) reference this
file to avoid drift.
=== PROCESS ===
1. SCAN THE PROJECT
Read all existing files to understand:
- What the app does (README, pubspec.yaml, package.json, etc.)
- Existing design decisions (theme files, constants, styles)
- Existing screens and navigation structure
- Existing data models and collection/table names
- Existing user-facing strings and microcopy
- The tech stack (Flutter, React, Node.js, etc.)
If the project is empty or just scaffolded, infer from the task description.
2. PRODUCE THE DESIGN SPEC
Generate `design-spec.md` with ALL of the following sections.
Every section is MANDATORY. Do not skip sections even if they seem
premature — decisions made now prevent rework later.
=== DESIGN SPEC TEMPLATE ===
The output file must follow this exact structure:
```markdown
# Design Spec — {App Name}
> Version: 1.0 | Created: {date} | Status: LOCKED
>
> This file is the single source of truth for all design decisions.
> Do NOT change values here without updating all code that references them.
> All skills (/iterate, /ship, /qa) must conform to this spec.
## 1. Identity
### App Name
- **Display name:** {name as shown to users}
- **Package/bundle ID:** {com.example.appname}
- **Internal project name:** {snake_case or kebab-case used in code}
### Terminology Lock
These terms are FINAL. Do not use synonyms, abbreviations, or alternatives
in code, UI, tests, or documentation.
| Concept | User-Facing Term | Internal Field Name | Notes |
|---------|-----------------|--------------------:|-------|
| {e.g., virtual currency} | {e.g., Paw Points} | {e.g., pawPoints} | {context} |
| ... | ... | ... | ... |
## 2. Design Tokens
### Color Palette
| Token Name | Hex | Usage |
|-----------|-----|-------|
| primary | #{hex} | Main action buttons, app bar, links |
| primaryVariant | #{hex} | Pressed/hover state of primary |
| secondary | #{hex} | Secondary actions, accents |
| secondaryVariant | #{hex} | Pressed/hover state of secondary |
| surface | #{hex} | Card backgrounds, input fields |
| background | #{hex} | Page/scaffold background |
| error | #{hex} | Error states, destructive actions |
| onPrimary | #{hex} | Text/icons on primary color |
| onSecondary | #{hex} | Text/icons on secondary color |
| onSurface | #{hex} | Text/icons on surface color |
| onBackground | #{hex} | Text/icons on background color |
| onError | #{hex} | Text/icons on error color |
| success | #{hex} | Success states, confirmations |
| warning | #{hex} | Warning states, caution indicators |
| neutral100 | #{hex} | Lightest neutral (borders, dividers) |
| neutral500 | #{hex} | Mid neutral (secondary text, icons) |
| neutral900 | #{hex} | Darkest neutral (primary text) |
All colors MUST be referenced via theme tokens in code. Zero hardcoded hex values.
### Typography Scale
| Style Name | Font Family | Size (sp/px) | Weight | Line Height | Usage |
|-----------|-------------|-------------… |
