Component Library¶

Overview¶

Our component library provides a comprehensive set of reusable UI components that embody our brand identity. Built on our color system, typography scale, and spacing grid, these components ensure consistency and quality across all documentation.

Design Principles¶

Visual Consistency¶

Every component follows our established design tokens:

Colors: Uses our purple/amber brand palette
Typography: Built on Inter/JetBrains Mono hierarchy
Spacing: Follows 8px baseline grid
Shadows: Consistent elevation system
Radius: Harmonious border radius scale

Interaction Excellence¶

Smooth transitions with optimized easing curves
Hover states that provide clear feedback
Focus management for keyboard accessibility
Touch-friendly sizing for mobile devices

Accessibility First¶

WCAG 2.1 AA compliance for all color combinations
Keyboard navigation support throughout
Screen reader friendly markup
High contrast mode adaptations

Button Components¶

Primary Buttons¶

<button class="brand-button brand-button--primary">
  Primary Action
</button>
<button class="brand-button brand-button--primary brand-button--large">
  Large Primary
</button>
<button class="brand-button brand-button--primary brand-button--small">
  Small Primary
</button>

Secondary & Outline Buttons¶

<button class="brand-button brand-button--secondary">Secondary</button>
<button class="brand-button brand-button--outline">Outline</button>
<button class="brand-button brand-button--ghost">Ghost</button>

Card Components¶

Standard Cards¶

This is a standard card component with hover effects and proper spacing according to our design system.

Elevated cards draw more attention and work well for featured content or important information.

Featured cards use our brand gradient and colored borders to highlight the most important content.

<!-- Standard Card -->
<div class="brand-card">
  <div class="brand-card__header">
    <h3 class="brand-card__title">Card Title</h3>
    <p class="brand-card__subtitle">Card subtitle</p>
  </div>
  <div class="brand-card__content">
    <p>Card content goes here...</p>
  </div>
  <div class="brand-card__footer">
    <span>Footer content</span>
    <button>Action</button>
  </div>
</div>

<!-- Elevated Card -->
<div class="brand-card brand-card--elevated">
  <!-- Content -->
</div>

<!-- Featured Card -->
<div class="brand-card brand-card--featured">
  <!-- Content -->
</div>

Enhanced Admonitions¶

Our enhanced admonitions integrate seamlessly with Material's existing system:

ℹ️

Information

This is an enhanced admonition with improved styling and brand integration.

✅

Success

Success admonitions use our semantic green color for positive feedback.

⚠️

Warning

Warning admonitions alert users to important information they should be aware of.

<div class="brand-admonition">
  <div class="brand-admonition__icon">ℹ️</div>
  <div class="brand-admonition__content">
    <h4 class="brand-admonition__title">Title</h4>
    <p>Admonition content...</p>
  </div>
</div>

<!-- Variants -->
<div class="brand-admonition brand-admonition--success">...</div>
<div class="brand-admonition brand-admonition--warning">...</div>
<div class="brand-admonition brand-admonition--error">...</div>

Form Components¶

Input Fields¶

Standard Input

Focused Input

Error Input

This field is required

<input class="brand-input" type="text" placeholder="Enter text..." />
<input class="brand-input brand-input--error" type="text" />

Badge Components¶

Default Primary Success Warning Error Outline

<span class="brand-badge">Default</span>
<span class="brand-badge brand-badge--primary">Primary</span>
<span class="brand-badge brand-badge--success">Success</span>
<span class="brand-badge brand-badge--warning">Warning</span>
<span class="brand-badge brand-badge--error">Error</span>
<span class="brand-badge brand-badge--outline">Outline</span>

Progress Components¶

Progress Bar (75%)

Progress Bar (40%)

<div class="brand-progress">
  <div class="brand-progress__bar" style="width: 75%;"></div>
</div>

<nav class="brand-nav">
  <a href="#" class="brand-nav__item brand-nav__item--active">Home</a>
  <a href="#" class="brand-nav__item">Features</a>
  <a href="#" class="brand-nav__item">Documentation</a>
  <a href="#" class="brand-nav__item">About</a>
</nav>

Design Tokens¶

Shadows¶

Our elevation system creates depth and hierarchy:

Small
brand-shadow-sm

Medium
brand-shadow-md

Large
brand-shadow-lg

Purple
brand-shadow-purple-md

Border Radius¶

Consistent rounded corners throughout:

SM
4px

LG
8px

2XL
16px

Full
Pill

Transitions¶

Smooth, professional animations:

Token	Duration	Easing	Usage
`brand-transition-fast`	150ms	ease-out	Hover states, small interactions
`brand-transition-normal`	250ms	ease-out	General transitions, focus states
`brand-transition-slow`	350ms	ease-out	Layout changes, large movements

Usage Guidelines¶

Component Composition¶

Best Practices

✅ Combine components logically (cards contain buttons, badges, etc.)
✅ Use semantic HTML as the foundation
✅ Apply ARIA labels for interactive elements
✅ Test keyboard navigation throughout
✅ Maintain visual hierarchy with proper spacing

Accessibility Requirements¶

Essential Considerations

Minimum touch targets: 44px for mobile interactions
Color contrast: 4.5:1 minimum for all text
Focus indicators: Visible focus states for all interactive elements
Screen readers: Descriptive text for all interactive components
Keyboard navigation: Tab order follows visual hierarchy

Performance Optimization¶

CSS containment applied to complex components
GPU acceleration for smooth animations
Efficient selectors to minimize style recalculation
Reduced motion support for accessibility

This component library provides the building blocks for creating consistent, accessible, and beautiful user interfaces that embody our brand identity.