Wds 7 Design System

Follow the instructions in ./workflow.md.

Phase 5: Design System Workflow

Overview

Purpose: Extract, organize, and maintain reusable design components as they're discovered during Phase 4 specification work.

Key Principle: Design system is optional and on-demand. Components are added as they surface, not created upfront.

---

When This Workflow Runs

Triggered from Phase 4:

• After component specification is complete
• Only if design system is enabled in project
• First component triggers automatic initialization

Not a Separate Phase:

• Runs in parallel with Phase 4
• Integrated into component specification flow
• Designer doesn't "switch" to design system mode

---

Three Design System Modes

Chosen during Phase 1 (Project Exploration):

Mode A: No Design System

• Components stay page-specific
• AI/dev team handles consistency
• Faster for simple projects
• This workflow doesn't run

Mode B: Custom Design System

• Designer defines components in Figma
• Components extracted as discovered
• Figma MCP endpoints for integration
• This workflow extracts and links to Figma
• See: ../wds-6-asset-generation/workflow-figma.md for complete Figma workflow

Mode C: Component Library Design System

• Uses shadcn/Radix/etc.
• Library chosen during setup
• Components mapped to library defaults
• This workflow maps to library components

---

Architecture

Three-Way Split

Page Specification (Logical View)
├── Component references
├── Page-specific content
└── Layout/structure

Design System (Visual/Component Library)
├── Component definitions
├── States & variants
└── Styling/tokens

Functionality/Storyboards (Behavior)
├── Interactions
├── State transitions
└── User flows

Clean Separation

Specification = Content (what the component is) Organization = Structure (where it lives) Design System = Optional (chosen in Phase 1)

---

Workflow Components

1. Design System Router

File: design-system-router.md

Purpose: Identify if component is new, similar, or duplicate

Flow:

Component specified → Router checks design system
├── No similar component → Create new
└── Similar component found → Opportunity/Risk Assessment

2. Opportunity/Risk Assessment

Folder: assessment/

Purpose: Help designer make informed decisions about component reuse

7 Micro-Instructions:

1. Scan existing components 2. Compare attributes 3. Calculate similarity 4. Identify opportunities 5. Identify risks 6. Present decision to designer 7. Execute decision

3. Component Operations

Folder: operations/

Purpose: Execute design system actions

4 Operations:

• Initialize design system (first component)
• Create new component
• Add variant to existing component
• Update component definition

4. Output Templates

Folder: templates/

Purpose: Consistent design system file structure

3 Templates:

• Component specification
• Design tokens
• Component library config

---

Integration with Phase 4

Called from: workflows/wds-4-ux-design/steps-p/step-03-components-objects.md

Integration Point:

For each component:
1. Specify component (Phase 4)
2. Component specification complete
3. → Check: Design system enabled?
4. → YES: Call design-system-router.md
5. → Router extracts component-level info
6. → Router returns reference
7. Update page spec with reference
8. Continue to next component

Result:

• Page spec contains references + page-specific content
• Design system contains component definitions
• Clean separation maintained

---

Key Risks & Mitigation

1. Component Matching

Risk: How to recognize "same" vs "similar" vs "different"

Mitigation: Similarity scoring + designer judgment via assessment flow

2. Circular References

Risk: Page → Component → Functionality → Component

Mitigation: Clear hierarchy (Page → Component → Functionality)

3. Sync Problems

Risk: Component evolves, references may break

Mitigation: Reference IDs + update notifications

4. Component Boundaries

Risk: Icon in button? Nested components?

Mitigation: Designer conversation + guidelines in shared knowledge

5. First Component

Risk: When to initialize design system?

Mitigation: Auto-initialize on first component if enabled

6. Storyboard Granularity

Risk: Component behavior vs page flow

Mitigation: Clear separation guidelines in shared knowledge

---

Shared Knowledge

Location: data/design-system/

Purpose: Centralized design system principles referenced by all component types

Documents:

• token-architecture.md - Structure vs style separation
• naming-conventions.md - Token naming rules
• state-management.md - Component states
• validation-patterns.md - Form validation
• component-boundaries.md - What's a component?
• figma-component-structure.md - Figma component organization (Mode B)

Usage: Component-type instructions reference these documents as needed

---

Figma Integration (Mode B)

Location: ../wds-6-asset-generation/workflow-figma.md

Purpose: Enable seamless Figma ↔ WDS synchronization for custom design systems

Documents:

• figma-designer-guide.md - Step-by-step guide for designers
• figma-mcp-integration.md - Technical MCP integration guide
• figma-component-structure.md - Component organization in Figma (in data/design-system/)
• prototype-to-figma-workflow.md - NEW: Extract HTML prototypes to Figma for visual refinement
• when-to-extract-decision-guide.md - NEW: Decision framework for prototype extraction

Workflows:

A. Figma → WDS (Existing): 1. Designer creates/updates component in Figma 2. Designer adds WDS component ID to description 3. MCP reads component via Figma API 4. Agent generates/updates WDS specification 5. Designer reviews and confirms

B. Prototype → Figma → WDS (NEW): 1. HTML prototype created (Phase 4D) 2. Extract to Figma using html.to.design 3. Designer refines visual design in Figma 4. Extract design system updates (tokens, components) 5. Re-render prototype with enhanced design system 6. Iterate until polished

Key Features:

• Component structure guidelines
• Design token mapping
• Variant and state organization
• Node ID tracking
• Bidirectional sync workflow
• Iterative visual refinement (prototype → Figma → design system → re-render)

---

Company Customization

Key Feature: Companies can fork WDS and customize design system standards

Customization Points:

• data/design-system/ - Company-specific principles
• object-types/ - Company component patterns
• templates/ - Company output formats

Result: Every project automatically uses company standards

---

Output Structure

D-Design-System/
├── 01-Visual-Design/          [Early design exploration - pre-scenario]
│   ├── mood-boards/           [Visual inspiration, style exploration]
│   ├── design-concepts/       [NanoBanana outputs, design explorations]
│   ├── color-exploration/     [Color palette experiments]
│   └── typography-tests/      [Font pairing and hierarchy tests]
├── 02-Assets/                 [Final production assets]
│   ├── logos/                 [Brand logos and variations]
│   ├── icons/                 [Icon sets]
│   ├── images/                [Photography, illustrations]
│   └── graphics/              [Custom graphics and elements]
├── components/
│   ├── button.md              [Component ID: btn-001]
│   ├── input-field.md         [Component ID: inp-001]
│   ├── card.md                [Component ID: crd-001]
│   └── ...
├── design-tokens.md           Colors, spacing, typography
├── component-library-config.md Which library (if Mode C)
└── figma-mappings.md          Figma endpoints (if Mode B)

Component File Structure:

# Button Component [btn-001]

**Type:** Interactive
**Library:** shadcn/ui Button (if Mode C)
**Figma:** [Link] (if Mode B)

## Variants

- primary
- secondary
- ghost

## States

- default
- hover
- active
- disabled

## Styling

[Design tokens or Figma reference]

## Used In

- Login page (login button)
- Signup page (create account button)
- Dashboard (action buttons)

---

Next Steps

1. Read design-system-router.md to understand routing logic 2. Review assessment/ folder for decision-making process 3. Check operations/ for available actions 4. Reference data/design-system/ for principles 5. Use templates/ for consistent output

---

This workflow is called automatically from Phase 4. You don't need to run it manually.

Step 1: Scan Existing Components

STEP GOAL:

Find all components in the design system that match the current component type. Scan the design system folder, extract component metadata, and build a candidate list for comparison.

MANDATORY EXECUTION RULES (READ FIRST):

Universal Rules:

• 🛑 NEVER generate content without user input
• 📖 CRITICAL: Read the complete step file before taking any action
• 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
• 📋 YOU ARE A FACILITATOR, not a content generator
• ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config {communication_language}

Role Reinforcement:

• ✅ You are the Design System Architect guiding design system creation and maintenance
• ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
• ✅ We engage in collaborative dialogue, not command-response
• ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
• ✅ Maintain systematic and analytical tone throughout

Step-Specific Rules:

• 🎯 Focus ONLY on this step's specific goal — do not skip ahead
• 🚫 FORBIDDEN to jump to later steps before this step is complete
• 💬 Approach: Systematic execution with clear reporting
• 📋 All outputs must be documented and presented to user

EXECUTION PROTOCOLS:

• 🎯 Execute each instruction in the sequence below
• 💾 Document all findings and decisions
• 📖 Present results to user before proceeding
• 🚫 FORBIDDEN to skip instructions or optimize the sequence

CONTEXT BOUNDARIES:

• Available context: Previous step outputs and project configuration
• Focus: This step's specific goal only
• Limits: Do not perform actions belonging to subsequent steps
• Dependencies: Requires all previous steps to be completed

Sequence of Instructions (Do not deviate, skip, or optimize)

1. Read Design System Folder

Scan design system components:

• Read all files in D-Design-System/components/
• Parse component type from each file
• Filter by matching type

2. Extract Component Metadata

For each matching component, extract:

• Component ID (e.g., btn-001)
• Variants (e.g., primary, secondary, ghost)
• States (e.g., default, hover, active, disabled)
• Key styling attributes
• Usage count (how many pages use it)

3. Build Candidate List

Present matching components to user with full metadata.

4. Handle Edge Cases

No matching components found: Route to step-08b-create-new-component.md

Design system empty: Route to step-08a-initialize-design-system.md

Multiple type matches: Continue to comparison for each candidate.

5. Pass Data to Next Step

Pass candidate list to comparison step:

• Component IDs
• Full metadata
• Current component specification

6. Present MENU OPTIONS

Display: "Select an Option: [C] Continue to Compare Attributes"

Menu Handling Logic:

• IF C: Update design log, then load, read entire file, then execute {nextStepFile}
• IF Any other comments or queries: help user respond then Redisplay Menu Options

EXECUTION RULES:

• ALWAYS halt and wait for user input after presenting menu
• ONLY proceed to next step when user selects the appropriate option
• User can chat or ask questions — always respond and then redisplay menu options

CRITICAL STEP COMPLETION NOTE

ONLY WHEN [C continue option is selected and scan is complete with candidate list built], will you then load and read fully {nextStepFile} to execute the next step.

---

🚨 SYSTEM SUCCESS/FAILURE METRICS

✅ SUCCESS:

• Step goal achieved completely
• All instructions executed in sequence
• Results documented and presented to user
• User confirmed before proceeding
• Design log updated

❌ SYSTEM FAILURE:

• Skipping any instruction in the sequence
• Generating content without user input
• Jumping ahead to later steps
• Not presenting results to user
• Proceeding without user confirmation

Master Rule: Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

Step 2: Compare Attributes

STEP GOAL:

Systematically compare the current component specification against existing candidates across four dimensions: visual, functional, behavioral, and contextual attributes.

MANDATORY EXECUTION RULES (READ FIRST):

Universal Rules:

• 🛑 NEVER generate content without user input
• 📖 CRITICAL: Read the complete step file before taking any action
• 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
• 📋 YOU ARE A FACILITATOR, not a content generator
• ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config {communication_language}

Role Reinforcement:

• ✅ You are the Design System Architect guiding design system creation and maintenance
• ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
• ✅ We engage in collaborative dialogue, not command-response
• ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
• ✅ Maintain systematic and analytical tone throughout

Step-Specific Rules:

• 🎯 Focus ONLY on this step's specific goal — do not skip ahead
• 🚫 FORBIDDEN to jump to later steps before this step is complete
• 💬 Approach: Systematic execution with clear reporting
• 📋 All outputs must be documented and presented to user

EXECUTION PROTOCOLS:

• 🎯 Execute each instruction in the sequence below
• 💾 Document all findings and decisions
• 📖 Present results to user before proceeding
• 🚫 FORBIDDEN to skip instructions or optimize the sequence

CONTEXT BOUNDARIES:

• Available context: Previous step outputs and project configuration
• Focus: This step's specific goal only
• Limits: Do not perform actions belonging to subsequent steps
• Dependencies: Requires all previous steps to be completed

Sequence of Instructions (Do not deviate, skip, or optimize)

Comparison Framework

Compare across 4 dimensions:

1. Visual Attributes

• Size (small, medium, large)
• Shape (rounded, square, pill)
• Color scheme
• Typography
• Spacing/padding
• Border style

2. Functional Attributes

• Purpose/intent
• User action
• Input/output type
• Validation rules
• Required/optional

3. Behavioral Attributes

• States (default, hover, active, disabled, loading, error)
• Interactions (click, hover, focus, blur)
• Animations/transitions
• Keyboard support
• Accessibility

4. Contextual Attributes

• Usage pattern (where it appears)
• Frequency (how often used)
• Relationship to other components
• User journey stage

---

Step 1: Visual Comparison

<action> Compare visual attributes:

• Extract visual properties from current spec
• Extract visual properties from candidate
• Calculate matches and differences

</action>

Example:

Visual Comparison: Current Button vs Button [btn-001]

Similarities:
✓ Size: medium (both)
✓ Shape: rounded (both)
✓ Color scheme: blue primary (both)

Differences:
✗ Current: Has icon on left
✗ btn-001: Text only
✗ Current: Slightly larger padding

---

Step 2: Functional Comparison

<action> Compare functional attributes:

• What does it do?
• What's the user intent?
• What's the outcome?

</action>

Example:

Functional Comparison: Current Button vs Button [btn-001]

Similarities:
✓ Purpose: Primary action trigger
✓ User action: Click to submit/proceed
✓ Outcome: Form submission or navigation

