Design Spec

---
name: design-spec
description: "Lock down design decisions before implementation — app name, terminology, design tokens, screen inventory, data models, and microcopy. Outputs a design-spec.md that other skills reference."
version: 1.0.0
category: spec
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 |
  |-----------|-------------|-------------|--------|------------|-------|
  | displayLarge | {font} | {size} | {weight} | {height} | Hero text, onboarding |
  | headlineMedium | {font} | {size} | {weight} | {height} | Screen titles |
  | titleLarge | {font} | {size} | {weight} | {height} | Section headers |
  | titleMedium | {font} | {size} | {weight} | {height} | Card titles |
  | bodyLarge | {font} | {size} | {weight} | {height} | Primary body text |
  | bodyMedium | {font} | {size} | {weight} | {height} | Secondary body text |
  | labelLarge | {font} | {size} | {weight} | {height} | Button text |
  | labelSmall | {font} | {size} | {weight} | {height} | Captions, hints |

  All text styles MUST be referenced via TextTheme/typography tokens. Zero inline font sizes.

  ### Spacing Grid

  Base unit: {N}dp/px

  | Token | Value | Usage |
  |-------|-------|-------|
  | xs | {N}dp | Tight padding (icon gaps, inline spacing) |
  | sm | {N}dp | Small padding (list item internal) |
  | md | {N}dp | Standard padding (card content, form fields) |
  | lg | {N}dp | Section spacing (between cards, groups) |
  | xl | {N}dp | Major section breaks, screen margins |
  | xxl | {N}dp | Hero spacing, onboarding gaps |

  ### Border Radii

  | Token | Value | Usage |
  |-------|-------|-------|
  | none | 0 | Sharp corners (dividers, full-width elements) |
  | sm | {N}dp | Subtle rounding (chips, tags) |
  | md | {N}dp | Standard rounding (cards, buttons) |
  | lg | {N}dp | Prominent rounding (modals, sheets) |
  | full | 9999dp | Pill shape (avatar, badges) |

  ### Elevation / Shadows

  | Token | Value | Usage |
  |-------|-------|-------|
  | none | 0 | Flat elements |
  | low | {N} | Cards, subtle depth |
  | medium | {N} | Floating action buttons, dropdowns |
  | high | {N} | Modals, overlays |

  ## 3. Screen Inventory

  ### Navigation Structure

  {Describe the navigation pattern: bottom tabs, drawer, stack-only, etc.}

  ### Screen List

  | Screen | Route/Path | Purpose | Key Components |
  |--------|-----------|---------|----------------|
  | {name} | {/path} | {what it does} | {main widgets/sections} |
  | ... | ... | ... | ... |

  ### Navigation Flow

  ```
  {ASCII diagram or description of screen-to-screen navigation}
  ```

  ## 4. Data Models

  ### Collection/Table Names

  | Entity | Collection/Table Name | Primary Key | Notes |
  |--------|----------------------|-------------|-------|
  | {entity} | {name} | {field} | {notes} |
  | ... | ... | ... | ... |

  ### Field Naming Convention

  - Case: {camelCase / snake_case}
  - Timestamps: {createdAt/created_at} format, stored as {DateTime/ISO8601/epoch}
  - IDs: {uuid / auto-increment / firestore-generated}
  - Booleans: prefix with {is/has/can} (e.g., isActive, hasPermission)
  - Enums: stored as {string / int}, values: {UPPER_CASE / lowercase}

  ### Core Models

  For each model, list ALL fields with types:

  #### {ModelName}
  | Field | Type | Required | Default | Notes |
  |-------|------|----------|---------|-------|
  | {field} | {type} | {Y/N} | {default} | {notes} |
  | ... | ... | ... | ... | ... |

  ## 5. Copy & Microcopy

  ### Key UI Strings

  | Context | String | Notes |
  |---------|--------|-------|
  | Empty state — {screen} | "{text}" | Shown when no data exists |
  | Error — generic | "{text}" | Fallback error message |
  | Error — network | "{text}" | No internet connection |
  | Error — auth | "{text}" | Session expired / unauthorized |
  | Success — {action} | "{text}" | Confirmation after action |
  | CTA — primary | "{text}" | Main call-to-action button |
  | Loading | "{text}" | Loading indicator text |
  | Onboarding — step 1 | "{text}" | First onboarding screen |
  | ... | ... | ... |

  ### String Storage Convention

  All user-facing strings MUST be stored in:
  - {location: e.g., lib/constants/strings.dart, src/i18n/en.json, etc.}

  Zero hardcoded strings in UI code.

  ## 6. Iconography & Assets

  | Icon/Asset | Source | Usage |
  |-----------|--------|-------|
  | App icon | {path or description} | Launcher icon |
  | {feature icon} | {MaterialIcons.name / custom asset path} | {where used} |
  | ... | ... | ... |

  ## 7. Platform-Specific Decisions

  | Decision | Value | Rationale |
  |----------|-------|-----------|
  | Min SDK/OS version | {value} | {why} |
  | Target platforms | {list} | {why} |
  | Orientation lock | {portrait/landscape/both} | {why} |
  | Dark mode support | {yes/no/later} | {why} |
  | Offline support | {yes/no/later} | {why} |
  | Auth method | {email/social/anonymous} | {why} |

  ## 8. Change Log

  | Date | Section | Change | Reason |
  |------|---------|--------|--------|
  | {date} | — | Initial spec created | — |
  ```

  === POST-GENERATION ===

  After generating design-spec.md:

  1. VERIFY CONSISTENCY: Cross-check that:
     - Every screen in the inventory uses only colors from the palette
     - Every data model field name follows the naming convention
     - Every user-facing term matches the terminology lock table
     - All routes in the screen inventory are unique

  2. VERIFY AGAINST EXISTING CODE (if code exists):
     - Flag any hardcoded colors, strings, or spacing values in existing code
       that contradict the spec. List them as "Migration Items" at the bottom.
     - Flag any existing field names that don't match the spec's naming convention.
     - Flag any screens that exist in code but are missing from the inventory.

  3. COMMIT the design-spec.md:
     - Commit message: "spec: lock design decisions in design-spec.md"

  === OUTPUT ===

  After generating the file:

    ## Design Spec Locked
    - App: {app name}
    - Screens: {count}
    - Models: {count}
    - Design tokens: {count of unique tokens defined}
    - Terminology entries: {count}
    - Migration items: {count of existing code violations, or "none — greenfield"}
    - File: design-spec.md

  NEXT STEPS:

  Recommended pipeline after `/design-spec`:
  - "Run `/iterate` to start building with the locked spec."
  - "Run `/arch-review` to validate architecture against the spec."
  - "Run `/bootstrap` to scaffold the project from the spec."
---