@fractaldesign/fractalstyler 0.0.0-stage → 0.9.0

package/docs/references/configurations-api.md

@@ -0,0 +1,220 @@
+---
+title: Configurations API
+description: Complete registry of every configuration variable, runtime token, attribute axis and class pattern in the current system, read verbatim from the Sass sources.
+type: fractalstyler
+---
+
+# Configurations API — every variable, token, attribute and class in the system
+
+> Companion to [`configurations.md`](configurations.md) (the *why* and *how to edit*).
+> This document is the *what*: every Sass configuration variable in
+> `_00_config.sass`, every CSS custom property in `_00_tokens.sass`, every
+> `data-*` axis, and every class family the loops and partials emit — with
+> values, defaults, consumers, and who reads what.
+>
+> Sources read verbatim:
+> `_00_config.sass`, `_00_fonts.sass`, `_00_tokens.sass`, `_01_base.sass`,
+> `_02_dimensions.sass`, `_03_typography.sass`, `_04_containers.sass`,
+> `_05_layouts.sass`, `_06_shells.sass`, `_07_interactions.sass`,
+> `_08_visuals.sass`, `_09_own.sass`, `index.sass`.
+> `colorpacks.sass` and `themeplates.sass` are raw Sass variable palettes
+> (`$green90`-style ladder constants); they emit no classes and no tokens and
+> are intentionally not part of this API.
+>
+> Three kinds of API — do not mix them:
+>
+> | Kind | Example | Set where / when |
+> |---|---|---|
+> | **A. Sass source variables** | `$steps`, `$gap-families`, `$frame-ratios`, `$shadow-specs` | `src/lib/styles/_00_config.sass` — edit in place, then recompile |
+> | **B. Runtime CSS props + `data-*` modes** | `--space-md`, `data-mode="dark"`, `data-variant="ghost"` | In the browser, live, no recompile |
+> | **C. Classes** (loop families + partial classes) | `.gap-md`, `.grid-4`, `button[data-variant="ghost"]` | Baked at compile time from A; themed at runtime by B |
+
+---
+
+## 1. A — Sass configuration (`_00_config.sass`)
+
+The whole compile-time surface is seven variables. They are *not* `!default`
+and have no `with (…)` override: they are the system's own config, edited in
+place. Everything loop-generated (the entire L1 space ladder, the L3 frames,
+the `--shade-*` elevation tokens) is expanded from them.
+
+| Variable | Value | Consumed by | Effect of a change |
+|---|---|---|---|
+| `$steps` | `('xs' 'sm' 'md' 'bs' 'lg' 'xl' '2xl' '3xl')` — 8 steps | `_02_dimensions.sass` (gap/pad/mar loops), `scripts/update-registry.js` | Every space family is crossed with this list: a new step emits `.gap-…`/`.pad-…`/`.mar-…` rows for all 17 families — **only if** a matching `--space-<step>` token exists in `_00_tokens.sass`, else the emitted `var()` points at nothing |
+| `$gap-families` | `(gap: gap, rgap: row-gap, cgap: column-gap)` — 3 families | `_02_dimensions.sass` | Key = class prefix, value = CSS property. Add `xgap: column-gap` and `.xgap-*` classes compile; remove a key and its classes cease to exist |
+| `$pad-families` | `(pad: padding, px: padding-inline, py: padding-block, pt: padding-top, pr: padding-right, pb: padding-bottom, pl: padding-left)` — 7 families | `_02_dimensions.sass` | Same key→property contract. `px`/`py` are logical (inline/block, RTL-safe); named sides are physical |
+| `$mar-families` | `(mar: margin, mx: margin-inline, my: margin-block, mt: margin-top, mr: margin-right, mb: margin-bottom, ml: margin-left)` — 7 families | `_02_dimensions.sass` | Same key→property contract. There are no negative-margin classes and no side-family aliases beyond these |
+| `$frame-ratios` | `('16-9': '16 / 9', '9-16': '9 / 16', '4-3': '4 / 3', '3-4': '3 / 4', '3-2': '3 / 2', '2-3': '2 / 3', '1-1': '1 / 1')` — 7 ratios | `_05_layouts.sass` (`.frame-*` loop) | Key = class suffix, value = `aspect-ratio` literal. Add `'21-9': '21 / 9'` and `.frame-21-9` compiles |
+| `$breakpoints` | `(md: 768px, bs: 1024px, lg: 1280px)` | `_06_shells.sass` (`$md`/`$bs`/`$lg` locals → rail visibility media queries) | Renaming or moving a key moves the rail seams. **Not** a complete seam inventory: `_05_layouts` and parts of `_06` hardcode `1025px`/`1281px`/`1441px`/`769px` literals; change both together |
+| `$shadow-specs` | 8 steps, each `(y1, b1, a1, y2, b2, a2)` — key/ambient layer pairs | `:root` loop in `_00_config.sass` | Emits the `--shade-*` token per step (`var(--shadow-rim)` + two shadow layers). The `.shadow-*` classes read the separate `--shadow-*` channel tokens instead |
+
+The header table of the file also fixes the step ladder semantics for humans:
+key alpha tightens `0.14 → 0.02`, ambient alpha widens `0.00 → 0.08`, key blur
+`1 → 24px`, ambient blur `0 → 64px` as steps grow.
+
+---
+
+## 2. B — runtime tokens (`_00_tokens.sass`)
+
+Structure: two authoring mixins, `=light-theme-tokens` and
+`=dark-theme-tokens`, are applied by `[data-mode='dark']` and
+`[data-mode='light']` respectively. **A `data-mode` attribute on `<html>` is
+mandatory** — the colour roles live inside the mode mixins, not `:root`;
+without the attribute no colour token is defined. The `:root` block carries
+everything mode-independent: fonts, type/space/radius scales, motion language,
+control metrics, page chrome.
+
+### 2.1 Colour roles (light / dark)
+
+| Token | Light | Dark | Read by |
+|---|---|---|---|
+| `--white-fixed` | `#FFFFFF` | `#FFFFFF` | `.text-white`, `button[data-variant="primary"|"soft"|"destructive"]` |
+| `--black-fixed` | `#171717` | `#171717` | `.text-black` |
+| `--bg` | `#ffffff` | `#101010` | `.bg`, `button[data-variant="outline"]` |
+| `--bg-surface` | `#FBFBF9` | `#202021` | `.surface`, `body`, `.app-header` |
+| `--bg-panel` | `#FBFBF9` | `#1f1f20` | `.panel`, `.card` |
+| `--bg-sunken` | `#F7F6F0` | `#1f1f20` | `.sunken` |
+| `--bg-raised` | `#F4F4F5` | `#3a3a3a` | `.raised`, `.accordion-trigger:hover` |
+| `--bg-extra` | `rgb(247, 248, 249)` | `#111111` | `.extra` |
+| `--bg-input` | `#f8f9fa` | `#1c1c1d` | `.input`, `.select` |
+| `--bg-button` | `#CED8D3` | `#171818` | reserved button fill channel |
+| `--text-primary` | `#262627` | `#EDF2F7` | `.text-primary`, body, headings |
+| `--text-secondary` | `#777777` | `#c7c7c7` | `.text-secondary` |
+| `--text-muted` | `#a3a4a7` | `#7c7c7c` | `.text-muted`, `.breadcrumb-*`, `.inputs-wrapper label` |
+| `--text-inverse` | `#ffffff` | `#7c7c7c` | `.text-inverse` — flips with mode by design |
+| `--state-surface` | `#F2EFE9` | `#7c7c7c` | `button[data-variant="secondary"]` |
+| `--state-hover` | `#ECE7DF` | `#4a4a4b` | `a.nav-link:hover`, `button[data-variant="secondary"|"outline"|"ghost"]:hover`, `button.icon:hover` |
+| `--state-selected` | `#E4DFD5` | `#666668` | selected-state channel |
+| `--border` | `#d8d8d8` | `#2f2f2f` | `.border`, `.bt`/`.br`/`.bb`/`.bl`, `.input`, `.select`, `.card`, `.accordion-item` |
+| `--border-subtle` | `#eceaea` | `#1e1e1f` | `.border-subtle`, `.bt-sub`/… |
+| `--border-strong` | `#cfcfcf` | `#7c7c7c` | `.border-strong`, `.bt-str`/…, `button[data-variant="secondary"]` |
+| `--theme-color` | `#ff4400` | `#2F9E44` | `.link`, `.text-theme`, `button[data-variant="primary"]`, `a.primary`, focus rims |
+| `--theme-color-alt` | `#be2f00` | `#36731d` | `.link:hover`, `a.primary` hover |
+| `--theme-color-sub` | `#feb18a` | *(undefined in dark — inherits)* | `button[data-variant="soft"]` |
+| `--success` / `--success-hover` | `#10B981` / `#059669` | `#34D399` / `#6EE7B7` | `.text-success`, `.bg-success` |
+| `--warning` / `--warning-hover` | `#F59E0B` / `#D97706` | `#FBBF24` / `#FCD34D` | `.text-warning`, `.bg-warning` |
+| `--danger` / `--danger-hover` | `#bf2a2a` / `#DC2626` | `#b21a1a` / `#FCA5A5` | `.text-danger`, `.bg-danger`, `button[data-variant="destructive"]` |
+| `--info` / `--info-hover` | `#3B82F6` / `#2563EB` | `#60A5FA` / `#93C5FD` | `.text-info`, `.bg-info` |
+| `--ring` | `rgba(0, 127, 78, 0.35)` | `rgba(16, 185, 129, 0.4)` | `.input`/`.select` focus, `.accordion-trigger` focus |
+| `--shadow-color` | `15 13 42` | `0 0 0` | every `--shadow-*` channel (RGB triplet) |
+| `--shadow-rim` | `transparent` | `inset 0 1px 0 rgba(255,255,255,0.09)` | prefixed onto `--shade-*` tokens |
+| `--shadow-umbra` | *(undefined in light)* | `rgb(0 0 0 / 0.50)` | dark-only umbra channel |
+| `--shadow-xs` … `--shadow-3xl` | two-layer key+ambient, identical values in both mixins | same | `.shadow-xs` … `.shadow-3xl` |
+
+### 2.2 Mode-independent `:root` tokens
+
+| Group | Tokens | Notes |
+|---|---|---|
+| Fonts | `--font-sans` (`"Timeless Sans", sans-serif`), `--timeless-sans`, `--timeless-grotesk` | `@font-face` families declared in `_00_fonts.sass`; `--font-mono` is *not* defined — `.mono` reads it and falls back to the browser stack until a mono face is added |
+| Type scale | `--text-scaling: 1.25`; `--text-xs` `0.67rem`, `--text-sm` `0.75rem`, `--text-md` `0.875rem`, `--text-bs` `1rem`; `--text-lg`+ each `calc(previous * var(--text-scaling))` up to `--text-5xl` | Fixed rem rungs to base, then compounded — not fluid interpolation |
+| Space scale | `--unit-space: 0.25rem`; `--space-xs` = unit, `sm` ×2, `md` ×3, `bs` ×4, `lg` ×6, `xl` ×8, `2xl` ×12, `3xl` ×16 | The rung set must mirror `$steps` — see §1 |
+| Radius | `--radius-xs: 2px`, `sm: 4px`, `md: 8px`, `bs: 16px`, `lg: 32px`, `full: 9999px` | Six channels; no literal-radius ladder exists |
+| Control metrics | `--control-h-sm: 21px`, `--control-h-bs: 32px`, `--control-h-lg: 38px`; `--height-sm: 16px`, `md: 20px`, `bs: 27px`, `lg: 32px` | `.h-*` classes read `--height-*`; `.input`/`.select` read `--height-lg` |
+| Avatar / switch | `--avatar-size: 32px`, `--switch-w: 40px`, `--switch-h: 22px`, `--switch-thumb: 16px` | Load-bearing pairings documented in the source |
+| Motion | `--transin1..3`, `--transout1..3` (cubic-beziers); `--speed0: 50ms`, `--speed1: 90ms`, `--speed2: 140ms`, `--speed3: 220ms`; `--motionin1..3`/`--motionout1..3` = duration + easing | Every `transition:` in the system reads these |
+| Page chrome | `--header-height: 64px`, `--footer-height: 32px`, `--fit-height` (their sum), `--prose-clamp: 65ch`, `--content-clamp: 1600px`, `--app-inline: var(--space-lg)`, `--card-min: 240px`, `--sidebar-width`/`-left`/`-right: 280px`, `--z-sticky: 100`, `--z-raised: 200`, `--z-modal: 300`, `--z-toast: 500` | Shell geometry the L4 classes read |
+| Pop colors | `--greenpop1..4`, `--orangepop1..6` | Named accent literals; `.orange1`…`.orange6` ink classes read the orange set |
+| Elevation (from `_00_config.sass`) | `--shade-xs` … `--shade-3xl` | Loop-generated from `$shadow-specs` — rim + key layer + ambient layer |
+
+---
+
+## 3. B — `data-*` attribute API
+
+| Attribute | Where | Values | Effect |
+|---|---|---|---|
+| `data-mode` | `<html>` (mandatory) | `light` \| `dark` | Applies `=light-theme-tokens` / `=dark-theme-tokens` — the entire colour-role set |
+| `data-shape` | `.card` | `modern` | `border-radius: var(--radius-sm)` |
+| `data-shape` | `button` | `modern` \| `curved` \| `round` | Corner treatment: `--radius-sm` / `--radius-md` / `--radius-full` |
+| `data-variant` | `button` | `primary` \| `secondary` \| `soft` \| `outline` \| `ghost` \| `link` \| `destructive` | Paint variant of the button quartet (`destructive` also runs the `vibrating` keyframes on hover) |
+| `data-size` | `button` | `sm` \| `md` \| `bs` \| `lg` | Metrics variant: height + font-size channels |
+
+Class-attribute states (not `data-*`, but part of the same runtime surface):
+`.app-shell.open` (left rail becomes a fixed drawer below 1025px),
+`.accordion-item.open` (expands `.accordion-content`),
+`.ta-c.mleft`/`.ta-r.mleft` (de-centers below 1024px),
+`.content-section.null|narrow-half|narrow-wide|narrow-full`,
+`.input.small`/`.select.small`, `.hide-mobile`/`.hide-desktop`.
+
+---
+
+## 4. C — class registry (summary)
+
+414 concrete classes across the layers; the full inventory with properties,
+kinds and examples is [`../REGISTRY.api.md`](../REGISTRY.api.md) (generated),
+and the grep cheatsheet is [`../../REGISTRY.md`](../../REGISTRY.md).
+
+| Layer | Partial | Count | Contents |
+|---|---|---|---|
+| L0 | `_01_base.sass` | 2 | `.bdr` debug outline, `.mode-wipe` view-transition kill switch |
+| L1 | `_02_dimensions.sass` | 154 | 17 space families × 8 steps (136), 6 radius channels, `.wfull`/`.hfull`/`.full`, `.minw0`/`.minh0`/`.min0`, `.h-sm`…`.h-lg`, `.hfull-vh`, `.hfull-vh-fitted` |
+| L2 | `_04_containers.sass` | 54 | `.box` + 10 alignment modifiers, `.row` + 9, `.grid` + 16, `.wrap`, `.grow`, `.shrink-0`, position set, `.scroll-y`/`.scroll-x`, `.card` (+`data-shape`), `.chip`, `.prose-section`, `.nav-section`, `.page-header`, `.inputs-wrapper`, `.checkbox-wrapper` |
+| L3 | `_05_layouts.sass` | 23 | `.grid-1/2/3/4/6` (divisor stepping), `.cspan-1`…`.cspan-8`, `.card-grid`, `.prose`, 7 `.frame-*` (from `$frame-ratios`), `.reel` |
+| L4 | `_06_shells.sass` | 16 | `.app-shell` (+`.open` drawer compound), `.app-header` (+`.clamped`), `.app-main` (+`.clamped`), `.main-section`, `.sidebar-left`, `.sidebar-right`, `.app-footer`, `.content-section` (+`.null`/`.narrow-half`/`.narrow-wide`/`.narrow-full`) |
+| L5 | `_03_typography.sass` | 55 | `.text-xs`…`.text-5xl`, `.text-body*`, `.page-*`/`.card-*`/`.breadcrumb-*`/`.nav-*`/`.header-nav`, `.lh11`–`.lh16`, `.ls-*`, `.weight-300`–`.weight-800`, `.tt-*`, `.ta-*` (+`.mleft`), `.mono`, `.sans`, `.truncate` |
+| L5 | `_07_interactions.sass` | 31 | `button` element base, `button.icon/modern/primary`, 7 `button[data-variant]`, 3 `button[data-shape]`, 4 `button[data-size]`, `.input`(+`.small`), `.select`(+`.small`), `.link`, `.link-plain`, `.link-parent` (+`.link-title` child), `a.nav-link`, `a.primary`(+`.modern`), `a.outline`(+`.modern`) |
+| L5 | `_08_visuals.sass` | 52 | 6 bare backgrounds, 11 ink, 4 status fills, `.border`/`.border-subtle`/`.border-strong`, 12 partition borders (`.bt`/`.br`/`.bb`/`.bl` × 3 weights), 8 `.shadow-*`, `.hide-mobile`/`.hide-desktop`, `.orange1`–`.orange6` |
+| Custom | `_09_own.sass` | 27 | `.site-logomotif`, `.logotype`, `.project-circle`, the `.mascot`/`.mascotgl` families, `.hero-name`, the `.accordion` family |
+
+Every class entry in `registry.json` carries: `class`, `kind`
+(`family`/`class`/`modifier`/`child`/`variant`/`compound`/`element`),
+`layer`, `property` (declarations, with `@media` steps inline), `file`,
+`description`, `example`.
+
+---
+
+## 5. Fonts (`_00_fonts.sass`)
+
+`@font-face` declarations only — no classes, no tokens:
+
+| Family | File | Weight | Style |
+|---|---|---|---|
+| `Google Sans Flex` | `/fonts/GoogleSansFlex.woff2` | 300 800 | normal, italic |
+| `Google Sans` | `/fonts/GoogleSans.woff2` | 400 700 | normal |
+| `Google Sans` (italic) | `/fonts/GoogleSans-Italic.woff2` | 400 700 | italic |
+| `Google Sans Code` | `/fonts/googlesanscode.woff2` | 300 800 | normal |
+| `Timeless Sans` | `/fonts/TimelessSansVF.woff2` | 300 800 | normal, italic |
+| `Timeless Grotesk` | `/fonts/TimelessSansVF.woff2` | 300 800 | normal, italic |
+| `General Sans` | `/fonts/generalsans.woff2` | 300 700 | normal |
+| `Satoshi` | `/fonts/satoshi.woff2` | 300 800 | normal |
+| `Stack Sans` | `/fonts/stacksans.woff2` | 300 800 | normal |
+
+`--font-sans` resolves to `Timeless Sans`; `Google Sans`/`General Sans`/
+`Satoshi`/`Stack Sans` are alternate stacks a consumer can swap in.
+
+---
+
+## 6. Token → defined-in → read-by index
+
+| Token group | Defined in | Read by |
+|---|---|---|
+| `--shade-*` | `_00_config.sass` `:root` loop | (reserved elevation channel; `.shadow-*` classes read `--shadow-*` instead) |
+| Colour roles (§2.1) | `_00_tokens.sass` mode mixins | L5 dress classes, interactions, body |
+| `--font-sans`, `--timeless-*` | `_00_tokens.sass` `:root` | `body`, `.sans` |
+| `--text-*` | `_00_tokens.sass` `:root` | `.text-*`, `.text-body*`, semantic type roles |
+| `--space-*`, `--unit-space` | `_00_tokens.sass` `:root` | all 17 L1 space families |
+| `--radius-*` | `_00_tokens.sass` `:root` | `.radius-*`, `.chip`, `.input`, `.select`, `.card`, `button[data-shape]`, `a.nav-link` |
+| `--height-*`, `--control-h-*` | `_00_tokens.sass` `:root` | `.h-*`, `.input`/`.select`, `.accordion-trigger` |
+| `--motion*`, `--speed*`, `--trans*` | `_00_tokens.sass` `:root` | every `transition:` in the system |
+| `--header-height`, `--footer-height`, `--fit-height` | `_00_tokens.sass` `:root` | `.app-header`, `.app-main`, `.hfull-vh-fitted`, rails |
+| `--prose-clamp`, `--content-clamp`, `--app-inline`, `--card-min` | `_00_tokens.sass` `:root` | `.prose`, `.app-header.clamped`, `.app-main.clamped`, shells, `.card-grid` |
+| `--sidebar-width*`, `--z-*` | `_00_tokens.sass` `:root` | rails, `.app-header`, drawer |
+| `--shadow-*`, `--shadow-color`, `--shadow-rim` | `_00_tokens.sass` mode mixins | `.shadow-*` classes, `--shade-*` composition |
+| `--greenpop*`, `--orangepop*` | `_00_tokens.sass` `:root` | `.orange1`…`.orange6` (green set reserved) |
+
+---
+
+## 7. Regeneration pipeline
+
+| Script | Emits |
+|---|---|
+| `scripts/update-registry.js` | `registry.json`, `REGISTRY.md`, `docs/REGISTRY.md`, `skills/fractal-styler/references/fractals.md`, `skills/fractal-styler/references/tokens.md` |
+| `scripts/class-vocab.js` | `docs/REGISTRY.api.md` (reads `registry.json`) |
+| `lint/browser.mjs --out docs/browser.html` | `docs/browser.html` (searchable registry browser) |
+| `scripts/build-css.js` | `dist/css/fractalstyler.css` + `.min.css` (plain-CSS distribution) |
+| `scripts/validate-deck.js` | exit 0/1 — every class named in docs/components resolves against the compiled stylesheet |
+| `lint/cli.mjs` | exit 0/1 — token purity and contract lint |
+| `cli/main.mjs` (`fractalstyler` bin) | consumer scaffolds: `npx @fractaldesign/fractalstyler init\|eject\|lint` — track or eject the styles, place these docs into a project, wire the VS Code extension |
+
+`pnpm registry` runs the first two; `pnpm browser` regenerates the browser
+page; `pnpm check` runs the validator and the contract linter. Consumers get
+the same registry builder after `eject` as `scripts/build-registry.mjs`.

