{"id":27910645,"url":"https://github.com/dnvt/baseline-kit","last_synced_at":"2026-02-26T18:06:06.443Z","repository":{"id":264940537,"uuid":"894726090","full_name":"dnvt/baseline-kit","owner":"dnvt","description":"A lightweight, flexible grid system for React applications with precise control over spacing and layout.","archived":false,"fork":false,"pushed_at":"2025-03-09T20:27:32.000Z","size":29357,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-20T19:38:57.064Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dnvt.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-11-26T21:54:48.000Z","updated_at":"2025-03-09T20:26:59.000Z","dependencies_parsed_at":"2024-12-24T16:18:12.794Z","dependency_job_id":"b942f29f-777a-4629-b0b1-9caac912cd8d","html_url":"https://github.com/dnvt/baseline-kit","commit_stats":null,"previous_names":["dnvt/padded-grid"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/dnvt/baseline-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnvt%2Fbaseline-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnvt%2Fbaseline-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnvt%2Fbaseline-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnvt%2Fbaseline-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dnvt","download_url":"https://codeload.github.com/dnvt/baseline-kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnvt%2Fbaseline-kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29867158,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T16:38:37.846Z","status":"ssl_error","status_checked_at":"2026-02-26T16:37:58.932Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-06T09:50:15.093Z","updated_at":"2026-02-26T18:06:06.424Z","avatar_url":"https://github.com/dnvt.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Baseline Kit\n\n![Build Status](https://img.shields.io/github/actions/workflow/status/dnvt/baseline-kit/test.yml)\n![npm version](https://img.shields.io/npm/v/baseline-kit)\n![License](https://img.shields.io/github/license/dnvt/baseline-kit)\n\nBaseline 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](http://medium.com/design-bootcamp/the-padded-grid-a-designers-hack-to-achieve-baseline-fit-fc40d022bc84) on achieving perfect baseline alignment in digital layouts.\n\n![Demo visual](kit.png)\n\n## Table of Contents\n  - [Features](#features)\n  - [Requirements](#requirements)\n  - [Installation](#installation)\n  - [Quick Start](#quick-start)\n  - [Core Concepts](#core-concepts)\n    - [Base Unit](#base-unit)\n    - [Spacing Values](#spacing-values)\n    - [Grid Snapping](#grid-snapping)\n    - [Debugging Modes](#debugging-modes)\n  - [Components](#components)\n    - [Component Hierarchy](#component-hierarchy)\n    - [Key Components](#key-components)\n      - [Config](#config)\n      - [Baseline](#baseline)\n      - [Guide](#guide)\n      - [Box](#box)\n  - [Theme System](#theme-system)\n    - [CSS Import Options](#css-import-options)\n    - [Theme Options](#theme-options)\n    - [Theme Variables Reference](#theme-variables-reference)\n  - [Browser Support](#browser-support)\n  - [React 19 Features](#react-19-features)\n  - [Server-Side Rendering (SSR)](#server-side-rendering-ssr)\n    - [SSR-Friendly Design](#ssr-friendly-design)\n    - [SSR Mode Prop](#ssr-mode-prop)\n  - [Development](#development)\n  - [Performance Features](#performance-features)\n  - [Contributing](#contributing)\n  - [License](#license)\n\n## Features\n\n- 📏 **Baseline Grid:** Core system for maintaining vertical rhythm and consistent spacing across your layouts\n- 🎯 **Column Grid Guide:** Customizable overlay system for visualizing column-based layouts and alignment\n- 📦 **Box Component:** Basic container with configurable spacing that snaps to the baseline grid\n- 🧩 **Layout Component:** CSS Grid-based container with automatic column calculations and baseline alignment\n- 📐 **Stack Component:** Flex-based container that maintains consistent spacing and baseline alignment\n- 🎨 **Theme System:** Customizable colors and debug visuals through a centralized configuration\n\n## Requirements\n\n- **React 19**: Baseline Kit is built for React 19 and uses the latest React features like the `use` hook\n- **Modern Browsers**: Supporting the latest CSS features\n\n## Installation\n\n```shell\n# Using npm\nnpm install baseline-kit\n\n# Using yarn\nyarn add baseline-kit\n\n# Using pnpm\npnpm add baseline-kit\n```\n\nAfter installation, import both the styles and theme in your application:\n\n```tsx\n// Import in your main entry file (e.g., index.js, App.js)\nimport 'baseline-kit/styles';  // Required core styles\nimport 'baseline-kit/theme';   // Recommended theme (or use your own)\n```\n\nFor frameworks like Remix that use URL imports in a links function:\n\n```tsx\nexport const links = () =\u003e [\n  { rel: \"stylesheet\", href: \"baseline-kit/styles\" },\n  { rel: \"stylesheet\", href: \"baseline-kit/theme\" }\n];\n```\n\nIf you prefer a single CSS file that includes everything:\n\n```tsx\n// Alternative: Import everything in one file\nimport 'baseline-kit/full';\n\n// For Remix:\nexport const links = () =\u003e [\n  { rel: \"stylesheet\", href: \"baseline-kit/full\" }\n];\n```\n\nBaseline Kit is written in TypeScript and includes built-in type definitions—no additional packages required.\n\n## Quick Start\n\n```tsx\nimport React from 'react'\nimport { Config, Guide, Baseline, Box } from 'baseline-kit'\n\nfunction App() {\n  const isDev = process.env.NODE_ENV === 'development'\n  const debugging = isDev ? 'visible' : 'hidden'\n\n  return (\n    \u003cConfig\n      base={8}\n      baseline={{ debugging }}\n      box={{ debugging }}\n      guide={{ debugging }}\n      spacer={{ debugging }}\n    \u003e\n      {/* Baseline Grid for typography alignment */}\n      \u003cBaseline\n        height=\"100vh\"\n        debugging=\"visible\"\n      /\u003e\n\n      {/* Column Grid Guide */}\n      \u003cGuide\n        variant=\"pattern\"\n        columns={['100px', '200px', '100px']}\n        gap={16}\n        align=\"center\"\n        width=\"1200px\"\n      /\u003e\n\n      {/* Box with baseline alignment */}\n      \u003cBox\n        block={[2, 5]}\n        debugging=\"visible\"\n      \u003e\n        \u003ch1\u003eContent Aligned to the Grid\u003c/h1\u003e\n      \u003c/Box\u003e\n\n      \u003cmain\u003eYour main content goes here...\u003c/main\u003e\n    \u003c/Config\u003e\n  )\n}\n```\n\n## Core Concepts\n\n### Base Unit\n\nThe base unit is the foundation of Baseline Kit's spacing system. All measurements are calculated as multiples of this\nunit:\n\n```tsx\n\u003cConfig base={8}\u003e     // Sets 8px as the base unit\n  \u003cLayout\n    block={17}        // Will be rounded to 16px (2 * base)\n    inline={22}       // Will be rounded to 24px (3 * base)\n  \u003e\n    {/* Content automatically aligned to the 8px grid */}\n  \u003c/Layout\u003e\n\u003c/Config\u003e\n```\n\n### Spacing Values\n\nSpacing props (`block`, `inline`, `gap`) accept values in three formats:\n\n```\n// Single number (applies to both sides)\nblock={16}                  // 16px top and bottom\n\n// Array [start, end]\nblock={[2, 3]}                // 2px top, 3px bottom\n\n// Object with explicit values\nblock={{ start: 2, end: 3 }}  // Same as above\n```\n\n### Grid Snapping\n\nComponents automatically adjust their spacing to maintain baseline grid alignment:\n\n- **Box**: Adjusts bottom padding to ensure total height aligns with base unit\n- **Stack**: Maintains baseline alignment in flex layouts\n- **Layout**: Ensures grid cells align with baseline\n\n### Debugging Modes\n\nThree modes are available for development and testing:\n\n```tsx\ndebugging = \"visible\"        // Shows all grid lines and measurements\ndebugging = \"hidden\"         // Elements exist but are invisible\ndebugging = \"none\"           // Removes debug elements entirely\n```\n\n## Components\n\n### Component Hierarchy\n\n#### 1. Core Components\n\n- **`Box`** Basic container for text alignment\n- **`Stack`** Flex-based layouts (one-dimensional)\n- **`Layout`** Grid-based layouts (two-dimensional)\n\n#### 2. Development Tools\n\n- **`Baseline`** Horizontal grid overlay\n- **`Guide`** Vertical grid overlay\n- **`Spacer`** Precise spacing measurement\n\n#### 3. Configuration\n\n- **`Config`** Theme and settings provider\n\n### Key Components\n\n#### Config\n\n```tsx\n\u003cConfig\n  base={8}                         // Base unit for calculations\n  baseline={{ debugging }}         // Baseline grid visibility\n  guide={{ debugging }}            // Guide customization\n\u003e\n  {children}\n\u003c/Config\u003e\n```\n\n#### Baseline\n\n```tsx\n\u003cBaseline\n  height=\"100vh\"          // Overlay height\n  variant=\"line\"          // \"line\" or \"flat\"\n  debugging=\"visible\"     // Show the grid overlay\n/\u003e\n```\n\n#### Guide\n\n```tsx\n\u003cGuide\n  variant=\"pattern\"                     // \"line\", \"pattern\", \"fixed\", or \"auto\"\n  columns={['100px', '1fr', '100px']}   // Column definition\n  gap={8}                               // Gap value\n  width=\"1200px\"                        // Container width\n/\u003e\n```\n\n#### Box\n\n```tsx\n\u003cBox\n  block={[2, 5]}         // Vertical padding in base units\n  span={2}               // Grid column span when used in Layout\n  snapping=\"height\"      // \"none\", \"height\", or \"clamp\"\n\u003e\n  \u003cp\u003eContent aligned to baseline grid\u003c/p\u003e\n\u003c/Box\u003e\n```\n\n## Theme System\n\nBaseline Kit comes with a flexible CSS structure and theming system:\n\n1. `core.css` - Contains the core component styles required for functionality (imported via `baseline-kit/styles`)\n2. `theme.css` - Contains color variables and theming with automatic dark mode support (imported via `baseline-kit/theme`)\n3. `baseline-kit.css` - Combined file with both core and theme styles (imported via `baseline-kit/full`)\n\n### CSS Import Options\n\nBaseline Kit gives you flexibility in how you include the styles:\n\n```tsx\n// Option 1: Import core styles and theme separately (recommended)\nimport 'baseline-kit/styles';\nimport 'baseline-kit/theme';\n\n// Option 2: Import everything in one file\nimport 'baseline-kit/full';\n```\n\n### Theme Options\n\nYou now have four options for using the theme system:\n\n#### 1. Use the Built-in Theme (with automatic dark mode)\n\n```tsx\nimport 'baseline-kit/theme';  // Default theme with light/dark mode support\n```\n\n#### 2. Use Specific Theme Variants\n\n```tsx\n// Use only the light theme (no dark mode)\nimport 'baseline-kit/theme/default';\n\n// Use only the dark theme\nimport 'baseline-kit/theme/dark';\n\n// Example: Apply dark theme regardless of system preference\nimport 'baseline-kit/styles';\nimport 'baseline-kit/theme/dark';\n```\n\n#### 3. Create a Custom Theme\n\nYou can use the tokens template as a starting point:\n\n```tsx\n// First check the token template to see available variables\nimport 'baseline-kit/theme/tokens';  // Just for reference (contains no values)\n```\n\nThen create your own custom theme file:\n\n```css\n/* yourCustomTheme.css */\n:root {\n  /* Component-specific colors */\n  --bk-baseline-color-line-theme: hsla(210, 100%, 50%, 0.15);\n  --bk-baseline-color-flat-theme: hsla(270, 100%, 60%, 0.2);\n  /* Add other component colors as needed */\n}\n\n/* Optional dark mode support */\n@media (prefers-color-scheme: dark) {\n  :root {\n    --bk-baseline-color-line-theme: hsla(210, 100%, 50%, 0.2);\n  }\n}\n```\n\nThen import your custom theme:\n\n```tsx\nimport 'baseline-kit/styles';            // Required core styles\nimport './path/to/yourCustomTheme.css';  // Your custom theme\n```\n\n#### 4. Override via Config\n\nFor minor adjustments, use the Config component:\n\n```tsx\n\u003cConfig\n  baseline={{\n    colors: {\n      line: 'rgba(255,0,0,0.1)',   // Custom red baseline lines\n      flat: 'rgba(255,0,0,0.05)',  // Custom red baseline backgrounds\n    }\n  }}\n\u003e\n  {/* Your components here */}\n\u003c/Config\u003e\n```\n\n### Theme Variables Reference\n\n| Component | Variable Pattern | Purpose |\n|-----------|-----------------|---------|\n| Baseline  | `--bk-baseline-color-[line/flat]-theme` | Colors for lines and backgrounds |\n| Guide     | `--bk-guide-color-[line/pattern/auto/fixed]-theme` | Colors for different guide variants |\n| Box       | `--bk-box-color-[line/flat/text]-theme` | Colors for borders, backgrounds and text |\n| Stack     | `--bk-stack-color-[line/flat/text]-theme` | Colors for borders, backgrounds and text |\n| Layout    | `--bk-layout-color-[line/flat/text]-theme` | Colors for borders, backgrounds and text |\n| Spacer    | `--bk-spacer-color-[line/flat/text]-theme` | Colors for borders, backgrounds and text |\n\nSee the [tokens file](https://github.com/dnvt/baseline-kit/blob/main/dist/theme/tokens.css) for a complete list of available variables.\n\n## Browser Support\n\n- Modern browsers (Chrome, Firefox, Safari, Edge)\n- Requires CSS Grid Layout support and CSS Custom Properties\n- Falls back gracefully in unsupported browsers\n\n## React 19 Features\n\nBaseline Kit leverages React 19's latest features:\n- **`use` Hook**: Replaces `useContext` for better performance and cleaner code\n- **Streamlined Context API**: Uses the simplified Context Provider syntax\n- **JSX Transform**: Takes advantage of the mandatory JSX transform in React 19\n\nThese modern features allow for cleaner code and better performance, but require React 19.\n\n## Server-Side Rendering (SSR)\n\nBaseline Kit is fully compatible with React's Server-Side Rendering in frameworks like Next.js, Remix, and other React Router-based applications.\n\n### SSR-Friendly Design\n\nComponents are designed to:\n- Provide consistent rendering between server and client\n- Avoid hydration mismatches by using deterministic initial values\n- Progressively enhance with client-side measurements after hydration\n- Work with frameworks that use streaming SSR\n\n### SSR Mode Prop\n\nComponents accept an `ssrMode` prop to explicitly optimize for server rendering:\n\n```tsx\n\u003cBaseline\n  height=\"100vh\"\n  ssrMode={true}\n  debugging=\"visible\"\n/\u003e\n```\n\nWith `ssrMode` enabled, components use simplified rendering during SSR and initial hydration, then enhance with full features after client-side hydration completes.\n\n## Development\n\n```shell\n# Clone the repository\ngit clone https://github.com/dnvt/baseline-kit.git\n\n# Install dependencies\nbun install\n\n# Start development server\nbun run dev\n\n# Run tests\nbun run test\n```\n\n## Performance Features\n\n- Virtualizes large grid overlays\n- Client-side only rendering for dynamic components\n- Optimized resize event handling\n- Optimizes re-renders using React.memo and useMemo\n- Supports tree-shaking for minimal bundle size\n\n## Contributing\n\nPlease see [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.\n\n## License\n\nMIT © [François Denavaut](https://github.com/dnvt)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnvt%2Fbaseline-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdnvt%2Fbaseline-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnvt%2Fbaseline-kit/lists"}