npm package: @hellboy/ds
Description: Hellboy Design System - Core components
Latest version: 0.6.1

# 🔥 @hellboy/ds - Hellboy Design System

> _Where chaos meets precision: A comprehensive, accessible-first design system for modern React applications_

[![npm version](https://img.shields.io/npm/v/@hellboy/ds.svg)](https://www.npmjs.com/package/@hellboy/ds)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)
[![React](https://img.shields.io/badge/React-18%20%7C%2019-blue)](https://reactjs.org/)

A complete design system with **44+ production-ready components**, dual theming (light/dark), and comprehensive accessibility features built with React, TypeScript, and modern web standards.


## 🆕 What's New in v0.6.1

- 📦 **Packaging & Build Fixes** - Ensure dist/theme.css generation, add prepare script, maintain nested component CSS, and rewrite @imports for reliable package consumption
- 🎯 **Component Architecture Fixes** - Moved component styles from src/style/components/ to src/components/ with proper shared styles organization
- 🔧 **CSS Import System Overhaul** - Complete refactor of component CSS imports, eliminating circular dependencies and broken paths

## ✨ Features

- 🎨 **44+ Components** - Buttons, inputs, dialogs, tables, avatars, toasts, and more
- 🌓 **Dual Theme System** - Light and dark modes with customizable colors (HSLA-based)
- ♿ **Accessibility First** - WCAG 2.1 AA compliant with AriaKit primitives
- 📱 **Desktop Priority** - Optimized for desktop (1024px+), tablet/mobile in roadmap
- 🎯 **TypeScript Native** - Full type safety and IntelliSense support
- 🔌 **Auto Dependencies** - Components automatically include all required dependencies
- 🎭 **150,000+ Icons** - Iconify integration for extensive icon library
- 📦 **Tree-shakeable** - Import only what you need
- 🚀 **CSS-First** - Minimal runtime overhead with CSS custom properties
- 💾 **Persistent Preferences** - User theme and color choices saved locally
- 📱 **Screen Examples** - Interactive examples of common UI patterns and layouts

## 🚀 Installation

```bash
npm install @hellboy/ds

# Peer dependencies (if not already installed)
npm install react react-dom
```

**That's it!** A single import is all you need:

```tsx
import '@hellboy/ds/index.css';
```

Default theme colors are embedded in `index.css` via CSS `@layer`, so everything works out of the box.

**Want to customize colors?** Load your own `theme.css` — it automatically overrides the defaults regardless of import order:

```tsx
// Custom theme always wins over the built-in defaults
import '@hellboy/ds/theme.css';   // package default (or your own)
import '@hellboy/ds/index.css';
```

> **💡 Already have a `/public/theme.css`?** Keep it as-is. A `<link>` tag in HTML loads CSS outside of any `@layer`, which has higher priority than the bundled defaults — your custom colors are automatically preserved.

The `index.css` includes:
- ✅ Component styles
- ✅ Light/dark mode rules
- ✅ Foundation CSS (typography, spacing, colors)
- ✅ Default theme colors (overridable via your own `theme.css`)

## 📖 Quick Start

### Basic Usage

```tsx
import '@hellboy/ds/index.css';
import { Button, Input, Banner } from '@hellboy/ds';

function App() {
  return (
    <div>
      <Banner type="info">
        Welcome to Hellboy Design System!
      </Banner>
      
      <Button variant="primary">Primary Action</Button>
      <Input label="Email" type="email" placeholder="you@example.com" />
    </div>
  );
}
```
import { Button, Input, Dialog, Banner, ThemeControl } from '@hellboy/ds';

export function App() {
  return (
    <div>
      {/* Theme switcher in top-right corner */}
      <ThemeControl />
      
      {/* Components work out of the box */}
      <Banner type="info">
        Welcome to Hellboy Design System!
      </Banner>
      
      <Button variant="primary">Primary Action</Button>
      <Input label="Email" type="email" placeholder="you@example.com" />
    </div>
  );
}
```

### Advanced: Tree-shaking (Individual Components)

Import only specific components to reduce bundle size:

```tsx
// Option 1: Single component import (recommended)
import '@hellboy/ds/index.css';
import { Button } from '@hellboy/ds';

// Option 2: Subpath imports (maximum tree-shaking)
import '@hellboy/ds/components/button/css';
import { Button } from '@hellboy/ds/components/button';
```

**Note**: Each component's CSS already includes all its dependencies (foundations, themes, utilities), so you never need to import foundation files manually.

## 🔌 Auto-Dependency Injection

Every component automatically includes everything it needs:

```tsx
// ✅ This works - button.css includes:
//    - Component styles
//    - Foundation CSS (typography, spacing, colors)
//    - Theme variables (light/dark)
//    - Shared utilities
import '@hellboy/ds/components/button/css';
import { Button } from '@hellboy/ds/components/button';
```

**Zero configuration required!** Just import and use.

## 🧱 Available Components (42+)

### Layout & Structure
- **Layout** - Main application layout with navigation
- **Page** - Page wrapper with consistent spacing  
- **Header** - Page headers with titles, subtitles, and tags
- **Hero** - Hero sections for landing pages
- **Section** - Content sections with automatic indexing
- **Grid** - Responsive grid system
- **Card** - Content cards with variants
- **Footer** - Page footer component
- **Divider** - Visual content separators

### Forms & Inputs
- **Button** - Interactive buttons (4 variants, 4 sizes, icons, loading states)
  - Dependencies: foundations, icons, theme
- **ButtonGroup** - Grouped button controls
- **Checkbox** - Accessible checkboxes with label support
  - Dependencies: foundations, theme
- **Radio** - Radio button groups
  - Dependencies: foundations, theme
- **Select** - Dropdown selection component
  - Dependencies: foundations, popover, theme
- **Input** - Text inputs with multiple types
  - `InputText`, `InputEmail`, `InputPassword`, `InputNumber`, `InputTel`, `InputUrl`, `InputSearch`, `InputDate`, `InputTime`, `InputDateTime`
  - Dependencies: foundations, icons, theme, popover (for date/time)
- **Textarea** - Multi-line text input
  - Dependencies: foundations, theme
- **RichTextarea** - Rich text editor with formatting toolbar
  - Dependencies: foundations, icons, floatingbar, select, tooltip, theme
  - External: DOMPurify for HTML sanitization
- **Slider** - Range slider control
  - Dependencies: foundations, theme
- **Switch** - Toggle switch component
  - Dependencies: foundations, theme

### Navigation
- **Navbar** - Main navigation bar with routing and tooltips
  - Dependencies: foundations, button, tooltip, backdrop, theme
- **Breadcrumbs** - Breadcrumb navigation
  - Dependencies: foundations, theme
- **FloatingBar** - Floating action bar
  - Dependencies: foundations, theme
- **PageIndex** - Auto-generated page navigation from sections
  - Dependencies: foundations, theme

### Feedback & Display
- **Avatar** - User avatars with initials fallback and icon support (2 sizes)
  - Dependencies: foundations, theme
- **Badge** - Status and label badges (8 variants)
  - Dependencies: foundations, theme
- **Tag** - Categorization tags (8 variants, 3 sizes)
  - Dependencies: foundations, theme
- **Banner** - Alert and notification banners (4 types: info, success, warning, error)
  - Dependencies: foundations, icons, button, theme
- **Toast** - Toast notifications with global management (timed + manual containers, position-based animations)
  - Dependencies: foundations, theme
  - External: React Portal
- **Dialog** - Modal dialogs with backdrop
  - Dependencies: foundations, backdrop, theme
  - External: React Portal
- **Drawer** - Slide-out panel component
  - Dependencies: foundations, backdrop, theme
- **Tooltip** - Contextual tooltips with auto-positioning
  - Dependencies: foundations, theme
  - External: React Portal
- **CodeBlock** - Syntax-highlighted code display
  - Dependencies: foundations, button, theme
- **List** - Structured list component
  - Dependencies: foundations, theme
- **Table** - Data tables with headers, rows, cells
  - Components: `Table`, `TableContainer`, `TableHead`, `TableBody`, `TableRow`, `TableCell`
  - Dependencies: foundations, theme

### Interactive
- **ThemeControl** - Theme switcher component (light/dark toggle)
  - Dependencies: foundations, button, theme
- **ColorControl** - Color customization interface
  - Dependencies: foundations, input, button, theme
- **DragHandle** - Drag and drop handles
  - Dependencies: foundations, icons, theme
- **Popover** - Floating popover component with positioning
  - Dependencies: foundations, theme
  - External: React Portal
- **Icon** - Icon component with Iconify integration
  - Dependencies: foundations
  - External: @iconify/react (150,000+ icons)

### Shared Components
- **Backdrop** - Modal/dialog backdrop overlay
  - Dependencies: foundations, theme

## 📦 Dependencies

### Included Dependencies (Auto-installed with package)
```json
{
  "@ariakit/react": "^0.4.0",      // Accessible component primitives
  "@iconify/react": "^6.0.2",       // Icon framework (150,000+ icons)
  "dompurify": "^3.2.2"             // HTML sanitization (RichTextarea)
}
```

### Peer Dependencies (Required by your app)
```json
{
  "react": "^18.0.0 || ^19.0.0",
  "react-dom": "^18.0.0 || ^19.0.0"
}
```

**Note**: Components automatically handle their CSS dependencies. When you import a component's CSS, it includes all required foundation styles, theme variables, and utilities.

## 🎨 Theme System

### Using Themes

```tsx
import { setTheme, getTheme, getUserPreferences, setUserPreferences } from '@hellboy/ds';

// Get current theme
const currentTheme = getTheme(); // 'light' | 'dark'

// Set theme (persists to localStorage)
setTheme('dark');

// Get all user preferences
const prefs = getUserPreferences();
console.log(prefs.theme); // 'light' | 'dark' | 'auto'

// Update preferences
setUserPreferences({ 
  theme: 'dark',
  colors: {
    primary: { hue: 220, saturation: 70, lightness: 50 }
  }
});
```

### Theme Features
- 🌓 **Dual Modes**: Light and dark themes included
- 🎨 **Customizable**: 7 color hues (primary, secondary, accent, success, warning, error, info)
- 💾 **Persistent**: Preferences saved to localStorage
- 🔄 **Auto Detection**: Respects system preference (prefers-color-scheme)
- 📐 **HSLA-based**: Hue, Saturation, Lightness, Alpha for easy customization

### CSS Custom Properties

Themes use CSS custom properties that you can override:

```css
:root {
  /* Color hues (0-360) */
  --primary-hue: 330;
  --secondary-hue: 240;
  --accent-hue: 180;
  
  /* Semantic colors */
  --color-primary: hsl(var(--primary-hue), 70%, 50%);
  --color-on-primary: hsl(var(--primary-hue), 70%, 10%);
  
  /* Typography */
  --font-family-heading: 'Signika', sans-serif;
  --font-family-body: 'Rubik', sans-serif;
  
  /* Spacing scale */
  --spacing-1: 0.25rem;  /* 4px */
  --spacing-2: 0.5rem;   /* 8px */
  /* ... up to spacing-16 */
}
```

## 🔄 Component API Examples

### Button

**Variants:** `primary` | `secondary` | `tertiary` | `ghost`  
**Sizes:** `xs` | `sm` | `md` (default) | `lg`

```tsx
import { Button } from '@hellboy/ds';

// Variants
<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="tertiary">Tertiary</Button>
<Button variant="ghost">Ghost</Button>

// Sizes
<Button size="xs">Extra Small</Button>
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>

// With icons (150,000+ from Iconify)
<Button startIcon="mdi:check">Save</Button>
<Button endIcon="mdi:arrow-right">Next</Button>
<Button iconOnly aria-label="Settings" startIcon="mdi:cog" />

// States
<Button isLoading>Saving...</Button>
<Button disabled>Disabled</Button>
<Button fullWidth>Full Width</Button>
```

**Props:**
- `variant` - Visual style
- `size` - Button size
- `isLoading` - Show loading spinner
- `disabled` - Disable interaction
- `fullWidth` - Expand to container width
- `startIcon` / `endIcon` - Icon names from Iconify
- `iconOnly` - Icon-only button (requires `aria-label`)

### Input Components

All input types: `InputText`, `InputEmail`, `InputPassword`, `InputNumber`, `InputTel`, `InputUrl`, `InputSearch`, `InputDate`, `InputTime`, `InputDateTime`

```tsx
import { InputText, InputEmail, InputPassword, InputNumber } from '@hellboy/ds';

// Basic inputs
<InputText label="Name" placeholder="Enter your name" />
<InputEmail label="Email" required />
<InputPassword label="Password" />

// With states
<InputText 
  label="Username" 
  helperText="Choose a unique username"
  error={errors.username}
/>

// Number input with constraints
<InputNumber 
  label="Age" 
  min={0} 
  max={120} 
  step={1}
/>

// Date/Time pickers
<InputDate label="Birthday" />
<InputTime label="Meeting Time" />
<InputDateTime label="Event Start" />

// Sizes
<InputText size="sm" label="Small" />
<InputText size="md" label="Medium" />
<InputText size="lg" label="Large" />
```

**Props:**
- `label` - Input label text
- `helperText` - Helper text below input
- `error` - Error message (triggers error state)
- `fullWidth` - Expand to container width
- `size` - Input size: `sm` | `md` | `lg`

### Textarea

```tsx
import { Textarea, RichTextarea } from '@hellboy/ds';

// Simple textarea
<Textarea 
  label="Comments" 
  placeholder="Enter your feedback..."
  rows={4}
/>

// Rich text editor
<RichTextarea
  value={content}
  onChange={setContent}
  placeholder="Start typing..."
  toolbarOptions={['bold', 'italic', 'link', 'orderedList', 'unorderedList']}
  showTopToolbar={true}
/>
```

### Banner

**Types:** `info` | `success` | `warning` | `error`

```tsx
import { Banner } from '@hellboy/ds';

<Banner type="info">
  This is an informational message.
</Banner>

<Banner type="success" onDismiss={() => console.log('Dismissed')}>
  <strong>Success!</strong> Your changes have been saved.
</Banner>

<Banner type="warning">
  <strong>Warning:</strong> This action cannot be undone.
</Banner>

<Banner type="error">
  <strong>Error:</strong> Something went wrong.
</Banner>
```

### Dialog

```tsx
import { Dialog, Button } from '@hellboy/ds';
import { useState } from 'react';

function MyComponent() {
  const [isOpen, setIsOpen] = useState(false);
  
  return (
    <>
      <Button onClick={() => setIsOpen(true)}>Open Dialog</Button>
      
      <Dialog
        open={isOpen}
        onClose={() => setIsOpen(false)}
        title="Confirm Action"
        size="md" // sm | md | lg
      >
        <p>Are you sure you want to continue?</p>
        
        <div style={{ display: 'flex', gap: '1rem', marginTop: '1rem' }}>
          <Button variant="secondary" onClick={() => setIsOpen(false)}>
            Cancel
          </Button>
          <Button onClick={() => setIsOpen(false)}>
            Confirm
          </Button>
        </div>
      </Dialog>
    </>
  );
}
```

### Table

```tsx
import { Table, TableContainer, TableHead, TableBody, TableRow, TableCell } from '@hellboy/ds';

<TableContainer>
  <Table bordered striped hover>
    <TableHead>
      <TableRow>
        <TableCell header>ID</TableCell>
        <TableCell header>Name</TableCell>
        <TableCell header>Email</TableCell>
      </TableRow>
    </TableHead>
    <TableBody>
      {users.map(user => (
        <TableRow key={user.id}>
          <TableCell>{user.id}</TableCell>
          <TableCell>{user.name}</TableCell>
          <TableCell>{user.email}</TableCell>
        </TableRow>
      ))}
    </TableBody>
  </Table>
</TableContainer>
```

### Tooltip

```tsx
import { Tooltip, Button } from '@hellboy/ds';

<Tooltip content="This is a helpful tip" placement="top">
  <Button>Hover me</Button>
</Tooltip>

<Tooltip 
  content={<strong>Rich content</strong>}
  placement="bottom"
  delay={500}
>
  <span>Delayed tooltip</span>
</Tooltip>
```

### Tag & Badge

```tsx
import { Tag, Badge } from '@hellboy/ds';

// Tags (8 variants, 3 sizes)
<Tag variant="primary">Primary</Tag>
<Tag variant="success" size="sm">Small Success</Tag>
<Tag variant="warning" size="lg">Large Warning</Tag>

// Badges
<Badge variant="primary">New</Badge>
<Badge variant="error">5</Badge>
```

### Avatar

**Sizes:** `md` (default) | `lg`

```tsx
import { Avatar } from '@hellboy/ds';

// With image URL
<Avatar src="https://via.placeholder.com/40" alt="John Doe" />

// With initials
<Avatar initials="JD" />

// With icon
<Avatar icon="mdi:user" />

// Sizes
<Avatar size="md" initials="JD" />
<Avatar size="lg" initials="JD" />
```

**Props:**
- `src` - Image URL
- `alt` - Image alt text
- `initials` - Fallback initials text (2 characters)
- `icon` - Icon name from Iconify
- `size` - Avatar size: `md` | `lg`

### Toast

```tsx
import { Toast, useToast } from '@hellboy/ds';

function MyComponent() {
  const { show, error, success, info, warning } = useToast();
  
  return (
    <>
      {/* Toast containers - render once at app level */}
      <Toast position="top-right" />
      
      {/* Trigger notifications */}
      <button onClick={() => success('Changes saved!', { duration: 3000 })}>Save</button>
      <button onClick={() => error('Something went wrong', { duration: 0 })}>Error (no auto-close)</button>
      <button onClick={() => info('FYI: Update available')}>Info</button>
      <button onClick={() => warning('This action is irreversible')}>Warning</button>
    </>
  );
}
```

**Features:**
- 📍 **Position-based animations** - Fade in/out with position awareness
- ⏱️ **Global timer management** - Unified handling for all timed toasts
- 🎯 **Auto-close** - Configurable duration (default 3000ms)
- 🖱️ **Manual control** - Keep open indefinitely or add close buttons
- 📦 **Dual containers** - Timed toasts + manual toasts with separate management

**Props:**
- `position` - Toast placement: `top-left` | `top-center` | `top-right` | `bottom-left` | `bottom-center` | `bottom-right`
- `duration` - Auto-close duration in ms (0 = never auto-close)
- `onClose` - Callback when toast closes

### Theme Control

```tsx
import { ThemeControl } from '@hellboy/ds';

// Theme switcher component
<ThemeControl />

// Or use programmatically
import { setTheme, getTheme } from '@hellboy/ds';

const currentTheme = getTheme(); // 'light' | 'dark'
setTheme('dark');
```

## � Changelog

### v0.5.9 (Latest)
- 🎯 **Banner Fixed Variant** - New `variant="fixed"` for sticky/floating banners at layout boundaries
- 📌 **Design System Status Banner** - Fixed top banner showing 85% maturity status throughout app
- 🎨 **Enhanced Banner Dismiss** - Icon-only ghost button using `iconOnly` and `startIcon` props
- 💾 **SessionStorage Persistence** - Banner dismissal persists during session, reappears on reload
- 📖 **Updated Documentation** - Complete examples of fixed banner positioning
-  **Enhanced Hero Component** - Support for layered background effects with z-index control

### v0.5.2
- ⚡ Added Icon Preloading System for faster loading of commonly used icons
- 📑 Added PageIndex sidebar navigation to Screen Examples page
- ✅ Fixed checkbox icon visibility by adding opacity: 1
- 🔔 Fixed banner and toast icon names from heroicons
- 📖 Enhanced documentation navigation with automatic section detection

### v0.5.1
- ✨ Added Avatar component with image, initials, and icon support
- ✨ Added Toast notification system with global management
- 🎯 Enhanced animation system with position-based transitions
- 📖 Complete component documentation and examples
- 🔧 Improved build configuration for optimal bundling

### v0.2.7
- Initial release with 42 components
- Comprehensive styling and theming system
- Full accessibility features (WCAG 2.1 AA)

## �🖥️ Platform Support

**Current Focus: Desktop Applications (1024px+)**

Hellboy Design System is currently optimized for desktop experiences. All components are designed, tested, and optimized primarily for desktop interfaces.

**Roadmap:**
- 📱 **Tablet Support** (768px - 1023px) - Q2 2026
- 📲 **Mobile Support** (< 768px) - Q3 2026
- 🎯 **Responsive Utilities** - Q2 2026

## ♿ Accessibility

Every component is built with accessibility as a core principle:

- ✅ **WCAG 2.1 AA Compliant** - Color contrast, focus indicators, semantic HTML
- ⌨️ **Keyboard Navigation** - Full keyboard support with logical tab order
- 🔊 **Screen Reader Support** - Proper ARIA labels, roles, and live regions with AriaKit
- 🎯 **Focus Management** - Visible focus indicators respecting user preferences
- 🏗️ **Semantic HTML** - Native elements enhanced with ARIA when needed for maximum compatibility
- 🎨 **Color Contrast** - AA compliant in both light and dark themes with HSLA customization
- ⚡ **Motion Respect** - Honors `prefers-reduced-motion` for animations and transitions
- 🔧 **AriaKit Foundation** - Built on battle-tested accessibility primitives from AriaKit

## � Documentation

Full component documentation and examples available at [https://hellboy-ds.web.app](https://hellboy-ds.web.app)

## 📱 Screen Examples

Interactive examples showcasing common UI patterns and layouts using Hellboy Design System components. Perfect for understanding implementation patterns and seeing components in real-world contexts.

### Available Examples

**Authentication Patterns:**
- Login forms with centered layouts
- Email/password input combinations
- Form validation states

**Dashboard Layouts:**
- Full sidebar navigation with content areas
- Top navbar only layouts
- Stats cards and data visualization

**List & Data Management:**
- User management tables with filters
- Product catalogs with search and sorting
- Data tables with pagination

### Features

- 🎯 **Fullscreen Dialogs** - Examples open in modal dialogs for focused viewing
- 📑 **PageIndex Navigation** - Right sidebar with automatic section navigation
- 🔄 **Interactive Components** - Fully functional examples you can interact with
- 📱 **Responsive Design** - Examples adapt to different screen sizes
- 🎨 **Theme Integration** - All examples respect light/dark theme settings

Visit the [Screen Examples page](https://hellboy-ds.web.app/screen-examples) to explore interactive implementations.

## �📐 Package Architecture

### Build Output

```
dist/
├── index.css              # Complete CSS bundle (~133 KB minified)
├── index.js               # All components (CommonJS)
├── index.mjs              # All components (ESM)
├── index.d.ts             # TypeScript declarations
└── components/
    ├── avatar.js          # Avatar component (CommonJS)
    ├── avatar.mjs         # Avatar component (ESM)
    ├── avatar.d.ts        # Avatar TypeScript types
    ├── avatar.css         # Avatar styles + all dependencies
    ├── toast.js           # Toast component (CommonJS)
    ├── toast.mjs          # Toast component (ESM)
    ├── toast.d.ts         # Toast TypeScript types
    ├── toast.css          # Toast styles + all dependencies
    └── ... (44 components)
```

### Import Patterns

```tsx
// ✅ Recommended: Full bundle
import '@hellboy/ds/index.css';
import { Button, Input, Dialog } from '@hellboy/ds';

// ✅ Advanced: Individual components (maximum tree-shaking)
import '@hellboy/ds/components/button/css';
import { Button } from '@hellboy/ds/components/button';
```

**Note**: Each component's CSS file includes all its dependencies, so you never need to manually import foundation files.

## 🤝 Contributing & Support

This design system is actively maintained with regular updates and new components being added. For bugs, feature requests, or questions, please refer to the [project documentation](https://hellboy-ds.web.app).

## 🚀 Getting Started Examples

### Simple Page

```tsx
import '@hellboy/ds/index.css';
import { Button, Input, Banner, Avatar } from '@hellboy/ds';

function App() {
  return (
    <div style={{ padding: '2rem' }}>
      <Avatar initials="JD" size="md" />
      
      <Banner type="info">Welcome to Hellboy DS!</Banner>
      
      <form style={{ marginTop: '1rem' }}>
        <Input label="Email" type="email" />
        <Input label="Password" type="password" />
        <Button type="submit" fullWidth>Sign In</Button>
      </form>
    </div>
  );
}
```

### With Theme Switching & Notifications

```tsx
import '@hellboy/ds/index.css';
import { ThemeControl, Button, Card, Toast, useToast } from '@hellboy/ds';

function App() {
  const { success } = useToast();
  
  return (
    <div style={{ padding: '2rem' }}>
      <Toast position="top-right" />
      
      <div style={{ position: 'fixed', top: '1rem', right: '1rem' }}>
        <ThemeControl />
      </div>
      
      <Card>
        <h1>My App</h1>
        <p>Theme automatically applies to all components!</p>
        <Button onClick={() => success('Everything works!')}>Click me</Button>
      </Card>
    </div>
  );
}
```

## 📁 Internal Structure Notes

This package uses wrapper files (`src/styles.css`, `src/tokens/index.css`, `src/themes/index.css`) to align with design system instructions while maintaining centralized authoring in `src/style/`. The canonical source for styles remains in `src/style/`; wrapper files are compatibility layers for the expected repo layout.

For development, edit files under `src/style/` and rebuild to propagate changes. The build process copies styles to `dist/` as expected by package exports.