baseline-kit v3.0.2

Baseline Kit

Baseline Kit is a lightweight development tool for visualizing and debugging grid systems and spacing in React applications. It provides configurable overlays for both column-based and baseline grids, flexible layout components, and theme-aware configuration—all optimized for performance and built with TypeScript. The library is based on the "Padded Grid" concept, originally explored in this article on achieving perfect baseline alignment in digital layouts.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Core Concepts
  • Base Unit
  • Spacing Values
  • Grid Snapping
  • Debugging Modes
• Components
  • Component Hierarchy
  • Key Components
    • Config
    • Baseline
    • Guide
    • Box
• Theme System
  • CSS Import Options
  • Theme Options
  • Theme Variables Reference
• Browser Support
• React 19 Features
• Server-Side Rendering (SSR)
  • SSR-Friendly Design
  • SSR Mode Prop
• Development
• Performance Features
• Contributing
• License

Features

• 📏 Baseline Grid: Core system for maintaining vertical rhythm and consistent spacing across your layouts
• 🎯 Column Grid Guide: Customizable overlay system for visualizing column-based layouts and alignment
• 📦 Box Component: Basic container with configurable spacing that snaps to the baseline grid
• 🧩 Layout Component: CSS Grid-based container with automatic column calculations and baseline alignment
• 📐 Stack Component: Flex-based container that maintains consistent spacing and baseline alignment
• 🎨 Theme System: Customizable colors and debug visuals through a centralized configuration

Requirements

• React 19: Baseline Kit is built for React 19 and uses the latest React features like the use hook
• Modern Browsers: Supporting the latest CSS features

Installation

# Using npm
npm install baseline-kit

# Using yarn
yarn add baseline-kit

# Using pnpm
pnpm add baseline-kit

After installation, import both the styles and theme in your application:

// Import in your main entry file (e.g., index.js, App.js)
import 'baseline-kit/styles';  // Required core styles
import 'baseline-kit/theme';   // Recommended theme (or use your own)

For frameworks like Remix that use URL imports in a links function:

export const links = () => [
  { rel: "stylesheet", href: "baseline-kit/styles" },
  { rel: "stylesheet", href: "baseline-kit/theme" }
];

If you prefer a single CSS file that includes everything:

// Alternative: Import everything in one file
import 'baseline-kit/full';

// For Remix:
export const links = () => [
  { rel: "stylesheet", href: "baseline-kit/full" }
];

Baseline Kit is written in TypeScript and includes built-in type definitions—no additional packages required.

Quick Start

import React from 'react'
import { Config, Guide, Baseline, Box } from 'baseline-kit'

function App() {
  const isDev = process.env.NODE_ENV === 'development'
  const debugging = isDev ? 'visible' : 'hidden'

  return (
    <Config
      base={8}
      baseline={{ debugging }}
      box={{ debugging }}
      guide={{ debugging }}
      spacer={{ debugging }}
    >
      {/* Baseline Grid for typography alignment */}
      <Baseline
        height="100vh"
        debugging="visible"
      />

      {/* Column Grid Guide */}
      <Guide
        variant="pattern"
        columns={['100px', '200px', '100px']}
        gap={16}
        align="center"
        width="1200px"
      />

      {/* Box with baseline alignment */}
      <Box
        block={[2, 5]}
        debugging="visible"
      >
        <h1>Content Aligned to the Grid</h1>
      </Box>

      <main>Your main content goes here...</main>
    </Config>
  )
}

Core Concepts

Base Unit

The base unit is the foundation of Baseline Kit's spacing system. All measurements are calculated as multiples of this unit:

<Config base={8}>     // Sets 8px as the base unit
  <Layout
    block={17}        // Will be rounded to 16px (2 * base)
    inline={22}       // Will be rounded to 24px (3 * base)
  >
    {/* Content automatically aligned to the 8px grid */}
  </Layout>
</Config>

Spacing Values

Spacing props (block, inline, gap) accept values in three formats:

// Single number (applies to both sides)
block={16}                  // 16px top and bottom

// Array [start, end]
block={[2, 3]}                // 2px top, 3px bottom

// Object with explicit values
block={{ start: 2, end: 3 }}  // Same as above

Grid Snapping

Components automatically adjust their spacing to maintain baseline grid alignment:

• Box: Adjusts bottom padding to ensure total height aligns with base unit
• Stack: Maintains baseline alignment in flex layouts
• Layout: Ensures grid cells align with baseline

Debugging Modes

Three modes are available for development and testing:

debugging = "visible"        // Shows all grid lines and measurements
debugging = "hidden"         // Elements exist but are invisible
debugging = "none"           // Removes debug elements entirely

Components

Component Hierarchy

1. Core Components

• Box Basic container for text alignment
• Stack Flex-based layouts (one-dimensional)
• Layout Grid-based layouts (two-dimensional)

2. Development Tools

• Baseline Horizontal grid overlay
• Guide Vertical grid overlay
• Spacer Precise spacing measurement