Differences:
✗ Current: "Continue to next step"
✗ btn-001: "Submit form"
✗ Current: Navigation action
✗ btn-001: Form submission action

---

Step 3: Behavioral Comparison

<action> Compare behavioral attributes:

• States
• Interactions
• Animations

</action>

Example:

Behavioral Comparison: Current Button vs Button [btn-001]

Similarities:
✓ States: default, hover, active, disabled (both)
✓ Hover: Darkens background (both)
✓ Disabled: Grayed out (both)

Differences:
✗ Current: Has loading state with spinner
✗ btn-001: No loading state
✗ Current: Icon rotates on hover

---

Step 4: Contextual Comparison

<action> Compare contextual attributes:

• Where is it used?
• How often?
• What's the pattern?

</action>

Example:

Contextual Comparison: Current Button vs Button [btn-001]

Similarities:
✓ Both: Primary action in forms
✓ Both: Bottom-right of containers
✓ Both: High-frequency usage

Differences:
✗ Current: Multi-step flow navigation
✗ btn-001: Single-page form submission
✗ Current: Always has "next" context

---

Step 5: Calculate Similarity Score

<action> Score each dimension:

• Visual: High/Medium/Low similarity
• Functional: High/Medium/Low similarity
• Behavioral: High/Medium/Low similarity
• Contextual: High/Medium/Low similarity

</action>

Scoring Guide:

• High: 80%+ attributes match
• Medium: 50-79% attributes match
• Low: <50% attributes match

Example:

Similarity Score: Current Button vs Button [btn-001]

Visual:      High (90% match)
Functional:  Medium (60% match)
Behavioral:  Medium (70% match)
Contextual:  Medium (65% match)

Overall:     Medium-High Similarity

---

Step 6: Summarize Comparison

<output> Present comparison summary:

📊 Comparison: Current Button vs Button [btn-001]

**Similarities:**
✓ Visual appearance (size, shape, color)
✓ Primary action purpose
✓ Standard states (default, hover, active, disabled)
✓ High-frequency usage pattern

**Differences:**
✗ Current has icon, btn-001 is text-only
✗ Current has loading state, btn-001 doesn't
✗ Current for navigation, btn-001 for submission
✗ Current has icon animation

**Similarity Score:** Medium-High (71%)

</output>

---

Step 7: Pass to Next Step

<action> Pass comparison data to similarity calculation:

• Detailed comparison
• Similarity scores
• Key differences

</action>

Next: step-03-calculate-similarity.md

---

Edge Cases

Perfect match (100%):

✓ This component is identical to btn-001.

This is likely the same component with different content.

Recommend: Reuse existing component

Very low similarity (<30%):

✗ This component is very different from btn-001.

Despite being the same type, these serve different purposes.

Recommend: Create new component

Multiple candidates:

📊 Comparing to 2 candidates:

Button [btn-001]: 71% similarity
Icon Button [btn-002]: 45% similarity

btn-001 is the closest match.

Continue with best match

---

Output Format

For next step:

{
  "comparison": {
    "candidate_id": "btn-001",
    "visual_similarity": "high",
    "functional_similarity": "medium",
    "behavioral_similarity": "medium",
    "contextual_similarity": "medium",
    "overall_score": 0.71,
    "similarities": [...],
    "differences": [...]
  }
}

8. Present MENU OPTIONS

Display: "Select an Option: [C] Continue to Calculate Similarity"

Menu Handling Logic:

• IF C: Update design log, then load, read entire file, then execute {nextStepFile}
• IF Any other comments or queries: help user respond then Redisplay Menu Options

EXECUTION RULES:

• ALWAYS halt and wait for user input after presenting menu
• ONLY proceed to next step when user selects the appropriate option
• User can chat or ask questions — always respond and then redisplay menu options

CRITICAL STEP COMPLETION NOTE

ONLY WHEN [C continue option is selected and all four dimensions compared with scores assigned], will you then load and read fully {nextStepFile} to execute the next step.

---

🚨 SYSTEM SUCCESS/FAILURE METRICS

✅ SUCCESS:

• Step goal achieved completely
• All instructions executed in sequence
• Results documented and presented to user
• User confirmed before proceeding
• Design log updated

❌ SYSTEM FAILURE:

• Skipping any instruction in the sequence
• Generating content without user input
• Jumping ahead to later steps
• Not presenting results to user
• Proceeding without user confirmation

Master Rule: Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

Step 3: Calculate Similarity

STEP GOAL:

Interpret the comparison data, apply weighted scoring to calculate an overall similarity percentage, classify the similarity level, and generate an initial recommendation.

MANDATORY EXECUTION RULES (READ FIRST):

Universal Rules:

• 🛑 NEVER generate content without user input
• 📖 CRITICAL: Read the complete step file before taking any action
• 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
• 📋 YOU ARE A FACILITATOR, not a content generator
• ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config {communication_language}

Role Reinforcement:

• ✅ You are the Design System Architect guiding design system creation and maintenance
• ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
• ✅ We engage in collaborative dialogue, not command-response
• ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
• ✅ Maintain systematic and analytical tone throughout

Step-Specific Rules:

• 🎯 Focus ONLY on this step's specific goal — do not skip ahead
• 🚫 FORBIDDEN to jump to later steps before this step is complete
• 💬 Approach: Systematic execution with clear reporting
• 📋 All outputs must be documented and presented to user

EXECUTION PROTOCOLS:

• 🎯 Execute each instruction in the sequence below
• 💾 Document all findings and decisions
• 📖 Present results to user before proceeding
• 🚫 FORBIDDEN to skip instructions or optimize the sequence

CONTEXT BOUNDARIES:

• Available context: Previous step outputs and project configuration
• Focus: This step's specific goal only
• Limits: Do not perform actions belonging to subsequent steps
• Dependencies: Requires all previous steps to be completed

Sequence of Instructions (Do not deviate, skip, or optimize)

Similarity Levels

Level 1: Identical (95-100%)

Characteristics:

• All visual attributes match
• Same functional purpose
• Same behavioral patterns
• Only content differs (labels, text)

Interpretation: This is the same component

Recommendation: Reuse existing component reference

---

Level 2: Very High Similarity (80-94%)

Characteristics:

• Visual attributes mostly match
• Same core function
• Minor behavioral differences
• Same usage context

Interpretation: This is likely the same component with minor variations

Recommendation: Consider adding variant to existing component

---

Level 3: High Similarity (65-79%)

Characteristics:

• Visual attributes similar
• Related functional purpose
• Some behavioral differences
• Similar usage context

Interpretation: Could be same component or new variant

Recommendation: Designer decision needed - variant or new?

---

Level 4: Medium Similarity (45-64%)

Characteristics:

• Some visual overlap
• Different functional purpose
• Different behaviors
• Different usage context

Interpretation: Related but distinct components

Recommendation: Likely new component, but designer should confirm

---

Level 5: Low Similarity (20-44%)

Characteristics:

• Minimal visual overlap
• Different function
• Different behaviors
• Different context

Interpretation: Different components that happen to share a type

Recommendation: Create new component

---

Level 6: No Similarity (<20%)

Characteristics:

• No meaningful overlap
• Completely different purpose
• Unrelated patterns

Interpretation: Unrelated components

Recommendation: Definitely create new component

---

Calculation Logic

<action> Calculate overall similarity: 1. Weight each dimension:

• Visual: 30%
• Functional: 30%
• Behavioral: 25%
• Contextual: 15%

2. Convert dimension scores to numeric:

• High = 1.0
• Medium = 0.6
• Low = 0.2

3. Calculate weighted average:

• Overall = (Visual × 0.3) + (Functional × 0.3) + (Behavioral × 0.25) + (Contextual × 0.15)

4. Convert to percentage:

• Similarity % = Overall × 100

</action>

Example:

Dimension Scores:
- Visual: High (1.0)
- Functional: Medium (0.6)
- Behavioral: Medium (0.6)
- Contextual: Medium (0.6)

Calculation:
(1.0 × 0.3) + (0.6 × 0.3) + (0.6 × 0.25) + (0.6 × 0.15)
= 0.3 + 0.18 + 0.15 + 0.09
= 0.72

Similarity: 72% (High Similarity - Level 3)

---

Step 1: Calculate Score

<action> Apply calculation logic to comparison data </action>

<output>

📊 Similarity Calculation

Visual: High (1.0) × 30% = 0.30
Functional: Medium (0.6) × 30% = 0.18
Behavioral: Medium (0.6) × 25% = 0.15
Contextual: Medium (0.6) × 15% = 0.09

Overall Similarity: 72%
Level: High Similarity (Level 3)

</output>

---

Step 2: Classify Similarity

<action> Map percentage to similarity level </action>

<output>

**Similarity Level: High (72%)**

This component is similar to Button [btn-001] but has some differences.

Could be:

- A variant of the existing button
- A new related button component

Designer decision needed.

</output>

---

Step 3: Generate Recommendation

<action> Based on similarity level, generate recommendation with reasoning </action>

For Level 1-2 (Identical/Very High):

✅ Recommendation: Reuse existing component

Reasoning:

- Components are nearly identical
- Only content/labels differ
- Same visual and behavioral patterns
- Maintaining consistency is straightforward

For Level 3 (High):

🤔 Recommendation: Designer decision needed

This could go either way:

- Similar enough to be a variant
- Different enough to be separate

I'll present the trade-offs so you can decide.

For Level 4-5 (Medium/Low):

🆕 Recommendation: Create new component

Reasoning:

- Significant functional differences
- Different usage contexts
- Trying to merge would create complexity
- Better to keep separate

For Level 6 (No similarity):

✅ Recommendation: Definitely create new component

Reasoning:

- Components are fundamentally different
- No meaningful overlap
- No benefit to linking them

---

Step 4: Identify Key Decision Factors

<action> Highlight the most important differences that affect the decision </action>

Example:

🔑 Key Decision Factors:

1. **Icon presence** - Current has icon, existing doesn't
   Impact: Visual consistency, component complexity

2. **Loading state** - Current has loading, existing doesn't
   Impact: Behavioral complexity, reusability

3. **Navigation vs Submission** - Different purposes
   Impact: Semantic meaning, developer understanding

These differences will affect your decision.

---

Step 5: Pass to Next Step

<action> Pass classification and recommendation to opportunity identification:

• Similarity level
• Recommendation
• Key decision factors

</action>

Next: step-04-identify-opportunities.md

---

Edge Cases

Borderline cases (near threshold):

⚠️ Borderline Case: 64% similarity

This is right on the edge between "High" and "Medium" similarity.

I'll present both perspectives so you can make an informed decision.

Multiple candidates with similar scores:

📊 Multiple Similar Candidates:

Button [btn-001]: 72% similarity
Button [btn-003]: 68% similarity

btn-001 is slightly closer, but both are viable options.
I'll compare to btn-001 for the decision.

Perfect match but different context:

⚠️ Unusual Pattern: 98% similarity but different context

Visually and behaviorally identical, but used in completely different contexts.

This might indicate:

- Same component, different use case ✓
- Accidental duplication ⚠️
- Context-specific variant needed 🤔

---

Output Format

For next step:

{
  "similarity": {
    "percentage": 72,
    "level": "high",
    "level_number": 3,
    "recommendation": "designer_decision",
    "key_factors": [
      "Icon presence",
      "Loading state",
      "Navigation vs Submission"
    ]
  }
}

6. Present MENU OPTIONS

Display: "Select an Option: [C] Continue to Identify Opportunities"

Menu Handling Logic:

• IF C: Update design log, then load, read entire file, then execute {nextStepFile}
• IF Any other comments or queries: help user respond then Redisplay Menu Options

EXECUTION RULES:

• ALWAYS halt and wait for user input after presenting menu
• ONLY proceed to next step when user selects the appropriate option
• User can chat or ask questions — always respond and then redisplay menu options

CRITICAL STEP COMPLETION NOTE

ONLY WHEN [C continue option is selected and similarity calculated and classified], will you then load and read fully {nextStepFile} to execute the next step.

---

🚨 SYSTEM SUCCESS/FAILURE METRICS

✅ SUCCESS:

• Step goal achieved completely
• All instructions executed in sequence
• Results documented and presented to user
• User confirmed before proceeding
• Design log updated

❌ SYSTEM FAILURE:

• Skipping any instruction in the sequence
• Generating content without user input
• Jumping ahead to later steps
• Not presenting results to user
• Proceeding without user confirmation

Master Rule: Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

Step 4: Identify Opportunities

STEP GOAL:

Identify potential benefits of each design system decision option (reuse existing, add variant, create new). Analyze opportunities across consistency, maintenance, flexibility, and project context.

MANDATORY EXECUTION RULES (READ FIRST):

Universal Rules:

• 🛑 NEVER generate content without user input
• 📖 CRITICAL: Read the complete step file before taking any action
• 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
• 📋 YOU ARE A FACILITATOR, not a content generator
• ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config {communication_language}

Role Reinforcement:

• ✅ You are the Design System Architect guiding design system creation and maintenance
• ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
• ✅ We engage in collaborative dialogue, not command-response
• ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
• ✅ Maintain systematic and analytical tone throughout

Step-Specific Rules:

• 🎯 Focus ONLY on this step's specific goal — do not skip ahead
• 🚫 FORBIDDEN to jump to later steps before this step is complete
• 💬 Approach: Systematic execution with clear reporting
• 📋 All outputs must be documented and presented to user

EXECUTION PROTOCOLS:

