Nookhive Logo
StyleguideAPI Reference

Implementation

Consistent implementation of the design system ensures a cohesive user experience and maintainable codebase. These guidelines help developers apply design principles effectively while maintaining flexibility for unique use cases.

Principles

Code Quality

  • Semantic HTML: Use proper HTML elements for their intended purpose
  • Accessibility: Include ARIA labels, proper heading hierarchy, and keyboard navigation
  • Performance: Optimize for fast loading and smooth interactions
  • Maintainability: Write clean, documented code that's easy to understand

Design System Usage

  • Use System Classes: Prefer semantic design system classes over custom CSS
  • Follow Patterns: Implement established patterns consistently
  • Document Deviations: When custom solutions are needed, document why
  • Contribute Back: Share reusable patterns with the team

CSS Class Reference

Typography Classes

<!-- Typography Hierarchy -->
<h1 className="title">Hero Title (48px)</h1>
<h1 className="text-h1">Page Title (32px)</h1>
<h2 className="text-h2">Section Heading (24px)</h2>
<h3 className="text-h3">Subsection (20px)</h3>
<h4 className="text-h4">Minor Heading (16px)</h4>
<h5 className="text-h5">Label (14px)</h5>
<h6 className="text-h6">Caption (12px)</h6>
<p className="text-body">Body Text (16px)</p>

Button Classes

<!-- Button Types -->
<button className="btn-primary">Primary Action</button>
<button className="btn-secondary">Secondary Action</button>
<button className="btn-tertiary">Tertiary Action</button>

<!-- Toggle Buttons -->
<div className="toggle-group">
  <button className="btn-toggle active">Active</button>
  <button className="btn-toggle">Inactive</button>
</div>

Form Classes

<!-- Input Fields -->
<input className="input-field" type="text" />
<input className="input-field error" type="email" />
<input className="input-field success" type="text" />
<textarea className="textarea-field"></textarea>

<!-- Validation Messages -->
<p className="validation-message error">Error message</p>
<p className="validation-message success">Success message</p>
<p className="validation-message warning">Warning message</p>

Layout Classes

<!-- Responsive Container -->
<div className="container-responsive">
  <!-- Content with proper margins -->
</div>

<!-- Responsive Grid Helpers -->
<div className="grid-cols-responsive-2" style={{ columnGap: '30px', rowGap: '30px' }}>
  <div>Column 1</div>
  <div>Column 2</div>
</div>

<div className="grid-cols-responsive-4" style={{ columnGap: '30px', rowGap: '30px' }}>
  <div>Col 1</div>
  <div>Col 2</div>
  <div>Col 3</div>
  <div>Col 4</div>
</div>

Responsive Implementation

Mobile-First Approach

  • Start with mobile design and enhance for larger screens
  • Use responsive grid helpers for automatic adaptation
  • Test touch targets are minimum 44px on mobile
  • Ensure content is readable without horizontal scrolling
  • Prioritize essential content and actions on small screens
<!-- Responsive Example -->
<div className="grid-cols-responsive-3" style={{ columnGap: '30px', rowGap: '30px' }}>
  <!-- Automatically becomes 1-column on mobile -->
  <div>Content 1</div>
  <div>Content 2</div>
  <div>Content 3</div>
</div>

Breakpoint Strategy

  • Small: 360px-425px (mobile phones)
  • Medium: 690px-790px (tablets)
  • Large: 1005px-1155px (desktops)
  • Use content-driven breakpoints, not device-specific
  • Test at breakpoint boundaries for smooth transitions
<!-- Breakpoint Usage (semantic helpers) -->
<div className="grid-cols-responsive-3" style={{ columnGap: '30px', rowGap: '30px' }}>
  <div>Area A</div>
  <div>Area B</div>
  <div>Area C</div>
</div>

Accessibility Implementation

WCAG 2.1 AA Compliance

Required Practices
  • Use semantic HTML elements (header, nav, main, section)
  • Provide alt text for all images
  • Ensure proper heading hierarchy (h1 → h2 → h3)
  • H1 headers must be bold and left-aligned
  • Include focus indicators for keyboard navigation
  • Use sufficient color contrast ratios (4.5:1 minimum)
  • Provide labels for all form inputs
Testing Checklist
  • Navigate entire interface using only keyboard
  • Test with screen reader (NVDA, JAWS, VoiceOver)
  • Verify color contrast with accessibility tools
  • Test at 200% zoom level
  • Validate HTML for semantic correctness
  • Check focus order is logical and visible

Performance Optimization

CSS Optimization

  • Use design system classes to minimize custom CSS
  • Eliminate unused CSS by importing only what's needed; avoid shim patterns and keep styles cohesive and semantic
  • Avoid excessive inline styles; prefer semantic classes defined in the design system
  • Use CSS custom properties for dynamic values
  • Minimize use of complex selectors

Loading Performance

  • Optimize font loading with font-display: swap
  • Use appropriate image formats and sizes
  • Implement lazy loading for non-critical content
  • Minimize layout shifts with proper sizing
  • Test performance on slower devices and networks

Quality Assurance Process

Pre-Deployment Checklist

  • Cross-browser testing (Chrome, Firefox, Safari, Edge)
  • Mobile device testing on actual devices
  • Accessibility audit with automated tools
  • Performance testing with Lighthouse
  • Visual regression testing
  • Code review for design system compliance

Ongoing Maintenance

  • Regular design system updates and documentation
  • User feedback collection and analysis
  • Performance monitoring and optimization
  • Accessibility testing with real users
  • Design system evolution based on usage patterns
  • Team training on new patterns and updates