11 KiB

Raw Blame History

Operation: Create New Component

Purpose: Add a new component to the design system.

When: No similar component exists, or designer chose to create new

Input: Component specification

Output: New component file in design system

Step 1: Generate Component ID

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

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

``` 🆔 Generated Component ID: btn-003 ```

Step 2: Determine Component Category

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)

Example:

Component: Button
Category: Interactive

Step 3: Extract Component-Level Information

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)

Step 4: Create Component File

Use component template to create file:

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

Template Structure:

# [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:]
```yaml
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]

[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:**

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

```yaml
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:

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`

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

Update design system statistics:

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

Generate reference for page spec:

Output:

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

Step 9: Complete

``` ✅ 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:

Retry
Create with different ID
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.**

11 KiB Raw Blame History

Operation: Create New Component

Step 1: Generate Component ID

Step 2: Determine Component Category

Step 3: Extract Component-Level Information

Step 4: Create Component File

Figma Reference

Library Component

Behavior

Interactions

Animations

Accessibility

Usage

When to Use

When Not to Use

Best Practices

Used In

Related Components

Version History

Notes

Library Component

Behavior

Interactions

Animations

Accessibility

Usage

When to Use

When Not to Use

Best Practices

Used In

Related Components

Version History

Notes

Step 7: Update Design System Stats

Step 8: Create Component Reference

Step 9: Complete

11 KiB

Raw Blame History