baseline-kit 3.0.1 → 5.0.0

package/README.md

@@ -4,34 +4,47 @@
 ![npm version](https://img.shields.io/npm/v/baseline-kit)
 ![License](https://img.shields.io/github/license/dnvt/baseline-kit)
 
-Baseline Kit is a lightweight development tool for visualizing and debugging grid systems and spacing in React 19 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.
+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, spacing primitives, 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.
 
 ![Demo visual](kit.png)
 
 ## Table of Contents
-  - [Base Unit](#base-unit)
-  - [Spacing Values](#spacing-values)
-  - [Grid Snapping](#grid-snapping)
-  - [Debugging Modes](#debugging-modes)
-  - [Component Hierarchy](#component-hierarchy)
-  - [Key Components](#key-components)
-    - [Config](#config)
-    - [Baseline](#baseline)
-    - [Guide](#guide)
-    - [Box](#box)
-  - [CSS Import Options](#css-import-options)
-  - [Theme Options](#theme-options)
-  - [Theme Variables Reference](#theme-variables-reference)
-  - [SSR-Friendly Design](#ssr-friendly-design)
-  - [SSR Mode Prop](#ssr-mode-prop)
+  - [Features](#features)
+  - [Requirements](#requirements)
+  - [Installation](#installation)
+  - [Quick Start](#quick-start)
+  - [Core Concepts](#core-concepts)
+    - [Base Unit](#base-unit)
+    - [Spacing Values](#spacing-values)
+    - [Grid Snapping](#grid-snapping)
+    - [Debugging Modes](#debugging-modes)
+  - [Components](#components)
+    - [Component Hierarchy](#component-hierarchy)
+    - [Key Components](#key-components)
+      - [Config](#config)
+      - [Baseline](#baseline)
+      - [Guide](#guide)
+      - [Box](#box)
+  - [Theme System](#theme-system)
+    - [CSS Import Options](#css-import-options)
+    - [Theme Options](#theme-options)
+    - [Theme Variables Reference](#theme-variables-reference)
+  - [Browser Support](#browser-support)
+  - [React 19 Features](#react-19-features)
+  - [Server-Side Rendering (SSR)](#server-side-rendering-ssr)
+    - [SSR-Friendly Design](#ssr-friendly-design)
+    - [SSR Mode Prop](#ssr-mode-prop)
+  - [Development](#development)
+  - [Performance Features](#performance-features)
+  - [Contributing](#contributing)
+  - [License](#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
+- 🧱 **Padder & Spacer:** Spacing primitives with optional baseline snapping
 - 🎨 **Theme System:** Customizable colors and debug visuals through a centralized configuration
 
 ## Requirements
@@ -52,35 +65,44 @@ yarn add baseline-kit
 pnpm add baseline-kit
 ```
 
-After installation, import both the styles and theme in your application:
+After installation, import the smallest entry point that matches your use case.
+For a development grid overlay, use the guide-only React and CSS subpaths:
 
 ```tsx
-// 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)
+import 'baseline-kit/styles/guide'
+import { Config, Guide } from 'baseline-kit/guide'
 ```
 
 For frameworks like Remix that use URL imports in a links function:
 
 ```tsx
 export const links = () => [
-  { rel: "stylesheet", href: "baseline-kit/styles" },
-  { rel: "stylesheet", href: "baseline-kit/theme" }
-];
+  { rel: 'stylesheet', href: 'baseline-kit/styles/guide' },
+]
 ```
 
-If you prefer a single CSS file that includes everything:
+For the full component set, import the root package and root component styles:
 
 ```tsx
-// Alternative: Import everything in one file
-import 'baseline-kit/full';
+import 'baseline-kit/styles'
+import 'baseline-kit/theme'
+import { Config, Guide, Baseline, Box } from 'baseline-kit'
+```
+
+If you prefer a single CSS file for every component plus the theme:
+
+```tsx
+import 'baseline-kit/styles/full'
 
 // For Remix:
 export const links = () => [
-  { rel: "stylesheet", href: "baseline-kit/full" }
-];
+  { rel: 'stylesheet', href: 'baseline-kit/styles/full' },
+]
 ```
 
+The browser reset is not included by default. Import `baseline-kit/reset` or
+`baseline-kit/styles/reset` only when you want Baseline Kit to provide one.
+
 Baseline Kit is written in TypeScript and includes built-in type definitions—no additional packages required.
 
 ## Quick Start
@@ -139,12 +161,12 @@ unit:
 
 ```tsx
 <Config base={8}>     // Sets 8px as the base unit
-  <Layout
+  <Padder
     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>
+  </Padder>
 </Config>
 ```
 
@@ -168,8 +190,7 @@ block={{ start: 2, end: 3 }}  // Same as above
 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
+- **Padder**: Snaps padded content to baseline-aligned multiples of the base unit
 
 ### Debugging Modes
 
@@ -185,21 +206,20 @@ debugging = "none"           // Removes debug elements entirely
 
 ### Component Hierarchy
 
-#### 1. Core Components
+#### 1. Spacing primitives
 
-- **`Box`** Basic container for text alignment
-- **`Stack`** Flex-based layouts (one-dimensional)
-- **`Layout`** Grid-based layouts (two-dimensional)
+- **`Box`** Basic container that snaps its height to the baseline grid
+- **`Padder`** Padding wrapper that snaps padded content to baseline multiples
+- **`Spacer`** Fixed-size spacer with optional measurement indicator overlay
 
-#### 2. Development Tools
+#### 2. Debug overlays
 
-- **`Baseline`** Horizontal grid overlay
-- **`Guide`** Vertical grid overlay
-- **`Spacer`** Precise spacing measurement
+- **`Baseline`** Horizontal baseline-grid overlay
+- **`Guide`** Column-grid overlay (line / pattern / fixed / auto variants)
 
 #### 3. Configuration
 
-- **`Config`** Theme and settings provider
+- **`Config`** Theme and settings provider (base unit, colors, debug modes)
 
 ### Key Components
 
@@ -241,7 +261,7 @@ debugging = "none"           // Removes debug elements entirely
 ```tsx
 <Box
   block={[2, 5]}         // Vertical padding in base units
-  span={2}               // Grid column span when used in Layout
+  span={2}               // Grid column span when placed in a CSS grid parent
   snapping="height"      // "none", "height", or "clamp"
 >
   <p>Content aligned to baseline grid</p>
@@ -252,21 +272,29 @@ debugging = "none"           // Removes debug elements entirely
 
 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`)
+1. `guide.css` - Guide-only overlay styles (imported via `baseline-kit/styles/guide`)
+2. `styles.css` - Root component styles and base variables (imported via `baseline-kit/styles`)
+3. `theme.css` - Color variables and theming with automatic dark mode support (imported via `baseline-kit/theme`)
+4. `reset.css` - Optional browser reset (imported via `baseline-kit/reset` or `baseline-kit/styles/reset`)
+5. `baseline-kit.css` - Combined root component styles and theme (imported via `baseline-kit/styles/full`)
 
 ### CSS Import Options
 
 Baseline Kit gives you flexibility in how you include the styles:
 
 ```tsx
-// Option 1: Import core styles and theme separately (recommended)
-import 'baseline-kit/styles';
-import 'baseline-kit/theme';
+// Guide-only overlay styles
+import 'baseline-kit/styles/guide'
+
+// Root component styles and theme separately
+import 'baseline-kit/styles'
+import 'baseline-kit/theme'
+
+// Root component styles and theme in one file
+import 'baseline-kit/styles/full'
 
-// Option 2: Import everything in one file
-import 'baseline-kit/full';
+// Optional reset
+import 'baseline-kit/reset'
 ```
 
 ### Theme Options
@@ -276,21 +304,21 @@ You now have four options for using the theme system:
 #### 1. Use the Built-in Theme (with automatic dark mode)
 
 ```tsx
-import 'baseline-kit/theme';  // Default theme with light/dark mode support
+import 'baseline-kit/theme' // Default theme with light/dark mode support
 ```
 
 #### 2. Use Specific Theme Variants
 
 ```tsx
 // Use only the light theme (no dark mode)
-import 'baseline-kit/theme/default';
+import 'baseline-kit/theme/default'
 
 // Use only the dark theme
-import 'baseline-kit/theme/dark';
+import 'baseline-kit/theme/dark'
 
 // Example: Apply dark theme regardless of system preference
-import 'baseline-kit/styles';
-import 'baseline-kit/theme/dark';
+import 'baseline-kit/styles'
+import 'baseline-kit/theme/dark'
 ```
 
 #### 3. Create a Custom Theme
@@ -299,7 +327,7 @@ You can use the tokens template as a starting point:
 
 ```tsx
 // First check the token template to see available variables
-import 'baseline-kit/theme/tokens';  // Just for reference (contains no values)
+import 'baseline-kit/theme/tokens' // Just for reference (contains no values)
 ```
 
 Then create your own custom theme file:
@@ -324,8 +352,8 @@ Then create your own custom theme file:
 Then import your custom theme:
 
 ```tsx
-import 'baseline-kit/styles';            // Required core styles
-import './path/to/yourCustomTheme.css';  // Your custom theme
+import 'baseline-kit/styles' // Required component styles
+import './path/to/yourCustomTheme.css' // Your custom theme
 ```
 
 #### 4. Override via Config
@@ -352,9 +380,8 @@ For minor adjustments, use the Config component:
 | Baseline  | `--bk-baseline-color-[line/flat]-theme` | Colors for lines and backgrounds |
 | Guide     | `--bk-guide-color-[line/pattern/auto/fixed]-theme` | Colors for different guide variants |
 | Box       | `--bk-box-color-[line/flat/text]-theme` | Colors for borders, backgrounds and text |
-| Stack     | `--bk-stack-color-[line/flat/text]-theme` | Colors for borders, backgrounds and text |
-| Layout    | `--bk-layout-color-[line/flat/text]-theme` | Colors for borders, backgrounds and text |
 | Spacer    | `--bk-spacer-color-[line/flat/text]-theme` | Colors for borders, backgrounds and text |
+| Padder    | `--bk-padder-color-theme` | Padder edge color |
 
 See the [tokens file](https://github.com/dnvt/baseline-kit/blob/main/dist/theme/tokens.css) for a complete list of available variables.
 
@@ -398,12 +425,16 @@ Components accept an `ssrMode` prop to explicitly optimize for server rendering:
 ```
 
 With `ssrMode` enabled, components use simplified rendering during SSR and initial hydration, then enhance with full features after client-side hydration completes.
+For debug overlays such as `Guide` and `Baseline`, `ssrMode` keeps the simplified fallback markup to avoid client measurement and row/column rendering in SSR-sensitive paths.
 
 ## Development
 
 ```shell
 # Clone the repository
-git clone https://github.com/dnvt/baseline-kit.git
+git clone --recurse-submodules https://github.com/dnvt/baseline-kit.git
+
+# If you already cloned without submodules
+git submodule update --init --recursive
 
 # Install dependencies
 bun install
@@ -415,6 +446,11 @@ bun run dev
 bun run test
 ```
 
+The `.maestro/source` directory is a workflow submodule. Generated local
+workflow surfaces such as `.claude/`, `maestro/`, `progress/`, and `plans/` are
+ignored. Do not run the Maestro layout migration until the submodule source is
+mounted at `.maestro/source` and the migration plan has been reviewed.
+
 ## Performance Features
 
 - Virtualizes large grid overlays

package/dist/README.md

@@ -4,34 +4,47 @@
 ![npm version](https://img.shields.io/npm/v/baseline-kit)
 ![License](https://img.shields.io/github/license/dnvt/baseline-kit)
 
-Baseline Kit is a lightweight development tool for visualizing and debugging grid systems and spacing in React 19 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.
+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, spacing primitives, 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.
 
 ![Demo visual](kit.png)
 
 ## Table of Contents
-  - [Base Unit](#base-unit)
-  - [Spacing Values](#spacing-values)
-  - [Grid Snapping](#grid-snapping)
-  - [Debugging Modes](#debugging-modes)
-  - [Component Hierarchy](#component-hierarchy)
-  - [Key Components](#key-components)
-    - [Config](#config)
-    - [Baseline](#baseline)
-    - [Guide](#guide)
-    - [Box](#box)
-  - [CSS Import Options](#css-import-options)
-  - [Theme Options](#theme-options)
-  - [Theme Variables Reference](#theme-variables-reference)
-  - [SSR-Friendly Design](#ssr-friendly-design)
-  - [SSR Mode Prop](#ssr-mode-prop)
+  - [Features](#features)
+  - [Requirements](#requirements)
+  - [Installation](#installation)
+  - [Quick Start](#quick-start)
+  - [Core Concepts](#core-concepts)
+    - [Base Unit](#base-unit)
+    - [Spacing Values](#spacing-values)
+    - [Grid Snapping](#grid-snapping)
+    - [Debugging Modes](#debugging-modes)
+  - [Components](#components)
+    - [Component Hierarchy](#component-hierarchy)
+    - [Key Components](#key-components)
+      - [Config](#config)
+      - [Baseline](#baseline)
+      - [Guide](#guide)
+      - [Box](#box)
+  - [Theme System](#theme-system)
+    - [CSS Import Options](#css-import-options)
+    - [Theme Options](#theme-options)
+    - [Theme Variables Reference](#theme-variables-reference)
+  - [Browser Support](#browser-support)
+  - [React 19 Features](#react-19-features)
+  - [Server-Side Rendering (SSR)](#server-side-rendering-ssr)
+    - [SSR-Friendly Design](#ssr-friendly-design)
+    - [SSR Mode Prop](#ssr-mode-prop)
+  - [Development](#development)
+  - [Performance Features](#performance-features)
+  - [Contributing](#contributing)
+  - [License](#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
+- 🧱 **Padder & Spacer:** Spacing primitives with optional baseline snapping
 - 🎨 **Theme System:** Customizable colors and debug visuals through a centralized configuration
 
 ## Requirements
@@ -52,35 +65,44 @@ yarn add baseline-kit
 pnpm add baseline-kit
 ```
 
-After installation, import both the styles and theme in your application:
+After installation, import the smallest entry point that matches your use case.
+For a development grid overlay, use the guide-only React and CSS subpaths:
 
 ```tsx
-// 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)
+import 'baseline-kit/styles/guide'
+import { Config, Guide } from 'baseline-kit/guide'
 ```
 
 For frameworks like Remix that use URL imports in a links function:
 
 ```tsx
 export const links = () => [
-  { rel: "stylesheet", href: "baseline-kit/styles" },
-  { rel: "stylesheet", href: "baseline-kit/theme" }
-];
+  { rel: 'stylesheet', href: 'baseline-kit/styles/guide' },
+]
 ```
 
-If you prefer a single CSS file that includes everything:
+For the full component set, import the root package and root component styles:
 
 ```tsx
-// Alternative: Import everything in one file
-import 'baseline-kit/full';
+import 'baseline-kit/styles'
+import 'baseline-kit/theme'
+import { Config, Guide, Baseline, Box } from 'baseline-kit'
+```
+
+If you prefer a single CSS file for every component plus the theme:
+
+```tsx
+import 'baseline-kit/styles/full'
 
 // For Remix:
 export const links = () => [
-  { rel: "stylesheet", href: "baseline-kit/full" }
-];
+  { rel: 'stylesheet', href: 'baseline-kit/styles/full' },
+]
 ```
 
+The browser reset is not included by default. Import `baseline-kit/reset` or
+`baseline-kit/styles/reset` only when you want Baseline Kit to provide one.
+
 Baseline Kit is written in TypeScript and includes built-in type definitions—no additional packages required.
 
 ## Quick Start
@@ -139,12 +161,12 @@ unit:
 
 ```tsx
 <Config base={8}>     // Sets 8px as the base unit
-  <Layout
+  <Padder
     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>
+  </Padder>
 </Config>
 ```
 
@@ -168,8 +190,7 @@ block={{ start: 2, end: 3 }}  // Same as above
 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
+- **Padder**: Snaps padded content to baseline-aligned multiples of the base unit
 
 ### Debugging Modes
 
@@ -185,21 +206,20 @@ debugging = "none"           // Removes debug elements entirely
 
 ### Component Hierarchy
 
-#### 1. Core Components
+#### 1. Spacing primitives
 
-- **`Box`** Basic container for text alignment
-- **`Stack`** Flex-based layouts (one-dimensional)
-- **`Layout`** Grid-based layouts (two-dimensional)
+- **`Box`** Basic container that snaps its height to the baseline grid
+- **`Padder`** Padding wrapper that snaps padded content to baseline multiples
+- **`Spacer`** Fixed-size spacer with optional measurement indicator overlay
 
-#### 2. Development Tools
+#### 2. Debug overlays
 
-- **`Baseline`** Horizontal grid overlay
-- **`Guide`** Vertical grid overlay
-- **`Spacer`** Precise spacing measurement
+- **`Baseline`** Horizontal baseline-grid overlay
+- **`Guide`** Column-grid overlay (line / pattern / fixed / auto variants)
 
 #### 3. Configuration
 
-- **`Config`** Theme and settings provider
+- **`Config`** Theme and settings provider (base unit, colors, debug modes)
 
 ### Key Components
 
@@ -241,7 +261,7 @@ debugging = "none"           // Removes debug elements entirely
 ```tsx
 <Box
   block={[2, 5]}         // Vertical padding in base units
-  span={2}               // Grid column span when used in Layout
+  span={2}               // Grid column span when placed in a CSS grid parent
   snapping="height"      // "none", "height", or "clamp"
 >
   <p>Content aligned to baseline grid</p>
@@ -252,21 +272,29 @@ debugging = "none"           // Removes debug elements entirely
 
 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`)
+1. `guide.css` - Guide-only overlay styles (imported via `baseline-kit/styles/guide`)
+2. `styles.css` - Root component styles and base variables (imported via `baseline-kit/styles`)
+3. `theme.css` - Color variables and theming with automatic dark mode support (imported via `baseline-kit/theme`)
+4. `reset.css` - Optional browser reset (imported via `baseline-kit/reset` or `baseline-kit/styles/reset`)
+5. `baseline-kit.css` - Combined root component styles and theme (imported via `baseline-kit/styles/full`)
 
 ### CSS Import Options
 
 Baseline Kit gives you flexibility in how you include the styles:
 
 ```tsx
-// Option 1: Import core styles and theme separately (recommended)
-import 'baseline-kit/styles';
-import 'baseline-kit/theme';
+// Guide-only overlay styles
+import 'baseline-kit/styles/guide'
+
+// Root component styles and theme separately
+import 'baseline-kit/styles'
+import 'baseline-kit/theme'
+
+// Root component styles and theme in one file
+import 'baseline-kit/styles/full'
 
-// Option 2: Import everything in one file
-import 'baseline-kit/full';
+// Optional reset
+import 'baseline-kit/reset'
 ```
 
 ### Theme Options
@@ -276,21 +304,21 @@ You now have four options for using the theme system:
 #### 1. Use the Built-in Theme (with automatic dark mode)
 
 ```tsx
-import 'baseline-kit/theme';  // Default theme with light/dark mode support
+import 'baseline-kit/theme' // Default theme with light/dark mode support
 ```
 
 #### 2. Use Specific Theme Variants
 
 ```tsx
 // Use only the light theme (no dark mode)
-import 'baseline-kit/theme/default';
+import 'baseline-kit/theme/default'
 
 // Use only the dark theme
-import 'baseline-kit/theme/dark';
+import 'baseline-kit/theme/dark'
 
 // Example: Apply dark theme regardless of system preference
-import 'baseline-kit/styles';
-import 'baseline-kit/theme/dark';
+import 'baseline-kit/styles'
+import 'baseline-kit/theme/dark'
 ```
 
 #### 3. Create a Custom Theme
@@ -299,7 +327,7 @@ You can use the tokens template as a starting point:
 
 ```tsx
 // First check the token template to see available variables
-import 'baseline-kit/theme/tokens';  // Just for reference (contains no values)
+import 'baseline-kit/theme/tokens' // Just for reference (contains no values)
 ```
 
 Then create your own custom theme file:
@@ -324,8 +352,8 @@ Then create your own custom theme file:
 Then import your custom theme:
 
 ```tsx
-import 'baseline-kit/styles';            // Required core styles
-import './path/to/yourCustomTheme.css';  // Your custom theme
+import 'baseline-kit/styles' // Required component styles
+import './path/to/yourCustomTheme.css' // Your custom theme
 ```
 
 #### 4. Override via Config
@@ -352,9 +380,8 @@ For minor adjustments, use the Config component:
 | Baseline  | `--bk-baseline-color-[line/flat]-theme` | Colors for lines and backgrounds |
 | Guide     | `--bk-guide-color-[line/pattern/auto/fixed]-theme` | Colors for different guide variants |
 | Box       | `--bk-box-color-[line/flat/text]-theme` | Colors for borders, backgrounds and text |
-| Stack     | `--bk-stack-color-[line/flat/text]-theme` | Colors for borders, backgrounds and text |
-| Layout    | `--bk-layout-color-[line/flat/text]-theme` | Colors for borders, backgrounds and text |
 | Spacer    | `--bk-spacer-color-[line/flat/text]-theme` | Colors for borders, backgrounds and text |
+| Padder    | `--bk-padder-color-theme` | Padder edge color |
 
 See the [tokens file](https://github.com/dnvt/baseline-kit/blob/main/dist/theme/tokens.css) for a complete list of available variables.
 
@@ -398,12 +425,16 @@ Components accept an `ssrMode` prop to explicitly optimize for server rendering:
 ```
 
 With `ssrMode` enabled, components use simplified rendering during SSR and initial hydration, then enhance with full features after client-side hydration completes.
+For debug overlays such as `Guide` and `Baseline`, `ssrMode` keeps the simplified fallback markup to avoid client measurement and row/column rendering in SSR-sensitive paths.
 
 ## Development
 
 ```shell
 # Clone the repository
-git clone https://github.com/dnvt/baseline-kit.git
+git clone --recurse-submodules https://github.com/dnvt/baseline-kit.git
+
+# If you already cloned without submodules
+git submodule update --init --recursive
 
 # Install dependencies
 bun install
@@ -415,6 +446,11 @@ bun run dev
 bun run test
 ```
 
+The `.maestro/source` directory is a workflow submodule. Generated local
+workflow surfaces such as `.claude/`, `maestro/`, `progress/`, and `plans/` are
+ignored. Do not run the Maestro layout migration until the submodule source is
+mounted at `.maestro/source` and the migration plan has been reviewed.
+
 ## Performance Features
 
 - Virtualizes large grid overlays