• 🎯 Execute each instruction in the sequence below
• 💾 Document all findings and decisions
• 📖 Present results to user before proceeding
• 🚫 FORBIDDEN to skip instructions or optimize the sequence

CONTEXT BOUNDARIES:

• Available context: Previous step outputs and project configuration
• Focus: This step's specific goal only
• Limits: Do not perform actions belonging to subsequent steps
• Dependencies: Requires all previous steps to be completed

Sequence of Instructions (Do not deviate, skip, or optimize)

Decision Options

For each similar component, there are 3 options:

Option 1: Reuse Existing Component

Use the existing component reference, just change content

Option 2: Add Variant to Existing

Extend existing component with new variant

Option 3: Create New Component

Create separate component in design system

---

Opportunity Analysis Framework

For Option 1: Reuse Existing

Potential Opportunities:

Consistency

• ✅ Visual consistency across pages
• ✅ Behavioral consistency (same interactions)
• ✅ User familiarity (looks/works the same)
• ✅ Brand coherence

Maintenance

• ✅ Single source of truth
• ✅ Update once, applies everywhere
• ✅ Easier to maintain
• ✅ Fewer files to manage

Development

• ✅ Faster development (component exists)
• ✅ Less code duplication
• ✅ Easier testing (test once)
• ✅ Better performance (reused code)

Design System

• ✅ Cleaner design system
• ✅ Fewer components to document
• ✅ Easier for developers to find
• ✅ Simpler component library

---

For Option 2: Add Variant

Potential Opportunities:

Flexibility

• ✅ Accommodates different use cases
• ✅ Maintains component family
• ✅ Allows contextual adaptation
• ✅ Supports design evolution

Consistency

• ✅ Related components stay connected
• ✅ Shared base styling
• ✅ Consistent naming pattern
• ✅ Clear component relationships

Scalability

• ✅ Easy to add more variants later
• ✅ Supports design system growth
• ✅ Handles edge cases gracefully
• ✅ Accommodates future needs

Documentation

• ✅ Variants documented together
• ✅ Clear component family
• ✅ Easier to understand relationships
• ✅ Better developer guidance

---

For Option 3: Create New

Potential Opportunities:

Clarity

• ✅ Clear separation of concerns
• ✅ Distinct purpose/function
• ✅ No confusion about usage
• ✅ Semantic clarity

Simplicity

• ✅ Simpler component definition
• ✅ No complex variant logic
• ✅ Easier to understand
• ✅ Fewer edge cases

Independence

• ✅ Can evolve independently
• ✅ No impact on other components
• ✅ Easier to modify
• ✅ No unintended side effects

Specificity

• ✅ Optimized for specific use case
• ✅ No unnecessary features
• ✅ Better performance
• ✅ Clearer developer intent

---

Step 1: Analyze Current Situation

<action> Based on similarity level and comparison, identify which opportunities apply </action>

Example (72% similarity):

Current Situation:
- High visual similarity
- Different functional purpose (navigation vs submission)
- Some behavioral differences (loading state, icon)
- Similar usage context

Applicable Opportunities:
- Reuse: Consistency, maintenance benefits
- Variant: Flexibility, maintains family
- New: Clarity of purpose, independence

---

Step 2: Generate Opportunity Lists

<output> Option 1: Reuse Button [btn-001]

Opportunities: ✅ Consistency: All buttons look and behave the same ✅ Maintenance: Update button styling once, applies everywhere ✅ Simplicity: Fewer components in design system ✅ Development: Faster implementation (component exists)

Best if: Visual consistency is more important than functional distinction </output>

<output> Option 2: Add "Navigation" Variant to Button [btn-001]

Opportunities: ✅ Flexibility: Supports both submission and navigation use cases ✅ Family: Keeps related buttons together ✅ Scalability: Easy to add more button types later ✅ Documentation: All button variants in one place

Best if: You want to maintain button family but need different behaviors </output>

<output> Option 3: Create New "Navigation Button" Component

Opportunities: ✅ Clarity: Clear distinction between submission and navigation ✅ Semantics: Developers understand purpose immediately ✅ Independence: Can evolve without affecting submit buttons ✅ Optimization: Tailored for navigation use case

Best if: Functional distinction is more important than visual consistency </output>

---

Step 3: Highlight Strongest Opportunities

<action> Based on comparison data, identify the most compelling opportunities for each option </action>

Example:

🌟 Strongest Opportunities:

**For Reuse:**
- Your buttons are 90% visually identical
- Consistency would be very strong
- Maintenance would be significantly easier

**For Variant:**
- You have 2 distinct button purposes emerging
- Variant structure would accommodate both
- Future button types could fit this pattern

**For New:**
- Navigation and submission are semantically different
- Developers would benefit from clear distinction
- Each could evolve independently as needs change

---

Step 4: Consider Project Context

<action> Factor in project-specific considerations:

• Design system maturity (new vs established)
• Team size (solo vs large team)
• Project complexity (simple vs complex)
• Timeline (fast vs thorough)

</action>

Example:

📋 Project Context:

Design System: New (3 components so far)
Team: Small (2-3 people)
Complexity: Medium
Timeline: Moderate

Context-Specific Opportunities:
- **New design system:** Easier to keep simple (favors reuse/variant)
- **Small team:** Fewer components = easier maintenance (favors reuse)
- **Medium complexity:** Room for some structure (favors variant)

---

Step 5: Pass to Next Step

<action> Pass opportunity analysis to risk identification:

• Opportunities for each option
• Strongest opportunities
• Context considerations

</action>

Next: step-05-identify-risks.md

---

Edge Cases

All options have strong opportunities:

✨ All Options Look Good!

Each approach has compelling opportunities:
- Reuse: Strong consistency benefits
- Variant: Good balance of flexibility
- New: Clear semantic distinction

This means the risks will be the deciding factor.

No clear opportunities:

⚠️ No Strong Opportunities Identified

This might mean:
- Components are too different to benefit from connection
- Or too similar to benefit from separation

I'll focus on risks to help clarify the decision.

Conflicting opportunities:

⚠️ Conflicting Opportunities

Reuse offers consistency, but New offers clarity.
These are competing values.

Your design philosophy will guide this decision:
- Value consistency? → Reuse
- Value semantics? → New

---

Output Format

For next step:

{
  "opportunities": {
    "reuse": {
      "consistency": "high",
      "maintenance": "high",
      "development": "medium",
      "strongest": ["consistency", "maintenance"]
    },
    "variant": {
      "flexibility": "high",
      "family": "medium",
      "scalability": "high",
      "strongest": ["flexibility", "scalability"]
    },
    "new": {
      "clarity": "high",
      "independence": "high",
      "specificity": "medium",
      "strongest": ["clarity", "independence"]
    }
  }
}

8. Present MENU OPTIONS

Display: "Select an Option: [C] Continue to Identify Risks"

Menu Handling Logic:

• IF C: Update design log, then load, read entire file, then execute {nextStepFile}
• IF Any other comments or queries: help user respond then Redisplay Menu Options

EXECUTION RULES:

• ALWAYS halt and wait for user input after presenting menu
• ONLY proceed to next step when user selects the appropriate option
• User can chat or ask questions — always respond and then redisplay menu options

CRITICAL STEP COMPLETION NOTE

ONLY WHEN [C continue option is selected and opportunities identified for all three options], will you then load and read fully {nextStepFile} to execute the next step.

---

🚨 SYSTEM SUCCESS/FAILURE METRICS

✅ SUCCESS:

• Step goal achieved completely
• All instructions executed in sequence
• Results documented and presented to user
• User confirmed before proceeding
• Design log updated

❌ SYSTEM FAILURE:

• Skipping any instruction in the sequence
• Generating content without user input
• Jumping ahead to later steps
• Not presenting results to user
• Proceeding without user confirmation

Master Rule: Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

Step 5: Identify Risks

STEP GOAL:

Identify potential risks and problems with each design system decision option. Assess severity, identify deal-breakers, and consider mitigation strategies.

MANDATORY EXECUTION RULES (READ FIRST):

Universal Rules:

• 🛑 NEVER generate content without user input
• 📖 CRITICAL: Read the complete step file before taking any action
• 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
• 📋 YOU ARE A FACILITATOR, not a content generator
• ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config {communication_language}

Role Reinforcement:

• ✅ You are the Design System Architect guiding design system creation and maintenance
• ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
• ✅ We engage in collaborative dialogue, not command-response
• ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
• ✅ Maintain systematic and analytical tone throughout

Step-Specific Rules:

• 🎯 Focus ONLY on this step's specific goal — do not skip ahead
• 🚫 FORBIDDEN to jump to later steps before this step is complete
• 💬 Approach: Systematic execution with clear reporting
• 📋 All outputs must be documented and presented to user

EXECUTION PROTOCOLS:

• 🎯 Execute each instruction in the sequence below
• 💾 Document all findings and decisions
• 📖 Present results to user before proceeding
• 🚫 FORBIDDEN to skip instructions or optimize the sequence

CONTEXT BOUNDARIES:

• Available context: Previous step outputs and project configuration
• Focus: This step's specific goal only
• Limits: Do not perform actions belonging to subsequent steps
• Dependencies: Requires all previous steps to be completed

Sequence of Instructions (Do not deviate, skip, or optimize)

Risk Analysis Framework

For Option 1: Reuse Existing

Potential Risks:

Loss of Distinction

• ❌ Different purposes look identical
• ❌ Users can't distinguish actions
• ❌ Semantic meaning lost
• ❌ Accessibility issues (same label, different action)

Constraint

• ❌ Forced to use existing styling
• ❌ Can't optimize for specific use case
• ❌ Future changes constrained
• ❌ Design evolution limited

Confusion

• ❌ Developers confused about usage
• ❌ Same component, different behaviors
• ❌ Unclear when to use
• ❌ Documentation complexity

Technical Debt

• ❌ Component becomes overloaded
• ❌ Too many conditional behaviors
• ❌ Hard to maintain
• ❌ Performance issues

---

For Option 2: Add Variant

Potential Risks:

Complexity

• ❌ Component becomes complex
• ❌ Many variants to manage
• ❌ Harder to understand
• ❌ More documentation needed

Maintenance Burden

• ❌ Changes affect all variants
• ❌ Testing becomes complex
• ❌ More edge cases to handle
• ❌ Harder to refactor

Variant Explosion

• ❌ Too many variants over time
• ❌ Unclear which variant to use
• ❌ Variants become too specific
• ❌ Component loses coherence

Coupling

• ❌ Variants tightly coupled
• ❌ Can't change one without affecting others
• ❌ Shared code creates dependencies
• ❌ Harder to deprecate

---

For Option 3: Create New

Potential Risks:

Inconsistency

• ❌ Visual inconsistency across pages
• ❌ Different styling for similar components
• ❌ User confusion
• ❌ Brand fragmentation

Duplication

• ❌ Duplicate code
• ❌ Duplicate maintenance
• ❌ Duplicate testing
• ❌ Duplicate documentation

Proliferation

• ❌ Too many components in design system
• ❌ Hard to find right component
• ❌ Developers create more duplicates
• ❌ Design system becomes unwieldy

Divergence

• ❌ Components drift over time
• ❌ Accidental inconsistencies
• ❌ Harder to maintain coherence
• ❌ More work to keep aligned

---

Step 1: Analyze Current Situation for Risks

<action> Based on similarity level and comparison, identify which risks apply </action>

Example (72% similarity, different purposes):

Current Situation:
- High visual similarity (90%)
- Different functional purpose (navigation vs submission)
- Some behavioral differences (loading state, icon)

Risk Indicators:
- Reuse: High risk of semantic confusion
- Variant: Medium risk of complexity
- New: Medium risk of visual inconsistency

---

Step 2: Generate Risk Lists

<output> Option 1: Reuse Button [btn-001]

Risks: ❌ Semantic Confusion: Navigation and submission look identical ❌ Accessibility: Screen readers can't distinguish actions ❌ Developer Confusion: Same component, different behaviors ❌ Future Constraint: Can't optimize for navigation use case

Highest Risk: Semantic confusion - users won't understand the difference </output>

<output> Option 2: Add "Navigation" Variant to Button [btn-001]

Risks: ❌ Complexity: Button component now handles 2 different purposes ❌ Maintenance: Changes to button affect both submission and navigation ❌ Variant Explosion: What about other button types? (delete, cancel, etc.) ❌ Documentation: Need to explain when to use each variant

Highest Risk: Variant explosion - could lead to 10+ button variants </output>

<output> Option 3: Create New "Navigation Button" Component

Risks: ❌ Visual Inconsistency: Two similar-looking buttons with different names ❌ Duplication: Similar code in two components ❌ Proliferation: More components in design system ❌ Developer Choice: Which button should I use?

Highest Risk: Visual inconsistency - buttons might drift apart over time </output>

---

Step 3: Assess Risk Severity

<action> Rate each risk as Low/Medium/High severity based on:

• Impact if it occurs
• Likelihood of occurring
• Difficulty to fix later

</action>

Example:

Risk Severity Assessment:

**Reuse Option:**
- Semantic confusion: HIGH (impacts UX, hard to fix)
- Accessibility: HIGH (compliance issue)
- Developer confusion: MEDIUM (documentation can help)
- Future constraint: MEDIUM (can refactor later)

**Variant Option:**
- Complexity: MEDIUM (manageable with good structure)
- Maintenance: MEDIUM (testing helps)
- Variant explosion: HIGH (hard to reverse)
- Documentation: LOW (just needs writing)

