@hellboy/ds 0.1.3 → 0.2.7

package/README.md

@@ -1,149 +1,296 @@
-# Hellboy Design System
+# 🔥 @hellboy/ds - Hellboy Design System
 
-A comprehensive, accessible-first design system built with React, TypeScript, and modern web standards.
+> _Where chaos meets precision: A comprehensive, accessible-first design system for modern React applications_
 
-## 📦 Package Contents
+[![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/)
 
-### 🎨 Design Tokens
-- **Colors**: HSLA-based semantic color system with 7 base hues (primary, secondary, accent, success, warning, error, info)
-- **Typography**: Signika (headings) and Rubik (body) font families with consistent scale
-- **Spacing**: Consistent spacing scale from `--spacing-1` to `--spacing-16`
-- **Motion**: Transition tokens respecting `prefers-reduced-motion`
+A complete design system with **42+ production-ready components**, dual theming (light/dark), and comprehensive accessibility features built with React, TypeScript, and modern web standards.
 
-### 🧱 Foundations
-- **Global Styles**: Base HTML resets and typography
-- **Theme System**: Light/Dark modes with automatic system preference detection
-- **User Preferences**: Persistent theme and color settings
+## ✨ Features
 
-### 🎯 Components
+- 🎨 **42+ Components** - Buttons, inputs, dialogs, tables, 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
 
-**Layout & Structure**
+## 🚀 Installation
+
+```bash
+npm install @hellboy/ds
+
+# Peer dependencies (if not already installed)
+npm install react react-dom
+```
+
+**That's it!** All component dependencies are automatically included in the CSS bundles.
+
+## 📖 Quick Start
+
+### Basic Usage
+
+```tsx
+import '@hellboy/ds/dist/index.css';
+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/dist/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
+- **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 with variants, sizes, icons, and loading states
+### 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
-- **Input** - Text inputs (text, email, password, search, tel, url, number, date, time, datetime)
+  - 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
-
-**Navigation**
-- **Navbar** - Main navigation bar with routing
+  - 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
-
-**Feedback & Display**
-- **Badge** - Status and label badges
-- **Banner** - Alert and notification banners
+  - Dependencies: foundations, theme
+- **PageIndex** - Auto-generated page navigation from sections
+  - Dependencies: foundations, theme
+
+### Feedback & Display
+- **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
+- **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
-
-**Interactive**
-- **ThemeControl** - Theme switcher 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
-- **Icons** - Iconify integration with thousands of icons
-
-## 🚀 Getting Started
-
-### Installation
-
-```bash
-npm install @hellboy/ds @ariakit/react react react-dom
+  - 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)
+}
 ```
 
-### Usage
-
-```tsx
-import { Button, Layout, Page, Header, Section } from '@hellboy/ds';
-import '@hellboy/ds/styles.css';
-
-export function App() {
-  return (
-    <Layout>
-      <Page>
-        <Header 
-          title="Welcome" 
-          subtitle="Hellboy Design System"
-          tags={['React', 'TypeScript', 'Accessible']}
-        />
-        
-        <Section title="Getting Started">
-          <Button>Primary Button</Button>
-          <Button variant="secondary">Secondary Button</Button>
-          <Button variant="tertiary">Tertiary Button</Button>
-          <Button variant="ghost">Ghost Button</Button>
-          
-          <Button size="xs">Extra Small</Button>
-          <Button size="sm">Small</Button>
-          <Button size="md">Medium</Button>
-          <Button size="lg">Large</Button>
-          
-          <Button isLoading>Loading...</Button>
-          <Button startIcon="mdi:check">With Icon</Button>
-        </Section>
-      </Page>
-    </Layout>
-  );
+### 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
 
-Hellboy includes a comprehensive theming system with light/dark modes and customizable colors:
+### Using Themes
 
 ```tsx
-import { getUserPreferences, setUserPreferences } from '@hellboy/ds';
+import { setTheme, getTheme, getUserPreferences, setUserPreferences } from '@hellboy/ds';
 
-// Get current preferences
+// 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 theme
-setUserPreferences({ theme: 'dark' });
-
-// Customize colors
-setUserPreferences({
+// Update preferences
+setUserPreferences({ 
+  theme: 'dark',
   colors: {
     primary: { hue: 220, saturation: 70, lightness: 50 }
   }
 });
 ```
 
-## 📝 Building
-
-```bash
-npm run build      # Build the package
-npm run dev        # Watch mode
-npm run clean      # Clean dist directory
+### 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 */
+}
 ```
 
-## 📋 Features
-
-- ✅ **Accessibility-First**: Built with WCAG 2.1 AA compliance and AriaKit primitives
-- ✅ **TypeScript Native**: Full type safety and IntelliSense support
-- ✅ **Theme System**: Light/Dark modes with customizable colors (HSLA-based)
-- ✅ **Responsive**: Mobile-first, adaptive components
-- ✅ **Iconify Integration**: Access to thousands of icons
-- ✅ **Persistent Preferences**: User theme and color choices saved locally
-- ✅ **Modern Stack**: React 18+, CSS Custom Properties, Vite-optimized
-- ✅ **Semantic HTML**: Proper markup with ARIA attributes
-- ✅ **Performance**: CSS-first styling, minimal runtime overhead
-
 ## 🔄 Component API Examples
 
 ### Button
 
-**Variants:** `primary` | `secondary` | `tertiary` | `ghost`
-
+**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
@@ -153,106 +300,309 @@ npm run clean      # Clean dist directory
 - `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
-<Button size="xs">Extra Small</Button>
-<Button size="sm">Small</Button>
-<Button size="md">Medium (Default)</Button>
-<Button size="lg">Large</Button>
+import { InputText, InputEmail, InputPassword, InputNumber } from '@hellboy/ds';
 
-<Button variant="primary">Primary</Button>
-<Button variant="secondary">Secondary</Button>
-<Button variant="tertiary">Tertiary</Button>
-<Button variant="ghost">Ghost</Button>
+// Basic inputs
+<InputText label="Name" placeholder="Enter your name" />
+<InputEmail label="Email" required />
+<InputPassword label="Password" />
 
-<Button startIcon="mdi:check">Save</Button>
-<Button endIcon="mdi:arrow-right">Next</Button>
-<Button iconOnly aria-label="Settings">
-  <Icon name="mdi:cog" />
-</Button>
-```
+// 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" />
 
-### Input Types
+// Sizes
+<InputText size="sm" label="Small" />
+<InputText size="md" label="Medium" />
+<InputText size="lg" label="Large" />
+```
 
-All inputs support standard HTML input props plus:
+**Props:**
 - `label` - Input label text
 - `helperText` - Helper text below input
-- `error` - Error message
+- `error` - Error message (triggers error state)
 - `fullWidth` - Expand to container width
+- `size` - Input size: `sm` | `md` | `lg`
+
+### Textarea
 
 ```tsx
-<InputText label="Name" placeholder="Enter your name" />
-<InputEmail label="Email" required />
-<InputPassword label="Password" />
-<InputDate label="Birthday" />
-<InputNumber label="Age" min={0} max={120} />
+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>
 ```
 
-### Card
+### Dialog
 
 ```tsx
-<Card variant="elevated">
-  <h3>Card Title</h3>
-  <p>Card content goes here</p>
-</Card>
+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>
+    </>
+  );
+}
 ```
 
-### Badge
+### 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="success">Active</Badge>
-<Badge variant="error">Error</Badge>
+<Badge variant="error">5</Badge>
+```
+
+### 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');
 ```
 
+## 🖥️ 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:
 
-- **Keyboard Navigation**: Full support across all interactive components with logical tab order
-- **Screen Reader Support**: Proper ARIA labels, roles, and live regions
-- **Focus Management**: Visible focus indicators respecting user preferences
-- **Semantic HTML**: Native elements enhanced with ARIA when needed
-- **Color Contrast**: WCAG AA compliant color combinations in both themes
-- **Motion Respect**: Honors `prefers-reduced-motion` for animations
-- **AriaKit Foundation**: Leverages battle-tested accessibility primitives
+- ✅ **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
+- 🎯 **Focus Management** - Visible focus indicators respecting user preferences
+- 🏗️ **Semantic HTML** - Native elements enhanced with ARIA when needed
+- 🎨 **Color Contrast** - AA compliant in both light and dark themes
+- ⚡ **Motion Respect** - Honors `prefers-reduced-motion` for animations
+- 🔧 **AriaKit Foundation** - Built on battle-tested accessibility primitives from AriaKit
 
-## 🏗️ Development Status
+## 📐 Package Architecture
 
-Hellboy Design System is currently in **active development** (v0.1.x). The core architecture and components are production-ready for testing and exploration, with ongoing iterations to enhance functionality and accessibility coverage.
+### Build Output
 
-**What's Ready:**
-- Core theming system with light/dark modes
-- 25+ production-ready components
-- Full TypeScript support
-- Comprehensive accessibility features
+```
+dist/
+├── index.css              # Complete CSS bundle (~120 KB minified)
+├── index.js               # All components (CommonJS)
+├── index.mjs              # All components (ESM)
+├── index.d.ts             # TypeScript declarations
+├── theme.css              # Theme variables only
+└── components/
+    ├── button.js          # Button component (CommonJS)
+    ├── button.mjs         # Button component (ESM)
+    ├── button.d.ts        # Button TypeScript types
+    ├── button.css         # Button styles + all dependencies
+    └── ... (42 components)
+```
 
-**In Progress:**
-- Additional component variants
-- Enhanced customization APIs
-- Expanded documentation
-- Performance optimizations
+### Import Patterns
 
-## 📦 Package Structure
+```tsx
+// ✅ Recommended: Full bundle
+import '@hellboy/ds/dist/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';
+
+// ✅ Theme only (if building custom CSS)
+import '@hellboy/ds/dist/theme.css';
 ```
-@hellboy/ds
-├── components/     # All React components
-├── style/          # CSS and theming
-│   ├── foundations/   # Base styles
-│   ├── themes/        # Light/dark themes
-│   └── components/    # Component styles
-├── utils/          # Utility functions
-└── contexts/       # React contexts
-```
 
