bi-agents/_bmad/wds/workflows/7-design-system/steps-c/step-08a-initialize-design-system.md

name, description, nextStepFile

name	description	nextStepFile
step-08a-initialize-design-system	Create design system folder structure and initialize for the first component	./step-08b-create-new-component.md

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

``` 🎉 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`

```markdown
# 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

Create Figma mappings file:

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

Create component library config:

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

# 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

```json
{
  "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`

```markdown
# 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

Route to create-new-component operation: - Pass component specification - Generate first component ID - Create component file

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

---

Step 7: Generate Initial Catalog

Create interactive HTML catalog:

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

Mark design system as initialized:

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

---

Validation

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

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

``` 💡 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

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.