stylelint-plugin-rhythmguard 1.2.1 → 1.4.0

package/CHANGELOG.md

@@ -6,6 +6,53 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-02-21
+
+### Added
+
+- New shared configs:
+  - `stylelint-plugin-rhythmguard/configs/expanded`
+  - `stylelint-plugin-rhythmguard/configs/logical`
+  - `stylelint-plugin-rhythmguard/configs/migration`
+- New ESLint companion export: `stylelint-plugin-rhythmguard/eslint` with rule:
+  - `rhythmguard-tailwind/tailwind-class-use-scale`
+- Token migration source automation for `rhythmguard/prefer-token`:
+  - `tokenMapFromCssCustomProperties`
+  - `tokenMapFile`
+  - `tokenMapFromTailwindSpacing` + `tailwindConfigPath`
+- ESM wrapper entry points for package root, configs, presets, rules, and ESLint companion.
+
+### Changed
+
+- Broadened scale enforcement model with built-in property groups:
+  - `spacing`, `radius`, `typography`, `size`
+- New per-property override options:
+  - `propertyGroups`
+  - `propertyScales`
+- New math-function targeting options:
+  - `mathFunctionArguments`
+  - `ignoreMathFunctionArguments`
+- New `unitStrategy` option (`convert` or `exact`) for non-convertible unit workflows.
+- Compatibility updated to support Stylelint `^16 || ^17`.
+- Tailwind token-map extraction now supports `.js`, `.cjs`, and `.mjs` config files and merges `theme.spacing` with `theme.extend.spacing`.
+
+## [1.3.0] - 2026-02-17
+
+### Added
+
+- Strict `secondaryOptions` validation for all three rules:
+  - `rhythmguard/use-scale`
+  - `rhythmguard/prefer-token`
+  - `rhythmguard/no-offscale-transform`
+- Invalid option names (for example `sevverity`) now fail with Stylelint invalid option warnings instead of silently being ignored.
+- Type/shape validation for option payloads (for example `properties` must be an array, `tokenMap` must be an object).
+- Regression tests for invalid secondary option names and option value shapes.
+
+### Changed
+
+- Added `known-css-properties` as a direct runtime dependency to guarantee `properties` option validation in consumer installs.
+- `properties` option validation now checks supported spacing property names against known CSS property metadata (plus `translate-x`, `translate-y`, `translate-z`).
+
 ## [1.2.1] - 2026-02-17
 
 ### Fixed
@@ -15,6 +62,7 @@ The format follows Keep a Changelog principles and semantic versioning.
 - `rhythmguard/prefer-token` now supports `enforceInsideMathFunctions` for optional math-function enforcement.
 - Hardened `var()` token argument detection to parse the first argument structurally (rather than comma string splitting).
 - npm README link integrity: docs links now resolve to absolute GitHub URLs from the npm package page.
+- Release workflow now detects missing `NPM_TOKEN` and skips publish cleanly with an explicit notice instead of failing.
 
 ### Added
 

package/README.md

