step-08a-initialize-design-system.md 11 KB
name: 'step-08a-initialize-design-system' description: 'Create design system folder structure and initialize for the first component'
File References
nextStepFile: './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] ```Step 2: Create Folder Structure
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)
Step 3: Create Design Tokens Placeholder
Create initial design tokens file:
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`
markdown
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:
- Select component in Figma
- Right-click → Copy link to selection
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 Configurationjson
{ "colors": {}, "typography": {}, "spacing": {}, "borderRadius": {} }
````
[To be updated as design system grows]
## Installation Instructions
bash [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! ```Return to Workflow
Return to design system router:
- Signal initialization complete
- Pass first component reference
- Continue with component addition
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.