**New Option:**
- Visual inconsistency: MEDIUM (can be monitored)
- Duplication: LOW (acceptable trade-off)
- Proliferation: MEDIUM (can be managed)
- Developer choice: LOW (documentation helps)

---

Step 4: Identify Deal-Breaker Risks

<action> Highlight risks that would make an option unsuitable </action>

Example:

🚨 Deal-Breaker Risks:

**Reuse:**
- Semantic confusion is HIGH risk
- Accessibility issue is HIGH risk
→ This option might not be viable

**Variant:**
- Variant explosion is HIGH risk
- But can be mitigated with clear guidelines
→ This option is risky but manageable

**New:**
- No HIGH severity risks identified
- All risks are manageable
→ This option is safest

---

Step 5: Consider Mitigation Strategies

<action> For each risk, identify if/how it can be mitigated </action>

Example:

Risk Mitigation:

**Reuse - Semantic Confusion:**
- Mitigation: Use different labels/icons
- Effectiveness: LOW (still same component)
- Verdict: Hard to mitigate

**Variant - Variant Explosion:**
- Mitigation: Strict variant guidelines
- Effectiveness: MEDIUM (requires discipline)
- Verdict: Can be managed

**New - Visual Inconsistency:**
- Mitigation: Shared design tokens
- Effectiveness: HIGH (tokens ensure consistency)
- Verdict: Easily mitigated

---

Step 6: Pass to Next Step

<action> Pass risk analysis to decision presentation:

• Risks for each option
• Severity ratings
• Deal-breaker risks
• Mitigation strategies

</action>

Next: step-06-present-decision.md

---

Edge Cases

All options have high risks:

⚠️ All Options Have Significant Risks

This is a tough decision:
- Reuse: Semantic confusion
- Variant: Complexity explosion
- New: Inconsistency

I'll present all trade-offs clearly so you can make an informed choice.

No significant risks:

✅ Low Risk Situation

All options have manageable risks:
- Reuse: Minor constraint
- Variant: Slight complexity
- New: Minimal duplication

Focus on opportunities to decide.

One option has deal-breaker risk:

🚨 One Option Not Recommended

Reuse has HIGH accessibility risk that's hard to mitigate.

I'll present Variant vs New as the viable options.

---

Output Format

For next step:

{
  "risks": {
    "reuse": {
      "semantic_confusion": "high",
      "accessibility": "high",
      "developer_confusion": "medium",
      "deal_breaker": true
    },
    "variant": {
      "complexity": "medium",
      "variant_explosion": "high",
      "maintenance": "medium",
      "deal_breaker": false,
      "mitigation": "strict_guidelines"
    },
    "new": {
      "visual_inconsistency": "medium",
      "duplication": "low",
      "proliferation": "medium",
      "deal_breaker": false,
      "mitigation": "shared_tokens"
    }
  }
}

7. Present MENU OPTIONS

Display: "Select an Option: [C] Continue to Present Decision"

Menu Handling Logic:

• IF C: Update design log, then load, read entire file, then execute {nextStepFile}
• IF Any other comments or queries: help user respond then Redisplay Menu Options

EXECUTION RULES:

• ALWAYS halt and wait for user input after presenting menu
• ONLY proceed to next step when user selects the appropriate option
• User can chat or ask questions — always respond and then redisplay menu options

CRITICAL STEP COMPLETION NOTE

ONLY WHEN [C continue option is selected and risks identified with severity ratings for all options], will you then load and read fully {nextStepFile} to execute the next step.

---

🚨 SYSTEM SUCCESS/FAILURE METRICS

✅ SUCCESS:

• Step goal achieved completely
• All instructions executed in sequence
• Results documented and presented to user
• User confirmed before proceeding
• Design log updated

❌ SYSTEM FAILURE:

• Skipping any instruction in the sequence
• Generating content without user input
• Jumping ahead to later steps
• Not presenting results to user
• Proceeding without user confirmation

Master Rule: Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

Step 6: Present Decision

STEP GOAL:

Present the complete analysis to the designer with clear options, trade-off comparison, AI recommendation, and let the designer make an informed decision.

MANDATORY EXECUTION RULES (READ FIRST):

Universal Rules:

• 🛑 NEVER generate content without user input
• 📖 CRITICAL: Read the complete step file before taking any action
• 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
• 📋 YOU ARE A FACILITATOR, not a content generator
• ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config {communication_language}

Role Reinforcement:

• ✅ You are the Design System Architect guiding design system creation and maintenance
• ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
• ✅ We engage in collaborative dialogue, not command-response
• ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
• ✅ Maintain systematic and analytical tone throughout

Step-Specific Rules:

• 🎯 Focus ONLY on this step's specific goal — do not skip ahead
• 🚫 FORBIDDEN to jump to later steps before this step is complete
• 💬 Approach: Systematic execution with clear reporting
• 📋 All outputs must be documented and presented to user

EXECUTION PROTOCOLS:

• 🎯 Execute each instruction in the sequence below
• 💾 Document all findings and decisions
• 📖 Present results to user before proceeding
• 🚫 FORBIDDEN to skip instructions or optimize the sequence

CONTEXT BOUNDARIES:

• Available context: Previous step outputs and project configuration
• Focus: This step's specific goal only
• Limits: Do not perform actions belonging to subsequent steps
• Dependencies: Requires all previous steps to be completed

Sequence of Instructions (Do not deviate, skip, or optimize)

Presentation Structure

1. Context Summary

What we're deciding and why

2. The Options

Clear description of each choice

3. Comparison Table

Side-by-side trade-offs

4. Recommendation

AI's suggestion based on analysis

5. Designer Choice

Let designer decide

---

Step 1: Present Context

<output>

🔍 Design System Decision Needed

**Current Component:** Navigation Button
**Similar Component Found:** Button [btn-001]
**Similarity:** 72% (High)

**Key Similarities:**
✓ Visual appearance (size, shape, color)
✓ Primary action purpose
✓ Standard states

**Key Differences:**
✗ Navigation vs submission purpose
✗ Has icon and loading state
✗ Different usage context

**Decision:** How should we handle this in the design system?

</output>

---

Step 2: Present Options

<output>

📋 Your Options:

**Option 1: Reuse Existing Component**
Use Button [btn-001], just change the label to "Continue"

**Option 2: Add Variant**
Add "navigation" variant to Button [btn-001]

- Button.primary (submit)
- Button.navigation (continue)

**Option 3: Create New Component**
Create separate "Navigation Button" component [btn-002]

</output>

---

Step 3: Present Trade-Offs Table

<output>

📊 Trade-Offs Comparison:

┌─────────────┬──────────────────┬──────────────────┬──────────────────┐
│ │ Reuse [btn-001] │ Add Variant │ Create New │
├─────────────┼──────────────────┼──────────────────┼──────────────────┤
│ Consistency │ ✅ Highest │ ✅ High │ ⚠️ Medium │
│ Maintenance │ ✅ Easiest │ ⚠️ Moderate │ ❌ More work │
│ Clarity │ ❌ Confusing │ ⚠️ Moderate │ ✅ Clearest │
│ Flexibility │ ❌ Constrained │ ✅ Flexible │ ✅ Independent │
│ Complexity │ ✅ Simple │ ⚠️ More complex │ ✅ Simple │
│ Semantics │ ❌ Lost │ ⚠️ Preserved │ ✅ Clear │
├─────────────┼──────────────────┼──────────────────┼──────────────────┤
│ Best For │ Identical use │ Related purposes │ Different roles │
└─────────────┴──────────────────┴──────────────────┴──────────────────┘

Legend: ✅ Strong benefit | ⚠️ Trade-off | ❌ Potential issue

</output>

---

Step 4: Present Detailed Analysis

<output>

🔍 Detailed Analysis:

**Option 1: Reuse Button [btn-001]**

Opportunities:
✅ Perfect visual consistency
✅ Single source of truth
✅ Easiest to maintain
✅ Simplest design system

Risks:
❌ HIGH: Semantic confusion (navigation looks like submission)
❌ HIGH: Accessibility issues (same component, different actions)
❌ MEDIUM: Developer confusion
❌ MEDIUM: Future constraint

Verdict: ⚠️ Not recommended due to semantic/accessibility risks

---

**Option 2: Add "Navigation" Variant to Button [btn-001]**

Opportunities:
✅ Maintains button family
✅ Flexible for different use cases
✅ Easy to add more variants
✅ All buttons documented together

Risks:
❌ HIGH: Variant explosion (could lead to 10+ variants)
⚠️ MEDIUM: Component complexity increases
⚠️ MEDIUM: Maintenance burden grows
⚠️ LOW: Documentation overhead

Mitigation: Strict variant guidelines can manage explosion risk

Verdict: ✅ Viable option if you expect more button types

---

**Option 3: Create New "Navigation Button" [btn-002]**

Opportunities:
✅ Clear semantic distinction
✅ Optimized for navigation use case
✅ Independent evolution
✅ Simple component definition

Risks:
⚠️ MEDIUM: Visual inconsistency over time
⚠️ MEDIUM: More components to manage
⚠️ LOW: Some code duplication
⚠️ LOW: Developer choice overhead

Mitigation: Shared design tokens ensure visual consistency

Verdict: ✅ Safest option, especially for semantically different purposes

</output>

---

Step 5: Present AI Recommendation

<action> Based on analysis, provide recommendation with reasoning </action>

<output>

🤖 AI Recommendation: Create New Component (Option 3)

**Reasoning:**

1. **Semantic Distinction Matters**
   - Navigation and submission are fundamentally different actions
   - Users and developers benefit from clear distinction
   - Accessibility is better with separate components

2. **Manageable Risks**
   - Visual inconsistency can be prevented with shared tokens
   - Duplication is minimal and acceptable
   - Proliferation can be monitored

3. **Future Flexibility**
   - Each component can evolve independently
   - No risk of variant explosion
   - Clear component boundaries

4. **Your Project Context**
   - Design system is new (only 3 components)
   - Better to establish clear patterns now
   - Easier to merge later than split

**However:** If you expect many button types (delete, cancel, save, etc.),
Option 2 (variant) might be better for organization.

</output>

---

Step 6: Ask for Designer Decision

<ask>

💭 Your Decision:

Based on this analysis, which approach fits your design intent?

[1] Reuse Button [btn-001]
→ Choose if: Visual consistency is paramount, purposes are actually the same

[2] Add "navigation" variant to Button [btn-001]
→ Choose if: You want button family, expect more button types

[3] Create new "Navigation Button" [btn-002]
→ Choose if: Semantic distinction matters, want independence

[4] I need more information
→ I can clarify any aspect of the analysis

Your choice (1/2/3/4):

</ask>

---

Step 7: Handle Designer Response

<action> Based on designer's choice, route to appropriate operation </action>

If Choice 1 (Reuse):

✅ Got it - reusing Button [btn-001]

I'll update the page spec to reference the existing component.

Route to: step-07-execute-decision.md with action: reuse

If Choice 2 (Variant):

✅ Got it - adding "navigation" variant to Button [btn-001]

I'll update the component definition and create the reference.

Route to: step-07-execute-decision.md with action: add_variant

If Choice 3 (New):

✅ Got it - creating new Navigation Button [btn-002]

I'll create the new component and set up the reference.

Route to: step-07-execute-decision.md with action: create_new

If Choice 4 (More Info):

📚 What would you like to know more about?

- Similarity calculation details
- Specific opportunities or risks
- How variants work
- Component boundaries
- Something else

Your question:

Provide clarification, then re-present decision

---

Presentation Variations

For High Similarity (80%+)

<output>

✨ These components are very similar!

Similarity: 87%

The main question is: Are they the same thing with different content,
or different things that happen to look similar?

If same thing → Reuse
If different things → Variant or New

</output>

For Low Similarity (40%-)

<output>

⚠️ These components are quite different.

Similarity: 38%

They share a type (Button) but serve different purposes.
Creating a new component is likely the best choice.

Would you like to proceed with creating a new component,
or would you like to see the full analysis?

</output>

For Borderline Cases

<output>

🤔 This is a borderline case.

Similarity: 64% (right between "High" and "Medium")

This could go either way. I'll present both perspectives:

**Perspective 1: Similar Enough**
[Present variant option]

**Perspective 2: Different Enough**
[Present new component option]

Your design philosophy will guide this decision.

</output>

---

Edge Cases

Designer asks for recommendation:

Based on the analysis, I recommend Option 3 (Create New).

But this is your design system - you know your project best.

What's most important to you?

- Consistency? → Reuse or Variant
- Clarity? → New
- Flexibility? → Variant
- Simplicity? → Reuse or New

Designer is unsure:

That's okay! This is a judgment call.

Here's a simple heuristic:

If a developer saw both buttons, would they think:
A) "Same button, different label" → Reuse
B) "Related buttons, different purposes" → Variant
C) "Different buttons entirely" → New

What's your gut feeling?

Designer wants to defer decision:

✅ No problem!

I'll create it as a new component for now.

You can always:

- Merge it later if you decide they're the same
- Convert it to a variant if you see a pattern
- Keep it separate if the distinction is valuable

Design systems evolve - this isn't permanent.

---

Output Format

For next step:

{
  "decision": {
    "choice": "create_new",
    "component_id": "btn-002",
    "reasoning": "Semantic distinction matters",
    "designer_notes": "Navigation and submission are different actions"
  }
}

7. Present MENU OPTIONS

Display: "Select an Option: [1/2/3/4] Choose option or request more info"

