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 | |-----------|-------------|-------------…