npm package: @rhavenside/baseline
Description: A strict, layer-based design system with semantic tokens
Latest version: 2.1.4

# Base-Line Design System

<div align="center">
  <img src="https://examples.rhavenside.de/logo.svg" alt="Base-Line Logo" width="64" height="64">
</div>

A strict, layer-based design system with semantic tokens. Features a custom naming convention and token-based theming system.

[![npm version](https://img.shields.io/npm/v/@rhavenside/baseline.svg)](https://www.npmjs.com/package/@rhavenside/baseline)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

<div align="center">

**[📚 Documentation](https://baseline.rhavenside.de)** • **[🎨 Examples](https://examples.rhavenside.de)**

</div>

## Installation

Install Base-Line via npm:

```bash
npm install @rhavenside/baseline
```

Or via CDN:

```html
<link rel="stylesheet" href="https://unpkg.com/@rhavenside/baseline/dist/base-line.css">
```

## Quick Start

Base-Line automatically includes [Cadence](https://www.npmjs.com/package/@rhavenside/cadence) for motion and [Scaffold](https://www.npmjs.com/package/@rhavenside/scaffold) for layouts. No additional setup required!

### CSS Only

Include the CSS file in your HTML:

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <link rel="stylesheet" href="node_modules/@rhavenside/baseline/dist/base-line.css">
  <title>Base-Line Example</title>
</head>
<body>
  <div class="scaffold-container">
    <div class="scaffold-stack scaffold-stack--spacing-lg">
      <h1>Hello Base-Line</h1>
      <p>Welcome to the Base-Line Design System</p>
      <button class="c-button c-button--primary">Get Started</button>
    </div>
  </div>
</body>
</html>
```

**Note:** The example above uses Scaffold layout classes (`scaffold-container`, `scaffold-stack`) for structured layouts. All components use Cadence motion mixins automatically for smooth, consistent animations.

### With JavaScript

For interactive components (modals, dropdowns, tooltips, etc.), include the JavaScript:

```html
<script type="module">
  import '@rhavenside/baseline/js'
</script>
```

Or using CommonJS:

```javascript
require('@rhavenside/baseline/js')
```

### In Your Build System

#### Webpack / Vite / Rollup

```javascript
// Import CSS
import '@rhavenside/baseline/css'

// Import JavaScript
import { Modal, Dropdown, Tooltip } from '@rhavenside/baseline/js'
```

#### Sass/SCSS

```scss
// Import the full system
@import '~@rhavenside/baseline/dist/base-line.css';

// Or import SCSS source (if available)
@import '~@rhavenside/baseline/src/base.scss';
```

## Package Contents

After installation, the package includes:

```
node_modules/@rhavenside/baseline/
├── dist/
│   ├── base-line.css          # Compiled CSS (compressed)
│   ├── base-line.css.map      # Source map
│   ├── js/
│   │   ├── index.js           # Main JavaScript entry point
│   │   ├── alert.js
│   │   ├── button.js
│   │   ├── modal.js
│   │   └── ...                # All component files
│   └── fonts/
│       ├── baseline-icons.woff
│       ├── baseline-icons.woff2
│       └── *.ttf              # Custom fonts
```

## Architecture

The system is divided into 4 clear layers:

### Layer 1: Design Tokens (Foundation)

All design values are defined via CSS Custom Properties:

- **Colors**: Surface, Text, Accent, Border, State colors
- **Typography**: Font families, sizes, line-height, weight
- **Spacing**: Consistent step scale (based on Scaffold spacing: 8px/0.5rem base)
- **Radius**: Border-radius values
- **Shadow**: Shadow definitions
- **Z-Index**: Z-index scale
- **Motion**: Duration + easing functions

**Rule:** No value without token. Exception: `0` and `auto`.

### Layer 2: Layout System

Layout classes for standard layouts without custom CSS (powered by [Scaffold](https://www.npmjs.com/package/@rhavenside/scaffold)):

- `scaffold-container` - Container with max-width + responsive padding
- `scaffold-stack` - Vertical layouts with spacing options
- `scaffold-grid` - Flexible grid layouts (responsive columns)
- `scaffold-padding-*` - Padding utilities (xs, sm, md, lg, xl, xxl) with directional variants
- `scaffold-margin-*` - Margin utilities (xs, sm, md, lg, xl, xxl) with directional variants

**Rule:** No colors, no typography in layout classes.

**Example:**
```html
<div class="scaffold-container">
  <div class="scaffold-stack scaffold-stack--spacing-lg">
    <h1>Title</h1>
    <p>Content</p>
  </div>
  <div class="scaffold-grid scaffold-grid--cols-3">
    <div class="c-card">Card 1</div>
    <div class="c-card">Card 2</div>
    <div class="c-card">Card 3</div>
  </div>
</div>
```

### Motion System (Cadence)

All animations and transitions use [Cadence](https://www.npmjs.com/package/@rhavenside/cadence) for consistent motion timing:

- **motion-response()** - For direct user interactions (150ms) - Used in buttons, inputs, form controls
- **motion-transition()** - For state changes (300ms) - Used in modals, dropdowns, tooltips, alerts
- **motion-ambient()** - For continuous animations (varies) - Used in spinners, progress bars
- **motion-instant()** - For immediate changes (0ms) - Used for instant state updates

All components automatically use the appropriate motion intention based on their interaction pattern. This ensures consistent, accessible animations throughout your application.

## How Cadence, Scaffold, and Baseline Work Together

Base-Line is built on three complementary systems that work seamlessly together:

### Baseline - The Design System

**Baseline** provides the core design system:
- **Components**: Buttons, Cards, Modals, Forms, and 20+ other UI components
- **Design Tokens**: Colors, typography, spacing, shadows, and other design values
- **Utilities**: Limited utility classes for common needs

### Scaffold - The Layout System

**Scaffold** provides structured layout classes:
- **Container**: `scaffold-container` for max-width containers with responsive padding
- **Stack**: `scaffold-stack` for vertical layouts with consistent spacing
- **Grid**: `scaffold-grid` for flexible, responsive grid layouts
- **Padding**: Responsive padding utilities

Scaffold handles the **structure** of your page - where things are positioned and how they're spaced.

> **Note:** Scaffold can also be used independently. See [@rhavenside/scaffold](https://www.npmjs.com/package/@rhavenside/scaffold) for standalone usage.

### Cadence - The Motion System

**Cadence** provides consistent motion and animations:
- **Motion Intentions**: Different timing for different interaction types
  - `motion-response()` - Fast feedback for direct user actions (150ms)
  - `motion-transition()` - Smooth state changes (300ms)
  - `motion-ambient()` - Continuous animations (varies)
- **Automatic Integration**: All Baseline components automatically use Cadence for animations

Cadence handles the **motion** - how things animate and transition.

> **Note:** Cadence can also be used independently. See [@rhavenside/cadence](https://www.npmjs.com/package/@rhavenside/cadence) for standalone usage.

### Working Together

Here's how they work together in practice:

```html
<!-- Scaffold provides the layout structure -->
<div class="scaffold-container">
  <div class="scaffold-stack scaffold-stack--spacing-lg">
    
    <!-- Baseline provides the components -->
    <h1>Welcome</h1>
    <button class="c-button c-button--primary">Get Started</button>
    
    <!-- Cadence automatically animates the button on hover/click -->
    <!-- Scaffold provides spacing between elements -->
    <div class="scaffold-grid scaffold-grid--cols-3">
      <div class="c-card">
        <!-- Cadence animates card hover states -->
        Card 1
      </div>
      <div class="c-card">Card 2</div>
      <div class="c-card">Card 3</div>
    </div>
  </div>
</div>
```

**In summary:**
- **Scaffold** = Where things go (layout structure)
- **Baseline** = What things look like (components and design)
- **Cadence** = How things move (animations and transitions)

All three are included automatically when you install `@rhavenside/baseline` - no additional setup required!

> **Note:** This is a high-level overview. Detailed documentation for each system is available in the [full documentation](https://baseline.rhavenside.de).

### Layer 3: Components

Fully functional components with JavaScript support:

- **Buttons**: Primary, Secondary, Outline, Link variants
- **Forms**: Input, Select, Textarea, Checkbox, Radio, Switch, Range
- **Cards**: Standard, Elevated, Bordered variants
- **Modals**: Dialogs with backdrop and animations
- **Dropdowns**: Menus with positioning
- **Tooltips & Popovers**: Contextual information
- **Alerts**: Dismissible notifications
- **Badges**: Status indicators and shields
- **Tables**: Responsive tables with variants
- **Navigation**: Navbar, Nav, Tabs
- **Accordion**: Collapsible content sections
- **Carousel**: Image/content sliders
- **Pagination**: Page navigation
- **Progress**: Progress bars
- **Spinners**: Loading indicators
- **Toasts**: Toast notifications
- **Offcanvas**: Slide-out panels
- **Breadcrumbs**: Navigation breadcrumbs
- **List Groups**: Structured lists
- **Input Groups**: Combined form inputs

**Rule:** Components are state-driven and use tokens exclusively.

### Layer 4: Utilities

Intentionally limited utilities:

- Visibility (`u-hidden`, `u-visually-hidden`)
- Text alignment (`u-text-center`, `u-text-start`, etc.)
- Font size (`u-fs-1` to `u-fs-6`)
- Font weight (`u-fw-normal`, `u-fw-bold`, etc.)
- Overflow (`u-overflow-hidden`, etc.)
- Alignment (`u-flex`, `u-justify-between`, etc.)
- Spacing (`u-m-*`, `u-p-*`, `u-gap-*`)

**Forbidden:** Padding utilities for design, color utilities, shadow utilities.

## Naming Convention

### Tokens

Format: `--<category>-<meaning>[-<level>]`

```css
--color-surface
--color-surface-muted
--color-accent
--space-1 to --space-n
--radius-sm, --radius-md
--shadow-1, --shadow-2
--duration-fast, --duration-normal
--ease-standard, --ease-emphasized
```

### Layout Classes

Format: `scaffold-<role>` (powered by [Scaffold](https://www.npmjs.com/package/@rhavenside/scaffold))

```html
<div class="scaffold-container">
<div class="scaffold-stack scaffold-stack--spacing-lg">
<div class="scaffold-stack scaffold-stack--horizontal scaffold-stack--align-center">
<div class="scaffold-grid scaffold-grid--cols-3">
<div class="scaffold-padding-sm scaffold-margin-top-md">
```

### Components

Format: `c-<component>`

```html
<button class="c-button c-button--primary">Button</button>
<input class="c-input" type="text">
<div class="c-card">
```

**Variants:**
- `c-button--primary`, `c-button--secondary`
- `c-alert--danger`, `c-alert--success`

**Global States:**
- `is-active`, `is-disabled`, `is-show` (for collapse/accordion)
- `is-loading`, `is-open`, `has-error`

### Utilities

Format: `u-<function>`

```html
<div class="u-hidden">
<div class="u-text-center">
<div class="u-flex u-justify-between">
```

## JavaScript API

### Data API (Automatic Initialization)

Components can be initialized automatically via data attributes:

```html
<!-- Modal -->
<button 
  type="button" 
  class="c-button" 
  data-c-toggle="modal" 
  data-c-target="#myModal">
  Open Modal
</button>

<!-- Tooltip -->
<button 
  type="button" 
  class="c-button" 
  data-c-toggle="tooltip" 
  data-c-placement="top" 
  title="Tooltip text">
  Hover me
</button>

<!-- Popover -->
<button 
  type="button" 
  class="c-button" 
  data-c-toggle="popover" 
  data-c-title="Popover title" 
  data-c-content="Popover content">
  Click me
</button>
```

### Programmatic API

Import and use components programmatically:

```javascript
import { Modal, Dropdown, Tooltip } from '@rhavenside/baseline/js'

// Create a modal instance
const modalElement = document.querySelector('#myModal')
const modal = Modal.getOrCreateInstance(modalElement, {
  backdrop: true,
  keyboard: true
})

// Show the modal
modal.show()

// Create a tooltip
const tooltipElement = document.querySelector('[data-c-toggle="tooltip"]')
const tooltip = Tooltip.getOrCreateInstance(tooltipElement, {
  title: 'Custom tooltip text',
  placement: 'top'
})

// Show the tooltip
tooltip.show()
```

### Global Access

When loaded via script tag, components are available globally:

```javascript
// Access via window.BaseLine
const modal = window.BaseLine.Modal.getOrCreateInstance(element)
const tooltip = window.BaseLine.Tooltip.getOrCreateInstance(element)
```

## Available Components

| Component | CSS Class | JavaScript | Description |
|-----------|-----------|------------|-------------|
| Alert | `.c-alert` | `Alert` | Contextual feedback messages |
| Badge | `.c-badge` | - | Status indicators |
| Breadcrumb | `.c-breadcrumb` | - | Navigation breadcrumbs |
| Button | `.c-button` | `Button` | Interactive buttons |
| Card | `.c-card` | - | Content containers |
| Carousel | `.c-carousel` | `Carousel` | Image/content sliders |
| Dropdown | `.c-dropdown` | `Dropdown` | Dropdown menus |
| Modal | `.c-modal` | `Modal` | Modal dialogs |
| Nav | `.c-nav` | `Tab` | Navigation and tabs |
| Navbar | `.c-navbar` | - | Navigation bars |
| Offcanvas | `.c-offcanvas` | `Offcanvas` | Slide-out panels |
| Pagination | `.c-pagination` | - | Page navigation |
| Popover | `.c-popover` | `Popover` | Popovers |
| Progress | `.c-progress` | - | Progress bars |
| Spinner | `.c-spinner` | - | Loading spinners |
| Toast | `.c-toast` | `Toast` | Toast notifications |
| Tooltip | `.c-tooltip` | `Tooltip` | Tooltips |
| Accordion | `.c-accordion` | `Accordion` | Collapsible sections |
| Forms | `.c-input`, `.c-form-control` | - | Form inputs |
| Table | `.c-table` | - | Data tables |
| List Group | `.c-list-group` | - | Structured lists |

## Examples

### Button

```html
<button class="c-button c-button--primary">Primary</button>
<button class="c-button c-button--secondary">Secondary</button>
<button class="c-button c-button--outline-primary">Outline</button>
```

### Card

```html
<div class="c-card">
  <div class="c-card__header">
    <h5 class="c-card__title">Card Title</h5>
  </div>
  <div class="c-card__body">
    <p>Card content goes here.</p>
  </div>
</div>
```

### Modal

```html
<!-- Trigger Button -->
<button 
  type="button" 
  class="c-button c-button--primary" 
  data-c-toggle="modal" 
  data-c-target="#exampleModal">
  Launch Modal
</button>

<!-- Modal -->
<div class="c-modal c-fade" id="exampleModal" tabindex="-1">
  <div class="c-modal-dialog">
    <div class="c-modal-content">
      <div class="c-modal-header">
        <h5 class="c-modal-title">Modal Title</h5>
        <button type="button" class="c-close" data-c-dismiss="modal"></button>
      </div>
      <div class="c-modal-body">
        <p>Modal body text goes here.</p>
      </div>
      <div class="c-modal-footer">
        <button type="button" class="c-button c-button--secondary" data-c-dismiss="modal">Close</button>
        <button type="button" class="c-button c-button--primary">Save changes</button>
      </div>
    </div>
  </div>
</div>
```

### Form

```html
<div class="scaffold-container scaffold-container--narrow">
  <div class="scaffold-stack scaffold-stack--spacing-md">
    <div class="scaffold-stack scaffold-stack--spacing-sm">
      <label class="c-form-label" for="email">Email</label>
      <input type="email" class="c-form-control" id="email" placeholder="name@example.com">
    </div>

    <div class="scaffold-stack scaffold-stack--spacing-sm">
      <label class="c-form-label" for="password">Password</label>
      <input type="password" class="c-form-control" id="password">
    </div>

    <button type="submit" class="c-button c-button--primary">Submit</button>
  </div>
</div>
```

**Note:** This example demonstrates Scaffold layout classes for structured form layouts. All form inputs automatically use Cadence motion-response() for smooth focus and interaction transitions.

### Accordion

```html
<div class="c-accordion" id="accordionExample">
  <div class="c-accordion-item">
    <h2 class="c-accordion-header">
      <button
        class="c-accordion-button"
        type="button"
        data-c-toggle="collapse"
        data-c-target="#collapseOne"
        data-c-parent="#accordionExample">
        Accordion Item #1
      </button>
    </h2>
    <div id="collapseOne" class="c-collapse is-show" data-c-parent="#accordionExample">
      <div class="c-accordion-body">
        This is the first accordion body. It is open by default (has `is-show` class).
      </div>
    </div>
  </div>
  <div class="c-accordion-item">
    <h2 class="c-accordion-header">
      <button
        class="c-accordion-button c-collapsed"
        type="button"
        data-c-toggle="collapse"
        data-c-target="#collapseTwo"
        data-c-parent="#accordionExample">
        Accordion Item #2
      </button>
    </h2>
    <div id="collapseTwo" class="c-collapse" data-c-parent="#accordionExample">
      <div class="c-accordion-body">
        This is the second accordion body. It is closed by default (no `is-show` class, button has `c-collapsed`).
      </div>
    </div>
  </div>
</div>
```

**Note:** By default, only the first accordion item should be open (with `is-show` class on the collapse element). Other items should be closed (no `is-show` class, button has `c-collapsed` class). Accordions use Cadence motion-transition() for smooth expand/collapse animations.

## Dark Mode

Dark mode is automatically activated via `prefers-color-scheme`. Additionally, the `.theme-dark` class can be set manually:

```html
<html class="theme-dark">
```

Or via data attribute:

```html
<html data-bl-theme="dark">
```

## Theming

The system can be extended project-specifically without changing the core:

```css
:root {
  --color-accent: #0066cc;
  --color-primary: #0066cc;
  --space-4: 1.5rem;
  --radius-md: 0.5rem;
}

.theme-dark,
[data-bl-theme="dark"] {
  --color-surface: #1a1a1a;
  --color-text: #ffffff;
}
```

## Responsive Font Sizing (RFS)

Base-Line includes [RFS (Responsive Font Size)](https://github.com/twbs/rfs) for automatic responsive font sizing. All font sizes, paddings, and margins above 1.25rem automatically scale down on smaller screens.

## Browser Support

Base-Line supports all modern browsers:

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

## Dependencies

Base-Line includes the following peer dependencies that are automatically installed:

- **@rhavenside/cadence**: ^1.0.1 - Motion system for consistent animations and transitions
- **@rhavenside/scaffold**: ^1.1.9 - Layout system for structured page layouts
- **@popperjs/core**: ^2.11.8 - For positioning tooltips, popovers, and dropdowns

All dependencies are automatically installed when you install `@rhavenside/baseline`. No additional setup required!

## Version History

### Version 2.1.0 and above

**New Dependencies: Scaffold and Cadence Integration**

Version 2.1.0 introduces two new integrated systems:

**Scaffold Layout System (NEW)**

- **Scaffold is now included**: Scaffold layout classes are now part of Base-Line
- **Layout Classes Available**: Use `scaffold-container`, `scaffold-stack`, `scaffold-grid` for structured page layouts
- **Responsive by Default**: All Scaffold classes are responsive and work seamlessly with Baseline components

**Cadence Motion System Integration**

All interactive components now use the Cadence motion system for consistent, accessible animations:

- **Motion-Mixins in Components**: 10 components have been updated to use Cadence motion mixins:
  - `motion-transition()` for state changes (Alert, Toast, Tooltip, Popover, Dropdown, Accordion, Floating Label)
  - `motion-response()` for direct user interactions (Form Range, List Group)
- **Consistent Animation Timing**: All components now follow the same motion principles:
  - 150ms for direct user interactions (`motion-response`)
  - 300ms for state changes (`motion-transition`)
- **Improved Documentation**: README now includes comprehensive documentation for:
  - Cadence motion system integration
  - Scaffold layout system usage
  - Dependencies and their purposes

**Benefits:**
- Structured layout system (Scaffold) for consistent page layouts
- More consistent animations across all components (Cadence)
- Better accessibility (respects `prefers-reduced-motion`)
- Easier to maintain and extend motion behavior
- Clear motion intentions for different interaction types

### Version 2.0.8 and below

**Before 2.1.0:**

- **No Scaffold**: Layout classes were not available - developers had to create their own layout solutions
- **No unified motion system**: Components used hardcoded transition values or CSS variables for animations
- **Manual transition timing**: Manual transition timing management required
- **Less consistent**: Less consistent animation behavior across components

**Migration Notes:**

If you're upgrading from 2.0.8 or earlier:

- **No breaking changes**: All existing code will continue to work without modifications
- **Scaffold is NEW**: Scaffold layout classes (`scaffold-container`, `scaffold-stack`, `scaffold-grid`, etc.) are now available in Base-Line 2.1.0. You can start using them for structured page layouts
- **Motion improvements are internal**: The Cadence motion mixins are internal improvements that make animations more consistent. Existing component behavior remains the same
- **New features available**: You can now take advantage of:
  - Scaffold layout system for structured page layouts
  - More consistent animations (automatic, no code changes needed)
  - Better motion system documentation

If you were using custom transitions that override component defaults, you may want to review them to ensure they align with the new motion system principles (150ms for interactions, 300ms for state changes).

## License

MIT License - see [LICENSE](LICENSE) file for details.

- [npm Package](https://www.npmjs.com/package/@rhavenside/baseline)



Built with ❤️