Menu Handling Logic:

• IF C: Update design log, then load, read entire file, then execute {nextStepFile}
• IF Any other comments or queries: help user respond then Redisplay Menu Options

EXECUTION RULES:

• ALWAYS halt and wait for user input after presenting menu
• ONLY proceed to next step when user selects the appropriate option
• User can chat or ask questions — always respond and then redisplay menu options

CRITICAL STEP COMPLETION NOTE

ONLY WHEN [designer has selected an option (1/2/3) and decision is confirmed], will you then load and read fully {nextStepFile} to execute the next step.

---

🚨 SYSTEM SUCCESS/FAILURE METRICS

✅ SUCCESS:

• Step goal achieved completely
• All instructions executed in sequence
• Results documented and presented to user
• User confirmed before proceeding
• Design log updated

❌ SYSTEM FAILURE:

• Skipping any instruction in the sequence
• Generating content without user input
• Jumping ahead to later steps
• Not presenting results to user
• Proceeding without user confirmation

Master Rule: Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

Step 7: Execute Decision

STEP GOAL:

Execute the designer decision by routing to the appropriate operation: reuse existing component, add variant to existing, or create new component.

MANDATORY EXECUTION RULES (READ FIRST):

Universal Rules:

• 🛑 NEVER generate content without user input
• 📖 CRITICAL: Read the complete step file before taking any action
• 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
• 📋 YOU ARE A FACILITATOR, not a content generator
• ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config {communication_language}

Role Reinforcement:

• ✅ You are the Design System Architect guiding design system creation and maintenance
• ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
• ✅ We engage in collaborative dialogue, not command-response
• ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
• ✅ Maintain systematic and analytical tone throughout

Step-Specific Rules:

• 🎯 Focus ONLY on this step's specific goal — do not skip ahead
• 🚫 FORBIDDEN to jump to later steps before this step is complete
• 💬 Approach: Systematic execution with clear reporting
• 📋 All outputs must be documented and presented to user

EXECUTION PROTOCOLS:

• 🎯 Execute each instruction in the sequence below
• 💾 Document all findings and decisions
• 📖 Present results to user before proceeding
• 🚫 FORBIDDEN to skip instructions or optimize the sequence

CONTEXT BOUNDARIES:

• Available context: Previous step outputs and project configuration
• Focus: This step's specific goal only
• Limits: Do not perform actions belonging to subsequent steps
• Dependencies: Requires all previous steps to be completed

Sequence of Instructions (Do not deviate, skip, or optimize)

Execution Paths

Path A: Reuse Existing Component

Designer chose to use existing component as-is

Path B: Add Variant

Designer chose to add variant to existing component

Path C: Create New Component

Designer chose to create new component

---

Path A: Reuse Existing Component

Step 1: Confirm Action

<output>

✅ Reusing Button [btn-001]

I'll update your page spec to reference the existing component.

</output>

Step 2: Extract Page-Specific Content

<action> From complete specification, extract:

• Labels/text content
• Page-specific why/purpose
• Error messages
• Contextual information

</action>

Example:

Page-Specific Content:
- label: "Continue"
- why: "Navigate to next step in onboarding"
- context: "Multi-step form navigation"

Step 3: Create Reference

<action> Create reference to existing component:

• Component ID: btn-001
• Variant: primary (or whichever applies)
• Page-specific content

</action>

Output:

# C-UX-Scenarios/onboarding-page.md

Continue Button:
  component: Button.primary [btn-001]
  why: Navigate to next step in onboarding
  label: 'Continue'

Step 4: Update Component Usage

<action> Update design system component to track usage:

• Add page to "Used In" list
• Increment usage count

</action>

Update:

# D-Design-System/components/button.md

Used In:
  - Login page (login button)
  - Signup page (create account button)
  - Dashboard (action buttons)
  - Onboarding page (continue button)  ← Added

Step 5: Complete

<output>

✅ Done! Button [btn-001] is now used on onboarding page.

Page spec updated with reference.
Component usage tracked.

</output>

Return to Phase 4

---

Path B: Add Variant

Step 1: Confirm Action

<output>

✅ Adding "navigation" variant to Button [btn-001]

I'll update the component definition and create the reference.

</output>

Step 2: Extract Component-Level Info

<action> From complete specification, extract:

• Variant-specific styling
• Variant-specific states
• Variant-specific behaviors

</action>

Example:

Navigation Variant:
- icon: arrow-right
- loading_state: true
- hover_animation: icon_shift

Step 3: Update Component Definition

<action> Add variant to existing component:

• Add to variants list
• Document variant-specific attributes
• Maintain shared attributes

</action>

Update:

# D-Design-System/components/button.md

Button Component [btn-001]:
  variants:
    - primary (submit actions)
    - secondary (cancel actions)
    - navigation (continue/next actions)  ← Added

  shared_states:
    - default, hover, active, disabled

  variant_specific:
    navigation:
      icon: arrow-right
      loading_state: true
      hover_animation: icon_shift

Step 4: Create Reference

<action> Create reference with variant specified: </action>

Output:

# C-UX-Scenarios/onboarding-page.md

Continue Button:
  component: Button.navigation [btn-001]  ← Variant specified
  why: Navigate to next step in onboarding
  label: 'Continue'

Step 5: Update Usage Tracking

<action> Track variant usage: </action>

Update:

# D-Design-System/components/button.md

Variant Usage:
  primary: 5 pages
  secondary: 3 pages
  navigation: 1 page  ← Added

Step 6: Complete

<output>

✅ Done! Navigation variant added to Button [btn-001].

Component definition updated.
Page spec created with variant reference.
Variant usage tracked.

</output>

Return to Phase 4

---

Path C: Create New Component

Step 1: Confirm Action

<output>

✅ Creating new Navigation Button [btn-002]

I'll create the component definition and set up the reference.

</output>

Step 2: Generate Component ID

<action> Generate unique component ID:

• Check existing IDs
• Increment counter for type
• Format: [type-prefix]-[number]

</action>

Example:

Existing Button IDs: btn-001
New ID: btn-002

Step 3: Extract Component-Level Info

<action> From complete specification, extract:

• Visual attributes (size, shape, color)
• States (default, hover, active, disabled, loading)
• Behaviors (interactions, animations)
• Styling (design tokens or Figma reference)

</action>

Example:

Component-Level Info:
  type: Button
  purpose: Navigation actions
  states: [default, hover, active, disabled, loading]
  icon: arrow-right
  size: medium
  color: blue
  shape: rounded
  hover_animation: icon_shift

Step 4: Create Component File

<action> Create new component file using template: </action>

Route to: step-08b-create-new-component.md

Output:

# D-Design-System/components/navigation-button.md

# Navigation Button [btn-002]

**Type:** Interactive
**Purpose:** Navigation actions (continue, next, proceed)
**Library:** shadcn/ui Button (if Mode C)
**Figma:** [Link] (if Mode B)

## States
- default
- hover
- active
- disabled
- loading (with spinner)

## Styling
- Size: medium
- Color: blue primary
- Shape: rounded
- Icon: arrow-right
- Hover: icon shifts right

## Used In
- Onboarding page (continue button)

Step 5: Create Reference

<action> Create reference in page spec: </action>

Output:

# C-UX-Scenarios/onboarding-page.md

Continue Button:
  component: NavigationButton [btn-002]
  why: Navigate to next step in onboarding
  label: 'Continue'

Step 6: Update Design System Index

<action> Add to design system component list: </action>

Update:

# D-Design-System/components/README.md

Components:
  - Button [btn-001] - Primary action buttons
  - Input Field [inp-001] - Text input fields
  - Card [crd-001] - Content cards
  - Navigation Button [btn-002] - Navigation actions  ← Added

Step 7: Complete

<output>

✅ Done! Navigation Button [btn-002] created.

Component file created: D-Design-System/components/navigation-button.md
Page spec created with reference.
Design system index updated.

</output>

Return to Phase 4

---

Post-Execution Actions

Update Project State

<action> Update project tracking:

• Increment component count
• Update design system status
• Log decision for future reference

</action>

Example:

# A-Project-Brief/design-system-log.md

2024-12-09: Created Navigation Button [btn-002]
- Reason: Semantic distinction from submit buttons
- Decision: Create new vs variant
- Designer: Chose clarity over consistency

Notify Designer

<output>

📊 Design System Update:

Components: 4 (was 3)
Latest: Navigation Button [btn-002]

Your design system is growing! Consider reviewing component
organization when you reach 10+ components.

</output>

---

Error Handling

If component creation fails:

❌ Error creating component file.

Error: [error message]

Would you like to:

1. Retry
2. Create manually
3. Skip design system for this component

Your choice:

If reference creation fails:

❌ Error updating page spec.

Error: [error message]

Component was created successfully, but page reference failed.
I'll keep the complete spec on the page for now.

If ID conflict:

⚠️ Component ID conflict detected.

btn-002 already exists but with different content.

Generating alternative ID: btn-003

---

Validation

Before Completing

<action> Validate execution:

• ✓ Component file created (if new)
• ✓ Component updated (if variant)
• ✓ Page spec has reference
• ✓ Usage tracked
• ✓ Design system index updated

</action>

If validation fails:

⚠️ Validation Warning:

Some steps may not have completed successfully.
Please review:

- [List of potential issues]

Continue anyway? (y/n)

---

Return to Phase 4

<action> Return control to Phase 4 orchestration:

• Pass component reference
• Pass page-specific content
• Signal completion

</action>

Phase 4 continues with:

• Update page spec with reference
• Continue to next component
• Or complete page specification

---

Summary Output

<output>

✅ Design System Operation Complete

Action: Created new component
Component: Navigation Button [btn-002]
Page: Onboarding page
Reference: NavigationButton [btn-002]

Files Updated:

- D-Design-System/components/navigation-button.md (created)
- C-UX-Scenarios/onboarding-page.md (reference added)
- D-Design-System/components/README.md (index updated)

Next: Continue with next component in Phase 4

</output>

---

This completes the assessment and execution flow. Control returns to Phase 4.

### 5. Present MENU OPTIONS

Display: "**Select an Option:** [C] Continue to next operation"

#### Menu Handling Logic:

- IF C: Update design log, then load, read entire file, then execute {nextStepFile}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#5-present-menu-options)

#### EXECUTION RULES:

- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects the appropriate option
- User can chat or ask questions — always respond and then redisplay menu options

## CRITICAL STEP COMPLETION NOTE

ONLY WHEN [decision has been executed and design system updated accordingly], will you then load and read fully `{nextStepFile}` to execute the next step.

---

## 🚨 SYSTEM SUCCESS/FAILURE METRICS

### ✅ SUCCESS:

- Step goal achieved completely
- All instructions executed in sequence
- Results documented and presented to user
- User confirmed before proceeding
- Design log updated

### ❌ SYSTEM FAILURE:

- Skipping any instruction in the sequence
- Generating content without user input
- Jumping ahead to later steps
- Not presenting results to user
- Proceeding without user confirmation

**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

Step 8a: Initialize Design System

STEP GOAL:

Create the design system folder structure, token placeholders, mode-specific files, and component index. Prepare for the first component addition.

MANDATORY EXECUTION RULES (READ FIRST):

Universal Rules:

• 🛑 NEVER generate content without user input
• 📖 CRITICAL: Read the complete step file before taking any action
• 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
• 📋 YOU ARE A FACILITATOR, not a content generator
• ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config {communication_language}

Role Reinforcement:

• ✅ You are the Design System Architect guiding design system creation and maintenance
• ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
• ✅ We engage in collaborative dialogue, not command-response
• ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
• ✅ Maintain systematic and analytical tone throughout

Step-Specific Rules:

• 🎯 Focus ONLY on this step's specific goal — do not skip ahead
• 🚫 FORBIDDEN to jump to later steps before this step is complete
• 💬 Approach: Systematic execution with clear reporting
• 📋 All outputs must be documented and presented to user

EXECUTION PROTOCOLS:

• 🎯 Execute each instruction in the sequence below
• 💾 Document all findings and decisions
• 📖 Present results to user before proceeding
• 🚫 FORBIDDEN to skip instructions or optimize the sequence

CONTEXT BOUNDARIES:

• Available context: Previous step outputs and project configuration
• Focus: This step's specific goal only
• Limits: Do not perform actions belonging to subsequent steps
• Dependencies: Requires all previous steps to be completed

Sequence of Instructions (Do not deviate, skip, or optimize)

Step 1: Confirm Initialization

<output>

🎉 Initializing Design System!

This is your first design system component.
I'll create the folder structure and add this component.

Design System Mode: [Custom/Library]
Component Library: [shadcn/Radix/etc. if applicable]

</output>

---

Step 2: Create Folder Structure

<action> Create design system folders:

D-Design-System/
├── components/
├── design-tokens.md (placeholder)
├── component-library-config.md (if Mode C)
└── figma-mappings.md (if Mode B)

</action>

<output>

📁 Created Design System Structure:

D-Design-System/
├── components/ (empty, ready for first component)
├── design-tokens.md (placeholder)
└── [mode-specific files]

✅ Folder structure ready!

</output>

---

Step 3: Create Design Tokens Placeholder

<action> Create initial design tokens file: </action>

File: D-Design-System/design-tokens.md

# Design Tokens

**Status:** To be defined

Design tokens will be extracted as components are added to the design system.

## Token Categories

### Colors
- Primary colors
- Secondary colors
- Semantic colors (success, error, warning, info)
- Neutral colors