@@ -12,13 +12,22 @@ High-precision spacing governance for CSS and design systems.
 [![License: MIT](https://img.shields.io/badge/license-MIT-white.svg)](./LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D18.18-black.svg)](https://nodejs.org/)
 
-`stylelint-plugin-rhythmguard` enforces spacing discipline across margin, padding, gap, inset, scroll spacing, and translate motion offsets.
+`stylelint-plugin-rhythmguard` enforces scale and token discipline across spacing, radius, typography, size, and translate motion offsets.
+
+## Demo
+
+<p align="center">
+  <a href="./assets/rhythmguard-campaign-60s.webm">
+    <img src="./assets/rhythmguard-campaign-60s.gif" width="100%" alt="Rhythmguard 60-second demo" />
+  </a>
+</p>
 
 I built Rhythmguard after 20 years of watching teams ignore spacing scales and ship arbitrary pixel values everywhere.
 
 It is built for teams that want:
 
 - zero random spacing values in production CSS
+- consistent numeric scales for radius, typography, and sizing primitives
 - token-first spacing workflows
 - predictable autofix behavior for large migrations
 - consistent layout rhythm across web surfaces
@@ -69,11 +78,44 @@ npm install --save-dev stylelint stylelint-plugin-rhythmguard
 }
 ```
 
+### Expanded config
+
+```json
+{
+  "extends": ["stylelint-plugin-rhythmguard/configs/expanded"]
+}
+```
+
+`expanded` enables scale enforcement for spacing + radius + typography + size property groups.
+
+### Logical config
+
+```json
+{
+  "extends": ["stylelint-plugin-rhythmguard/configs/logical"]
+}
+```
+
+`logical` composes Rhythmguard strict mode with `stylelint-plugin-logical-css` recommended rules.
+
+### Migration config
+
+```json
+{
+  "extends": ["stylelint-plugin-rhythmguard/configs/migration"]
+}
+```
+
+`migration` keeps on-scale numeric values temporarily while auto-building token mappings from CSS custom properties and optional Tailwind spacing config.
+
 Stable shared config entry points:
 
 - `stylelint-plugin-rhythmguard/configs/recommended`
 - `stylelint-plugin-rhythmguard/configs/strict`
 - `stylelint-plugin-rhythmguard/configs/tailwind`
+- `stylelint-plugin-rhythmguard/configs/expanded`
+- `stylelint-plugin-rhythmguard/configs/logical`
+- `stylelint-plugin-rhythmguard/configs/migration`
 
 ### Full custom setup
 
@@ -85,13 +127,22 @@ Stable shared config entry points:
       true,
       {
         "preset": "rhythmic-4",
+        "propertyGroups": ["spacing", "radius"],
+        "propertyScales": {
+          "font-size": [12, 14, 16, 20, 24]
+        },
         "units": ["px", "rem", "em"],
+        "unitStrategy": "convert",
         "baseFontSize": 16,
         "tokenPattern": "^--space-",
         "tokenFunctions": ["var", "theme", "token"],
         "allowNegative": true,
         "allowPercentages": true,
-        "fixToScale": true
+        "fixToScale": true,
+        "enforceInsideMathFunctions": true,
+        "mathFunctionArguments": {
+          "clamp": [1, 3]
+        }
       }
     ],
     "rhythmguard/prefer-token": [
@@ -99,6 +150,9 @@ Stable shared config entry points:
       {
         "tokenPattern": "^--space-",
         "allowNumericScale": false,
+        "tokenMapFromCssCustomProperties": true,
+        "tokenMapFromTailwindSpacing": true,
+        "tailwindConfigPath": "./tailwind.config.mjs",
         "tokenMap": {
           "4px": "var(--space-1)",
           "8px": "var(--space-2)",
@@ -146,6 +200,26 @@ Scale resolution precedence:
 3. `preset`
 4. default `rhythmic-4` scale
 
+## Option Validation
+
+Rhythmguard validates `secondaryOptions` for each rule before linting declarations.
+
+- Unknown option names fail fast with Stylelint invalid option warnings.
+- Invalid option shapes fail fast (for example string vs array mismatches).
+- `properties` string entries are validated against supported scale-targetable CSS property names.
+- `propertyGroups` values are validated against built-in groups: `spacing`, `radius`, `typography`, and `size`.
+- Math function argument maps are validated per function (`calc`, `clamp`, `min`, `max`) and positive 1-based argument indexes.
+
+Example typo that now fails immediately:
+
+```json
+{
+  "rules": {
+    "rhythmguard/use-scale": [true, { "sevverity": "warning" }]
+  }
+}
+```
+
 ## Built-in Scale Presets
 
 | Preset | Pattern | Scale |
@@ -235,6 +309,10 @@ Checks:
 - `inset*`, `scroll-margin*`, `scroll-padding*`
 - `translate`, `translate-x`, `translate-y`, `translate-z`
 - `transform` translation functions (`translate`, `translateX`, `translateY`, `translateZ`, `translate3d`)
+- optional property groups:
+  - `radius` (`border-radius*`, corner radii, `outline-offset`)
+  - `typography` (`font-size`, `line-height`, `letter-spacing`, `word-spacing`)
+  - `size` (`width`, `height`, min/max size, logical `inline-size`/`block-size`)
 
 Example:
 
@@ -260,6 +338,7 @@ Options:
 | `customScale` | `Array<number|string>` | `undefined` | Highest-priority custom scale override |
 | `scale` | `Array<number|string>` | `[0,4,8,12,16,24,32,40,48,64]` | Allowed spacing values |
 | `units` | `string[]` | `['px','rem','em']` | Units considered for scale enforcement |
+| `unitStrategy` | `'convert' \| 'exact'` | `'convert'` | `convert`: compare via px conversion (`px/rem/em`). `exact`: compare against same-unit scale values (for example `vw`, `cqi`) |
 | `baseFontSize` | `number` | `16` | Used for `rem`/`em` conversion |
 | `tokenPattern` | `string` | `^--space-` | Regex for accepted token variable names |
 | `tokenFunctions` | `string[]` | `['var','theme','token']` | Functions treated as tokenized values |
@@ -267,7 +346,11 @@ Options:
 | `allowPercentages` | `boolean` | `true` | Allows `%` values without scale checks |
 | `fixToScale` | `boolean` | `true` | Enables nearest-value autofix |
 | `enforceInsideMathFunctions` | `boolean` | `false` | Lints `calc()/clamp()/min()/max()` internals |
-| `properties` | `Array<string|RegExp>` | built-in spacing patterns | Override targeted property set |
+| `mathFunctionArguments` | `Record<mathFn, number[]>` | `{}` | Restricts linting to specific 1-based argument indexes per math function |
+| `ignoreMathFunctionArguments` | `Record<mathFn, number[]>` | `{}` | Excludes specific 1-based argument indexes per math function |
+| `propertyGroups` | `Array<'spacing' \| 'radius' \| 'typography' \| 'size'>` | `['spacing']` | Selects built-in property groups when `properties` is not provided |
+| `properties` | `Array<string|RegExp>` | built-in spacing patterns | Override targeted property set; string values must be supported spacing property names |
+| `propertyScales` | `Record<propertyOrRegex, scaleOrPreset>` | `{}` | Per-property scale overrides (supports exact names or `/regex/flags` keys) |
 
 ### `rhythmguard/prefer-token`
 
@@ -300,10 +383,20 @@ Options:
 | `customScale` | `Array<number|string>` | `undefined` | Highest-priority custom scale override |
 | `scale` | `Array<number|string>` | `[0,4,8,12,16,24,32,40,48,64]` | Used when `allowNumericScale` is enabled |
 | `baseFontSize` | `number` | `16` | Used for scale checks with `rem`/`em` |
+| `unitStrategy` | `'convert' \| 'exact'` | `'convert'` | Matching strategy when `allowNumericScale` is enabled |
+| `units` | `string[]` | `['px','rem','em']` | Units considered for numeric scale checks |
 | `enforceInsideMathFunctions` | `boolean` | `false` | Lints `calc()/clamp()/min()/max()` internals |
+| `mathFunctionArguments` | `Record<mathFn, number[]>` | `{}` | Restricts linting to specific 1-based argument indexes per math function |
+| `ignoreMathFunctionArguments` | `Record<mathFn, number[]>` | `{}` | Excludes specific 1-based argument indexes per math function |
 | `tokenMap` | `Record<string,string>` | `{}` | Enables autofix from raw value to token |
+| `tokenMapFile` | `string` | `null` | JSON file path to merge additional token mappings |
+| `tokenMapFromCssCustomProperties` | `boolean` | `false` | Auto-builds mappings from matching custom property declarations in the same stylesheet |
+| `tokenMapFromTailwindSpacing` | `boolean` | `false` | Auto-builds mappings from `theme.spacing` and `theme.extend.spacing` in Tailwind config |
+| `tailwindConfigPath` | `string` | `null` | Path to Tailwind config used by `tokenMapFromTailwindSpacing` (`.js`, `.cjs`, `.mjs`) |
 | `ignoreValues` | `string[]` | CSS global keywords + `auto` | Skips keyword literals |
-| `properties` | `Array<string|RegExp>` | built-in spacing patterns | Override targeted property set |
+| `propertyGroups` | `Array<'spacing' \| 'radius' \| 'typography' \| 'size'>` | `['spacing']` | Selects built-in property groups when `properties` is not provided |
+| `properties` | `Array<string|RegExp>` | built-in spacing patterns | Override targeted property set; string values must be supported spacing property names |
+| `propertyScales` | `Record<propertyOrRegex, scaleOrPreset>` | `{}` | Per-property scale overrides for numeric migration mode |
 
 ### `rhythmguard/no-offscale-transform`
 
@@ -325,7 +418,7 @@ Example:
 
 Options:
 
-`rhythmguard/no-offscale-transform` accepts the same scale options as `rhythmguard/use-scale`, but only for transform translation properties.
+`rhythmguard/no-offscale-transform` accepts the same scale options as `rhythmguard/use-scale` (including `unitStrategy`, math argument targeting, and deterministic autofix), but only for transform translation properties. Its secondary options are also validated for unknown keys and invalid value shapes.
 
 ## Tailwind CSS Integration
 
@@ -343,7 +436,29 @@ Rhythmguard works well in Tailwind projects, but it enforces what Stylelint can
   - `class="p-4 gap-2"`
   - `class="p-[13px] translate-y-[18px]"`
 
-Those are not Stylelint declaration nodes, so they are outside this plugin's scope.
+Those are not Stylelint declaration nodes, so they are outside Stylelint rule scope.
+
+### Companion ESLint layer for class strings
+
+Rhythmguard now ships an ESLint companion export for class-string governance:
+
+```js
+// eslint.config.js (flat config)
+import rhythmguard from 'stylelint-plugin-rhythmguard/eslint';
+
+export default [
+  {
+    plugins: {
+      'rhythmguard-tailwind': rhythmguard,
+    },
+    rules: {
+      'rhythmguard-tailwind/tailwind-class-use-scale': ['error', { scale: [0, 4, 8, 12, 16, 24, 32] }],
+    },
+  },
+];
+```
+
+This rule targets arbitrary spacing utilities such as `p-[13px]`, `gap-[18px]`, `translate-x-[10px]`, and autofixes to the nearest configured scale value.
 
 ### Recommended stack for full Tailwind enforcement
 
@@ -362,7 +477,8 @@ Suggested setup:
 
 Then pair with:
 
-- `eslint-plugin-tailwindcss` for class-string rules (including arbitrary-value governance).
+- `stylelint-plugin-rhythmguard/eslint` for arbitrary spacing class-string scale enforcement.
+- `eslint-plugin-tailwindcss` for broader class-string linting and conventions.
 - `prettier-plugin-tailwindcss` for deterministic class ordering.
 
 Detailed setup reference: [`docs/TAILWIND.md`](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/TAILWIND.md).
@@ -371,14 +487,7 @@ Detailed setup reference: [`docs/TAILWIND.md`](https://github.com/PetriLahdelma/
 
 By default, `tokenFunctions` includes `theme`, so values like `theme(spacing.4)` are treated as tokenized values.
 
-### Product direction
-
-We should extend Tailwind coverage thoroughly, but in the right architecture:
-
-- keep `stylelint-plugin-rhythmguard` focused on CSS declaration enforcement
-- add a complementary Tailwind class-string layer (ESLint/plugin side) for utility classes
-
-This avoids brittle parsing hacks and gives full coverage without compromising rule quality.
+This keeps CSS declaration enforcement and template class-string enforcement separated but coordinated.
 
 ## Programmatic Presets
 
@@ -389,6 +498,7 @@ console.log(rhythmguard.presets.listScalePresetNames());
 console.log(rhythmguard.presets.listCommunityScalePresetNames());
 console.log(rhythmguard.presets.getCommunityScaleMetadata('product-decimal-10'));
 console.log(rhythmguard.presets.scales['rhythmic-4']);
+console.log(Object.keys(rhythmguard.eslint.rules));
 ```
 
 ## Autofix Philosophy
@@ -402,9 +512,9 @@ It will not guess token mappings without your map.
 
 ## Compatibility
 
-- Stylelint: `^16.0.0`
+- Stylelint: `^16.0.0 || ^17.0.0`
 - Node.js: `>=18.18.0`
-- Module format: CommonJS plugin package
+- Module format: dual `require` + `import` entry points (CommonJS + ESM wrappers)
 - Note: Stylelint `16.0.0` has known autofix/API behavior differences; CI enforces floor compatibility and runs non-blocking full-suite observability on the floor version.
 
 ## Development
@@ -441,8 +551,9 @@ Detailed methodology and custom args are documented in [`docs/BENCHMARKING.md`](
 1. Create a GitHub release.
 2. `release.yml` runs the Node/Stylelint matrix validation.
 3. A tarball smoke test validates package exports and install behavior.
-4. The package is published to npm with provenance (`npm publish --provenance`).
-5. `post-publish-smoke.yml` verifies the published npm version can be installed and run in a clean project.
+4. If `NPM_TOKEN` is configured in repository secrets, the package is published to npm with provenance (`npm publish --provenance`).
+5. If `NPM_TOKEN` is not configured, publish is skipped with an explicit workflow notice.
+6. `post-publish-smoke.yml` verifies the published npm version can be installed and run in a clean project (and skips cleanly if the version is not on npm).
 
 ## Support and Bug Reports
 

package/assets/rhythmguard-campaign-60s-template.html

@@ -0,0 +1,322 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Rhythmguard 60s Campaign Frame</title>
+    <style>
+      @font-face {
+        font-family: "GeistPixel";
+        src: url("../node_modules/geist/dist/fonts/geist-pixel/GeistPixel-Line.woff2") format("woff2");
+        font-weight: 400;
+        font-style: normal;
+      }
+
+      :root {
+        --bg: #000;
+        --fg: #fff;
+      }
+
+      * {
+        box-sizing: border-box;
+      }
+
+      html,
+      body {
+        width: 1920px;
+        height: 1080px;
+        margin: 0;
+        padding: 0;
+        overflow: hidden;
+        background: var(--bg);
+        color: var(--fg);
+        font-family: "GeistPixel", monospace;
+      }
+
+      body {
+        padding: 28px;
+      }
+
+      .frame {
+        width: 100%;
+        height: 100%;
+        border: 4px solid var(--fg);
+        display: grid;
+        grid-template-rows: 118px 1fr 110px;
+      }
+
+      .header {
+        border-bottom: 2px solid var(--fg);
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        padding: 0 30px;
+        font-size: 34px;
+        letter-spacing: 0.5px;
+      }
+
+      .main {
+        display: grid;
+        grid-template-columns: minmax(0, 2.1fr) minmax(0, 1fr);
+        gap: 28px;
+        padding: 28px 30px;
+      }
+
+      .hero {
+        border: 2px solid var(--fg);
+        padding: 26px;
+        display: grid;
+        grid-template-rows: auto auto auto 1fr;
+        gap: 18px;
+      }
+
+      .kicker {
+        font-size: 30px;
+        letter-spacing: 0.8px;
+        margin: 0;
+      }
+
+      .title {
+        font-size: 96px;
+        letter-spacing: 1px;
+        line-height: 1;
+        margin: 0;
+      }
+
+      .subtitle {
+        font-size: 42px;
+        letter-spacing: 0.8px;
+        margin: 0;
+      }
+
+      .terminal {
+        border: 2px solid var(--fg);
+        display: grid;
+        grid-template-rows: 50px 1fr;
+        min-height: 360px;
+      }
+
+      .terminal-bar {
+        border-bottom: 2px solid var(--fg);
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        padding: 0 16px;
+        font-size: 24px;
+      }
+
+      .terminal-dots {
+        display: flex;
+        gap: 10px;
+      }
+
+      .terminal-dot {
+        width: 12px;
+        height: 12px;
+        border: 2px solid var(--fg);
+      }
+
+      pre {
+        margin: 0;
+        padding: 16px;
+        font-family: "GeistPixel", monospace;
+        font-size: 30px;
+        line-height: 1.45;
+        white-space: pre-wrap;
+      }
+
+      .side {
+        display: grid;
+        grid-template-rows: 1fr 1fr;
+        gap: 18px;
+      }
+
+      .card {
+        border: 2px solid var(--fg);
+        padding: 18px;
+        display: grid;
+        grid-template-rows: auto 1fr;
+        gap: 12px;
+      }
+
+      .card h2 {
+        margin: 0;
+        font-size: 36px;
+        letter-spacing: 0.8px;
+      }
+
+      .rules {
+        margin: 0;
+        padding-left: 24px;
+        font-size: 31px;
+        line-height: 1.5;
+      }
+
+      .meta {
+        margin: 0;
+        font-size: 30px;
+        line-height: 1.5;
+      }
+
+      .footer {
+        border-top: 2px solid var(--fg);
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        padding: 0 30px;
+        font-size: 30px;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="frame">
+      <header class="header">
+        <div id="step">STEP 1 / 6</div>
+        <div>Rhythmguard</div>
+      </header>
+      <main class="main">
+        <section class="hero">
+          <p class="kicker" id="kicker">INSTALL + STRICT CONFIG</p>
+          <h1 class="title" id="title">NO RANDOM 13PX.</h1>
+          <p class="subtitle" id="subtitle">SCALE OR TOKEN. PERIOD.</p>
+          <div class="terminal">
+            <div class="terminal-bar">
+              <div class="terminal-dots">
+                <span class="terminal-dot"></span>
+                <span class="terminal-dot"></span>
+                <span class="terminal-dot"></span>
+              </div>
+              <span id="terminal-title">terminal // setup</span>
+            </div>
+            <pre id="code"></pre>
+          </div>
+        </section>
+        <aside class="side">
+          <section class="card">
+            <h2>RULES</h2>
+            <ul class="rules">
+              <li>use-scale</li>
+              <li>prefer-token</li>
+              <li>no-offscale-transform</li>
+            </ul>
+          </section>
+          <section class="card">
+            <h2>WHY</h2>
+            <p class="meta" id="why"></p>
+          </section>
+        </aside>
+      </main>
+      <footer class="footer">
+        <div>stylelint-plugin-rhythmguard</div>
+      </footer>
+    </div>
+
+    <script>
+      const scenes = [
+        {
+          kicker: "INSTALL + STRICT CONFIG",
+          title: "NO RANDOM 13PX.",
+          subtitle: "SCALE OR TOKEN. PERIOD.",
+          terminalTitle: "terminal // setup",
+          code: [
+            "$ npm i -D stylelint stylelint-plugin-rhythmguard",
+            "$ cat .stylelintrc.json",
+            "{",
+            '  "extends": ["stylelint-plugin-rhythmguard/configs/strict"]',
+            "}",
+            '$ npx stylelint "src/**/*.css"',
+          ],
+          why: "Shared config replaces ad-hoc spacing rules across files.",
+        },
+        {
+          kicker: "RULE 1 // USE-SCALE",
+          title: "LOCK TO SCALE.",
+          subtitle: "EVERY SPACING VALUE GETS CHECKED.",
+          terminalTitle: "report // use-scale",
+          code: [
+            "Button.css:12",
+            "  Expected spacing from configured scale.",
+            "  ✕ margin-top: 13px",
+            "  ✓ margin-top: 12px",
+            "",
+            "Autofix maps to nearest safe scale step.",
+          ],
+          why: "Scale discipline keeps layouts predictable in large systems.",
+        },
+        {
+          kicker: "RULE 2 // PREFER-TOKEN",
+          title: "TOKENS FIRST.",
+          subtitle: "RAW PIXELS BECOME DESIGN TOKENS.",
+          terminalTitle: "report // prefer-token",
+          code: [
+            "Card.css:8",
+            "  Expected token, not raw literal.",
+            "  ✕ padding: 16px",
+            "  ✓ padding: var(--space-4)",
+            "",
+            "tokenMap applies safe automatic replacements.",
+          ],
+          why: "Token usage makes theme changes and audits low-risk.",
+        },
+        {
+          kicker: "RULE 3 // TRANSFORM OFFSETS",
+          title: "MOTION IN RHYTHM.",
+          subtitle: "TRANSLATES STAY ON THE SAME SCALE.",
+          terminalTitle: "report // no-offscale-transform",
+          code: [
+            "Toast.css:22",
+            "  Off-scale translate value detected.",
+            "  ✕ transform: translateY(7px)",
+            "  ✓ transform: translateY(8px)",
+            "",
+            "Motion offsets align with layout spacing values.",
+          ],
+          why: "Spacing + motion consistency improves visual quality.",
+        },
+        {
+          kicker: "AUTOFIX WORKFLOW",
+          title: "FIX FAST, SAFELY.",
+          subtitle: "MIGRATE LEGACY CSS WITHOUT DRAMA.",
+          terminalTitle: "autofix // migration",
+          code: [
+            "$ npx stylelint \"src/**/*.css\" --fix",
+            "Applied fixes:",
+            "  - use-scale: 124",
+            "  - prefer-token: 98",
+            "  - no-offscale-transform: 19",
+            "",
+            "Review diff and ship.",
+          ],
+          why: "Autofix handles repetitive cleanup at production scale.",
+        },
+        {
+          kicker: "READY TO SHIP",
+          title: "RHYTHMGUARD",
+          subtitle: "SPACING GOVERNANCE FOR REAL-WORLD TEAMS.",
+          terminalTitle: "next // adopt",
+          code: [
+            "Extends available:",
+            "  - configs/recommended",
+            "  - configs/strict",
+            "  - configs/tailwind",
+            "",
+            "No random spacing values in production CSS.",
+          ],
+          why: "Consistent spacing rules reduce regressions release after release.",
+        },
+      ];
+
+      const sceneQuery = Number(new URLSearchParams(window.location.search).get("scene") || "1");
+      const index = Math.min(Math.max(sceneQuery, 1), scenes.length) - 1;
+      const scene = scenes[index];
+
+      document.getElementById("step").textContent = `STEP ${index + 1} / ${scenes.length}`;
+      document.getElementById("kicker").textContent = scene.kicker;
+      document.getElementById("title").textContent = scene.title;
+      document.getElementById("subtitle").textContent = scene.subtitle;
+      document.getElementById("terminal-title").textContent = scene.terminalTitle;
+      document.getElementById("code").textContent = scene.code.join("\n");
+      document.getElementById("why").textContent = scene.why;
+    </script>
+  </body>
+</html>