@hellboy/ds 0.1.2 → 0.1.3

package/README.md

@@ -1,65 +1,119 @@
-# Hellboy Design System - Core
+# Hellboy Design System
 
-Base package for the Hellboy Design System containing foundational components, tokens, and styling utilities.
+A comprehensive, accessible-first design system built with React, TypeScript, and modern web standards.
 
 ## 📦 Package Contents
 
-### Tokens
-- **Colors**: Primary, neutral, and semantic colors
-- **Typography**: Font families, sizes, weights, and line heights
-- **Spacing**: Consistent spacing scale
+### 🎨 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`
 
-### Foundations
-- **Global Reset**: Base HTML and element resets
-- **Utilities**: Helper functions for style injection
+### 🧱 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
 
-### Components
-- **Button**: Accessible interactive component with multiple variants and sizes (powered by AriaKit)
+### 🎯 Components
+
+**Layout & Structure**
+- **Layout** - Main application layout with navigation
+- **Page** - Page wrapper with consistent spacing
+- **Header** - Page headers with titles, subtitles, and tags
+- **Section** - Content sections with automatic indexing
+- **Grid** - Responsive grid system
+- **Card** - Content cards with variants
+- **Footer** - Page footer component
+
+**Forms & Inputs**
+- **Button** - Interactive buttons with variants, sizes, icons, and loading states
+- **Checkbox** - Accessible checkboxes with label support
+- **Radio** - Radio button groups
+- **Select** - Dropdown selection component
+- **Input** - Text inputs (text, email, password, search, tel, url, number, date, time, datetime)
+- **Slider** - Range slider control
+
+**Navigation**
+- **Navbar** - Main navigation bar with routing
+- **FloatingBar** - Floating action bar
+
+**Feedback & Display**
+- **Badge** - Status and label badges
+- **Banner** - Alert and notification banners
+- **CodeBlock** - Syntax-highlighted code display
+- **List** - Structured list component
+
+**Interactive**
+- **ThemeControl** - Theme switcher component
+- **ColorControl** - Color customization interface
+- **DragHandle** - Drag and drop handles
+- **Icons** - Iconify integration with thousands of icons
 
 ## 🚀 Getting Started
 
 ### Installation
 
 ```bash
-npm install @hellboy-ds/core @ariakit/react react react-dom
+npm install @hellboy/ds @ariakit/react react react-dom
 ```
 
 ### Usage
 
 ```tsx
-import { Button, injectGlobalStyles } from '@hellboy-ds/core';
-
-// Inject global styles once at app initialization
-injectGlobalStyles();
+import { Button, Layout, Page, Header, Section } from '@hellboy/ds';
+import '@hellboy/ds/styles.css';
 
-// Use the Button component
 export function App() {
   return (
-    <div>
-      <Button>Primary Button</Button>
-      <Button variant="secondary">Secondary Button</Button>
-      <Button variant="tertiary">Tertiary Button</Button>
-      <Button size="lg">Large Button</Button>
-      <Button isLoading>Loading...</Button>
-      <Button disabled>Disabled Button</Button>
-    </div>
+    <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>
   );
 }
 ```
 
-## 🎨 Customization
+## 🎨 Theme System
 
-All tokens are exported and can be imported directly:
+Hellboy includes a comprehensive theming system with light/dark modes and customizable colors:
 
 ```tsx
-import { colors, typography, spacing } from '@hellboy-ds/core';
-
-// Use tokens in your components
-const customStyle = {
-  color: colors.primary,
-  fontSize: typography.fontSize.lg,
-  padding: spacing[4],
-};
+import { getUserPreferences, setUserPreferences } from '@hellboy/ds';
+
+// Get current preferences
+const prefs = getUserPreferences();
+console.log(prefs.theme); // 'light' | 'dark' | 'auto'
+
+// Update theme
+setUserPreferences({ theme: 'dark' });
+
+// Customize colors
+setUserPreferences({
+  colors: {
+    primary: { hue: 220, saturation: 70, lightness: 50 }
+  }
+});
 ```
 
 ## 📝 Building
