@rhavenside/baseline

v2.1.4

Published

6 months ago

A strict, layer-based design system with semantic tokens

0High
0Medium
0Low

rhavenside

design-system css scss tokens components baseline baseline

Base-Line Design System

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

📚 Documentation • 🎨 Examples

Installation

Install Base-Line via npm:

npm install @rhavenside/baseline

Or via CDN:

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

Quick Start

Base-Line automatically includes Cadence for motion and Scaffold for layouts. No additional setup required!

CSS Only

Include the CSS file in your 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:

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

Or using CommonJS:

require('@rhavenside/baseline/js')

In Your Build System

Webpack / Vite / Rollup

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

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

Sass/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):

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:

<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 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 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 for standalone usage.

Working Together

Here's how they work together in practice:

<!-- 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.

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

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

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

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

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

<!-- 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:

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:

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

<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

<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

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

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

<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 class="theme-dark">

Or via data attribute:

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

Theming

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

: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) 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 file for details.

npm Package

Built with ❤️