package/docs/references/configurations.md

@@ -0,0 +1,258 @@
+---
+title: Configurations
+description: How the styling system is configured — the Sass source variables, the token mixins, and the loop-generated class families, file by file, with edit recipes and pitfalls.
+type: fractalstyler
+---
+
+# Configurations — how `src/lib/styles` is wired
+
+> Companion to [`configurations-api.md`](configurations-api.md) (the *what* —
+> every variable, token, attribute and class, verbatim).
+> This document is the *why* and *how to edit*: what each partial owns, what
+> each `$` variable in `_00_config.sass` drives, and what you must touch
+> together when you change one of them.
+
+## Golden rule for this whole document
+
+**The `.sass` partials are the configuration.** There is no settings file, no
+preset registry, no theme JSON — a "config change" is an edit to
+`_00_config.sass` (loops and maps), `_00_tokens.sass` (tokens and mode
+mixins), or a layer partial (classes), followed by regeneration:
+
+```bash
+pnpm registry    # update-registry.js + class-vocab.js → registry.json, REGISTRY.md, docs, skill refs
+pnpm lint        # token purity + contract lint
+pnpm check       # validate-deck.js + svelte-check
+```
+
+Never edit the generated surfaces (`registry.json`, `REGISTRY.md`,
+`docs/REGISTRY.api.md`, `docs/browser.html`, `dist/css/*`,
+`skills/fractal-styler/references/*.md`) — they are overwritten on the next
+run, by design.
+
+## Overview
+
+### Three moving parts
+
+1. **`_00_config.sass`** — Sass variables (`$steps`, the family maps,
+   `$frame-ratios`, `$breakpoints`, `$shadow-specs`). The loop half of the
+   class system is *generated* from these.
+2. **`_00_tokens.sass`** — CSS custom properties: two colour-mode mixins
+   (`=light-theme-tokens` / `=dark-theme-tokens`, applied by
+   `[data-mode='light']` / `[data-mode='dark']`) plus one mode-independent
+   `:root` block (type, space, radius, motion, control metrics, page chrome).
+3. **The layer partials** (`_01`…`_09`) — hand-authored classes. Every class
+   rides a token; literals exist only where a token cannot (1px hairlines,
+   aspect ratios, breakpoint px).
+
+`index.sass` composes them in cascade order: config and tokens first, then
+`_01`…`_09`. `colorpacks.sass` and `themeplates.sass` are raw Sass colour
+palettes consumed by hand-picked tokens; they emit no classes and no tokens
+and are never part of the class API.
+
+### Where to look while reading this doc
+
+| Task | File to open |
+|---|---|
+| Change what the loops generate (steps, families, frames, shadow specs) | `_00_config.sass` |
+| Change colours, add a colour role, dark mode | `_00_tokens.sass` |
+| Add a font face | `_00_fonts.sass` |
+| Add a spacing/radius/size utility | `_02_dimensions.sass` |
+| Add type roles/modifiers | `_03_typography.sass` |
+| Add a container or alignment rule | `_04_containers.sass` |
+| Add a grid/layout/frame/reel rule | `_05_layouts.sass` |
+| Add shell scaffolding | `_06_shells.sass` |
+| Add inputs/links/buttons | `_07_interactions.sass` |
+| Add backgrounds/ink/borders/shadows/visibility | `_08_visuals.sass` |
+| Project-specific extensions | `_09_own.sass` |
+
+---
+
+## 1. `_00_config.sass` — the loop generator
+
+### 1.1. `$steps` — the step vocabulary
+
+`('xs' 'sm' 'md' 'bs' 'lg' 'xl' '2xl' '3xl')` — eight steps. Every space
+family (gap, pad, mar and their sides) is crossed with this list by the
+`@each` loops in `_02_dimensions.sass`, so the entire L1 ladder is
+`17 families × 8 steps = 136 classes`.
+
+Editing it is a **two-file change**: a step without a matching
+`--space-<step>` token in `_00_tokens.sass` compiles, but every class for it
+points at an undefined `var()` — the declaration is dropped silently at
+computed-value time. A token without the step is dead weight (no classes).
+Change both, then run `pnpm registry`.
+
+### 1.2. The family maps — `$gap-families`, `$pad-families`, `$mar-families`
+
+Each map is `class prefix → CSS property`:
+
+```sass
+$gap-families: (gap: gap, rgap: row-gap, cgap: column-gap)
+$pad-families: (pad: padding, px: padding-inline, py: padding-block, pt: padding-top, pr: padding-right, pb: padding-bottom, pl: padding-left)
+$mar-families: (mar: margin, mx: margin-inline, my: margin-block, mt: margin-top, mr: margin-right, mb: margin-bottom, ml: margin-left)
+```
+
+`_02_dimensions.sass` does nothing but loop these maps over `$steps`. The
+`px`/`py`/`mx`/`my` keys are logical (inline/block — RTL-safe); the named
+sides (`pt`, `ml`, …) are physical. To add a family: add the map entry, and
+the classes compile on the next build — no other edit needed. To retire one:
+delete the entry and every class it generated disappears from the compiled
+CSS (grep your markup first).
+
+Note the naming drift this system retired: `.pad-x-*`/`.marg-*`/`.square-*`
+literal ladders and `-mob`/`-desk` responsive bands **do not exist** — the
+current families are the ones above, in one base band, all token-routed.
+
+### 1.3. `$frame-ratios` — aspect-ratio media boxes
+
+`('16-9': '16 / 9', …)` — key becomes the `.frame-<key>` suffix, value the
+`aspect-ratio` literal. `_05_layouts.sass` loops it: each `.frame-*` gets
+`aspect-ratio`, `overflow: hidden`, `position: relative`, and
+`img, video, iframe, svg` fill-and-cover rules. Add a ratio, get a class;
+that is the whole mechanism.
+
+### 1.4. `$breakpoints` — the named seams
+
+`(md: 768px, bs: 1024px, lg: 1280px)`. Consumed via `map.get` by
+`_06_shells.sass` for the rail visibility seams. **This is not the complete
+seam inventory**: `_05_layouts.sass` (grid stepping) and the `narrow-*`
+widths in `_06_shells.sass` hardcode `769px`/`1025px`/`1281px`/`1441px`
+literals. If you move a seam, move both the map entry and the literals —
+grep `min-width` / `max-width` across the partials before assuming the map
+is the only place a seam lives.
+
+### 1.5. `$shadow-specs` — the elevation ladder
+
+Eight steps of `(y1, b1, a1, y2, b2, a2)` pairs. The `:root` loop at the
+bottom of `_00_config.sass` composes each into a `--shade-<step>` token:
+`var(--shadow-rim)` + a tight key layer + a wide ambient layer. The header
+comment table (key alpha, ambient alpha, key blur, ambient blur per step) is
+the design intent — keep it in sync with the numbers.
+
+The `.shadow-*` **classes** do not read these — they read the
+`--shadow-<step>` channel tokens defined in the mode mixins of
+`_00_tokens.sass`. Two ladders, two jobs: `--shade-*` is the composed
+rim+key+ambient recipe, `--shadow-*` is the plain channel the utilities
+apply.
+
+---
+
+## 2. `_00_tokens.sass` — the token contract
+
+### 2.1. Colour modes are mixins, and `data-mode` is mandatory
+
+```sass
+=light-theme-tokens
+	--bg: #ffffff
+	…
+=dark-theme-tokens
+	--bg: #101010
+	…
+
+[data-mode='dark']
+	+dark-theme-tokens
+[data-mode='light']
+	+light-theme-tokens
+```
+
+The colour roles live **only** inside these mixins. Unlike the old system
+there is no marker-free light default: a page without a `data-mode`
+attribute on `<html>` has no colour tokens defined at all. Whatever renders
+the page (Svelte layout, static template) must stamp
+`data-mode="light"` or `data-mode="dark"`.
+
+### 2.2. The mode-independent `:root` block
+
+Everything else: `--font-sans` and the timeless stacks, `--text-scaling` plus
+the type rungs, `--unit-space` plus the space rungs, the six `--radius-*`
+channels, control/avatar/switch metrics, the motion language
+(`--speed*`, `--trans*`, `--motion*`), page chrome (`--header-height`,
+`--footer-height`, `--fit-height`, `--prose-clamp`, `--content-clamp`,
+`--app-inline`, `--card-min`, `--sidebar-width*`, `--z-*`), control heights
+and the pop colors.
+
+Known gap, kept honest: `.mono` reads `--font-mono`, which no partial defines
+yet — it falls back to the browser mono stack until a mono face lands in
+`_00_fonts.sass` and a `--font-mono` token is added here.
+
+### 2.3. Editing rules
+
+- **Add a colour role**: add it to *both* mixins (or deliberately to one —
+  see `--theme-color-sub`, light-only, and `--shadow-umbra`, dark-only — and
+  say so in a comment).
+- **Add a step token**: mirror `$steps` (see §1.1).
+- **Never** hardcode a hex or pixel in a layer partial that a token covers —
+  the lint (`lint/cli.mjs`) enforces token purity.
+
+---
+
+## 3. The layer partials (`_01`–`_09`) — what each owns
+
+| Partial | Layer | Owns | Conventions to keep |
+|---|---|---|---|
+| `_01_base.sass` | L0 | Element resets, view-transition defaults, `.bdr` | No classes beyond the debug outline and `.mode-wipe` |
+| `_02_dimensions.sass` | L1 | The three `@each` family loops, radius channels, full/zero sizing, `.h-*` control heights, viewport heights | Classes here are generated or one-liners; no component logic |
+| `_03_typography.sass` | L5 | `.text-*` primitives, semantic roles (`.page-title`, `.nav-link`…), `.lh*`, `.ls-*`, `.weight-*`, `.tt-*`, `.ta-*` (+`.mleft`), `.mono`, `.sans`, `.truncate` | Roles compose tokens; `.mleft` is the only media-query modifier |
+| `_04_containers.sass` | L2 | `.box`/`.row`/`.grid` + nested alignment modifiers, `.wrap`, `.grow`, `.shrink-0`, positions, `.scroll-y`/`.scroll-x`, `.card`, `.chip`, section wrappers | Alignment modifiers **nest under their base** — never standalone; x* is always the horizontal/inline axis, y* the vertical/block axis |
+| `_05_layouts.sass` | L3 | `.grid-1/2/3/4/6` (divisor stepping), `.cspan-*`, `.card-grid`, `.prose`, `.frame-*` loop, `.reel` | Grids are pure stepping — no default gap; compose `.gap-*`. The reel's `> *` is the system's one sanctioned child combinator (matched literally in `scripts/validate-deck.js`) |
+| `_06_shells.sass` | L4 | `.app-shell` canon, header/main/footer, role-bound rails, `.content-section` widths | Rails are display:none below their seam and resurrected by media queries — left rail becomes an off-canvas drawer via `.app-shell.open` below 1025px |
+| `_07_interactions.sass` | L5 | `.input`/`.select`, the link family, the `button` element base + its `data-variant`/`data-shape`/`data-size` axes, `a.primary`/`a.outline` | Buttons are styled via the bare `button` element plus attributes — there is no `.button` class |
+| `_08_visuals.sass` | L5 | Bare backgrounds, ink, status fills, the partition-law border set, `.shadow-*`, `.hide-mobile`/`.hide-desktop`, `.orange1`–`.orange6` | Bare dress before compositions; components own their own hover states — there is no standalone `.hover`/`.transition` |
+| `_09_own.sass` | Custom | The mascot families, `.hero-name`, the accordion, logotype bits | The sanctioned escape hatch; anything project-specific that cannot be expressed canonically |
+
+---
+
+## 4. Quick-edit cookbook
+
+**Add a spacing step** (e.g. a hypothetical `4xl`):
+1. `$steps` in `_00_config.sass` → append `'4xl'`.
+2. `--space-4xl` in `_00_tokens.sass` `:root` → define the value.
+3. `pnpm registry` — 17 new classes appear per family map.
+
+**Add a space family** (e.g. `.igap-*` for inline gaps):
+1. Add `igap: column-gap` to the right family map in `_00_config.sass`.
+2. Nothing else — the loop and the registry pick it up.
+
+**Add a frame ratio**:
+1. Add `'21-9': '21 / 9'` to `$frame-ratios`.
+2. `pnpm registry` — `.frame-21-9` compiles and is indexed.
+
+**Move a breakpoint seam**:
+1. Edit `$breakpoints` in `_00_config.sass`.
+2. Grep `min-width|max-width` in `_05_layouts.sass` and `_06_shells.sass` for
+   hardcoded literals (769/1025/1281/1441) and move them together.
+
+**Add a colour role**:
+1. Add the token to `=light-theme-tokens` **and** `=dark-theme-tokens` in
+   `_00_tokens.sass`.
+2. If it needs a class: bare one-liner in `_08_visuals.sass`
+   (`.text-<role>` / `.bg-<role>`), following the existing rows.
+
+**Add any other class**:
+1. Put it in the partial that owns its layer (see §3) — never invent a new
+   partial without approval.
+2. Document it with a trailing `// …` on the selector line — that comment is
+   what `scripts/update-registry.js` lifts into the registry description.
+3. `pnpm registry && pnpm lint && pnpm check`.
+
+---
+
+## 5. Pitfalls that have bitten before
+
+- **A `$steps` entry without its token** compiles clean and silently emits
+  classes that do nothing (undefined `var()`). Always change both files.
+- **Editing generated files** (`registry.json`, `REGISTRY.md`,
+  `docs/REGISTRY.api.md`) — overwritten on the next `pnpm registry`.
+- **Assuming `$breakpoints` is the whole seam story** — the grid and
+  narrow-width literals live outside the map.
+- **Expecting a marker-free light mode** — colour tokens only exist under a
+  `data-mode` attribute; no attribute means no colours.
+- **Naming drift**: `.pad-x-*`, `.marg-*`, `.square-*`, `.radius-0`,
+  `-mob`/`-desk` bands and negative-margin classes are gone. The living
+  vocabulary is `.pad`/`.px`/`.py`/`.pt`/`.pr`/`.pb`/`.pl`,
+  `.mar`/`.mx`/`.my`/`.mt`/`.mr`/`.mb`/`.ml`, the six radius channels — all
+  across the eight steps.
+- **A child combinator** (`> *`) anywhere but the reel trips
+  `scripts/validate-deck.js`. That guard is deliberate; a second exception
+  should be a conscious edit there.