### Typography
- Font families
- Font sizes
- Font weights
- Line heights
- Letter spacing

### Spacing
- Spacing scale
- Padding values
- Margin values
- Gap values

### Layout
- Breakpoints
- Container widths
- Grid columns

### Effects
- Shadows
- Border radius
- Transitions
- Animations

---

**Tokens will be populated as components are specified.**

---

Step 4: Create Mode-Specific Files

If Mode B: Custom Design System

<action> Create Figma mappings file: </action>

File: D-Design-System/figma-mappings.md

# Figma Component Mappings

**Figma File:** [To be specified]
**Last Updated:** [Date]

## Component Mappings

Components in this design system are linked to Figma components for visual reference and design handoff.

### Format

Component ID → Figma Node ID [component-id] → figma://file/[file-id]/node/[node-id]

## Mappings

[To be populated as components are added]

---

**How to find Figma node IDs:**
1. Select component in Figma
2. Right-click → Copy link to selection
3. Extract node ID from URL

If Mode C: Component Library

<action> Create component library config: </action>

File: D-Design-System/component-library-config.md

````markdown

Component Library Configuration

Library: [shadcn/Radix/MUI/etc.] Version: [Version] Installation: [Installation command]

Library Components Used

This design system uses components from [Library Name].

Component Mappings

Format: WDS Component → Library Component

[To be populated as components are added]

Customizations

Theme Configuration

{
  "colors": {},
  "typography": {},
  "spacing": {},
  "borderRadius": {}
}

````

[To be updated as design system grows]

Installation Instructions

[Installation commands]

---

Library documentation: [Link]

````

---

Step 5: Create Component Index

<action> Create components README: </action>

File: D-Design-System/components/README.md

# Design System Components

**Total Components:** 1
**Last Updated:** [Date]

## Component List

### Interactive Components
- [First component will be listed here]

### Form Components
[None yet]

### Layout Components
[None yet]

### Content Components
[None yet]

---

## Component Naming Convention

**Format:** `[type]-[number]`

Examples:
- btn-001 (Button)
- inp-001 (Input Field)
- crd-001 (Card)

## Component File Structure

Each component file includes:
- Component ID
- Type and purpose
- Variants (if any)
- States
- Styling/tokens
- Usage tracking

---

**Components are added automatically as they're discovered during specification.**

---

Step 6: Add First Component

<action> Route to create-new-component operation:

• Pass component specification
• Generate first component ID
• Create component file

</action>

Route to: step-08b-create-new-component.md

---

Step 7: Generate Initial Catalog

<action> Create interactive HTML catalog: </action>

Load and execute: step-08e-generate-catalog.md

Initial catalog includes:

• Project introduction
• Design tokens (if defined)
• First component showcase
• Getting started guide
• Empty changelog

Output:

✅ Initial catalog generated

File: D-Design-System/catalog.html
Components: 1
View: file:///path/to/catalog.html

---

Step 8: Update Project Config

<action> Mark design system as initialized: </action>

Update project config:

design_system:
  enabled: true
  mode: [mode]
  initialized: true
  initialized_date: [date]
  folder: D-Design-System/
  first_component: [component-id]
  catalog: D-Design-System/catalog.html

---

Success Message

✅ Design system initialized

Mode: [mode]
Folder: D-Design-System/
First component: [ComponentType] [[component-id]]
Catalog: D-Design-System/catalog.html

Design system is ready to use.
Components will be extracted automatically as discovered.
Interactive catalog available for viewing.
added to the design system if they're reusable.

Next: Continue with component specification in Phase 4

</output>

---

Validation

<action> Validate initialization:

• ✓ D-Design-System/ folder exists
• ✓ components/ subfolder exists
• ✓ design-tokens.md created
• ✓ Mode-specific files created
• ✓ Component index created
• ✓ First component added
• ✓ Project config updated

</action>

If validation fails:

⚠️ Initialization Warning

Some files may not have been created successfully.
Please check:
- [List of missing files]

Would you like to retry initialization? (y/n)

---

Error Handling

If folder already exists:

⚠️ D-Design-System/ folder already exists.

This shouldn't happen for first component initialization.

Options:
1. Use existing structure (merge)
2. Backup and recreate
3. Cancel initialization

Your choice:

If component creation fails:

❌ Error creating first component.

Error: [error message]

Design system structure was created, but component addition failed.
You can add components manually or retry.

If mode not specified:

⚠️ Design system mode not specified in project config.

Please specify:
1. Custom (Figma-based)
2. Component Library (shadcn/Radix/etc.)

Your choice:

---

Post-Initialization

Designer Guidance

<output>

💡 Design System Tips:

**What happens next:**

- As you specify components, I'll check for similarities
- Reusable components will be added to the design system
- You'll make decisions about variants vs new components

**Best practices:**

- Be consistent with component boundaries
- Think about reusability early
- Don't over-engineer - start simple

**You can always:**

- Add components manually
- Refactor the design system
- Merge or split components later

Design systems evolve - this is just the beginning!

</output>

---

Return to Workflow

<action> Return to design system router:

• Signal initialization complete
• Pass first component reference
• Continue with component addition

</action>

Router continues with: Adding first component to design system

---

This operation runs once per project. Subsequent components use create-new-component or add-variant operations.

### 9. Present MENU OPTIONS

Display: "**Select an Option:** [C] Continue to Create First Component"

#### Menu Handling Logic:

- IF C: Update design log, then load, read entire file, then execute {nextStepFile}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#9-present-menu-options)

#### EXECUTION RULES:

- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects the appropriate option
- User can chat or ask questions — always respond and then redisplay menu options

## CRITICAL STEP COMPLETION NOTE

ONLY WHEN [C continue option is selected and design system structure is initialized], will you then load and read fully `{nextStepFile}` to execute the next step.

---

## 🚨 SYSTEM SUCCESS/FAILURE METRICS

### ✅ SUCCESS:

- Step goal achieved completely
- All instructions executed in sequence
- Results documented and presented to user
- User confirmed before proceeding
- Design log updated

### ❌ SYSTEM FAILURE:

- Skipping any instruction in the sequence
- Generating content without user input
- Jumping ahead to later steps
- Not presenting results to user
- Proceeding without user confirmation

**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

Step 8b: Create New Component

STEP GOAL:

Add a new component to the design system: generate ID, determine category, extract attributes, create component file from template, update index and stats.

MANDATORY EXECUTION RULES (READ FIRST):

Universal Rules:

• 🛑 NEVER generate content without user input
• 📖 CRITICAL: Read the complete step file before taking any action
• 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
• 📋 YOU ARE A FACILITATOR, not a content generator
• ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config {communication_language}

Role Reinforcement:

• ✅ You are the Design System Architect guiding design system creation and maintenance
• ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
• ✅ We engage in collaborative dialogue, not command-response
• ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
• ✅ Maintain systematic and analytical tone throughout

Step-Specific Rules:

• 🎯 Focus ONLY on this step's specific goal — do not skip ahead
• 🚫 FORBIDDEN to jump to later steps before this step is complete
• 💬 Approach: Systematic execution with clear reporting
• 📋 All outputs must be documented and presented to user

EXECUTION PROTOCOLS:

• 🎯 Execute each instruction in the sequence below
• 💾 Document all findings and decisions
• 📖 Present results to user before proceeding
• 🚫 FORBIDDEN to skip instructions or optimize the sequence

CONTEXT BOUNDARIES:

• Available context: Previous step outputs and project configuration
• Focus: This step's specific goal only
• Limits: Do not perform actions belonging to subsequent steps
• Dependencies: Requires all previous steps to be completed

Sequence of Instructions (Do not deviate, skip, or optimize)

Step 1: Generate Component ID

<action> Generate unique component ID: 1. Determine component type prefix 2. Check existing IDs for that type 3. Increment counter 4. Format: [prefix]-[number] </action>

Type Prefixes:

Button → btn
Input Field → inp
Card → crd
Modal → mdl
Dropdown → drp
Checkbox → chk
Radio → rad
Toggle → tgl
Tab → tab
Accordion → acc
Alert → alt
Badge → bdg
Avatar → avt
Icon → icn
Image → img
Link → lnk
Text → txt
Heading → hdg
List → lst
Table → tbl
Form → frm
Container → cnt
Grid → grd
Flex → flx
Divider → div
Spacer → spc

Example:

Component Type: Button
Existing Button IDs: btn-001, btn-002
New ID: btn-003

<output>

🆔 Generated Component ID: btn-003

</output>

---

Step 2: Determine Component Category

<action> Categorize component for organization:

• Interactive (buttons, links, controls)
• Form (inputs, selects, checkboxes)
• Layout (containers, grids, dividers)
• Content (text, images, media)
• Feedback (alerts, toasts, modals)
• Navigation (tabs, breadcrumbs, menus)

</action>

Example:

Component: Button
Category: Interactive

---

Step 3: Extract Component-Level Information

<action> From complete specification, extract component-level info:

Visual Attributes:

• Size (small, medium, large)
• Shape (rounded, square, pill)
• Color scheme
• Typography
• Spacing/padding
• Border style

Behavioral Attributes:

• States (default, hover, active, disabled, loading, error)
• Interactions (click, hover, focus, blur)
• Animations/transitions
• Keyboard support
• Accessibility attributes

Functional Attributes:

• Purpose/role
• Input/output type
• Validation rules
• Required/optional

Design System Attributes:

• Variants (if any)
• Design tokens used
• Figma reference (if Mode B)
• Library component (if Mode C)

</action>

---

Step 4: Create Component File

<action> Use component template to create file: </action>

File: D-Design-System/components/[component-name].md

Template Structure:

````markdown

[Component Name] [component-id]

Type: [Interactive/Form/Layout/Content/Feedback/Navigation] Category: [Specific category] Purpose: [Brief description]

---

Overview

[Component description and when to use it]

---

Variants

[If component has variants, list them]

Example:

• primary - Main call-to-action
• secondary - Secondary actions
• ghost - Subtle actions

[If no variants:] This component has no variants.

---

States

Required States:

• default
• hover
• active
• disabled

Optional States:

• loading
• error
• success
• focus

State Descriptions: [Describe what each state looks like/does]

---

Styling

Visual Properties

Size: [small/medium/large or specific values] Shape: [rounded/square/pill or specific border-radius] Colors: [Color tokens or values] Typography: [Font tokens or values] Spacing: [Padding/margin values]

Design Tokens

[If using design tokens:]

colors:
  background: primary-500
  text: white
  border: primary-600

typography:
  font-size: text-base
  font-weight: semibold

spacing:
  padding-x: 4
  padding-y: 2

effects:
  border-radius: md
  shadow: sm

````

Figma Reference

[If Mode B - Custom Design System:] Figma Component: [Link to Figma component] Node ID: [Figma node ID] Last Synced: [Date]

Library Component

[If Mode C - Component Library:] Library: [shadcn/Radix/etc.] Component: [Library component name] Customizations: [Any overrides from library default]

---

Behavior

Interactions

Click: [What happens on click]

Hover: [What happens on hover]

Focus: [What happens on focus]

Keyboard: [Keyboard shortcuts/navigation]

Animations

[If component has animations:]

• [Animation description]
• Duration: [ms]
• Easing: [easing function]

---

Accessibility

ARIA Attributes:

• role: [role]
• aria-label: [label]
• aria-disabled: [when disabled]
• [Other ARIA attributes]

Keyboard Support:

• Enter/Space: [action]
• Tab: [navigation]
• [Other keyboard support]

Screen Reader: [How screen readers should announce this component]

---

Usage

When to Use

[Guidelines for when this component is appropriate]

When Not to Use

[Guidelines for when to use a different component]

Best Practices

• [Best practice 1]
• [Best practice 2]
• [Best practice 3]

---

Used In

Pages: [List of pages using this component]

Usage Count: [Number]

Examples:

• [Page name] - [Specific usage]
• [Page name] - [Specific usage]

---

Related Components

[If this component is related to others:]

• [Related component 1] - [Relationship]
• [Related component 2] - [Relationship]

---

Version History

Created: [Date] Last Updated: [Date]

Changes:

• [Date]: Created component
• [Date]: [Change description]

---

Notes

[Any additional notes, considerations, or future plans]

````

---

Step 5: Populate Template

<action> Fill template with extracted information: </action>

Example Output:

# Button [btn-003]

**Type:** Interactive
**Category:** Action
**Purpose:** Trigger primary and secondary actions

---

## Overview

Buttons are used to trigger actions. They should have clear, action-oriented labels that describe what will happen when clicked.

Use buttons for important actions that change state or navigate to new content.

---

## Variants

- **primary** - Main call-to-action (submit, save, continue)
- **secondary** - Secondary actions (cancel, back)
- **ghost** - Subtle actions (close, dismiss)

---

## States

**Required States:**
- default - Normal state
- hover - Mouse over button
- active - Button being clicked
- disabled - Button cannot be clicked

**Optional States:**
- loading - Action in progress (shows spinner)

**State Descriptions:**

**Default:** Blue background, white text, medium size
**Hover:** Darker blue background, slight scale increase
**Active:** Even darker blue, slight scale decrease
**Disabled:** Gray background, gray text, reduced opacity
**Loading:** Disabled state + spinner icon

---

## Styling

### Visual Properties

**Size:** medium (h-10, px-4)
**Shape:** rounded (border-radius: 0.375rem)
**Colors:**
- Background: blue-600
- Text: white
- Border: none

**Typography:**
- Font size: 14px
- Font weight: 600
- Line height: 1.5