-## 🤝 Contributing
+**Note**: Each component's CSS file includes all its dependencies, so you never need to manually import foundation files.
+
+## 🚀 Getting Started Examples
 
-This is an evolving design system. Feedback and contributions are welcome as the system matures toward its comprehensive vision of balanced, accessible, and beautiful design.
+### Simple Page
+
+```tsx
+import '@hellboy/ds/dist/index.css';
+import { Button, Input, Banner } from '@hellboy/ds';
 
-## 📄 License
+function App() {
+  return (
+    <div style={{ padding: '2rem' }}>
+      <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>
+  );
+}
+```
 
-MIT
+### With Theme Switching
 
----
+```tsx
+import '@hellboy/ds/dist/index.css';
+import { ThemeControl, Button, Card } from '@hellboy/ds';
 
-**Built with the philosophy of balance:** Light and Dark, Chaos and Precision, Beauty and Function. ✨
+function App() {
+  return (
+    <div style={{ padding: '2rem' }}>
+      <div style={{ position: 'fixed', top: '1rem', right: '1rem' }}>
+        <ThemeControl />
+      </div>
+      
+      <Card>
+        <h1>My App</h1>
+        <p>Theme automatically applies to all components!</p>
+        <Button>Click me</Button>
+      </Card>
+    </div>
+  );
+}
+```