package/lint/browser.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// =============================================================================
+// fractalstyler browser — interactive styling classes registry browser.
+//
+// Opens the class registry as a searchable, zero-dependency browser page.
+// Usage:
+//   node lint/browser.mjs           # opens in default browser
+//   node lint/browser.mjs --out <f> # writes HTML to specific file
+// =============================================================================
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { renderBrowserHtml } from '../scripts/class-vocab.js';
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const REGISTRY_PATH = path.join(PKG_ROOT, 'registry.json');
+
+function usage() {
+	console.log(`Usage:
+  fractalstyler browser [dir]     # open registry browser
+Options:
+  --registry <f>  registry.json override
+  --out <file>    write HTML to file instead of opening`);
+}
+
+function openInBrowser(file) {
+	const opener =
+		process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+	const args = process.platform === 'win32' ? ['/c', 'start', '', file] : [file];
+	try {
+		execFileSync(opener, args, { stdio: 'ignore' });
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function main() {
+	const args = process.argv.slice(2);
+	let out;
+	let registryOverride;
+
+	for (let i = 0; i < args.length; i++) {
+		if (args[i] === '--out') out = args[++i];
+		else if (args[i] === '--registry') registryOverride = args[++i];
+		else if (args[i] === '--help' || args[i] === '-h') {
+			usage();
+			process.exit(0);
+		}
+	}
+
+	const regFile = registryOverride ? path.resolve(registryOverride) : REGISTRY_PATH;
+	if (!fs.existsSync(regFile)) {
+		console.error(`Registry file not found at: ${regFile}. Run "pnpm registry" first.`);
+		process.exit(1);
+	}
+
+	const data = JSON.parse(fs.readFileSync(regFile, 'utf8'));
+	const html = renderBrowserHtml(data);
+
+	const target = out ? path.resolve(out) : path.join(os.tmpdir(), `fractalstyler-browser-${process.pid}.html`);
+	fs.writeFileSync(target, html, 'utf8');
+
+	if (out) {
+		console.log(`✔ Registry browser page written to: ${target}`);
+		return;
+	}
+
+	console.log(`✔ Registry: ${regFile}`);
+	console.log(`✔ Opening browser page: ${target}`);
+	if (!openInBrowser(target)) {
+		console.log(`Open file in your browser: file://${target}`);
+	}
+}
+
+main();