docs: update all documentation and add AI tooling configs
- Rewrite README.md with current architecture, features and stack - Update docs/API.md with all current endpoints (corporate, BI, client 360) - Update docs/ARCHITECTURE.md with cache, modular queries, services, ETL - Update docs/GUIA-USUARIO.md for all roles (admin, corporate, agente) - Add docs/INDEX.md documentation index - Add PROJETO.md comprehensive project reference - Add BI-CCC-Implementation-Guide.md - Include AI agent configs (.claude, .agents, .gemini, _bmad) - Add netbird VPN configuration - Add status report Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
318
_bmad/wds/data/design-system/component-boundaries.md
Normal file
318
_bmad/wds/data/design-system/component-boundaries.md
Normal file
@@ -0,0 +1,318 @@
|
||||
# Component Boundaries
|
||||
|
||||
**Purpose:** Guidelines for determining what constitutes a component.
|
||||
|
||||
**Referenced by:** Design system router, assessment flow
|
||||
|
||||
---
|
||||
|
||||
## The Core Question
|
||||
|
||||
**"Is this one component or multiple components?"**
|
||||
|
||||
This is the most common design system challenge.
|
||||
|
||||
---
|
||||
|
||||
## Guiding Principles
|
||||
|
||||
### Principle 1: Single Responsibility
|
||||
|
||||
**A component should do one thing well.**
|
||||
|
||||
✅ **Good:** Button component triggers actions
|
||||
❌ **Bad:** Button component that also handles forms, navigation, and modals
|
||||
|
||||
### Principle 2: Reusability
|
||||
|
||||
**A component should be reusable across contexts.**
|
||||
|
||||
✅ **Good:** Input Field used in login, signup, profile forms
|
||||
❌ **Bad:** Login-Specific Input Field that only works on login page
|
||||
|
||||
### Principle 3: Independence
|
||||
|
||||
**A component should work independently.**
|
||||
|
||||
✅ **Good:** Card component that can contain any content
|
||||
❌ **Bad:** Card component that requires specific parent container
|
||||
|
||||
---
|
||||
|
||||
## Common Boundary Questions
|
||||
|
||||
### Q1: Icon in Button
|
||||
|
||||
**Question:** Is the icon part of the button or separate?
|
||||
|
||||
**Answer:** Depends on usage:
|
||||
|
||||
**Part of Button (Variant):**
|
||||
|
||||
```yaml
|
||||
Button Component:
|
||||
variants:
|
||||
- with-icon-left
|
||||
- with-icon-right
|
||||
- icon-only
|
||||
```
|
||||
|
||||
**When:** Icon is always the same type (e.g., always arrow for navigation)
|
||||
|
||||
**Separate Components:**
|
||||
|
||||
```yaml
|
||||
Button Component: (text only)
|
||||
Icon Component: (standalone)
|
||||
Composition: Button + Icon
|
||||
```
|
||||
|
||||
**When:** Icons vary widely, button can exist without icon
|
||||
|
||||
**Recommendation:** Start with variant, split if complexity grows.
|
||||
|
||||
---
|
||||
|
||||
### Q2: Label with Input
|
||||
|
||||
**Question:** Is the label part of the input or separate?
|
||||
|
||||
**Answer:** Usually part of Input Field component:
|
||||
|
||||
```yaml
|
||||
Input Field Component:
|
||||
includes:
|
||||
- Label
|
||||
- Input element
|
||||
- Helper text
|
||||
- Error message
|
||||
```
|
||||
|
||||
**Reason:** These always appear together in forms, form a semantic unit.
|
||||
|
||||
---
|
||||
|
||||
### Q3: Card with Button
|
||||
|
||||
**Question:** Is the button part of the card?
|
||||
|
||||
**Answer:** Usually separate:
|
||||
|
||||
```yaml
|
||||
Card Component: (container)
|
||||
Button Component: (action)
|
||||
Composition: Card contains Button
|
||||
```
|
||||
|
||||
**Reason:** Card is a container, button is an action. Different purposes.
|
||||
|
||||
---
|
||||
|
||||
### Q4: Navigation Bar Items
|
||||
|
||||
**Question:** Is each nav item a component?
|
||||
|
||||
**Answer:** Depends on complexity:
|
||||
|
||||
**Simple (Single Component):**
|
||||
|
||||
```yaml
|
||||
Navigation Bar Component:
|
||||
includes: All nav items as configuration
|
||||
```
|
||||
|
||||
**Complex (Composition):**
|
||||
|
||||
```yaml
|
||||
Navigation Bar: (container)
|
||||
Navigation Item: (individual item)
|
||||
Composition: Nav Bar contains Nav Items
|
||||
```
|
||||
|
||||
**Threshold:** If nav items have complex individual behavior, split them.
|
||||
|
||||
---
|
||||
|
||||
## Decision Framework
|
||||
|
||||
### Step 1: Ask These Questions
|
||||
|
||||
1. **Can it exist independently?**
|
||||
- Yes → Probably separate component
|
||||
- No → Probably part of parent
|
||||
|
||||
2. **Does it have its own states/behaviors?**
|
||||
- Yes → Probably separate component
|
||||
- No → Probably part of parent
|
||||
|
||||
3. **Is it reused in different contexts?**
|
||||
- Yes → Definitely separate component
|
||||
- No → Could be part of parent
|
||||
|
||||
4. **Does it have a clear single purpose?**
|
||||
- Yes → Good component candidate
|
||||
- No → Might need to split further
|
||||
|
||||
### Step 2: Consider Complexity
|
||||
|
||||
**Low Complexity:** Keep together
|
||||
|
||||
- Icon in button
|
||||
- Label with input
|
||||
- Simple list items
|
||||
|
||||
**High Complexity:** Split apart
|
||||
|
||||
- Complex nested structures
|
||||
- Independent behaviors
|
||||
- Different lifecycle
|
||||
|
||||
### Step 3: Think About Maintenance
|
||||
|
||||
**Together:**
|
||||
|
||||
- ✅ Easier to keep consistent
|
||||
- ❌ Component becomes complex
|
||||
|
||||
**Apart:**
|
||||
|
||||
- ✅ Simpler components
|
||||
- ❌ More components to manage
|
||||
|
||||
---
|
||||
|
||||
## Composition Patterns
|
||||
|
||||
### Pattern 1: Container + Content
|
||||
|
||||
**Container provides structure, content is flexible.**
|
||||
|
||||
```yaml
|
||||
Card Component: (container)
|
||||
- Can contain: text, images, buttons, etc.
|
||||
- Provides: padding, border, shadow
|
||||
```
|
||||
|
||||
### Pattern 2: Compound Component
|
||||
|
||||
**Multiple parts that work together.**
|
||||
|
||||
```yaml
|
||||
Accordion Component:
|
||||
- Accordion Container
|
||||
- Accordion Item
|
||||
- Accordion Header
|
||||
- Accordion Content
|
||||
```
|
||||
|
||||
### Pattern 3: Atomic Component
|
||||
|
||||
**Single, indivisible unit.**
|
||||
|
||||
```yaml
|
||||
Button Component:
|
||||
- Cannot be broken down further
|
||||
- Self-contained
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Red Flags
|
||||
|
||||
### Too Many Variants
|
||||
|
||||
**Warning:** Component has 10+ variants
|
||||
|
||||
**Problem:** Probably multiple components disguised as variants
|
||||
|
||||
**Solution:** Split into separate components based on purpose
|
||||
|
||||
### Conditional Complexity
|
||||
|
||||
**Warning:** Component has many "if this, then that" rules
|
||||
|
||||
**Problem:** Component doing too many things
|
||||
|
||||
**Solution:** Split into simpler, focused components
|
||||
|
||||
### Context-Specific Behavior
|
||||
|
||||
**Warning:** Component behaves differently in different contexts
|
||||
|
||||
**Problem:** Not truly reusable
|
||||
|
||||
**Solution:** Create context-specific components or use composition
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Button
|
||||
|
||||
**One Component:**
|
||||
|
||||
```yaml
|
||||
Button:
|
||||
variants: primary, secondary, ghost
|
||||
states: default, hover, active, disabled, loading
|
||||
```
|
||||
|
||||
**Reason:** All variants serve same purpose (trigger action), share behavior
|
||||
|
||||
### Example 2: Input Types
|
||||
|
||||
**Multiple Components:**
|
||||
|
||||
```yaml
|
||||
Text Input: (text entry)
|
||||
Select Dropdown: (choose from list)
|
||||
Checkbox: (toggle option)
|
||||
Radio: (choose one)
|
||||
```
|
||||
|
||||
**Reason:** Different purposes, different behaviors, different HTML elements
|
||||
|
||||
### Example 3: Modal
|
||||
|
||||
**Compound Component:**
|
||||
|
||||
```yaml
|
||||
Modal: (overlay + container)
|
||||
Modal Header: (title + close button)
|
||||
Modal Body: (content area)
|
||||
Modal Footer: (actions)
|
||||
```
|
||||
|
||||
**Reason:** Complex structure, but parts always used together
|
||||
|
||||
---
|
||||
|
||||
## When in Doubt
|
||||
|
||||
**Start simple:**
|
||||
|
||||
1. Create as single component
|
||||
2. Add variants as needed
|
||||
3. Split when complexity becomes painful
|
||||
|
||||
**It's easier to split later than merge later.**
|
||||
|
||||
---
|
||||
|
||||
## Company Customization
|
||||
|
||||
Companies can define their own boundary rules:
|
||||
|
||||
```markdown
|
||||
# Acme Corp Component Boundaries
|
||||
|
||||
**Rule 1:** Icons are always separate components
|
||||
**Rule 2:** Form fields include labels (never separate)
|
||||
**Rule 3:** Cards never include actions (composition only)
|
||||
```
|
||||
|
||||
**Consistency within a company matters more than universal rules.**
|
||||
|
||||
---
|
||||
|
||||
**Use this guide when the design system router detects similarity and you need to decide: same component, variant, or new component?**
|
||||
697
_bmad/wds/data/design-system/figma-component-structure.md
Normal file
697
_bmad/wds/data/design-system/figma-component-structure.md
Normal file
@@ -0,0 +1,697 @@
|
||||
# Figma Component Structure for WDS
|
||||
|
||||
**Purpose:** Guidelines for organizing and structuring components in Figma for seamless WDS integration.
|
||||
|
||||
**Referenced by:** Mode B (Custom Design System) workflows
|
||||
|
||||
---
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Figma components should mirror WDS component structure** to enable seamless synchronization and specification generation.
|
||||
|
||||
```
|
||||
Figma Component → WDS Component Specification → React Implementation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Component Organization in Figma
|
||||
|
||||
### File Structure
|
||||
|
||||
**Recommended Figma file organization:**
|
||||
|
||||
```
|
||||
Design System File (Figma)
|
||||
├── 📄 Cover (project info)
|
||||
├── 🎨 Foundation
|
||||
│ ├── Colors
|
||||
│ ├── Typography
|
||||
│ ├── Spacing
|
||||
│ └── Effects
|
||||
├── ⚛️ Components
|
||||
│ ├── Buttons
|
||||
│ ├── Inputs
|
||||
│ ├── Cards
|
||||
│ └── [other component types]
|
||||
└── 📱 Examples
|
||||
└── Component usage examples
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- Clear organization
|
||||
- Easy navigation
|
||||
- Matches WDS structure
|
||||
- Facilitates MCP integration
|
||||
|
||||
---
|
||||
|
||||
## Component Naming Convention
|
||||
|
||||
### Format
|
||||
|
||||
**Pattern:** `[ComponentType]/[ComponentName]`
|
||||
|
||||
**Examples:**
|
||||
|
||||
```
|
||||
Button/Primary
|
||||
Button/Secondary
|
||||
Button/Ghost
|
||||
Input/Text
|
||||
Input/Email
|
||||
Card/Profile
|
||||
Card/Content
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
|
||||
- Use forward slash for hierarchy
|
||||
- Title case for names
|
||||
- Match WDS component names
|
||||
- Consistent across all components
|
||||
|
||||
---
|
||||
|
||||
## Component Properties
|
||||
|
||||
### Required Properties
|
||||
|
||||
**Every component must have:**
|
||||
|
||||
1. **Description**
|
||||
- Component purpose
|
||||
- When to use
|
||||
- WDS component ID (e.g., "btn-001")
|
||||
|
||||
2. **Variants**
|
||||
- Organized by property
|
||||
- Clear naming
|
||||
- All states included
|
||||
|
||||
3. **Auto Layout**
|
||||
- Proper spacing
|
||||
- Responsive behavior
|
||||
- Padding/gap values
|
||||
|
||||
**Example Description:**
|
||||
|
||||
```
|
||||
Button Primary [btn-001]
|
||||
|
||||
Primary action button for main user actions.
|
||||
Use for: Submit forms, confirm actions, proceed to next step.
|
||||
|
||||
WDS Component: Button.primary [btn-001]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Variant Structure
|
||||
|
||||
### Organizing Variants
|
||||
|
||||
**Use Figma's variant properties:**
|
||||
|
||||
**Property 1: Type** (variant)
|
||||
|
||||
- Primary
|
||||
- Secondary
|
||||
- Ghost
|
||||
- Outline
|
||||
|
||||
**Property 2: Size**
|
||||
|
||||
- Small
|
||||
- Medium
|
||||
- Large
|
||||
|
||||
**Property 3: State**
|
||||
|
||||
- Default
|
||||
- Hover
|
||||
- Active
|
||||
- Disabled
|
||||
- Loading
|
||||
|
||||
**Property 4: Icon** (optional)
|
||||
|
||||
- None
|
||||
- Left
|
||||
- Right
|
||||
- Only
|
||||
|
||||
**Result:** Figma generates all combinations automatically
|
||||
|
||||
---
|
||||
|
||||
### Variant Naming
|
||||
|
||||
**Format:** `Property=Value`
|
||||
|
||||
**Examples:**
|
||||
|
||||
```
|
||||
Type=Primary, Size=Medium, State=Default
|
||||
Type=Primary, Size=Medium, State=Hover
|
||||
Type=Secondary, Size=Large, State=Disabled
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- Clear property structure
|
||||
- Easy to find specific variants
|
||||
- MCP can parse programmatically
|
||||
- Matches WDS variant system
|
||||
|
||||
---
|
||||
|
||||
## State Documentation
|
||||
|
||||
### Required States
|
||||
|
||||
**Interactive Components (Buttons, Links):**
|
||||
|
||||
- Default
|
||||
- Hover
|
||||
- Active (pressed)
|
||||
- Disabled
|
||||
- Focus (optional)
|
||||
- Loading (optional)
|
||||
|
||||
**Form Components (Inputs, Selects):**
|
||||
|
||||
- Default (empty)
|
||||
- Focus (active)
|
||||
- Filled (has content)
|
||||
- Disabled
|
||||
- Error
|
||||
- Success (optional)
|
||||
|
||||
**Feedback Components (Alerts, Toasts):**
|
||||
|
||||
- Default
|
||||
- Success
|
||||
- Error
|
||||
- Warning
|
||||
- Info
|
||||
|
||||
---
|
||||
|
||||
### State Visual Indicators
|
||||
|
||||
**Document state changes:**
|
||||
|
||||
**Hover:**
|
||||
|
||||
- Background color change
|
||||
- Border change
|
||||
- Shadow change
|
||||
- Scale change
|
||||
- Cursor change
|
||||
|
||||
**Active:**
|
||||
|
||||
- Background color (darker)
|
||||
- Scale (slightly smaller)
|
||||
- Shadow (reduced)
|
||||
|
||||
**Disabled:**
|
||||
|
||||
- Opacity (0.5-0.6)
|
||||
- Cursor (not-allowed)
|
||||
- Grayscale (optional)
|
||||
|
||||
**Loading:**
|
||||
|
||||
- Spinner/progress indicator
|
||||
- Disabled interaction
|
||||
- Loading text
|
||||
|
||||
---
|
||||
|
||||
## Design Tokens in Figma
|
||||
|
||||
### Using Figma Variables
|
||||
|
||||
**Map Figma variables to WDS tokens:**
|
||||
|
||||
**Colors:**
|
||||
|
||||
```
|
||||
Figma Variable → WDS Token
|
||||
primary/500 → color-primary-500
|
||||
gray/900 → color-gray-900
|
||||
success/600 → color-success-600
|
||||
```
|
||||
|
||||
**Typography:**
|
||||
|
||||
```
|
||||
Figma Style → WDS Token
|
||||
Text/Display → text-display
|
||||
Text/Heading-1 → text-heading-1
|
||||
Text/Body → text-body
|
||||
```
|
||||
|
||||
**Spacing:**
|
||||
|
||||
```
|
||||
Figma Variable → WDS Token
|
||||
spacing/2 → spacing-2
|
||||
spacing/4 → spacing-4
|
||||
spacing/8 → spacing-8
|
||||
```
|
||||
|
||||
**Effects:**
|
||||
|
||||
```
|
||||
Figma Effect → WDS Token
|
||||
shadow/sm → shadow-sm
|
||||
shadow/md → shadow-md
|
||||
radius/md → radius-md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Component Documentation
|
||||
|
||||
### Component Description Template
|
||||
|
||||
```
|
||||
[Component Name] [component-id]
|
||||
|
||||
**Purpose:** [Brief description]
|
||||
|
||||
**When to use:**
|
||||
- [Use case 1]
|
||||
- [Use case 2]
|
||||
|
||||
**When not to use:**
|
||||
- [Anti-pattern 1]
|
||||
- [Anti-pattern 2]
|
||||
|
||||
**WDS Component:** [ComponentType].[variant] [component-id]
|
||||
|
||||
**Variants:** [List of variants]
|
||||
**States:** [List of states]
|
||||
**Size:** [Available sizes]
|
||||
|
||||
**Accessibility:**
|
||||
- [ARIA attributes]
|
||||
- [Keyboard support]
|
||||
- [Screen reader behavior]
|
||||
```
|
||||
|
||||
**Example:**
|
||||
|
||||
```
|
||||
Button Primary [btn-001]
|
||||
|
||||
**Purpose:** Trigger primary actions in the interface
|
||||
|
||||
**When to use:**
|
||||
- Submit forms
|
||||
- Confirm important actions
|
||||
- Proceed to next step
|
||||
- Primary call-to-action
|
||||
|
||||
**When not to use:**
|
||||
- Secondary actions (use Button Secondary)
|
||||
- Destructive actions (use Button Destructive)
|
||||
- Navigation (use Link component)
|
||||
|
||||
**WDS Component:** Button.primary [btn-001]
|
||||
|
||||
**Variants:** primary, secondary, ghost, outline
|
||||
**States:** default, hover, active, disabled, loading
|
||||
**Size:** small, medium, large
|
||||
|
||||
**Accessibility:**
|
||||
- role="button"
|
||||
- aria-disabled when disabled
|
||||
- aria-busy when loading
|
||||
- Keyboard: Enter/Space to activate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Auto Layout Best Practices
|
||||
|
||||
### Spacing
|
||||
|
||||
**Use consistent spacing values:**
|
||||
|
||||
- Padding: 8px, 12px, 16px, 24px
|
||||
- Gap: 4px, 8px, 12px, 16px
|
||||
- Match WDS spacing tokens
|
||||
|
||||
**Auto Layout Settings:**
|
||||
|
||||
- Horizontal/Vertical alignment
|
||||
- Padding (all sides or specific)
|
||||
- Gap between items
|
||||
- Resizing behavior
|
||||
|
||||
---
|
||||
|
||||
### Resizing Behavior
|
||||
|
||||
**Set appropriate constraints:**
|
||||
|
||||
**Buttons:**
|
||||
|
||||
- Hug contents (width)
|
||||
- Fixed height
|
||||
- Min width for touch targets (44px)
|
||||
|
||||
**Inputs:**
|
||||
|
||||
- Fill container (width)
|
||||
- Fixed height (40-48px)
|
||||
- Responsive to content
|
||||
|
||||
**Cards:**
|
||||
|
||||
- Fill container or fixed width
|
||||
- Hug contents (height)
|
||||
- Responsive to content
|
||||
|
||||
---
|
||||
|
||||
## Component Instances
|
||||
|
||||
### Creating Instances
|
||||
|
||||
**Best practices:**
|
||||
|
||||
- Always use component instances (not detached)
|
||||
- Override only necessary properties
|
||||
- Maintain connection to main component
|
||||
- Document overrides if needed
|
||||
|
||||
**Overridable Properties:**
|
||||
|
||||
- Text content
|
||||
- Icons
|
||||
- Colors (if using variables)
|
||||
- Spacing (if needed)
|
||||
|
||||
**Non-Overridable:**
|
||||
|
||||
- Structure
|
||||
- Layout
|
||||
- Core styling
|
||||
- States
|
||||
|
||||
---
|
||||
|
||||
## Figma to WDS Mapping
|
||||
|
||||
### Component ID System
|
||||
|
||||
**Add WDS component ID to Figma:**
|
||||
|
||||
**In component description:**
|
||||
|
||||
```
|
||||
Button Primary [btn-001]
|
||||
```
|
||||
|
||||
**In component name:**
|
||||
|
||||
```
|
||||
Button/Primary [btn-001]
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- Easy to find components
|
||||
- Clear WDS mapping
|
||||
- MCP can extract ID
|
||||
- Bidirectional sync
|
||||
|
||||
---
|
||||
|
||||
### Node ID Tracking
|
||||
|
||||
**Figma generates unique node IDs:**
|
||||
|
||||
**Format:**
|
||||
|
||||
```
|
||||
figma://file/[file-id]/node/[node-id]
|
||||
```
|
||||
|
||||
**How to get node ID:**
|
||||
|
||||
1. Select component in Figma
|
||||
2. Right-click → "Copy link to selection"
|
||||
3. Extract node ID from URL
|
||||
|
||||
**Store in WDS:**
|
||||
|
||||
```yaml
|
||||
# D-Design-System/figma-mappings.md
|
||||
Button [btn-001] → figma://file/abc123/node/456:789
|
||||
Input [inp-001] → figma://file/abc123/node/456:790
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Sync Workflow
|
||||
|
||||
### Figma → WDS
|
||||
|
||||
**When component is created/updated in Figma:**
|
||||
|
||||
1. Designer creates/updates component
|
||||
2. Designer adds WDS component ID to description
|
||||
3. MCP reads component via Figma API
|
||||
4. MCP extracts:
|
||||
- Component structure
|
||||
- Variants
|
||||
- States
|
||||
- Properties
|
||||
- Design tokens used
|
||||
5. MCP generates/updates WDS specification
|
||||
6. Designer reviews and confirms
|
||||
|
||||
---
|
||||
|
||||
### WDS → Figma
|
||||
|
||||
**When specification is updated in WDS:**
|
||||
|
||||
1. Specification updated in WDS
|
||||
2. Designer notified of changes
|
||||
3. Designer updates Figma component
|
||||
4. Designer confirms sync
|
||||
5. Node ID verified/updated
|
||||
|
||||
**Note:** This is semi-automated. Full automation requires Figma API write access.
|
||||
|
||||
---
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
### Component Creation
|
||||
|
||||
- [ ] Component name follows convention
|
||||
- [ ] WDS component ID in description
|
||||
- [ ] All variants defined
|
||||
- [ ] All states documented
|
||||
- [ ] Auto layout properly configured
|
||||
- [ ] Design tokens used (not hardcoded values)
|
||||
- [ ] Accessibility notes included
|
||||
- [ ] Usage guidelines documented
|
||||
|
||||
### Variant Structure
|
||||
|
||||
- [ ] Variants organized by properties
|
||||
- [ ] Property names clear and consistent
|
||||
- [ ] All combinations make sense
|
||||
- [ ] No redundant variants
|
||||
- [ ] States properly differentiated
|
||||
|
||||
### Documentation
|
||||
|
||||
- [ ] Purpose clearly stated
|
||||
- [ ] When to use documented
|
||||
- [ ] When not to use documented
|
||||
- [ ] Accessibility requirements noted
|
||||
- [ ] Examples provided
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
### ❌ Mistake 1: Hardcoded Values
|
||||
|
||||
**Wrong:**
|
||||
|
||||
```
|
||||
Background: #2563eb (hardcoded hex)
|
||||
Padding: 16px (hardcoded value)
|
||||
```
|
||||
|
||||
**Right:**
|
||||
|
||||
```
|
||||
Background: primary/600 (variable)
|
||||
Padding: spacing/4 (variable)
|
||||
```
|
||||
|
||||
### ❌ Mistake 2: Detached Instances
|
||||
|
||||
**Wrong:**
|
||||
|
||||
- Detaching component instances
|
||||
- Losing connection to main component
|
||||
- Manual updates required
|
||||
|
||||
**Right:**
|
||||
|
||||
- Always use instances
|
||||
- Override only necessary properties
|
||||
- Maintain component connection
|
||||
|
||||
### ❌ Mistake 3: Inconsistent Naming
|
||||
|
||||
**Wrong:**
|
||||
|
||||
```
|
||||
btn-primary
|
||||
ButtonSecondary
|
||||
button_ghost
|
||||
```
|
||||
|
||||
**Right:**
|
||||
|
||||
```
|
||||
Button/Primary
|
||||
Button/Secondary
|
||||
Button/Ghost
|
||||
```
|
||||
|
||||
### ❌ Mistake 4: Missing States
|
||||
|
||||
**Wrong:**
|
||||
|
||||
- Only default state
|
||||
- No hover/active states
|
||||
- No disabled state
|
||||
|
||||
**Right:**
|
||||
|
||||
- All required states
|
||||
- Visual differentiation
|
||||
- State transitions documented
|
||||
|
||||
### ❌ Mistake 5: No WDS Component ID
|
||||
|
||||
**Wrong:**
|
||||
|
||||
```
|
||||
Button Primary
|
||||
(no component ID)
|
||||
```
|
||||
|
||||
**Right:**
|
||||
|
||||
```
|
||||
Button Primary [btn-001]
|
||||
(clear WDS mapping)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Button Component in Figma
|
||||
|
||||
**Component Name:** `Button/Primary [btn-001]`
|
||||
|
||||
**Description:**
|
||||
|
||||
```
|
||||
Button Primary [btn-001]
|
||||
|
||||
Primary action button for main user actions.
|
||||
|
||||
WDS Component: Button.primary [btn-001]
|
||||
Variants: primary, secondary, ghost, outline
|
||||
States: default, hover, active, disabled, loading
|
||||
Sizes: small, medium, large
|
||||
```
|
||||
|
||||
**Variants:**
|
||||
|
||||
```
|
||||
Type=Primary, Size=Medium, State=Default
|
||||
Type=Primary, Size=Medium, State=Hover
|
||||
Type=Primary, Size=Medium, State=Active
|
||||
Type=Primary, Size=Medium, State=Disabled
|
||||
Type=Primary, Size=Large, State=Default
|
||||
[... all combinations]
|
||||
```
|
||||
|
||||
**Properties:**
|
||||
|
||||
- Auto Layout: Horizontal
|
||||
- Padding: 16px (horizontal), 12px (vertical)
|
||||
- Gap: 8px (if icon)
|
||||
- Border Radius: 8px
|
||||
- Background: primary/600 (variable)
|
||||
|
||||
---
|
||||
|
||||
### Input Component in Figma
|
||||
|
||||
**Component Name:** `Input/Text [inp-001]`
|
||||
|
||||
**Description:**
|
||||
|
||||
```
|
||||
Input Text [inp-001]
|
||||
|
||||
Text input field for user data entry.
|
||||
|
||||
WDS Component: Input.text [inp-001]
|
||||
States: default, focus, filled, disabled, error, success
|
||||
```
|
||||
|
||||
**Variants:**
|
||||
|
||||
```
|
||||
State=Default
|
||||
State=Focus
|
||||
State=Filled
|
||||
State=Disabled
|
||||
State=Error
|
||||
State=Success
|
||||
```
|
||||
|
||||
**Properties:**
|
||||
|
||||
- Auto Layout: Horizontal
|
||||
- Padding: 12px
|
||||
- Height: 44px (fixed)
|
||||
- Border: 1px solid gray/300
|
||||
- Border Radius: 8px
|
||||
- Background: white
|
||||
|
||||
---
|
||||
|
||||
## Further Reading
|
||||
|
||||
- **Figma MCP Integration:** `figma-mcp-integration.md`
|
||||
- **Designer Guide:** `figma-designer-guide.md`
|
||||
- **Token Architecture:** `token-architecture.md`
|
||||
- **Component Boundaries:** `component-boundaries.md`
|
||||
|
||||
---
|
||||
|
||||
**This structure enables seamless Figma ↔ WDS integration and maintains design system consistency across tools.**
|
||||
200
_bmad/wds/data/design-system/naming-conventions.md
Normal file
200
_bmad/wds/data/design-system/naming-conventions.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# Design System Naming Conventions
|
||||
|
||||
**Purpose:** Consistent naming across design system components and tokens.
|
||||
|
||||
**Referenced by:** Component-type instructions, design system operations
|
||||
|
||||
---
|
||||
|
||||
## Component IDs
|
||||
|
||||
**Format:** `[type-prefix]-[number]`
|
||||
|
||||
**Prefixes:**
|
||||
|
||||
- btn = Button
|
||||
- inp = Input Field
|
||||
- chk = Checkbox
|
||||
- rad = Radio
|
||||
- tgl = Toggle
|
||||
- drp = Dropdown
|
||||
- mdl = Modal
|
||||
- crd = Card
|
||||
- alt = Alert
|
||||
- bdg = Badge
|
||||
- tab = Tab
|
||||
- acc = Accordion
|
||||
|
||||
**Examples:**
|
||||
|
||||
- `btn-001` = First button component
|
||||
- `inp-002` = Second input field component
|
||||
- `mdl-001` = First modal component
|
||||
|
||||
**Rules:**
|
||||
|
||||
- Always lowercase
|
||||
- Always hyphenated
|
||||
- Always zero-padded (001, not 1)
|
||||
- Sequential within type
|
||||
|
||||
---
|
||||
|
||||
## Component Names
|
||||
|
||||
**Format:** `[Type] [Descriptor]` or just `[Type]`
|
||||
|
||||
**Examples:**
|
||||
|
||||
- `Button` (generic)
|
||||
- `Navigation Button` (specific)
|
||||
- `Primary Button` (variant-focused)
|
||||
- `Icon Button` (visual-focused)
|
||||
|
||||
**Rules:**
|
||||
|
||||
- Title case
|
||||
- Descriptive but concise
|
||||
- Avoid redundancy (not "Button Button")
|
||||
|
||||
---
|
||||
|
||||
## Variant Names
|
||||
|
||||
**Format:** Lowercase, hyphenated
|
||||
|
||||
**Purpose-Based:**
|
||||
|
||||
- `primary` - Main action
|
||||
- `secondary` - Secondary action
|
||||
- `destructive` - Delete/remove
|
||||
- `success` - Positive confirmation
|
||||
- `warning` - Caution
|
||||
- `navigation` - Navigation action
|
||||
|
||||
**Visual-Based:**
|
||||
|
||||
- `outlined` - Border, no fill
|
||||
- `ghost` - Transparent background
|
||||
- `solid` - Filled background
|
||||
|
||||
**Size-Based:**
|
||||
|
||||
- `small` - Compact
|
||||
- `medium` - Default
|
||||
- `large` - Prominent
|
||||
|
||||
**Rules:**
|
||||
|
||||
- Lowercase
|
||||
- Hyphenated for multi-word
|
||||
- Semantic over visual when possible
|
||||
|
||||
---
|
||||
|
||||
## State Names
|
||||
|
||||
**Standard States:**
|
||||
|
||||
- `default` - Normal state
|
||||
- `hover` - Mouse over
|
||||
- `active` - Being clicked/pressed
|
||||
- `focus` - Keyboard focus
|
||||
- `disabled` - Cannot interact
|
||||
- `loading` - Processing
|
||||
- `error` - Error state
|
||||
- `success` - Success state
|
||||
- `warning` - Warning state
|
||||
|
||||
**Rules:**
|
||||
|
||||
- Lowercase
|
||||
- Single word preferred
|
||||
- Use standard names when possible
|
||||
|
||||
---
|
||||
|
||||
## Design Token Names
|
||||
|
||||
**Format:** `--{category}-{property}-{variant}`
|
||||
|
||||
**Color Tokens:**
|
||||
|
||||
```
|
||||
--color-primary-500
|
||||
--color-gray-900
|
||||
--color-success-600
|
||||
--color-error-500
|
||||
```
|
||||
|
||||
**Typography Tokens:**
|
||||
|
||||
```
|
||||
--text-xs
|
||||
--text-base
|
||||
--text-4xl
|
||||
--font-normal
|
||||
--font-bold
|
||||
```
|
||||
|
||||
**Spacing Tokens:**
|
||||
|
||||
```
|
||||
--spacing-1
|
||||
--spacing-4
|
||||
--spacing-8
|
||||
```
|
||||
|
||||
**Component Tokens:**
|
||||
|
||||
```
|
||||
--button-padding-x
|
||||
--input-border-color
|
||||
--card-shadow
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
|
||||
- Kebab-case
|
||||
- Hierarchical (general → specific)
|
||||
- Semantic names preferred
|
||||
|
||||
---
|
||||
|
||||
## File Names
|
||||
|
||||
**Component Files:**
|
||||
|
||||
```
|
||||
button.md
|
||||
navigation-button.md
|
||||
input-field.md
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
|
||||
- Lowercase
|
||||
- Hyphenated
|
||||
- Match component name (simplified)
|
||||
|
||||
---
|
||||
|
||||
## Folder Names
|
||||
|
||||
```
|
||||
components/
|
||||
design-tokens/
|
||||
operations/
|
||||
assessment/
|
||||
templates/
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
|
||||
- Lowercase
|
||||
- Hyphenated
|
||||
- Plural for collections
|
||||
|
||||
---
|
||||
|
||||
**Consistency in naming makes the design system easier to navigate and maintain.**
|
||||
93
_bmad/wds/data/design-system/state-management.md
Normal file
93
_bmad/wds/data/design-system/state-management.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# Component State Management
|
||||
|
||||
**Purpose:** Guidelines for defining and managing component states.
|
||||
|
||||
**Referenced by:** Component-type instructions (Button, Input, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Standard States
|
||||
|
||||
### Interactive Components (Buttons, Links)
|
||||
|
||||
**Required:**
|
||||
|
||||
- `default` - Normal, ready for interaction
|
||||
- `hover` - Mouse over component
|
||||
- `active` - Being clicked/pressed
|
||||
- `disabled` - Cannot interact
|
||||
|
||||
**Optional:**
|
||||
|
||||
- `loading` - Processing action
|
||||
- `focus` - Keyboard focus
|
||||
|
||||
### Form Components (Inputs, Selects)
|
||||
|
||||
**Required:**
|
||||
|
||||
- `default` - Empty, ready for input
|
||||
- `focus` - Active input
|
||||
- `filled` - Has content
|
||||
- `disabled` - Cannot edit
|
||||
|
||||
**Optional:**
|
||||
|
||||
- `error` - Validation failed
|
||||
- `success` - Validation passed
|
||||
- `loading` - Fetching data
|
||||
|
||||
### Feedback Components (Alerts, Toasts)
|
||||
|
||||
**Required:**
|
||||
|
||||
- `default` - Neutral information
|
||||
- `success` - Positive feedback
|
||||
- `error` - Error feedback
|
||||
- `warning` - Caution feedback
|
||||
|
||||
---
|
||||
|
||||
## State Naming
|
||||
|
||||
**Use standard names:**
|
||||
|
||||
- ✅ `hover` not `mouseover`
|
||||
- ✅ `disabled` not `inactive`
|
||||
- ✅ `loading` not `processing`
|
||||
|
||||
**Be consistent across components.**
|
||||
|
||||
---
|
||||
|
||||
## State Transitions
|
||||
|
||||
**Define how states change:**
|
||||
|
||||
```yaml
|
||||
Button States: default → hover (mouse enters)
|
||||
hover → active (mouse down)
|
||||
active → hover (mouse up)
|
||||
hover → default (mouse leaves)
|
||||
any → disabled (programmatically)
|
||||
any → loading (action triggered)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Visual Indicators
|
||||
|
||||
**Each state should be visually distinct:**
|
||||
|
||||
```yaml
|
||||
Button:
|
||||
default: blue background
|
||||
hover: darker blue + scale 1.02
|
||||
active: darkest blue + scale 0.98
|
||||
disabled: gray + opacity 0.6
|
||||
loading: disabled + spinner
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Reference this when specifying component states.**
|
||||
474
_bmad/wds/data/design-system/token-architecture.md
Normal file
474
_bmad/wds/data/design-system/token-architecture.md
Normal file
@@ -0,0 +1,474 @@
|
||||
# Design Token Architecture
|
||||
|
||||
**Purpose:** Core principles for separating semantic structure from visual style.
|
||||
|
||||
**Referenced by:** All component-type instructions
|
||||
|
||||
---
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Separate semantic structure from visual style.**
|
||||
|
||||
```
|
||||
HTML/Structure = Meaning (what it is)
|
||||
Design Tokens = Appearance (how it looks)
|
||||
|
||||
They should be independent!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Problem
|
||||
|
||||
**Bad Practice:**
|
||||
|
||||
```html
|
||||
<h2 class="text-4xl font-bold text-blue-600">Heading</h2>
|
||||
```
|
||||
|
||||
**Issues:**
|
||||
|
||||
- Visual styling mixed with semantic HTML
|
||||
- Can't change h2 appearance without changing all h2s
|
||||
- h2 means "second-level heading" but looks like "display large"
|
||||
- Breaks separation of concerns
|
||||
|
||||
---
|
||||
|
||||
## The Solution
|
||||
|
||||
**Good Practice:**
|
||||
|
||||
**HTML (Semantic):**
|
||||
|
||||
```html
|
||||
<h2 class="heading-section">Heading</h2>
|
||||
```
|
||||
|
||||
**Design Tokens (Visual):**
|
||||
|
||||
```css
|
||||
.heading-section {
|
||||
font-size: var(--text-4xl);
|
||||
font-weight: var(--font-bold);
|
||||
color: var(--color-primary-600);
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- Semantic HTML stays semantic
|
||||
- Visual style is centralized
|
||||
- Can change appearance without touching HTML
|
||||
- Clear separation of concerns
|
||||
|
||||
---
|
||||
|
||||
## Token Hierarchy
|
||||
|
||||
### Level 1: Raw Values
|
||||
|
||||
```css
|
||||
--spacing-4: 1rem;
|
||||
--color-blue-600: #2563eb;
|
||||
--font-size-4xl: 2.25rem;
|
||||
```
|
||||
|
||||
### Level 2: Semantic Tokens
|
||||
|
||||
```css
|
||||
--text-heading-large: var(--font-size-4xl);
|
||||
--color-primary: var(--color-blue-600);
|
||||
--spacing-section: var(--spacing-4);
|
||||
```
|
||||
|
||||
### Level 3: Component Tokens
|
||||
|
||||
```css
|
||||
--button-padding-x: var(--spacing-section);
|
||||
--button-color-primary: var(--color-primary);
|
||||
--heading-size-section: var(--text-heading-large);
|
||||
```
|
||||
|
||||
**Use Level 2 or 3 in components, never Level 1 directly.**
|
||||
|
||||
---
|
||||
|
||||
## Application to WDS
|
||||
|
||||
### In Page Specifications
|
||||
|
||||
**Specify semantic structure:**
|
||||
|
||||
```yaml
|
||||
Page Structure:
|
||||
- Section Heading (h2)
|
||||
- Body text (p)
|
||||
- Primary button (button)
|
||||
```
|
||||
|
||||
**NOT visual styling:**
|
||||
|
||||
```yaml
|
||||
# ❌ Don't do this
|
||||
Page Structure:
|
||||
- Large blue bold text
|
||||
- 16px gray text
|
||||
- Blue rounded button
|
||||
```
|
||||
|
||||
### In Design System
|
||||
|
||||
**Specify visual styling:**
|
||||
|
||||
```yaml
|
||||
Section Heading:
|
||||
html_element: h2
|
||||
design_token: heading-section
|
||||
|
||||
Design Token Definition:
|
||||
heading-section:
|
||||
font-size: text-4xl
|
||||
font-weight: bold
|
||||
color: primary-600
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Component-Type Instructions
|
||||
|
||||
### Text Heading Example
|
||||
|
||||
**When specifying a heading:**
|
||||
|
||||
1. **Identify semantic level** (h1-h6)
|
||||
- h1 = Page title
|
||||
- h2 = Section heading
|
||||
- h3 = Subsection heading
|
||||
- etc.
|
||||
|
||||
2. **Map to design token**
|
||||
- h1 → display-large
|
||||
- h2 → heading-section
|
||||
- h3 → heading-subsection
|
||||
|
||||
3. **Store separately**
|
||||
- Page spec: `<h2>` (semantic)
|
||||
- Design system: `heading-section` token (visual)
|
||||
|
||||
**Example Output:**
|
||||
|
||||
**Page Spec:**
|
||||
|
||||
```yaml
|
||||
Hero Section:
|
||||
heading:
|
||||
element: h2
|
||||
token: heading-section
|
||||
content: 'Welcome to Our Product'
|
||||
```
|
||||
|
||||
**Design System:**
|
||||
|
||||
```yaml
|
||||
Tokens:
|
||||
heading-section:
|
||||
font-size: 2.25rem
|
||||
font-weight: 700
|
||||
line-height: 1.2
|
||||
color: gray-900
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Button Example
|
||||
|
||||
**When specifying a button:**
|
||||
|
||||
1. **Identify semantic element**
|
||||
- `<button>` for actions
|
||||
- `<a>` for navigation (even if styled as button)
|
||||
|
||||
2. **Map to component**
|
||||
- Action → Button component
|
||||
- Navigation → Link component (button variant)
|
||||
|
||||
3. **Store separately**
|
||||
- Page spec: `<button>` + purpose
|
||||
- Design system: Button component styling
|
||||
|
||||
**Example Output:**
|
||||
|
||||
**Page Spec:**
|
||||
|
||||
```yaml
|
||||
Login Form:
|
||||
submit_button:
|
||||
element: button
|
||||
type: submit
|
||||
component: Button.primary
|
||||
label: 'Log in'
|
||||
```
|
||||
|
||||
**Design System:**
|
||||
|
||||
```yaml
|
||||
Button Component:
|
||||
variants:
|
||||
primary:
|
||||
background: primary-600
|
||||
color: white
|
||||
padding: spacing-2 spacing-4
|
||||
border-radius: radius-md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Input Field Example
|
||||
|
||||
**When specifying an input:**
|
||||
|
||||
1. **Identify semantic type**
|
||||
- `<input type="text">` for text
|
||||
- `<input type="email">` for email
|
||||
- `<input type="password">` for password
|
||||
|
||||
2. **Map to component**
|
||||
- Text input → Input Field component
|
||||
- Email input → Input Field.email variant
|
||||
|
||||
3. **Store separately**
|
||||
- Page spec: Input type + validation + labels
|
||||
- Design system: Input Field styling
|
||||
|
||||
**Example Output:**
|
||||
|
||||
**Page Spec:**
|
||||
|
||||
```yaml
|
||||
Login Form:
|
||||
email_field:
|
||||
element: input
|
||||
type: email
|
||||
component: InputField.email
|
||||
label: 'Email address'
|
||||
placeholder: 'you@example.com'
|
||||
required: true
|
||||
validation: email_format
|
||||
```
|
||||
|
||||
**Design System:**
|
||||
|
||||
```yaml
|
||||
Input Field Component:
|
||||
base_styling:
|
||||
height: 2.5rem
|
||||
padding: spacing-2 spacing-3
|
||||
border: 1px solid gray-300
|
||||
border-radius: radius-md
|
||||
font-size: text-base
|
||||
|
||||
variants:
|
||||
email:
|
||||
icon: envelope
|
||||
autocomplete: email
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Why This Matters
|
||||
|
||||
### For Designers
|
||||
|
||||
✅ **Consistency:** All h2s can look the same without manual styling
|
||||
✅ **Flexibility:** Change all section headings by updating one token
|
||||
✅ **Clarity:** Semantic meaning preserved
|
||||
✅ **Scalability:** Easy to maintain as design system grows
|
||||
|
||||
### For Developers
|
||||
|
||||
✅ **Semantic HTML:** Proper HTML structure
|
||||
✅ **Accessibility:** Screen readers understand structure
|
||||
✅ **Maintainability:** Styling centralized
|
||||
✅ **Performance:** Reusable styles
|
||||
|
||||
### For Design Systems
|
||||
|
||||
✅ **Single Source of Truth:** Tokens define appearance
|
||||
✅ **Easy Updates:** Change tokens, not components
|
||||
✅ **Consistency:** Automatic consistency across pages
|
||||
✅ **Documentation:** Clear token → component mapping
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
### Mistake 1: Mixing Structure and Style
|
||||
|
||||
**❌ Bad:**
|
||||
|
||||
```yaml
|
||||
Page:
|
||||
- "Large blue heading" (h2)
|
||||
```
|
||||
|
||||
**✅ Good:**
|
||||
|
||||
```yaml
|
||||
Page:
|
||||
- Section heading (h2 → heading-section token)
|
||||
```
|
||||
|
||||
### Mistake 2: Hardcoding Visual Values
|
||||
|
||||
**❌ Bad:**
|
||||
|
||||
```yaml
|
||||
Button:
|
||||
background: #2563eb
|
||||
padding: 16px
|
||||
```
|
||||
|
||||
**✅ Good:**
|
||||
|
||||
```yaml
|
||||
Button:
|
||||
background: primary-600
|
||||
padding: spacing-4
|
||||
```
|
||||
|
||||
### Mistake 3: Using Visual Names for Semantic Elements
|
||||
|
||||
**❌ Bad:**
|
||||
|
||||
```yaml
|
||||
<h2 class="big-blue-text">
|
||||
```
|
||||
|
||||
**✅ Good:**
|
||||
|
||||
```yaml
|
||||
<h2 class="section-heading">
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Token Naming Conventions
|
||||
|
||||
### Colors
|
||||
|
||||
```
|
||||
--color-{category}-{shade}
|
||||
--color-primary-600
|
||||
--color-gray-900
|
||||
--color-success-500
|
||||
```
|
||||
|
||||
### Typography
|
||||
|
||||
```
|
||||
--text-{size}
|
||||
--text-base
|
||||
--text-lg
|
||||
--text-4xl
|
||||
```
|
||||
|
||||
### Spacing
|
||||
|
||||
```
|
||||
--spacing-{scale}
|
||||
--spacing-2
|
||||
--spacing-4
|
||||
--spacing-8
|
||||
```
|
||||
|
||||
### Component-Specific
|
||||
|
||||
```
|
||||
--{component}-{property}-{variant}
|
||||
--button-padding-primary
|
||||
--input-border-error
|
||||
--card-shadow-elevated
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation in WDS
|
||||
|
||||
### Phase 4: Page Specification
|
||||
|
||||
**Agent specifies:**
|
||||
|
||||
- Semantic HTML elements
|
||||
- Component references
|
||||
- Content and labels
|
||||
|
||||
**Agent does NOT specify:**
|
||||
|
||||
- Exact colors
|
||||
- Exact sizes
|
||||
- Exact spacing
|
||||
|
||||
### Phase 5: Design System
|
||||
|
||||
**Agent specifies:**
|
||||
|
||||
- Design tokens
|
||||
- Component styling
|
||||
- Visual properties
|
||||
|
||||
**Agent does NOT specify:**
|
||||
|
||||
- Page-specific content
|
||||
- Semantic structure
|
||||
|
||||
### Integration
|
||||
|
||||
**Page spec references design system:**
|
||||
|
||||
```yaml
|
||||
Hero:
|
||||
heading:
|
||||
element: h2
|
||||
token: heading-hero ← Reference to design system
|
||||
content: 'Welcome'
|
||||
```
|
||||
|
||||
**Design system defines token:**
|
||||
|
||||
```yaml
|
||||
Tokens:
|
||||
heading-hero:
|
||||
font-size: 3rem
|
||||
font-weight: 800
|
||||
color: gray-900
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Company Customization
|
||||
|
||||
**Companies can fork WDS and customize tokens:**
|
||||
|
||||
```
|
||||
Company Fork:
|
||||
├── data/design-system/
|
||||
│ ├── token-architecture.md (this file - keep principles)
|
||||
│ ├── company-tokens.md (company-specific token values)
|
||||
│ └── token-mappings.md (h2 → company-heading-large)
|
||||
```
|
||||
|
||||
**Result:** Every project uses company's design tokens automatically.
|
||||
|
||||
---
|
||||
|
||||
## Further Reading
|
||||
|
||||
- **Naming Conventions:** `naming-conventions.md`
|
||||
- **Component Boundaries:** `component-boundaries.md`
|
||||
- **State Management:** `state-management.md`
|
||||
|
||||
---
|
||||
|
||||
**This is a core principle. Reference this document from all component-type instructions.**
|
||||
74
_bmad/wds/data/design-system/validation-patterns.md
Normal file
74
_bmad/wds/data/design-system/validation-patterns.md
Normal file
@@ -0,0 +1,74 @@
|
||||
# Form Validation Patterns
|
||||
|
||||
**Purpose:** Standard patterns for form validation and error handling.
|
||||
|
||||
**Referenced by:** Input Field, Form component-type instructions
|
||||
|
||||
---
|
||||
|
||||
## Validation Types
|
||||
|
||||
### Client-Side Validation
|
||||
|
||||
**Required Fields:**
|
||||
|
||||
```yaml
|
||||
validation:
|
||||
required: true
|
||||
message: 'This field is required'
|
||||
```
|
||||
|
||||
**Format Validation:**
|
||||
|
||||
```yaml
|
||||
validation:
|
||||
type: email
|
||||
pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
|
||||
message: 'Please enter a valid email address'
|
||||
```
|
||||
|
||||
**Length Validation:**
|
||||
|
||||
```yaml
|
||||
validation:
|
||||
minLength: 8
|
||||
maxLength: 100
|
||||
message: 'Password must be 8-100 characters'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error States
|
||||
|
||||
**Visual Indicators:**
|
||||
|
||||
- Red border
|
||||
- Error icon
|
||||
- Error message below field
|
||||
- Error color for label
|
||||
|
||||
**Timing:**
|
||||
|
||||
- Show on blur (after user leaves field)
|
||||
- Show on submit attempt
|
||||
- Clear on valid input
|
||||
|
||||
---
|
||||
|
||||
## Success States
|
||||
|
||||
**Visual Indicators:**
|
||||
|
||||
- Green border (optional)
|
||||
- Success icon (optional)
|
||||
- Success message (optional)
|
||||
|
||||
**When to Show:**
|
||||
|
||||
- After successful validation
|
||||
- For critical fields (password strength)
|
||||
- For async validation (username availability)
|
||||
|
||||
---
|
||||
|
||||
**Reference this when specifying form components.**
|
||||
Reference in New Issue
Block a user