@@ -72,40 +126,133 @@ npm run clean      # Clean dist directory
 
 ## 📋 Features
 
-- ✅ Built with AriaKit for accessibility
-- ✅ Full ARIA support out of the box
-- ✅ CSS-in-JS styling with inline tokens
-- ✅ Strongly typed TypeScript components
-- ✅ Consistent design tokens system
-- ✅ Semantic color palette
-- ✅ Responsive and accessible components
-- ✅ Loading and disabled states
-
-## 🔄 Component Variants
-
-### Button Variants
-- `primary` - Main action button
-- `secondary` - Alternative action button
-- `tertiary` - Low emphasis action button
-
-### Button Sizes
-- `sm` - Small (32px height)
-- `md` - Medium (40px height) - default
-- `lg` - Large (48px height)
-
-### Button Props
-- `variant` - Button style variant
+- ✅ **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`
+
+**Sizes:** `xs` | `sm` | `md` (default) | `lg`
+
+**Props:**
+- `variant` - Visual style
 - `size` - Button size
 - `isLoading` - Show loading spinner
-- `disabled` - Disable the button
-- `fullWidth` - Make button full width
-- All standard AriaKit button attributes are supported
+- `disabled` - Disable interaction
+- `fullWidth` - Expand to container width
+- `startIcon` / `endIcon` - Icon names from Iconify
+- `iconOnly` - Icon-only button (requires `aria-label`)
+
+```tsx
+<Button size="xs">Extra Small</Button>
+<Button size="sm">Small</Button>
+<Button size="md">Medium (Default)</Button>
+<Button size="lg">Large</Button>
+
+<Button variant="primary">Primary</Button>
+<Button variant="secondary">Secondary</Button>
+<Button variant="tertiary">Tertiary</Button>
+<Button variant="ghost">Ghost</Button>
+
+<Button startIcon="mdi:check">Save</Button>
+<Button endIcon="mdi:arrow-right">Next</Button>
+<Button iconOnly aria-label="Settings">
+  <Icon name="mdi:cog" />
+</Button>
+```
+
+### Input Types
+
+All inputs support standard HTML input props plus:
+- `label` - Input label text
+- `helperText` - Helper text below input
+- `error` - Error message
+- `fullWidth` - Expand to container width
+
+```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} />
+```
+
+### Card
+
+```tsx
+<Card variant="elevated">
+  <h3>Card Title</h3>
+  <p>Card content goes here</p>
+</Card>
+```
+
+### Badge
+
+```tsx
+<Badge variant="primary">New</Badge>
+<Badge variant="success">Active</Badge>
+<Badge variant="error">Error</Badge>
+```
 
 ## ♿ Accessibility
 
-All components are built with accessibility in mind:
-- Full keyboard navigation support
-- ARIA attributes automatically managed
-- Screen reader friendly
-- Focus management
-- Semantic HTML
+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
+
+## 🏗️ Development Status
+
+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.
+
+**What's Ready:**
+- Core theming system with light/dark modes
+- 25+ production-ready components
+- Full TypeScript support
+- Comprehensive accessibility features
+
+**In Progress:**
+- Additional component variants
+- Enhanced customization APIs
+- Expanded documentation
+- Performance optimizations
+
+## 📦 Package Structure
+
+```
+@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
+
+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.
+
+## 📄 License
+
+MIT
+
+---
+
+**Built with the philosophy of balance:** Light and Dark, Chaos and Precision, Beauty and Function. ✨

package/dist/index.css

@@ -302,7 +302,7 @@ h6 {
   font-weight: var(--font-weight-semibold);
   line-height: var(--line-height-tight);
   color: var(--color-text-primary);
-  margin: 0 0 var(--spacing-2) 0;
+  margin: var(--spacing-6) 0 var(--spacing-2) 0;
 }
 h1 {
   font-size: var(--font-size-4xl);