Usage Guidelines

Usage guidelines help teams use components correctly and consistently. Clear dos and don'ts prevent misuse, reduce support burden, and ensure components deliver their intended value. These guidelines bridge the gap between component capabilities and real-world application.

Why Usage Guidelines Matter

Well-defined usage guidelines:

  • Prevent Misuse: Clear guidance reduces mistakes
  • Enable Self-Service: Teams can use components without asking
  • Maintain Consistency: Similar contexts use similar patterns
  • Reduce Support: Fewer questions and issues

Guideline Structure

1. When to Use

Describe appropriate use cases:

/**
 * Button Usage Guidelines
 * 
 * ✅ Use Button for:
 * - Primary actions (Save, Submit, Confirm)
 * - Secondary actions (Cancel, Back)
 * - Destructive actions (Delete, Remove)
 * - Navigation actions (Learn More, View Details)
 * 
 * ❌ Don't use Button for:
 * - Text links (use Link component)
 * - Icon-only actions without labels (use IconButton)
 * - Toggle switches (use Switch component)
 * - Navigation menus (use NavLink component)
 */

2. Contextual Recommendations

Provide guidance for different contexts:

/**
 * Button Context Guidelines
 * 
 * Forms:
 * - Use primary variant for submit button
 * - Use secondary variant for cancel button
 * - Place buttons at bottom right of form
 * - Use loading state during submission
 * 
 * Modals:
 * - Use primary variant for confirmation action
 * - Use ghost variant for cancel action
 * - Place buttons in footer
 * - Ensure keyboard navigation works
 * 
 * Toolbars:
 * - Use appropriate sizes for space constraints
 * - Group related actions
 * - Use icon buttons when space is limited
 */

3. Do's and Don'ts

Clear examples of correct and incorrect usage:

/**
 * Button Do's and Don'ts
 * 
 * ✅ DO:
 * - Use descriptive labels ("Save Changes" not "Click")
 * - Provide loading states for async actions
 * - Use appropriate variants for action priority
 * - Ensure sufficient touch target size (44x44px)
 * 
 * ❌ DON'T:
 * - Use buttons for navigation (use Link)
 * - Override focus styles (breaks accessibility)
 * - Use multiple primary buttons on same screen
 * - Use unclear labels ("OK", "Yes", "No")
 */

Component-Specific Guidelines

Buttons

✅ Do

  • Use descriptive labels that indicate action outcome
  • Use primary variant for main action on screen
  • Provide loading states for async actions
  • Use appropriate size for context

❌ Don't

  • Use buttons for navigation (use Link component)
  • Use multiple primary buttons on same screen
  • Use unclear labels ("OK", "Click here")
  • Remove focus styles (breaks accessibility)

Form Controls

✅ Do

  • Always associate labels with inputs
  • Provide helpful error messages
  • Use appropriate input types (email, tel, url)
  • Group related fields logically

❌ Don't

  • Use placeholder text as label
  • Hide validation errors until submit
  • Use generic "Error" messages
  • Require formatting users must guess

Modals/Dialogs

✅ Do

  • Use for critical confirmations
  • Provide clear title and description
  • Include primary and secondary actions
  • Trap focus and manage keyboard navigation

❌ Don't

  • Use for non-critical information (use Toast)
  • Nest modals within modals
  • Use modals for navigation
  • Block user from closing modal

Composition Guidelines

When to Compose

Use composition for complex use cases:

// ✅ Good: Compose for complex cases
<Card>
  <Card.Header>
    <Card.Title>User Profile</Card.Title>
    <Card.Actions>
      <Button variant="ghost" size="sm">Edit</Button>
    </Card.Actions>
  </Card.Header>
  <Card.Body>
    <TextField label="Name" />
    <TextField label="Email" />
  </Card.Body>
  <Card.Footer>
    <Button variant="primary">Save</Button>
    <Button variant="secondary">Cancel</Button>
  </Card.Footer>
</Card>

// ❌ Bad: Trying to handle everything with props
<Card 
  title="User Profile"
  hasEditButton
  fields={[...]}
  hasFooter
  footerActions={[...]}
/>

Accessibility Guidelines

Required Accessibility Practices

  • Keyboard Navigation: All interactive elements must be keyboard accessible
  • Focus Management: Focus should be visible and properly managed
  • Screen Reader Support: Components must be announced correctly
  • Color Contrast: Meet WCAG AA contrast requirements

Performance Guidelines

Optimization Best Practices

  • Lazy Loading: Load heavy components on demand
  • Memoization: Memoize expensive computations
  • Code Splitting: Split large component bundles
  • Virtualization: Use for long lists and tables

Content Guidelines

Labeling Best Practices

// ✅ Good: Clear, descriptive labels
<Button>Save Changes</Button>
<Button variant="danger">Delete Account</Button>
<Input label="Email Address" placeholder="[email protected]" />

// ❌ Bad: Vague, unclear labels
<Button>OK</Button>
<Button variant="danger">Delete</Button>
<Input placeholder="Enter text" />

Common Mistakes

1. Over-Customization

// ❌ Bad: Customizing too much
<Button 
  style={{
    borderRadius: '50px',
    backgroundColor: '#ff0000',
    fontSize: '20px',
    padding: '30px'
  }}
>
  Click me
</Button>

// ✅ Good: Use system variants
<Button variant="primary" size="lg">
  Click me
</Button>

2. Ignoring Context

// ❌ Bad: Wrong component for context
<Button onClick={() => router.push('/about')}>
  Learn More
</Button>

// ✅ Good: Use appropriate component
<Link href="/about">Learn More</Link>

3. Missing Error Handling

// ❌ Bad: No error state
<TextField label="Email" />

// ✅ Good: Proper error handling
<TextField 
  label="Email"
  error={errors.email}
  hint="We'll never share your email"
/>

Documentation Requirements

Required Sections

Every component's usage guidelines should include:

  • When to Use: Appropriate use cases
  • When Not to Use: Inappropriate use cases
  • Do's and Don'ts: Clear examples
  • Code Examples: Real-world usage patterns
  • Common Mistakes: What to avoid
  • Accessibility: Accessibility considerations

Related Resources