**Spacing:**
- Padding X: 16px
- Padding Y: 8px
- Gap (if icon): 8px

### Design Tokens

colors: primary: background: blue-600 hover: blue-700 active: blue-800 text: white

typography: size: text-sm weight: semibold

spacing: padding-x: 4 padding-y: 2 gap: 2

effects: border-radius: md shadow: sm transition: all 150ms ease ````

Library Component

Library: shadcn/ui Component: Button Customizations: None (using library defaults)

---

Behavior

Interactions

Click: Triggers associated action (form submit, navigation, etc.)

Hover:

• Background darkens
• Slight scale increase (1.02)
• Cursor changes to pointer

Focus:

• Blue outline ring
• Maintains hover state

Keyboard:

• Enter/Space triggers click
• Tab navigates to/from button

Animations

Hover Scale:

• Duration: 150ms
• Easing: ease-in-out
• Scale: 1.02

Click Feedback:

• Duration: 100ms
• Scale: 0.98

---

Accessibility

ARIA Attributes:

• role: button
• aria-label: [Descriptive label if icon-only]
• aria-disabled: true [when disabled]
• aria-busy: true [when loading]

Keyboard Support:

• Enter/Space: Triggers button action
• Tab: Moves focus to/from button

Screen Reader: Announces button label and state (disabled, busy, etc.)

---

Usage

When to Use

• Primary actions (submit forms, save data, proceed to next step)
• Secondary actions (cancel, go back, dismiss)
• Triggering modals or dialogs
• Navigation to new pages/sections

When Not to Use

• For navigation that looks like text (use Link component)
• For toggling states (use Toggle or Checkbox)
• For selecting from options (use Radio or Checkbox)

Best Practices

• Use action-oriented labels ("Save Changes" not "Save")
• Limit primary buttons to one per section
• Place primary button on the right in button groups
• Ensure sufficient touch target size (min 44x44px)
• Provide loading state for async actions

---

Used In

Pages: 1

Usage Count: 1

Examples:

• Login page - Submit credentials button

---

Related Components

• Link [lnk-001] - For text-style navigation
• Icon Button [btn-002] - For icon-only actions

---

Version History

Created: 2024-12-09 Last Updated: 2024-12-09

Changes:

• 2024-12-09: Created component

---

Notes

This is the primary button component. Consider adding more variants as needs emerge (danger, success, etc.).

````

---

Step 6: Update Component Index

<action> Add component to index: </action>

Update: D-Design-System/components/README.md

## Component List

### Interactive Components
- Button [btn-001] - Primary action buttons
- Icon Button [btn-002] - Icon-only actions
- Button [btn-003] - Standard action button  ← Added

**Total Interactive:** 3

---

Step 7: Update Design System Stats

<action> Update design system statistics: </action>

Update: D-Design-System/README.md (if exists)

**Total Components:** 4 (was 3)
**Last Updated:** [Date]
**Latest Addition:** Button [btn-003]

---

Step 8: Create Component Reference

<action> Generate reference for page spec: </action>

Output:

component_reference:
  id: btn-003
  name: Button
  variant: primary
  file: D-Design-System/components/button.md

---

Step 9: Complete

<output>

✅ Component Created: Button [btn-003]

File: D-Design-System/components/button.md
Category: Interactive
Variants: primary, secondary, ghost
States: default, hover, active, disabled, loading

Component index updated.
Design system stats updated.
Reference ready for page spec.

Next: Return to Phase 4 to complete page specification

</output>

---

Validation

<action> Validate component creation:

• ✓ Component file created
• ✓ Component ID unique
• ✓ Template fully populated
• ✓ Index updated
• ✓ Stats updated
• ✓ Reference generated

</action>

---

Error Handling

If ID conflict:

⚠️ Component ID btn-003 already exists.

Generating alternative ID: btn-004

If file creation fails:

❌ Error creating component file.

Error: [error message]

Would you like to:

1. Retry
2. Create with different ID
3. Skip design system for this component

Your choice:

If template population incomplete:

⚠️ Some component information is missing.

Missing:

- [List of missing fields]

I'll create the component with placeholders.
You can fill in details later.

---

This operation creates a new component. Return to Phase 4 with component reference.

### 10. Present MENU OPTIONS

Display: "**Select an Option:** [C] Continue or [M] Return to Activity Menu"

#### Menu Handling Logic:

- IF C: Update design log, then load, read entire file, then execute {nextStepFile}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#10-present-menu-options)

#### EXECUTION RULES:

- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects the appropriate option
- User can chat or ask questions — always respond and then redisplay menu options

## CRITICAL STEP COMPLETION NOTE

ONLY WHEN [component is created with full specification, index updated, and reference generated], will you then load and read fully `{nextStepFile}` to execute the next step.

---

## 🚨 SYSTEM SUCCESS/FAILURE METRICS

### ✅ SUCCESS:

- Step goal achieved completely
- All instructions executed in sequence
- Results documented and presented to user
- User confirmed before proceeding
- Design log updated

### ❌ SYSTEM FAILURE:

- Skipping any instruction in the sequence
- Generating content without user input
- Jumping ahead to later steps
- Not presenting results to user
- Proceeding without user confirmation

**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

Step 8c: Update Component

STEP GOAL:

Update an existing component definition: identify update type, analyze impact, apply changes, track version history, notify affected pages.

MANDATORY EXECUTION RULES (READ FIRST):

Universal Rules:

• 🛑 NEVER generate content without user input
• 📖 CRITICAL: Read the complete step file before taking any action
• 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
• 📋 YOU ARE A FACILITATOR, not a content generator
• ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config {communication_language}

Role Reinforcement:

• ✅ You are the Design System Architect guiding design system creation and maintenance
• ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
• ✅ We engage in collaborative dialogue, not command-response
• ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
• ✅ Maintain systematic and analytical tone throughout

Step-Specific Rules:

• 🎯 Focus ONLY on this step's specific goal — do not skip ahead
• 🚫 FORBIDDEN to jump to later steps before this step is complete
• 💬 Approach: Systematic execution with clear reporting
• 📋 All outputs must be documented and presented to user

EXECUTION PROTOCOLS:

• 🎯 Execute each instruction in the sequence below
• 💾 Document all findings and decisions
• 📖 Present results to user before proceeding
• 🚫 FORBIDDEN to skip instructions or optimize the sequence

CONTEXT BOUNDARIES:

• Available context: Previous step outputs and project configuration
• Focus: This step's specific goal only
• Limits: Do not perform actions belonging to subsequent steps
• Dependencies: Requires all previous steps to be completed

Sequence of Instructions (Do not deviate, skip, or optimize)

Step 1: Identify Update Type

<action> Determine what's being updated: </action>

Update Types:

Type A: Add New State

Adding state to all variants (e.g., loading, error, success)

Type B: Update Styling

Changing visual properties (colors, sizing, spacing)

Type C: Update Behavior

Changing interactions, animations, or keyboard support

Type D: Update Accessibility

Adding/modifying ARIA attributes or screen reader support

Type E: Update Documentation

Clarifying usage, adding examples, fixing errors

Type F: Refactor

Reorganizing component structure, splitting/merging variants

<ask>

What type of update is this?

[A] Add new state
[B] Update styling
[C] Update behavior
[D] Update accessibility
[E] Update documentation
[F] Refactor component

Your choice:

</ask>

---

Step 2: Load Current Component

<action> Read existing component file:

• Current definition
• All variants
• Current states
• Current styling
• Usage tracking

</action>

<output>

📖 Loaded Button [btn-001]

Current state:

- Variants: 3 (primary, secondary, navigation)
- States: default, hover, active, disabled
- Used in: 9 pages
- Last updated: 2024-12-09

</output>

---

Step 3: Analyze Impact

<action> Determine impact of update: </action>

Impact Assessment:

Scope

• All variants affected?
• Specific variant only?
• All instances affected?
• Specific usage only?

Breaking Changes

• Does this change existing behavior?
• Will existing pages need updates?
• Does this affect developers?

Compatibility

• Compatible with current usage?
• Requires page spec updates?
• Requires code changes?

<output>

📊 Impact Analysis:

Update: Adding "loading" state to all button variants

Scope: All variants (primary, secondary, navigation)
Affected Pages: 9 pages using Button component
Breaking Change: No (additive only)
Compatibility: Fully compatible (optional state)

Impact Level: Low (safe to proceed)

</output>

---

Step 4: Confirm Update

<ask>

Ready to update Button [btn-001]

Update: Add "loading" state
Impact: 9 pages (no breaking changes)

This will:
✓ Add loading state to component definition
✓ Update all variant documentation
✓ Maintain backward compatibility

Proceed with update? (y/n)

</ask>

---

Step 5: Apply Update

<action> Update component file based on type: </action>

Type A: Add New State

Update States Section:

Before:

## States

**Shared States:**
- default
- hover
- active
- disabled

After:

## States

**Shared States:**

- default
- hover
- active
- disabled
- loading ← Added

**State Descriptions:**

**Loading:**

- Disabled interaction
- Shows spinner icon
- Maintains button size
- Reduced opacity (0.7)

Update Variant-Specific Sections (if needed):

### Variant-Specific Styling

**Navigation (loading state):**

- Spinner + arrow icon
- Arrow fades out during loading

Type B: Update Styling

Update Styling Section:

Before:

### Visual Properties

**Border Radius:** 0.375rem (md)

After:

### Visual Properties

**Border Radius:** 0.5rem (lg) ← Updated

**Change Reason:** Increased for better visual consistency with other components

Type C: Update Behavior

Update Behavior Section:

Before:

### Keyboard

- Enter/Space: Triggers button action
- Tab: Moves focus to/from button

After:

### Keyboard

- Enter/Space: Triggers button action
- Tab: Moves focus to/from button
- Escape: Cancels action (if in progress) ← Added

Type D: Update Accessibility

Update Accessibility Section:

Before:

**ARIA Attributes:**

- role: button
- aria-disabled: true [when disabled]

After:

**ARIA Attributes:**

- role: button
- aria-disabled: true [when disabled]
- aria-busy: true [when loading] ← Added
- aria-live: polite [for status updates] ← Added

Type E: Update Documentation

Update Usage Section:

Before:

### When to Use

- Primary actions
- Secondary actions

After:

### When to Use

- Primary actions (submit forms, save data, proceed to next step)
- Secondary actions (cancel, go back, dismiss)
- Triggering modals or dialogs ← Added
- Navigation to new pages/sections ← Added

### When Not to Use

- For navigation that looks like text (use Link component) ← Added
- For toggling states (use Toggle or Checkbox) ← Added

Type F: Refactor

Example: Split variant into separate component

## Refactoring Note

**Date:** 2024-12-09
**Change:** Moved "icon-only" variant to separate Icon Button component

**Reason:** Icon-only buttons have significantly different:

- Visual structure (no text)
- Accessibility requirements (requires aria-label)
- Usage patterns (toolbars, compact spaces)

**Migration:**

- Old: Button.icon-only [btn-001]
- New: Icon Button [btn-002]

**Affected Pages:** 5 pages
**Migration Status:** Complete

---

Step 6: Update Version History

<action> Track update in version history: </action>

Update:

## Version History

**Created:** 2024-12-01
**Last Updated:** 2024-12-09

**Changes:**

- 2024-12-01: Created component
- 2024-12-05: Added navigation variant
- 2024-12-09: Added loading state to all variants ← Added

---

Step 7: Notify Affected Pages

<action> If update affects existing usage, create notification: </action>

<output>

📢 Component Update Notification

Component: Button [btn-001]
Update: Added loading state
Affected Pages: 9

Pages using this component:

- Login page
- Signup page
- Dashboard
- [... 6 more]

Action Required: None (backward compatible)

Optional: Consider using loading state for async actions

Documentation: See Button component for loading state usage

</output>

---

Step 8: Update Design System Stats

<action> Update design system metadata: </action>

Update: D-Design-System/README.md

**Last Updated:** 2024-12-09
**Recent Changes:**
- Button [btn-001]: Added loading state

---

Step 9: Complete

<output>

✅ Component Updated: Button [btn-001]

Update Type: Add new state
Changes:

- Added "loading" state to all variants
- Updated state documentation
- Version history updated

Impact:

- 9 pages affected
- No breaking changes
- Backward compatible

Next Steps:

- Pages can optionally use new loading state
- No immediate action required
- Consider updating high-traffic pages first

</output>

---

Validation

<action> Validate update:

• ✓ Component file updated
• ✓ Changes documented
• ✓ Version history updated
• ✓ Impact assessed
• ✓ Notifications sent (if needed)
• ✓ Backward compatibility maintained

</action>

---

Error Handling

If update creates breaking change:

⚠️ Breaking Change Detected

This update will break existing usage:

- [List of breaking changes]
- Affected pages: [count]

Breaking changes require:

1. Designer confirmation
2. Migration plan
3. Page spec updates

Proceed with breaking change? (y/n)

If yes, I'll create a migration checklist.

If component file locked:

⚠️ Component file is being edited elsewhere.

Component: Button [btn-001]
Status: Locked by [user/process]

Options:

1. Wait and retry
2. Force update (may cause conflicts)
3. Cancel update

Your choice:

If update conflicts with variants:

⚠️ Update Conflict Detected

You're trying to add "loading" state to all variants,
but "navigation" variant already has a different loading implementation.

Current navigation loading: Spinner + icon animation
Proposed loading: Spinner only

Options:

