Component Overview

The Lufa Design System provides a comprehensive set of React components built with accessibility and customization in mind. Components are organized by their role and purpose for better discoverability.

Component Categories

Foundation

Layout and structure components that form the building blocks of your UI.

• Box - Flexible container with padding, margin, background, and border utilities
• Stack - Flexbox layout for vertical/horizontal stacking with consistent spacing
• Flex - Advanced flexbox layout primitive
• Grid - Two-dimensional grid layout primitive
• Container - Max-width centered container for responsive layouts
• Center - Centers content horizontally and vertically
• Divider - Visual separator for content sections
• AspectRatio - Maintains consistent aspect ratios for media and containers
• Cluster - Wrapping layout for collections with intelligent spacing
• Bleed - Breaks out of container constraints for full-width content

Content

Display components for text, icons, badges, and visual elements.

• Text - Typography component with semantic variants and accessibility features
• Icon - SVG icon wrapper with semantic sizing and colors (Lucide React integration)
• Badge - Status and labeling component
• Link - Inline anchor with token-based states and safe external-link defaults

Interaction

Interactive elements like buttons, inputs, and form controls.

• Button - Interactive button with variants, sizes, and states
• Input - Text input field with design system styling
• Label - Text label for form controls and UI elements

Composition

Complex patterns that combine multiple components.

• Card - Composed container for grouped content and actions

Utility

Technical helpers and accessibility utilities.

• Portal - Renders children into a portal outside of the DOM hierarchy
• VisuallyHidden - Hides content visually but leaves it available to screen readers

Navigation

• DotNav - Controlled vertical navigation for long, section-based pages

Hooks

• useScrollSpy - Tracks active sections and coordinates programmatic scrolling

Design Principles

All Lufa components follow these core principles:

1. Accessibility First

• WCAG 2.1 AA compliant by default
• Semantic HTML elements
• Keyboard navigation support
• Screen reader optimized
• Focus management

2. Token-Based Design

• All design values use semantic tokens
• Automatic light/dark theme support
• Consistent spacing, colors, and typography
• Easy customization

3. Polymorphic API

• as prop for semantic HTML flexibility
• Type-safe props based on element type
• Maintains accessibility with semantic elements

4. Performance Optimized

• CSS Modules for scoped styles
• CSS custom properties for theming
• Tree-shakeable imports
• Minimal runtime overhead

5. Developer Experience

• Full TypeScript support
• Clear prop APIs
• Comprehensive documentation
• Interactive examples

Usage Patterns

Composing Components

Lufa components are designed to be composed together:

import { Box, Icon, Stack, Text } from '@grasdouble/lufa_design-system';

function UserCard({ name, email, role }) {
  return (
    <Box padding="comfortable" background="surface" borderRadius="medium" borderWidth="thin" borderColor="default">
      <Stack direction="vertical" spacing="compact">
        <Stack direction="horizontal" spacing="compact" align="center">
          <Icon name="user" color="primary" />
          <Text variant="heading-sm">{name}</Text>
        </Stack>
        <Text variant="body-sm" color="secondary">
          {email}
        </Text>
        <Text variant="caption" color="muted">
          {role}
        </Text>
      </Stack>
    </Box>
  );
}

Component Status

API	Status	Category	Playwright	Docs	Storybook
Box	✅ Stable	Foundation	✅	✅	✅
Stack	✅ Stable	Foundation	✅	✅	✅
Flex	✅ Stable	Foundation	✅	✅	✅
Grid	✅ Stable	Foundation	✅	✅	✅
Container	✅ Stable	Foundation	✅	✅	✅
Center	✅ Stable	Foundation	✅	✅	✅
Divider	✅ Stable	Foundation	✅	✅	✅
AspectRatio	✅ Stable	Foundation	✅	✅	✅
Cluster	✅ Stable	Foundation	✅	✅	✅
Bleed	✅ Stable	Foundation	✅	✅	✅
Text	✅ Stable	Content	✅	✅	✅
Icon	✅ Stable	Content	✅	✅	✅
Badge	✅ Stable	Content	✅	✅	✅
Link	✅ Stable	Content	✅	✅	✅
Button	✅ Stable	Interaction	✅	✅	✅
Input	✅ Stable	Interaction	✅	✅	✅
Label	✅ Stable	Interaction	✅	✅	✅
Card	✅ Stable	Composition	✅	✅	✅
Portal	✅ Stable	Utility	✅	✅	✅
VisuallyHidden	✅ Stable	Utility	✅	✅	✅
DotNav	✅ Stable	Navigation	—	✅	✅
useScrollSpy	✅ Stable	Hook	✅	✅	Via DotNav

Next Steps

• Explore individual component documentation in the sidebar
• Learn about design tokens
• Browse the Storybook source for interactive examples

Work in Progress

This design system is actively being developed. More components and features will be added regularly.