🔥 @hellboy/ds - Hellboy Design System

Where chaos meets precision: A comprehensive, accessible-first design system for modern React applications

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

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:

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:

// 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

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="[email protected]" />
    </div>
  );
}

import { Button, Input, Dialog, Banner, ThemeControl } from '@hellboy/ds';

export function App() { return ( {/* Theme switcher in top-right corner */}

  {/* 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="[email protected]" />
</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:

// ✅ 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)

{
  "@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)

{
  "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

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:

: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

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

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

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

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

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

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

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

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

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

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

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

📱 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 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

// ✅ 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.

🚀 Getting Started Examples

Simple Page

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

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.