3. Configuration

• Config Theme and settings provider

Key Components

Config

<Config
  base={8}                         // Base unit for calculations
  baseline={{ debugging }}         // Baseline grid visibility
  guide={{ debugging }}            // Guide customization
>
  {children}
</Config>

Baseline

<Baseline
  height="100vh"          // Overlay height
  variant="line"          // "line" or "flat"
  debugging="visible"     // Show the grid overlay
/>

Guide

<Guide
  variant="pattern"                     // "line", "pattern", "fixed", or "auto"
  columns={['100px', '1fr', '100px']}   // Column definition
  gap={8}                               // Gap value
  width="1200px"                        // Container width
/>

Box

<Box
  block={[2, 5]}         // Vertical padding in base units
  span={2}               // Grid column span when used in Layout
  snapping="height"      // "none", "height", or "clamp"
>
  <p>Content aligned to baseline grid</p>
</Box>

Theme System

Baseline Kit comes with a flexible CSS structure and theming system:

1. core.css - Contains the core component styles required for functionality (imported via baseline-kit/styles)
2. theme.css - Contains color variables and theming with automatic dark mode support (imported via baseline-kit/theme)
3. baseline-kit.css - Combined file with both core and theme styles (imported via baseline-kit/full)

CSS Import Options

Baseline Kit gives you flexibility in how you include the styles:

// Option 1: Import core styles and theme separately (recommended)
import 'baseline-kit/styles';
import 'baseline-kit/theme';

// Option 2: Import everything in one file
import 'baseline-kit/full';

Theme Options

You now have four options for using the theme system:

1. Use the Built-in Theme (with automatic dark mode)

import 'baseline-kit/theme';  // Default theme with light/dark mode support

2. Use Specific Theme Variants

// Use only the light theme (no dark mode)
import 'baseline-kit/theme/default';

// Use only the dark theme
import 'baseline-kit/theme/dark';

// Example: Apply dark theme regardless of system preference
import 'baseline-kit/styles';
import 'baseline-kit/theme/dark';

3. Create a Custom Theme

You can use the tokens template as a starting point:

// First check the token template to see available variables
import 'baseline-kit/theme/tokens';  // Just for reference (contains no values)

Then create your own custom theme file:

/* yourCustomTheme.css */
:root {
  /* Component-specific colors */
  --bk-baseline-color-line-theme: hsla(210, 100%, 50%, 0.15);
  --bk-baseline-color-flat-theme: hsla(270, 100%, 60%, 0.2);
  /* Add other component colors as needed */
}

/* Optional dark mode support */
@media (prefers-color-scheme: dark) {
  :root {
    --bk-baseline-color-line-theme: hsla(210, 100%, 50%, 0.2);
  }
}

Then import your custom theme:

import 'baseline-kit/styles';            // Required core styles
import './path/to/yourCustomTheme.css';  // Your custom theme

4. Override via Config

For minor adjustments, use the Config component:

<Config
  baseline={{
    colors: {
      line: 'rgba(255,0,0,0.1)',   // Custom red baseline lines
      flat: 'rgba(255,0,0,0.05)',  // Custom red baseline backgrounds
    }
  }}
>
  {/* Your components here */}
</Config>

Theme Variables Reference

See the tokens file for a complete list of available variables.

Browser Support

• Modern browsers (Chrome, Firefox, Safari, Edge)
• Requires CSS Grid Layout support and CSS Custom Properties
• Falls back gracefully in unsupported browsers

React 19 Features

Baseline Kit leverages React 19's latest features:

• use Hook: Replaces useContext for better performance and cleaner code
• Streamlined Context API: Uses the simplified Context Provider syntax
• JSX Transform: Takes advantage of the mandatory JSX transform in React 19

These modern features allow for cleaner code and better performance, but require React 19.

Server-Side Rendering (SSR)

Baseline Kit is fully compatible with React's Server-Side Rendering in frameworks like Next.js, Remix, and other React Router-based applications.

SSR-Friendly Design

Components are designed to:

• Provide consistent rendering between server and client
• Avoid hydration mismatches by using deterministic initial values
• Progressively enhance with client-side measurements after hydration
• Work with frameworks that use streaming SSR

SSR Mode Prop

Components accept an ssrMode prop to explicitly optimize for server rendering:

<Baseline
  height="100vh"
  ssrMode={true}
  debugging="visible"
/>

With ssrMode enabled, components use simplified rendering during SSR and initial hydration, then enhance with full features after client-side hydration completes.

Development

# Clone the repository
git clone https://github.com/dnvt/baseline-kit.git

# Install dependencies
bun install

# Start development server
bun run dev

# Run tests
bun run test

Performance Features

• Virtualizes large grid overlays
• Client-side only rendering for dynamic components
• Optimized resize event handling
• Optimizes re-renders using React.memo and useMemo
• Supports tree-shaking for minimal bundle size

Contributing

Please see CONTRIBUTING.md for detailed guidelines.

License

MIT © François Denavaut