diff --git a/README.md b/README.md index 76149512f6..115cf0aa51 100644 --- a/README.md +++ b/README.md @@ -264,9 +264,11 @@ Additional commands for enhanced quality and validation: | Command | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| `/speckit.clarify` | Clarify underspecified areas (recommended before `/speckit.plan`; formerly `/quizme`) | -| `/speckit.analyze` | Cross-artifact consistency & coverage analysis (run after `/speckit.tasks`, before `/speckit.implement`) | -| `/speckit.checklist` | Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English") | +| `/speckit.clarify` | Clarify underspecified areas (recommended before `/speckit.plan`; formerly `/quizme`) | +| `/speckit.wireframe` | Generate dark-theme SVG wireframes for visual validation (recommended after `/speckit.clarify`) | +| `/speckit.wireframe-light` | Generate light-theme SVG wireframes for visual validation | +| `/speckit.analyze` | Cross-artifact consistency & coverage analysis (run after `/speckit.tasks`, before `/speckit.implement`) | +| `/speckit.checklist` | Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English") | ### Environment Variables diff --git a/docs/toc.yml b/docs/toc.yml index 18650cb571..f5a4fea717 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -17,3 +17,5 @@ items: - name: Local Development href: local-development.md + - name: Wireframe Generation + href: wireframes.md diff --git a/docs/wireframes.md b/docs/wireframes.md new file mode 100644 index 0000000000..00832bc07f --- /dev/null +++ b/docs/wireframes.md @@ -0,0 +1,121 @@ +# Wireframe Generation + +## Overview + +The wireframe commands generate SVG wireframes from your feature specification, providing visual validation before technical implementation begins. This creates a stakeholder review checkpoint in the SDD workflow. + +## Commands + +| Command | Description | +|---------|-------------| +| `/speckit.wireframe` | Generate dark-theme SVG wireframes | +| `/speckit.wireframe-light` | Generate light-theme SVG wireframes | + +## When to Use + +**Use wireframes when:** +- Your feature has user-facing UI components +- You need stakeholder sign-off before implementation +- Complex user flows need visual clarification +- You want to validate the spec interpretation visually + +**Skip wireframes when:** +- Backend-only features (APIs, services) +- Infrastructure or DevOps work +- Pure data processing features + +## Workflow Integration + +``` +/speckit.specify → /speckit.clarify → /speckit.wireframe → [REVIEW] → /speckit.plan +``` + +Wireframes provide a "hard stop" for stakeholder approval before investing in technical planning and implementation. + +## Output Location + +Wireframes are saved to a `wireframes/` subdirectory within the feature's spec directory: + +``` +specs/[###-feature-name]/wireframes/ +``` + +For example: +``` +specs/001-user-profile/ +├── spec.md +├── wireframes/ +│ ├── profile-view.svg +│ └── profile-edit.svg +└── plan.md (after /speckit.plan) +``` + +## Canvas Sizes + +| Canvas | Dimensions | Use Case | +|--------|------------|----------| +| Standard | 1400×800 | Default for most screens | +| Wide | 1600×800 | Extra annotation space (100px margins) | +| Tall | 1400×1000 | Complex vertical layouts | +| Extended | 1600×1000 | Full annotation mode | + +## Layout Structure + +Each wireframe shows **side-by-side Desktop and Mobile** views: + +| Section | Position | Size | +|---------|----------|------| +| Desktop area | x=40, y=60 | 900×680 (3-column layout) | +| Mobile area | x=980, y=60 | 360×700 (phone frame) | + +**Desktop 3-column layout:** +- Sidebar: 200px +- Main content: 440px +- Detail panel: 240px +- 10px gaps between columns + +## Dark vs Light Theme + +Both themes use the same layout structure with different color palettes: + +### Dark Theme (`/speckit.wireframe`) +- Background: `#0f172a` → `#1e293b` gradient +- Primary accent: `#8b5cf6` (violet) +- Best for: Developer presentations, dark mode applications + +### Light Theme (`/speckit.wireframe-light`) +- Background: `#ffffff` → `#f0f4f8` gradient +- Primary accent: `#8b5cf6` (violet) +- Best for: Client presentations, light mode applications + +## Multi-Page Wireframes + +For complex features, the command generates multiple SVG files: + +| Scenario | Naming Pattern | Example | +|----------|----------------|---------| +| Sequential flow | `NN-step-name.svg` | `01-login.svg`, `02-register.svg` | +| State variations | `screen-state.svg` | `dashboard-empty.svg`, `dashboard-error.svg` | +| Role variations | `screen-role.svg` | `settings-admin.svg`, `settings-member.svg` | + +## Annotations + +Wireframes include annotation callouts that explain UI interactions: +- Annotation boxes in margin areas +- Dashed leader lines connecting to UI elements +- Color-coded by interaction type + +## Example Usage + +``` +/speckit.wireframe +``` + +The command will: +1. Identify the feature's spec file +2. Analyze UI requirements from the spec +3. Recommend a wireframe strategy +4. Generate SVG files in the wireframes directory +5. Confirm files are ready for browser review + +After generation, open the SVG files in any browser to review with stakeholders. diff --git a/spec-driven.md b/spec-driven.md index 70b9789708..365118782a 100644 --- a/spec-driven.md +++ b/spec-driven.md @@ -83,6 +83,24 @@ This command transforms a simple feature description (the user-prompt) into a co 3. **Template-Based Generation**: Copies and customizes the feature specification template with your requirements 4. **Directory Structure**: Creates the proper `specs/[branch-name]/` structure for all related documents +### The `/speckit.wireframe` Command (Optional) + +After clarifying the specification with `/speckit.clarify`, this optional command generates visual wireframes for stakeholder review: + +1. **Spec Analysis**: Reads the feature specification to identify UI components and user flows +2. **Layout Planning**: Determines desktop (900px) and mobile (360px) layouts side-by-side +3. **SVG Generation**: Creates annotated wireframes with realistic placeholder content +4. **Visual Checkpoint**: Enables stakeholder review before investing in technical planning + +This command is recommended for features with user-facing UI components. For backend-only features, skip directly to `/speckit.plan`. + +**Workflow integration:** +``` +/speckit.specify → /speckit.clarify → /speckit.wireframe → [STAKEHOLDER REVIEW] → /speckit.plan +``` + +Use `/speckit.wireframe` for dark theme or `/speckit.wireframe-light` for light theme wireframes. + ### The `/speckit.plan` Command Once a feature specification exists, this command creates a comprehensive implementation plan: diff --git a/templates/commands/wireframe-light.md b/templates/commands/wireframe-light.md new file mode 100644 index 0000000000..590ce4e38b --- /dev/null +++ b/templates/commands/wireframe-light.md @@ -0,0 +1,462 @@ +--- +description: Generate SVG wireframes (light theme) from a spec for visual validation before implementation. +handoffs: + - label: Build Technical Plan + agent: speckit.plan + prompt: Create implementation plan for the visualized spec + - label: Generate Dark Theme + agent: speckit.wireframe + prompt: Generate dark theme version of these wireframes + - label: Clarify Requirements + agent: speckit.clarify + prompt: Refine spec requirements based on wireframe feedback +--- + +## User Input + +```text +$ARGUMENTS +``` + +## Outline + +Generate light-themed SVG wireframes from a feature specification for visual validation before technical planning. + +### 1. Identify the Spec + +If `$ARGUMENTS` is provided, use it as the spec file path. Otherwise, look for the spec in the current feature's directory: + +```bash +# Find spec.md in SPECS_DIR (set by speckit workflow) or detect from branch +ls specs/*/spec.md +``` + +Ask the user which spec to use if multiple exist, or use the only one if there's just one. + +### 2. Read the Spec + +**Use the Read tool** to read the full spec file. Extract and note: +- Feature name and purpose +- User stories and acceptance criteria +- UI requirements and interactions +- Any mentioned screens, forms, lists, or components +- Error states or edge cases mentioned + +This is critical - wireframes must accurately reflect the spec requirements. + +### 3. Plan the Wireframes + +**CRITICAL RULES**: +1. **Every feature gets at least one wireframe** - no exceptions. If a feature exists, it gets visualized. +2. **The number of wireframes is determined by the spec content** - do NOT assume 1 feature = 1 SVG. +3. **Non-UI features still need wireframes** - use architecture diagrams, data flow diagrams, system diagrams, or process flows. + +**Wireframe Types by Feature Category**: + +| Feature Type | Wireframe Approach | +|--------------|-------------------| +| UI screens (forms, lists, dashboards) | Desktop + Mobile side-by-side layouts | +| Backend/infrastructure (RLS, APIs, auth) | Architecture diagrams showing components and data flow | +| Testing frameworks | Test flow diagrams, coverage dashboards | +| Integrations | System integration diagrams, API flow charts | +| Security features | Security architecture, threat model diagrams | +| Data features | Entity relationship diagrams, data flow visualizations | + +**Determine how many wireframes based on spec content**: +- Count distinct user stories - each major flow may need its own wireframe +- Count distinct screens mentioned - each screen needs visualization +- Count distinct states (loading, error, empty, success) - consider separate wireframes for complex states +- Count distinct user roles - different views may need separate wireframes + +**Common wireframe needs**: +- List views (showing multiple items) +- Detail views (showing single item) +- Forms (create/edit) +- Special states (empty, loading, error) +- Architecture/system diagrams (for non-UI features) +- Flow diagrams (for processes and integrations) + +#### Determine Wireframe Strategy + +Based on the spec complexity, choose the appropriate approach: + +**Multi-Page** (create multiple SVG files): +- User flows with 3+ steps (auth, checkout, onboarding) +- State variations needing dedicated visualization (loading, error, empty, success) +- Different user roles with distinct views + +**Naming conventions**: +| Scenario | Pattern | Example | +|----------|---------|---------| +| Sequential flow | `NN-step-name.svg` | `01-login.svg`, `02-register.svg` | +| State variations | `screen-state.svg` | `dashboard-empty.svg`, `dashboard-error.svg` | +| Role variations | `screen-role.svg` | `settings-admin.svg`, `settings-member.svg` | + +**Expanded Canvas** (larger than 1400x800): +- Extensive annotations explaining complex interactions +- Flow arrows connecting multiple components +- Dense dashboards with many interconnected elements + +**Canvas options**: +| Canvas | viewBox | Use case | +|--------|---------|----------| +| Standard | `0 0 1400 800` | Default for most screens | +| Wide | `0 0 1600 800` | Extra annotation margins (100px each side) | +| Tall | `0 0 1400 1000` | Complex vertical layouts | +| Extended | `0 0 1600 1000` | Full annotation mode | + +Present your strategy recommendation to the user before generating. + +### 4. Generate SVG Wireframes + +Create SVG wireframes following the light theme patterns. + +**MANDATORY WATERMARK**: Every SVG file MUST include the generation header comment immediately after the opening `` tag. Replace placeholders: +- `[SPEC_FILE_PATH]` → actual spec file path (e.g., `specs/001-user-auth/spec.md`) +- `[YYYY-MM-DD]` → current date + +This watermark enables verification in future sessions via: +```bash +grep -r "GENERATED BY: /speckit.wireframe-light" specs/*/wireframes/ +``` + +**File location**: Create a `wireframes/` subdirectory within the feature's spec directory: +``` +specs/[###-feature-name]/wireframes/ +``` + +Create the directory if it doesn't exist: +```bash +mkdir -p specs/[feature-name]/wireframes +``` + +**Side-by-Side Layout Template** (Desktop left, Mobile right): +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + WIREFRAME TITLE + + + DESKTOP + + + + + + + + + + + MOBILE + + + + + + + + 9:41 + + + +``` + +**Layout Dimensions**: +| Section | Position | Size | Notes | +|---------|----------|------|-------| +| Desktop area | x=40, y=60 | 900×680 | 3-column layout | +| - Sidebar | x=40 | 200px wide | Navigation | +| - Main | x=250 | 440px wide | Primary content | +| - Detail | x=700 | 240px wide | Item details | +| - Gaps | | 10px | Between columns | +| Mobile area | x=980, y=60 | 360×700 | Phone frame | +| - Content | x=990, y=70 | 340×660 | 10px padding | + +**Component Sizing Standards** (use consistently): +| Component | Desktop | Mobile | rx | +|-----------|---------|--------|-----| +| Primary button | 100×36 | 80×32 | 6 | +| Icon button | 40×40 | 36×36 | 6 | +| FAB | r=28 | r=24 | circle | +| Text input | height=36 | height=32 | 6 | +| Card | - | - | 8 | +| List item | - | - | 6 | +| Badge (pill) | height=22 | height=20 | 11 | +| Avatar large | r=24 | r=20 | circle | +| Avatar small | r=16 | r=14 | circle | + +**Light Theme Color Palette**: +- Background: gradient `#ffffff` → `#f0f4f8` +- Primary: `#8b5cf6` (violet) +- Accent: `#d946ef` (fuchsia) +- Panels: `#ffffff`, `#f3f4f6` +- Borders: `#e5e7eb`, `#d1d5db` +- Text: `#1f2937` (headings), `#374151`/`#6b7280` (body), `#9ca3af` (muted) +- Success: `#22c55e`, Warning: `#eab308`, Error: `#ef4444` + +**Design Guidelines**: +- Include annotation boxes to explain UI elements +- Show realistic placeholder data (not "Lorem ipsum") +- Use the sizing standards above for consistent component dimensions + +#### Multi-Page Flow Guidelines + +When creating multi-page wireframes: +1. **Maintain consistency** - Same header/nav structure, colors, typography across all files +2. **Add flow indicators** - Progress bars, step numbers, "Back"/"Next" button states +3. **Include transition notes** - Annotate what action triggers navigation to next screen + +#### Wide Canvas Template (1600x800) + +For extra annotation space, use this adjusted layout: + +```xml + + +``` + +**Adjusted positions for 1600 wide**: +| Section | Standard (1400) | Wide (1600) | +|---------|-----------------|-------------| +| Desktop area | x=40 | x=140 | +| Mobile area | x=980 | x=1080 | +| Left annotation strip | N/A | x=20, width=100 | +| Right annotation strip | N/A | x=1480, width=100 | + +**Margin-to-View Mapping:** +| Margin | Annotates | Target coordinates | +|--------|-----------|-------------------| +| Left (x=20) | **Desktop** elements | x2 in range 140-940 | +| Right (x=1480) | **Mobile** elements | x2 in range 1080-1440 | + +Leader lines should connect annotations to their **adjacent** view, not reach across the screen. + +#### Annotation Callout Template + +```xml + + + + onClick + → /api/submit + + +``` + +#### Annotation Vertical Ordering (Prevent Crossing Lines) + +**Critical**: Order annotations in the margin to match the vertical position of their targets in the view. This prevents leader lines from crossing each other. + +**Process**: +1. **List target elements** with their y-coordinates in the view +2. **Sort by y-coordinate** (top to bottom) +3. **Place annotations** in the margin in the same top-to-bottom order + +**Example** - Annotating a mobile view with 3 elements: + +| Target Element | Target Y | Annotation Y (margin) | +|----------------|----------|----------------------| +| Header | y=70 | y=100 (top) | +| Form fields | y=200 | y=200 (middle) | +| Submit button | y=400 | y=320 (bottom) | + +**Wrong** (causes crossing): +``` +Margin Mobile View +┌─────┐ ┌─────────┐ +│ A3 │───┐ ┌──│ Target1 │ ← A3 points UP (crosses A1, A2) +├─────┤ │ │ ├─────────┤ +│ A1 │───┼──┘ │ Target2 │ ← A1 crosses A3 +├─────┤ │ ├─────────┤ +│ A2 │───┴─────│ Target3 │ +└─────┘ └─────────┘ +``` + +**Correct** (no crossing): +``` +Margin Mobile View +┌─────┐ ┌─────────┐ +│ A1 │─────────│ Target1 │ ← Horizontal or slight angle +├─────┤ ├─────────┤ +│ A2 │─────────│ Target2 │ ← Parallel lines +├─────┤ ├─────────┤ +│ A3 │─────────│ Target3 │ ← No crossing +└─────┘ └─────────┘ +``` + +**Spacing guideline**: Space annotation boxes ~80-120px apart vertically in the margin. + +**Leader Line Coordinate Calculation**: + +Leader lines MUST precisely connect annotations to their target elements. Calculate exact coordinates: + +1. **Find the target element's position** - Note its x, y, width, height from the SVG +2. **Calculate the connection point** on the target: + - Left edge: `x1 = target.x` + - Right edge: `x1 = target.x + target.width` + - Top edge: `y1 = target.y` + - Center: `x1 = target.x + target.width/2`, `y1 = target.y + target.height/2` +3. **Set line endpoint (x2, y2)** at the annotation box edge facing the target + +Example - Annotating a button at x=300, y=200, width=100, height=36: +```xml + + + + + SUBMIT BTN + + +``` + +For diagonal lines, ensure the endpoint lands ON the target element, not near it. + +#### SVG Draw Order + +**Important**: In SVG, elements render in document order - later elements appear on top. + +When using annotations with leader lines: +1. Place annotation boxes (rectangles + text) in the margin areas +2. Place all `` elements in a dedicated group at the END of the SVG + +This ensures leader lines are always visible, even when crossing over form elements or other content. + +#### Leader Lines Group Template + +Place all leader lines in a dedicated group at the END of the SVG, just before ``: + +```xml + + + + + + + + + + +``` + +**Key points:** +- Use absolute coordinates (not relative to transform groups) +- Group related lines with comments (left margin, right margin) +- This group must be the LAST element before `` + +#### State Variation Indicators + +| State | Visual treatment | +|-------|------------------| +| Loading | Skeleton placeholders, animated spinner, disabled buttons | +| Empty | Illustration placeholder, "No items" message, CTA | +| Error | Red accent border, error icon, retry button | +| Success | Green accent, checkmark icon, confirmation message | + +**Animated Loading Spinner Template**: + +Use SVG `` for smooth rotation animation: + +```xml + + + + + + + + + +``` + +**Spinner sizes** (adjust r and path d values): +| Size | Radius | Path d | +|------|--------|--------| +| Small | r=8 | `M 0 -8 A 8 8 0 0 1 8 0` | +| Medium | r=12 | `M 0 -12 A 12 12 0 0 1 12 0` | +| Large | r=20 | `M 0 -20 A 20 20 0 0 1 20 0` | + +The path draws a quarter arc. For a half-arc spinner, use: +```xml + +``` + +### 5. Verify + +After creating the wireframes: +1. List the created SVG files in `specs/[feature-name]/wireframes/` +2. Confirm files can be opened in a browser for visual review +3. Ready for stakeholder review before proceeding to `/speckit.plan` + +## Workflow Integration + +``` +/speckit.specify → /speckit.clarify → /speckit.wireframe-light → [REVIEW] → /speckit.plan +``` + +Wireframes provide a visual checkpoint for stakeholder approval before investing in technical planning and implementation. + +## Example + +For a spec about "User Profile" feature in `specs/001-user-profile/`: + +1. Create folder: `specs/001-user-profile/wireframes/` +2. Generate: + - `profile-view.svg` - View profile page + - `profile-edit.svg` - Edit profile form +3. Review wireframes with stakeholders +4. Proceed to `/speckit.plan` when approved diff --git a/templates/commands/wireframe.md b/templates/commands/wireframe.md new file mode 100644 index 0000000000..97f27207d7 --- /dev/null +++ b/templates/commands/wireframe.md @@ -0,0 +1,462 @@ +--- +description: Generate SVG wireframes (dark theme) from a spec for visual validation before implementation. +handoffs: + - label: Build Technical Plan + agent: speckit.plan + prompt: Create implementation plan for the visualized spec + - label: Generate Light Theme + agent: speckit.wireframe-light + prompt: Generate light theme version of these wireframes + - label: Clarify Requirements + agent: speckit.clarify + prompt: Refine spec requirements based on wireframe feedback +--- + +## User Input + +```text +$ARGUMENTS +``` + +## Outline + +Generate dark-themed SVG wireframes from a feature specification for visual validation before technical planning. + +### 1. Identify the Spec + +If `$ARGUMENTS` is provided, use it as the spec file path. Otherwise, look for the spec in the current feature's directory: + +```bash +# Find spec.md in SPECS_DIR (set by speckit workflow) or detect from branch +ls specs/*/spec.md +``` + +Ask the user which spec to use if multiple exist, or use the only one if there's just one. + +### 2. Read the Spec + +**Use the Read tool** to read the full spec file. Extract and note: +- Feature name and purpose +- User stories and acceptance criteria +- UI requirements and interactions +- Any mentioned screens, forms, lists, or components +- Error states or edge cases mentioned + +This is critical - wireframes must accurately reflect the spec requirements. + +### 3. Plan the Wireframes + +**CRITICAL RULES**: +1. **Every feature gets at least one wireframe** - no exceptions. If a feature exists, it gets visualized. +2. **The number of wireframes is determined by the spec content** - do NOT assume 1 feature = 1 SVG. +3. **Non-UI features still need wireframes** - use architecture diagrams, data flow diagrams, system diagrams, or process flows. + +**Wireframe Types by Feature Category**: + +| Feature Type | Wireframe Approach | +|--------------|-------------------| +| UI screens (forms, lists, dashboards) | Desktop + Mobile side-by-side layouts | +| Backend/infrastructure (RLS, APIs, auth) | Architecture diagrams showing components and data flow | +| Testing frameworks | Test flow diagrams, coverage dashboards | +| Integrations | System integration diagrams, API flow charts | +| Security features | Security architecture, threat model diagrams | +| Data features | Entity relationship diagrams, data flow visualizations | + +**Determine how many wireframes based on spec content**: +- Count distinct user stories - each major flow may need its own wireframe +- Count distinct screens mentioned - each screen needs visualization +- Count distinct states (loading, error, empty, success) - consider separate wireframes for complex states +- Count distinct user roles - different views may need separate wireframes + +**Common wireframe needs**: +- List views (showing multiple items) +- Detail views (showing single item) +- Forms (create/edit) +- Special states (empty, loading, error) +- Architecture/system diagrams (for non-UI features) +- Flow diagrams (for processes and integrations) + +#### Determine Wireframe Strategy + +Based on the spec complexity, choose the appropriate approach: + +**Multi-Page** (create multiple SVG files): +- User flows with 3+ steps (auth, checkout, onboarding) +- State variations needing dedicated visualization (loading, error, empty, success) +- Different user roles with distinct views + +**Naming conventions**: +| Scenario | Pattern | Example | +|----------|---------|---------| +| Sequential flow | `NN-step-name.svg` | `01-login.svg`, `02-register.svg` | +| State variations | `screen-state.svg` | `dashboard-empty.svg`, `dashboard-error.svg` | +| Role variations | `screen-role.svg` | `settings-admin.svg`, `settings-member.svg` | + +**Expanded Canvas** (larger than 1400x800): +- Extensive annotations explaining complex interactions +- Flow arrows connecting multiple components +- Dense dashboards with many interconnected elements + +**Canvas options**: +| Canvas | viewBox | Use case | +|--------|---------|----------| +| Standard | `0 0 1400 800` | Default for most screens | +| Wide | `0 0 1600 800` | Extra annotation margins (100px each side) | +| Tall | `0 0 1400 1000` | Complex vertical layouts | +| Extended | `0 0 1600 1000` | Full annotation mode | + +Present your strategy recommendation to the user before generating. + +### 4. Generate SVG Wireframes + +Create SVG wireframes following the dark theme patterns. + +**MANDATORY WATERMARK**: Every SVG file MUST include the generation header comment immediately after the opening `` tag. Replace placeholders: +- `[SPEC_FILE_PATH]` → actual spec file path (e.g., `specs/001-user-auth/spec.md`) +- `[YYYY-MM-DD]` → current date + +This watermark enables verification in future sessions via: +```bash +grep -r "GENERATED BY: /speckit.wireframe" specs/*/wireframes/ +``` + +**File location**: Create a `wireframes/` subdirectory within the feature's spec directory: +``` +specs/[###-feature-name]/wireframes/ +``` + +Create the directory if it doesn't exist: +```bash +mkdir -p specs/[feature-name]/wireframes +``` + +**Side-by-Side Layout Template** (Desktop left, Mobile right): +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + WIREFRAME TITLE + + + DESKTOP + + + + + + + + + + + MOBILE + + + + + + + + 9:41 + + + +``` + +**Layout Dimensions**: +| Section | Position | Size | Notes | +|---------|----------|------|-------| +| Desktop area | x=40, y=60 | 900×680 | 3-column layout | +| - Sidebar | x=40 | 200px wide | Navigation | +| - Main | x=250 | 440px wide | Primary content | +| - Detail | x=700 | 240px wide | Item details | +| - Gaps | | 10px | Between columns | +| Mobile area | x=980, y=60 | 360×700 | Phone frame | +| - Content | x=990, y=70 | 340×660 | 10px padding | + +**Component Sizing Standards** (use consistently): +| Component | Desktop | Mobile | rx | +|-----------|---------|--------|-----| +| Primary button | 100×36 | 80×32 | 6 | +| Icon button | 40×40 | 36×36 | 6 | +| FAB | r=28 | r=24 | circle | +| Text input | height=36 | height=32 | 6 | +| Card | - | - | 8 | +| List item | - | - | 6 | +| Badge (pill) | height=22 | height=20 | 11 | +| Avatar large | r=24 | r=20 | circle | +| Avatar small | r=16 | r=14 | circle | + +**Dark Theme Color Palette**: +- Background: gradient `#0f172a` → `#1e293b` +- Primary: `#8b5cf6` (violet) +- Accent: `#d946ef` (fuchsia) +- Panels: `#1e293b`, `#334155` +- Borders: `#475569` +- Text: `#fff` (headings), `#94a3b8`/`#cbd5e1` (body), `#64748b` (muted) +- Success: `#22c55e`, Warning: `#eab308`, Error: `#ef4444` + +**Design Guidelines**: +- Include annotation boxes to explain UI elements +- Show realistic placeholder data (not "Lorem ipsum") +- Use the sizing standards above for consistent component dimensions + +#### Multi-Page Flow Guidelines + +When creating multi-page wireframes: +1. **Maintain consistency** - Same header/nav structure, colors, typography across all files +2. **Add flow indicators** - Progress bars, step numbers, "Back"/"Next" button states +3. **Include transition notes** - Annotate what action triggers navigation to next screen + +#### Wide Canvas Template (1600x800) + +For extra annotation space, use this adjusted layout: + +```xml + + +``` + +**Adjusted positions for 1600 wide**: +| Section | Standard (1400) | Wide (1600) | +|---------|-----------------|-------------| +| Desktop area | x=40 | x=140 | +| Mobile area | x=980 | x=1080 | +| Left annotation strip | N/A | x=20, width=100 | +| Right annotation strip | N/A | x=1480, width=100 | + +**Margin-to-View Mapping:** +| Margin | Annotates | Target coordinates | +|--------|-----------|-------------------| +| Left (x=20) | **Desktop** elements | x2 in range 140-940 | +| Right (x=1480) | **Mobile** elements | x2 in range 1080-1440 | + +Leader lines should connect annotations to their **adjacent** view, not reach across the screen. + +#### Annotation Callout Template + +```xml + + + + onClick + → /api/submit + + +``` + +#### Annotation Vertical Ordering (Prevent Crossing Lines) + +**Critical**: Order annotations in the margin to match the vertical position of their targets in the view. This prevents leader lines from crossing each other. + +**Process**: +1. **List target elements** with their y-coordinates in the view +2. **Sort by y-coordinate** (top to bottom) +3. **Place annotations** in the margin in the same top-to-bottom order + +**Example** - Annotating a mobile view with 3 elements: + +| Target Element | Target Y | Annotation Y (margin) | +|----------------|----------|----------------------| +| Header | y=70 | y=100 (top) | +| Form fields | y=200 | y=200 (middle) | +| Submit button | y=400 | y=320 (bottom) | + +**Wrong** (causes crossing): +``` +Margin Mobile View +┌─────┐ ┌─────────┐ +│ A3 │───┐ ┌──│ Target1 │ ← A3 points UP (crosses A1, A2) +├─────┤ │ │ ├─────────┤ +│ A1 │───┼──┘ │ Target2 │ ← A1 crosses A3 +├─────┤ │ ├─────────┤ +│ A2 │───┴─────│ Target3 │ +└─────┘ └─────────┘ +``` + +**Correct** (no crossing): +``` +Margin Mobile View +┌─────┐ ┌─────────┐ +│ A1 │─────────│ Target1 │ ← Horizontal or slight angle +├─────┤ ├─────────┤ +│ A2 │─────────│ Target2 │ ← Parallel lines +├─────┤ ├─────────┤ +│ A3 │─────────│ Target3 │ ← No crossing +└─────┘ └─────────┘ +``` + +**Spacing guideline**: Space annotation boxes ~80-120px apart vertically in the margin. + +**Leader Line Coordinate Calculation**: + +Leader lines MUST precisely connect annotations to their target elements. Calculate exact coordinates: + +1. **Find the target element's position** - Note its x, y, width, height from the SVG +2. **Calculate the connection point** on the target: + - Left edge: `x1 = target.x` + - Right edge: `x1 = target.x + target.width` + - Top edge: `y1 = target.y` + - Center: `x1 = target.x + target.width/2`, `y1 = target.y + target.height/2` +3. **Set line endpoint (x2, y2)** at the annotation box edge facing the target + +Example - Annotating a button at x=300, y=200, width=100, height=36: +```xml + + + + + SUBMIT BTN + + +``` + +For diagonal lines, ensure the endpoint lands ON the target element, not near it. + +#### SVG Draw Order + +**Important**: In SVG, elements render in document order - later elements appear on top. + +When using annotations with leader lines: +1. Place annotation boxes (rectangles + text) in the margin areas +2. Place all `` elements in a dedicated group at the END of the SVG + +This ensures leader lines are always visible, even when crossing over form elements or other content. + +#### Leader Lines Group Template + +Place all leader lines in a dedicated group at the END of the SVG, just before ``: + +```xml + + + + + + + + + + +``` + +**Key points:** +- Use absolute coordinates (not relative to transform groups) +- Group related lines with comments (left margin, right margin) +- This group must be the LAST element before `` + +#### State Variation Indicators + +| State | Visual treatment | +|-------|------------------| +| Loading | Skeleton placeholders, animated spinner, disabled buttons | +| Empty | Illustration placeholder, "No items" message, CTA | +| Error | Red accent border, error icon, retry button | +| Success | Green accent, checkmark icon, confirmation message | + +**Animated Loading Spinner Template**: + +Use SVG `` for smooth rotation animation: + +```xml + + + + + + + + + +``` + +**Spinner sizes** (adjust r and path d values): +| Size | Radius | Path d | +|------|--------|--------| +| Small | r=8 | `M 0 -8 A 8 8 0 0 1 8 0` | +| Medium | r=12 | `M 0 -12 A 12 12 0 0 1 12 0` | +| Large | r=20 | `M 0 -20 A 20 20 0 0 1 20 0` | + +The path draws a quarter arc. For a half-arc spinner, use: +```xml + +``` + +### 5. Verify + +After creating the wireframes: +1. List the created SVG files in `specs/[feature-name]/wireframes/` +2. Confirm files can be opened in a browser for visual review +3. Ready for stakeholder review before proceeding to `/speckit.plan` + +## Workflow Integration + +``` +/speckit.specify → /speckit.clarify → /speckit.wireframe → [REVIEW] → /speckit.plan +``` + +Wireframes provide a visual checkpoint for stakeholder approval before investing in technical planning and implementation. + +## Example + +For a spec about "User Profile" feature in `specs/001-user-profile/`: + +1. Create folder: `specs/001-user-profile/wireframes/` +2. Generate: + - `profile-view.svg` - View profile page + - `profile-edit.svg` - Edit profile form +3. Review wireframes with stakeholders +4. Proceed to `/speckit.plan` when approved