Skip to content

MAINTENANCE.md

Latest commit

 

History

History
324 lines (245 loc) · 8.62 KB

MAINTENANCE.md

File metadata and controls

324 lines (245 loc) · 8.62 KB
Raw

Maintenance Guide

⚠️ AI Instructions: When a new component is created, you MUST update all locations listed below. Do NOT skip any section. Follow the format exactly as shown in existing entries.

When to Use This File

Reference this file when:

  • Creating a new component
  • Renaming an existing component
  • Deleting a component
  • Changing a component's category
  • Adding a new pattern

Checklist: New Component

When adding a new component, update these files in order:

  • 1. Create component .md file
  • 2. Update INDEX.md — Component Registry
  • 3. Update INDEX.md — Decision Tree (if applicable)
  • 4. Update INDEX.md — Common Patterns (if applicable)
  • 5. Update related component docs — Related Components table

1. Create Component Documentation

Location: components/ui/[component-name]/[component-name].md

Action: Copy component.template.md and fill in all sections.

Required sections:

  • Mental Model
  • When to Use
  • When NOT to Use
  • Anatomy
  • Props
  • Usage examples
  • Behavior & Animation
  • Accessibility
  • Edge Cases
  • Related Components

2. Update Component Registry

Location: INDEX.md → Component Registry section

Action: Add a new row to the appropriate category table.

Format:

| ComponentName | `components/ui/component-name/component-name.md` | One-liner description |

Categories:

  • Primitives — Low-level building blocks (Button, Input, Select)
  • Layout — Structure and spacing (Card, Stack, Grid)
  • Feedback — Status and responses (Toast, Banner, Spinner)
  • Overlays — Layered UI (Modal, Sheet, Popover)
  • Data Display — Showing information (Table, List, Avatar)
  • Navigation — Moving around (Tabs, Breadcrumb, Sidebar)
  • Composite — High-level patterns (FormField, DataTable)

Example — Adding a new "Chip" component to Primitives:

Before:

### Primitives
| Component | Path | One-liner |
|-----------|------|-----------|
| Button | `components/ui/button/button.md` | Actions and triggers |
| Input | `components/ui/input/input.md` | Single-line text entry |

After:

### Primitives
| Component | Path | One-liner |
|-----------|------|-----------|
| Button | `components/ui/button/button.md` | Actions and triggers |
| Chip | `components/ui/chip/chip.md` | Compact interactive element |
| Input | `components/ui/input/input.md` | Single-line text entry |

Rules:

  • Keep alphabetical order within each category
  • One-liner should be 3-6 words
  • Path must match actual file location

3. Update Decision Trees

Location: INDEX.md → Quick Decision Trees section

Action: Add the component to relevant decision tree(s).

When to add:

  • Component serves a distinct user need
  • Component is an alternative to existing options
  • Users might be confused about when to use it

Format:

├── Scenario description → ComponentName (path/to/component.md)

Example — Adding "Chip" to the action decision tree:

Before:

### User needs to take an action

Action type? ├── Primary page action → Button ├── Icon only → IconButton └── Navigation that looks like action → LinkButton

After:

### User needs to take an action

Action type? ├── Primary page action → Button ├── Icon only → IconButton ├── Compact toggleable action → Chip (components/ui/chip/chip.md) └── Navigation that looks like action → LinkButton

Rules:

  • Add to ALL relevant decision trees
  • Include the file path for new/less common components
  • Place in logical order (most common first, or alphabetical)

4. Update Common Patterns

Location: INDEX.md → Common Patterns section

Action: Add or update pattern entries if the component is used in common patterns.

When to add:

  • Component is essential to a recurring pattern
  • New pattern emerges from component usage

Format:

| Pattern Name | `patterns/pattern-name.md` | Component1, Component2, NewComponent |

Example — Adding "Chip" to filter pattern:

Before:

| Pattern | Guide | Components Used |
|---------|-------|-----------------|
| Form with validation | `patterns/forms.md` | FormField, Button, Toast |

After:

| Pattern | Guide | Components Used |
|---------|-------|-----------------|
| Form with validation | `patterns/forms.md` | FormField, Button, Toast |
| Filter interface | `patterns/filters.md` | Chip, Select, Button |

5. Update Related Components

Location: Other component .md files → Related Components section

Action: Add the new component to related components' docs.

When to add:

  • New component is an alternative to existing component
  • New component is commonly used with existing component
  • Users might confuse the two

Format:

| Instead of... | Use... | When... |
|---------------|--------|---------|
| ThisComponent | `NewComponent` | Scenario when new component is better |

Example — Updating Button.md to reference Chip:

Add to components/ui/button/button.md → Related Components:

| Instead of... | Use... | When... |
|---------------|--------|---------|
| Button | `Chip` | Compact, toggleable selections |

Add to components/ui/chip/chip.md → Related Components:

| Instead of... | Use... | When... |
|---------------|--------|---------|
| Chip | `Button` | Primary actions, form submissions |

Components to check:

  • Direct alternatives (similar function)
  • Common companions (often used together)
  • Parent/child relationships (one contains the other)

Quick Reference: What to Update

Adding... Update these files
New primitive component INDEX.md Registry (Primitives), Decision tree, Related components
New layout component INDEX.md Registry (Layout), Related components
New feedback component INDEX.md Registry (Feedback), Feedback decision tree, Related components
New overlay component INDEX.md Registry (Overlays), Overlay decision tree, Related components
New data display component INDEX.md Registry (Data Display), Content decision tree, Related components
New navigation component INDEX.md Registry (Navigation), Related components
New composite component INDEX.md Registry (Composite), Relevant decision trees, Common patterns, Related components
New pattern INDEX.md Common Patterns table, Create pattern .md file

Validation Checklist

After making updates, verify:

  • Component appears in INDEX.md Component Registry
  • Component is in correct category
  • Path in registry matches actual file location
  • Added to relevant decision tree(s) in INDEX.md
  • Related components updated (both directions)
  • Alphabetical order maintained in registry
  • One-liner is concise and clear
  • All links/paths are correct

Example: Full Update Flow

Scenario: Adding a new Chip component

Step 1: Create documentation

components/ui/chip/chip.md  ← Copy from component.template.md and fill in

Step 2: Update registry in INDEX.md

### Primitives
| Chip | `components/ui/chip/chip.md` | Compact interactive element |

Step 3: Update decision tree in INDEX.md

### User needs to take an action
├── Compact toggleable action → Chip (components/ui/chip/chip.md)

### User needs to input data
├── Selection from options
│   ├── Toggleable visual selections → Chip (components/ui/chip/chip.md)

Step 4: Update common patterns (if applicable)

| Filter interface | `patterns/filters.md` | Chip, Select, Button |

Step 5: Update related component docs

In button/button.md:

| Button | `Chip` | Compact, toggleable selections |

In tag/tag.md:

| Tag | `Chip` | When element needs to be interactive/dismissible |

In chip/chip.md:

| Chip | `Button` | Primary actions, form submissions |
| Chip | `Tag` | Non-interactive labels |

Removing a Component

When deleting a component:

  1. Remove from Component Registry
  2. Remove from Decision Trees
  3. Remove from Common Patterns
  4. Update Related Components in other docs
  5. Delete the component's .md file
  6. Search for any other references in docs

Renaming a Component

When renaming a component:

  1. Rename the .md file and folder
  2. Update Component Registry (name and path)
  3. Update Decision Trees
  4. Update Common Patterns
  5. Update Related Components in all docs
  6. Search and replace old name in all docs