1. Override navigation variant (make consistent)
2. Keep navigation variant different (document exception)
3. Cancel update

Your choice:

---

Post-Update Actions

If Breaking Change

<action> Create migration checklist: </action>

Output:

# Migration Checklist: Button [btn-001] Update

**Update:** [Description]
**Breaking Changes:** [List]
**Affected Pages:** [Count]

## Migration Steps

- [ ] Review all affected pages
- [ ] Update page specifications
- [ ] Test updated pages
- [ ] Update documentation
- [ ] Deploy changes

## Affected Pages

- [ ] Login page - [Specific changes needed]
- [ ] Signup page - [Specific changes needed]
- [ ] Dashboard - [Specific changes needed]
[... more pages]

## Rollback Plan

If issues arise:
1. Revert component file to previous version
2. Restore page specifications
3. Document issues encountered

If Major Update

<action> Suggest design system review: </action>

<output>

💡 Design System Health Check Recommended

This is a significant update to a widely-used component.

Consider reviewing:

- Component consistency across design system
- Other components that might need similar updates
- Overall design system patterns

Schedule a design system review session?

</output>

---

This operation updates a component. Changes apply to all future usage automatically.

### 10. Present MENU OPTIONS

Display: "**Select an Option:** [C] Continue or [M] Return to Activity Menu"

#### Menu Handling Logic:

- IF C: Update design log, then load, read entire file, then execute {nextStepFile}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#10-present-menu-options)

#### EXECUTION RULES:

- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects the appropriate option
- User can chat or ask questions — always respond and then redisplay menu options

## CRITICAL STEP COMPLETION NOTE

ONLY WHEN [component is updated, version history tracked, and affected pages notified], will you then load and read fully `{nextStepFile}` to execute the next step.

---

## 🚨 SYSTEM SUCCESS/FAILURE METRICS

### ✅ SUCCESS:

- Step goal achieved completely
- All instructions executed in sequence
- Results documented and presented to user
- User confirmed before proceeding
- Design log updated

### ❌ SYSTEM FAILURE:

- Skipping any instruction in the sequence
- Generating content without user input
- Jumping ahead to later steps
- Not presenting results to user
- Proceeding without user confirmation

**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

Step 8d: Add Variant

STEP GOAL:

Add a new variant to an existing component: extract variant-specific info, determine name, update component file, track usage, validate addition.

MANDATORY EXECUTION RULES (READ FIRST):

Universal Rules:

• 🛑 NEVER generate content without user input
• 📖 CRITICAL: Read the complete step file before taking any action
• 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
• 📋 YOU ARE A FACILITATOR, not a content generator
• ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config {communication_language}

Role Reinforcement:

• ✅ You are the Design System Architect guiding design system creation and maintenance
• ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
• ✅ We engage in collaborative dialogue, not command-response
• ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
• ✅ Maintain systematic and analytical tone throughout

Step-Specific Rules:

• 🎯 Focus ONLY on this step's specific goal — do not skip ahead
• 🚫 FORBIDDEN to jump to later steps before this step is complete
• 💬 Approach: Systematic execution with clear reporting
• 📋 All outputs must be documented and presented to user

EXECUTION PROTOCOLS:

• 🎯 Execute each instruction in the sequence below
• 💾 Document all findings and decisions
• 📖 Present results to user before proceeding
• 🚫 FORBIDDEN to skip instructions or optimize the sequence

CONTEXT BOUNDARIES:

• Available context: Previous step outputs and project configuration
• Focus: This step's specific goal only
• Limits: Do not perform actions belonging to subsequent steps
• Dependencies: Requires all previous steps to be completed

Sequence of Instructions (Do not deviate, skip, or optimize)

Step 1: Load Existing Component

<action> Read existing component file:

• Component ID
• Current variants
• Shared attributes
• Variant-specific attributes

</action>

Example:

Component: Button [btn-001]
Current Variants:
  - primary (submit actions)
  - secondary (cancel actions)

<output>

📖 Loaded Button [btn-001]

Current variants: 2 (primary, secondary)
Adding new variant: navigation

</output>

---

Step 2: Extract Variant-Specific Information

<action> From new component specification, extract:

• What's different from existing variants?
• What's shared with existing variants?
• Variant-specific styling
• Variant-specific behaviors
• Variant-specific states (if any)

</action>

Example:

Shared with existing:
  - Size: medium
  - Shape: rounded
  - Base states: default, hover, active, disabled

Different from existing:
  - Has icon (arrow-right)
  - Has loading state
  - Icon animation on hover
  - Purpose: navigation vs submission

---

Step 3: Determine Variant Name

<action> Generate descriptive variant name:

• Based on purpose or visual distinction
• Consistent with existing variant naming
• Clear and semantic

</action>

Examples:

Purpose-based:
- navigation (for navigation actions)
- destructive (for delete/remove actions)
- success (for positive confirmations)

Visual-based:
- outlined (border, no fill)
- ghost (transparent background)
- large (bigger size)

Context-based:
- header (used in headers)
- footer (used in footers)
- inline (used inline with text)

<ask>

Suggested variant name: "navigation"

This variant is for navigation actions (continue, next, proceed).

Is this name clear and appropriate? (y/n)
Or suggest alternative name:

</ask>

---

Step 4: Update Component File

<action> Add variant to component definition: </action>

Update Variants Section

Before:

## Variants

- **primary** - Main call-to-action (submit, save, continue)
- **secondary** - Secondary actions (cancel, back)

After:

## Variants

- **primary** - Main call-to-action (submit, save, continue)
- **secondary** - Secondary actions (cancel, back)
- **navigation** - Navigation actions (next, proceed, continue) ← Added

Add Variant-Specific Styling

Add section:

### Variant-Specific Styling

**Primary:**

- Background: blue-600
- Icon: none
- Loading: spinner only

**Secondary:**

- Background: gray-200
- Text: gray-900
- Icon: none

**Navigation:** ← Added

- Background: blue-600
- Icon: arrow-right
- Loading: spinner + icon
- Hover: icon shifts right

Update States (if variant has unique states)

If navigation variant has loading state but others don't:

## States

**Shared States (all variants):**

- default
- hover
- active
- disabled

**Variant-Specific States:**

**Navigation:**

- loading (shows spinner, disables interaction)

---

Step 5: Update Usage Tracking

<action> Track new variant usage: </action>

Add to component file:

## Variant Usage

**Primary:** 5 pages
**Secondary:** 3 pages
**Navigation:** 1 page ← Added

**Navigation variant used in:**

- Onboarding page (continue button)

---

Step 6: Update Component Complexity Note

<action> Add note about variant count: </action>

If this is 3rd+ variant:

## Notes

This component now has 3 variants. Consider:

- Are all variants necessary?
- Should any variants be separate components?
- Is the component becoming too complex?

Review component organization when reaching 5+ variants.

---

Step 7: Validate Variant Addition

<action> Check for potential issues: </action>

Variant Explosion Check:

⚠️ Variant Count: 3

This is manageable. Monitor for variant explosion as more are added.

Recommended maximum: 5 variants per component

Consistency Check:

✓ New variant consistent with existing variants
✓ Naming convention followed
✓ Shared attributes maintained

Complexity Check:

⚠️ Navigation variant adds loading state not present in other variants.

This increases component complexity. Consider:
- Should loading state be shared across all variants?
- Or is it truly navigation-specific?

Current approach: Variant-specific (acceptable)

---

Step 8: Update Component Version

<action> Track component changes: </action>

Update version history:

## Version History

**Created:** 2024-12-01
**Last Updated:** 2024-12-09

**Changes:**

- 2024-12-01: Created component with primary and secondary variants
- 2024-12-09: Added navigation variant ← Added

---

Step 9: Create Component Reference

<action> Generate reference for page spec: </action>

Output:

component_reference:
  id: btn-001
  name: Button
  variant: navigation  ← New variant
  file: D-Design-System/components/button.md

---

Step 10: Complete

<output>

✅ Variant Added: Button.navigation [btn-001]

Component: Button [btn-001]
New Variant: navigation
Total Variants: 3 (primary, secondary, navigation)

Component file updated:

- Variant added to list
- Variant-specific styling documented
- Usage tracking added
- Version history updated

Reference ready for page spec.

Next: Return to Phase 4 to complete page specification

</output>

---

Designer Guidance

<output>

💡 Variant Management Tips:

**Current Status:**

- Component: Button [btn-001]
- Variants: 3
- Status: Healthy

**Watch for:**

- 5+ variants → Consider splitting component
- Variants with very different purposes → Might need separate components
- Variants rarely used together → Might indicate separate components

**Best Practices:**

- Keep variants related (same base purpose)
- Use clear, semantic variant names
- Document when to use each variant
- Review variant list periodically

You can always refactor later if needed!

</output>

---

Validation

<action> Validate variant addition:

• ✓ Variant added to component file
• ✓ Variant-specific attributes documented
• ✓ Usage tracking updated
• ✓ Version history updated
• ✓ Reference generated
• ✓ Complexity checked

</action>

---

Error Handling

If variant name conflicts:

⚠️ Variant "navigation" already exists in Button [btn-001].

This might mean:

1. You're trying to add a duplicate
2. The existing variant should be updated
3. A different variant name is needed

Current navigation variant:
[Show existing variant details]

Options:

1. Update existing variant
2. Choose different name
3. Cancel

Your choice:

If component file not found:

❌ Error: Component file not found.

Component ID: btn-001
Expected file: D-Design-System/components/button.md

This shouldn't happen. Possible causes:

- File was deleted
- Component ID is incorrect
- Design system structure corrupted

Would you like to:

1. Create component as new
2. Specify correct component ID
3. Cancel

Your choice:

If variant too different:

⚠️ Warning: High Divergence Detected

The new variant is very different from existing variants:

- Different core purpose
- Different visual structure
- Different behavioral patterns

Similarity to existing variants: 35%

This might be better as a separate component.

Options:

1. Add as variant anyway
2. Create as new component instead
3. Review differences in detail

Your choice:

---

Post-Addition Review

<action> After adding variant, check component health: </action>

Component Health Check:

📊 Component Health: Button [btn-001]

Variants: 3
Complexity: Medium
Consistency: High
Usage: 9 pages

Health Status: ✅ Healthy

Recommendations:

- Document variant selection guidelines
- Consider adding variant usage examples
- Monitor for variant explosion

---

This operation adds a variant. Return to Phase 4 with component reference.

### 11. Present MENU OPTIONS

Display: "**Select an Option:** [C] Continue to Generate Catalog or [M] Return to Activity Menu"

#### Menu Handling Logic:

- IF C: Update design log, then load, read entire file, then execute {nextStepFile}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#11-present-menu-options)

#### EXECUTION RULES:

- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects the appropriate option
- User can chat or ask questions — always respond and then redisplay menu options

## CRITICAL STEP COMPLETION NOTE

ONLY WHEN [variant is added, component file updated, and usage tracked], will you then load and read fully `{nextStepFile}` to execute the next step.

---

## 🚨 SYSTEM SUCCESS/FAILURE METRICS

### ✅ SUCCESS:

- Step goal achieved completely
- All instructions executed in sequence
- Results documented and presented to user
- User confirmed before proceeding
- Design log updated

### ❌ SYSTEM FAILURE:

- Skipping any instruction in the sequence
- Generating content without user input
- Jumping ahead to later steps
- Not presenting results to user
- Proceeding without user confirmation

**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

Component Library Configuration

Library: [Library Name] Version: [Version] Last Updated: [Date]

---

Installation

[Installation commands]

---

Component Mappings

Format: WDS Component → Library Component

Interactive Components

• Button [btn-001] → shadcn/ui Button
• [More mappings]

Form Components

• Input Field [inp-001] → shadcn/ui Input
• [More mappings]

---

Theme Configuration

{
  "colors": {
    "primary": "#2563eb",
    "secondary": "#64748b"
  },
  "typography": {
    "fontFamily": "Inter, sans-serif"
  },
  "spacing": {
    "unit": "0.25rem"
  },
  "borderRadius": {
    "default": "0.375rem"
  }
}

---

Customizations

[Document any customizations from library defaults]

---

Library Documentation

Official Docs: [Link] Component Gallery: [Link] GitHub: [Link]

[Component Name] [[component-id]]

Type: [Interactive/Form/Layout/Content/Feedback/Navigation] Category: [Specific category] Purpose: [Brief description]

---

Overview

[Component description and when to use it]

---

Variants

[List variants if any, or state "This component has no variants"]

---

States

Required States:

• default
• [other required states]

Optional States:

• [optional states if any]

State Descriptions: [Describe each state]

---

Styling

Visual Properties

Size: [values] Shape: [values] Colors: [values] Typography: [values] Spacing: [values]

Design Tokens

[Token definitions]

Figma Reference

[If Mode B - Custom Design System]

Library Component

[If Mode C - Component Library]

---

Behavior

Interactions

[Describe interactions]

Animations

[Describe animations if any]

---

Accessibility

ARIA Attributes: [List ARIA attributes]

Keyboard Support: [List keyboard shortcuts]

Screen Reader: [How screen readers announce this]

---

Usage

When to Use

[Guidelines]

When Not to Use

[Guidelines]

Best Practices

• [Practice 1]
• [Practice 2]

---

Used In

Pages: [count]

Examples:

• [Page] - [Usage]

---

Related Components

[Related components if any]

---

Version History

Created: [Date] Last Updated: [Date]

Changes:

• [Date]: [Change]

---

Notes

[Additional notes]