@stnd/styles 0.5.2 → 0.5.3

package/_standard-02-color.scss

@@ -1,5 +1,42 @@
 @use "standard-00-variables" as *;
 
+/**
+ * @component Color System
+ * @category Foundation
+ * @description Seed-first OKLCH color engine. Set one thing — your light
+ * foreground color — and a full light/dark palette, ten semantic hues, and
+ * a shadow/elevation scale all derive from it via `oklch(from <seed> ...)`
+ * relative color syntax. Override at three depths: set `--color-light-foreground`
+ * alone (everything else follows); set individual `--color-light-*` /
+ * `--color-dark-*` tokens for per-scheme control; or theme fully via
+ * `[data-theme]` selectors, which re-resolve the whole token set at any
+ * element, not just `:root`.
+ *
+ * @property --color-light-foreground The primary light foreground seed. Change this alone and dark mode, all ten chromatic hues, and derived surfaces/borders/shadows follow.
+ * @property --color-light-background The root light background seed (default `white`).
+ * @property --color-dark-foreground Derived dark reading foreground (default ~85% lightness matching foreground hue).
+ * @property --color-dark-background Derived dark background (default ~20% lightness matching foreground hue).
+ * @property --color-background Active scheme background token.
+ * @property --color-foreground Active scheme foreground token.
+ * @property --color-accent Active accent color token (defaults to triadic +120°).
+ * @property --color-border Active border color token.
+ * @property --color-surface Active elevated surface background.
+ * @property --color-muted Active muted text color (~60% opacity).
+ * @property --color-subtle Active subtle UI text color (~40% opacity).
+ * @property --color-link Semantic link color token.
+ * @property --color-success Semantic success status color (`--color-green`).
+ * @property --color-warning Semantic warning status color (`--color-orange`).
+ * @property --color-error Semantic error status color (`--color-red`).
+ * @property --color-info Semantic info status color (`--color-blue`).
+ * @property --color-light Polarity alias resolving to the lighter tone of the active scheme.
+ * @property --color-dark Polarity alias resolving to the darker tone of the active scheme.
+ * @property --shadow Primary ambient shadow preset.
+ * @property .theme-light Forces light token set and color scheme on any subtree.
+ * @property .theme-dark Forces dark token set and color scheme on any subtree.
+ * @property .inverse Flips scheme to whichever mode is not currently active.
+ * @property [data-color-mode] Attribute forcing `"light"` or `"dark"` scheme mode.
+ */
+
 /* ==========================================================================
    STANDARD COLOR SYSTEM — Seed-First Architecture
 
@@ -42,18 +79,15 @@
   /* Tell browser we support both color schemes */
   color-scheme: light dark;
 
-  /* ===================================================================
-     STAGE 1: DARK SEED DERIVATION
-     The ink's soul carries into darkness.
-     Both dark seeds inherit hue from the light foreground — warm brown
-     ink begets a warm dark background and a warm soft foreground.
-     Themes override --color-dark-background / --color-dark-foreground
-     at [data-theme] specificity for a distinct dark mood.
-
-     Light fg #442f1c  →  oklch(0.30, 0.07, H≈60)  warm brown ink
-     Dark bg  derived  →  oklch(0.20, 0.02, H≈60)  same hue, very dark, muted
-     Dark fg  derived  →  oklch(0.85, 0.04, H≈60)  same hue, soft reading brightness
-     =================================================================== */
+  /**
+   * @component Dark Seed Derivation
+   * @category Foundation
+   * @description Both dark seeds inherit hue from the light foreground seed.
+   * Warm ink begets a warm dark background and a warm soft reading foreground.
+   *
+   * @property --color-dark-background Dark background matching foreground hue at ~20% lightness and muted chroma.
+   * @property --color-dark-foreground Dark foreground matching foreground hue at ~85% lightness for soft reading brightness.
+   */
 
   /* Dark background: foreground's hue at very low lightness, muted chroma */
   --color-dark-background: oklch(
@@ -71,17 +105,27 @@
       /* same hue — the vibe persists */
   );
 
-  /* ===================================================================
-     STAGE 2: LIGHT PALETTE
-     Full spectrum generated from light foreground seed via inline
-     relative color syntax. Each color is a self-contained transform:
-       oklch(from <seed> <safe-L> <safe-C> calc(h + offset))
-
-     Channel keywords l, c, h resolve inside the function scope.
-     No extraction into intermediate custom properties needed.
-     Safety: clamp(0.65, l, 0.70) for bright vibrant tones, max(0.12, c) for saturation.
-     Achromatic seeds (h = none) → none treated as 0 in calc() per spec.
-     =================================================================== */
+  /**
+   * @component Light Palette
+   * @category Foundation
+   * @description Full 10-hue chromatic spectrum generated from light foreground seed via inline relative color syntax.
+   *
+   * @property --color-light-red Error / Red (+25° hue offset).
+   * @property --color-light-orange Attention / Orange (+55° hue offset).
+   * @property --color-light-yellow Warning / Yellow (+85° hue offset).
+   * @property --color-light-green Success / Green (+145° hue offset).
+   * @property --color-light-cyan Info / Cyan (+190° hue offset).
+   * @property --color-light-blue Link / Blue (+240° hue offset).
+   * @property --color-light-magenta Magic / Magenta (+300° hue offset).
+   * @property --color-light-purple Purple (+270° hue offset).
+   * @property --color-light-pink Pink (+350° hue offset).
+   * @property --color-light-brown Brown (+60° hue offset).
+   * @property --color-light-accent-complementary Complementary accent (+180°).
+   * @property --color-light-accent-analogous Analogous accent (+30°).
+   * @property --color-light-accent-triadic Triadic accent (+120°).
+   * @property --color-light-accent-auto Default accent strategy (triadic).
+   * @property --color-light-accent Active light mode accent color.
+   */
 
   /* Error / Red — foreground hue + 25° */
   --color-light-red: oklch(
@@ -162,14 +206,27 @@
   --color-light-accent-auto: var(--color-light-accent-triadic);
   --color-light-accent: var(--color-light-accent-auto);
 
-  /* ===================================================================
-     STAGE 2B: DARK PALETTE
-     Full spectrum generated from dark foreground seed.
-     NOT a simple lightening of the light palette — independent vibe.
-     A warm dark-foreground seed gives warm darks. A cool one gives
-     cool darks. Two different seeds, two different moods.
-     Safety: clamp(0.55, l, 0.70) for softer tones on dark surfaces.
-     =================================================================== */
+  /**
+   * @component Dark Palette
+   * @category Foundation
+   * @description Full 10-hue chromatic spectrum generated from dark foreground seed for comfortable dark surfaces.
+   *
+   * @property --color-dark-red Dark mode red (+25° hue offset).
+   * @property --color-dark-orange Dark mode orange (+55° hue offset).
+   * @property --color-dark-yellow Dark mode yellow (+85° hue offset).
+   * @property --color-dark-green Dark mode green (+145° hue offset).
+   * @property --color-dark-cyan Dark mode cyan (+190° hue offset).
+   * @property --color-dark-blue Dark mode blue (+240° hue offset).
+   * @property --color-dark-magenta Dark mode magenta (+300° hue offset).
+   * @property --color-dark-purple Dark mode purple (+270° hue offset).
+   * @property --color-dark-pink Dark mode pink (+350° hue offset).
+   * @property --color-dark-brown Dark mode brown (+60° hue offset).
+   * @property --color-dark-accent-complementary Dark complementary accent (+180°).
+   * @property --color-dark-accent-analogous Dark analogous accent (+30°).
+   * @property --color-dark-accent-triadic Dark triadic accent (+120°).
+   * @property --color-dark-accent-auto Default dark accent strategy.
+   * @property --color-dark-accent Active dark mode accent color.
+   */
 
   /* Error / Red — dark foreground hue + 25° */
   --color-dark-red: oklch(
@@ -246,10 +303,25 @@
   /* On-accent (text drawn on accent surfaces) */
   --color-dark-on-accent: var(--color-dark-background);
 
-  /* ===================================================================
-     STAGE 2C: COMPUTED PALETTES
-     Always available for explicit "light-in-dark" or "dark-in-light" UI.
-     =================================================================== */
+  /**
+   * @component Computed Palettes
+   * @category Foundation
+   * @description Computed scheme-specific tints for muted text, subtle UI elements, borders, and shadows.
+   *
+   * @property --color-light-muted Light muted text color (~60% opacity).
+   * @property --color-light-subtle Light subtle text color (~40% opacity).
+   * @property --color-light-border Light border color (~10% opacity).
+   * @property --color-light-surface Light surface background (3% foreground mixed with background).
+   * @property --color-light-on-accent Text color drawn on light accent backgrounds.
+   * @property --color-dark-muted Dark muted text color (~65% opacity).
+   * @property --color-dark-subtle Dark subtle text color (~45% opacity).
+   * @property --color-dark-border Dark border color.
+   * @property --color-dark-surface Dark surface background.
+   * @property --color-light-shadow-base Base shadow seed for light mode.
+   * @property --color-light-highlight Base specular highlight for light mode.
+   * @property --color-dark-shadow-base Base shadow seed for dark mode.
+   * @property --color-dark-highlight Base specular highlight for dark mode.
+   */
 
   /* Light Computed Palette */
   --color-light-muted: oklch(from var(--color-light-foreground) l c h / 0.6);
@@ -293,12 +365,32 @@
     from var(--color-dark-foreground) min(1, calc(l + 0.05)) c h / 0.11
   );
 
-  /* ===================================================================
-     STAGE 3: SEMANTIC TOKENS (Default → Light Palette)
-     These are the tokens components actually consume.
-     Never reference --color-light-* or --color-dark-* in components.
-     Always use --color-red, --color-background, etc.
-     =================================================================== */
+  /**
+   * @component Semantic Tokens
+   * @category Foundation
+   * @description Semantic color tokens consumed across all components and styles.
+   *
+   * @property --color-background Active scheme root background.
+   * @property --color-foreground Active scheme text foreground.
+   * @property --color-accent Active scheme primary accent color.
+   * @property --color-header Heading text color.
+   * @property --color-red Semantic red hue.
+   * @property --color-orange Semantic orange hue.
+   * @property --color-yellow Semantic yellow hue.
+   * @property --color-green Semantic green hue.
+   * @property --color-cyan Semantic cyan hue.
+   * @property --color-blue Semantic blue hue.
+   * @property --color-magenta Semantic magenta hue.
+   * @property --color-purple Semantic purple hue.
+   * @property --color-pink Semantic pink hue.
+   * @property --color-brown Semantic brown hue.
+   * @property --color-success Status color for success states (`--color-green`).
+   * @property --color-warning Status color for warnings (`--color-orange`).
+   * @property --color-error Status color for errors (`--color-red`).
+   * @property --color-info Status color for informative notices (`--color-blue`).
+   * @property --color-link Active scheme link color.
+   * @property --color-on-accent Text color for elements over accent backgrounds.
+   */
   --color-background: var(--color-light-background);
   --color-foreground: var(--color-light-foreground);
   --color-accent: var(--color-light-accent);
@@ -331,11 +423,20 @@
      variants in all three dark-mode contexts, plus added missing
      non-OKLCH fallbacks. */
 
-  /* ===================================================================
-     STAGE 4: COMPUTED SEMANTIC COLORS
-     Derived from the scheme-aware --color-foreground/--color-background.
-     auto-adapt when the scheme switches.
-     =================================================================== */
+  /**
+   * @component Computed Semantics
+   * @category Foundation
+   * @description Scheme-aware computed colors derived from active foreground and background seeds.
+   *
+   * @property --color-muted Secondary text color (~60% alpha).
+   * @property --color-subtle Tertiary text and decorative icon color (~40% alpha).
+   * @property --color-border Standard structural border color (~10% alpha).
+   * @property --color-surface Elevated surface and card background.
+   * @property --color-light Polarity alias resolving to lighter color of active scheme.
+   * @property --color-dark Polarity alias resolving to darker color of active scheme.
+   * @property --color-darker Dark overlay tint.
+   * @property --color-glass Frosted glassmorphism background color (~80% alpha).
+   */
   --color-muted: var(--color-light-muted);
   --color-subtle: var(--color-light-subtle);
   --color-border: var(--color-light-border);
@@ -348,43 +449,25 @@
 
   --color-glass: oklch(from var(--color-background) l c h / 0.8);
 
-  /* ===================================================================
-     STAGE 5: SHADOWS & SURFACES
-     OKLCH-based for perceptually uniform elevation.
-     All derived from semantic pointers — auto-adapt to dark mode.
-     =================================================================== */
+  /**
+   * @component Surfaces & Elevation Colors
+   * @category Foundation
+   * @description Semantic elevation color seeds and surface hierarchy using perceptual OKLCH color spaces.
+   *
+   * @property --color-shadow Active base shadow color.
+   * @property --color-highlight Active specular highlight color.
+   * @property --color-surface-lowest Deepest recessed surface step.
+   * @property --color-surface-lower Sub-surface step mixed with transparency.
+   * @property --color-surface-low Low elevation surface step.
+   * @property --color-surface Base surface color.
+   * @property --color-surface-high Elevated surface step.
+   * @property --color-surface-highest Highest surface elevation step.
+   */
 
   /* Semantic Shadow Seeds */
   --color-shadow: var(--color-light-shadow-base);
   --color-highlight: var(--color-light-highlight);
 
-  /* Shadow building blocks — compose freely */
-  --shadow-ambient: 0 1px 1px var(--color-shadow); /* Felt more than seen */
-
-  /* This one pop a bit */
-  --shadow-lift:
-    0 4px 6px -1px var(--color-shadow), 0 2px 4px -2px var(--color-shadow);
-  /* Organicaly grows */
-  --shadow-glow: 0 4px var(--space) oklch(from var(--color-shadow) l c h / 0.15);
-  --shadow-inset:
-    inset 0 1px 3px var(--color-shadow), inset 0 -1px 0 0 var(--color-highlight);
-  --shadow-ring:
-    inset 0px 1px 1px var(--color-border),
-    inset 1px 0px 1px var(--color-border),
-    inset -1px 0px 1px var(--color-border),
-    inset 0px -1px 1px var(--color-border);
-
-  /* shadcn-style raised effect: inner highlight + border + shadow */
-  --shadow-raised:
-    inset 0 1px 0 0 var(--color-highlight), 0 0 0 1px var(--color-border),
-    var(--shadow-ambient);
-
-  /* Composed presets. Fixed 2026-07-14 — was accidentally doubled, now
-     matches the --shadow-lg/-xl progressive pattern (one layer). */
-  --shadow: var(--shadow-ambient);
-  --shadow-lg: var(--shadow-ambient), var(--shadow-lift);
-  --shadow-xl: var(--shadow-ambient), var(--shadow-lift), var(--shadow-glow);
-
   /* Surface elevation scale */
   --color-surface-low: color-mix(
     in srgb,
@@ -409,13 +492,23 @@
     var(--color-surface-high)
   );
   --color-surface-higher: color-mix(in srgb, white 50%, transparent);
-  /* ===================================================================
-     STAGE 6: DESIGN TOKENS (Border Shorthands)
-     =================================================================== */
+  /**
+   * @component Border Shorthands
+   * @category Foundation
+   * @description Pre-composed border shorthand tokens for clean layout boundaries.
+   *
+   * @property --border Standard border shorthand (`var(--stroke-width) solid var(--color-border)`).
+   * @property --border-accent Tinted accent border shorthand (`var(--stroke-width) solid oklch(...)`).
+   * @property --border-transparent Transparent layout placeholder border.
+   */
   --border-transparent: var(--stroke-width) solid transparent;
   --border-accent: var(--stroke-width) solid
     oklch(from var(--color-accent) l c h / 0.07);
-  --border: none;
+  /* Regressed to `0 solid transparent` at some point, then a prior audit
+     correctly flagged it as dead code but "fixed" it to `none` instead of
+     restoring the real value. Git history confirms the intended value —
+     unchanged across many commits before the regression — was this. */
+  --border: var(--stroke-width) solid var(--color-border);
 }
 
 /* =====================================================================
@@ -494,10 +587,19 @@
   }
 }
 
-/* =====================================================================
-   STAGE 7B: THEME UTILITIES (.inverse, .theme-dark, .theme-light)
-   Provides explicit control and local context switching.
-   ===================================================================== */
+/**
+ * @component Theme Classes & Mixins
+ * @category Foundation
+ * @description Utilities and classes for forcing color modes and contextual inversion on subtrees.
+ *
+ * @property .theme-light Forces light color scheme and tokens on the applied container.
+ * @property .theme-dark Forces dark color scheme and tokens on the applied container.
+ * @property .inverse Contextually inverts color scheme relative to current background mode.
+ * @property [data-theme] Scoped theme attribute allowing local theme switching on cards or panels.
+ * @property [data-color-mode] Attribute setting explicit `"light"` or `"dark"` mode.
+ * @property @mixin theme-light-tokens Mixin stamping active light palette tokens into a selector.
+ * @property @mixin theme-dark-tokens Mixin stamping active dark palette tokens into a selector.
+ */
 
 @mixin theme-light-tokens {
   --color-background: var(--color-light-background);

package/_standard-03-typography.scss

@@ -6,6 +6,27 @@
  * @description Fine-art typography system using variable fonts, OpenType features,
  * and mathematical scaling. Implements classical typography rules with modern web capabilities.
  * Supports multiple font families, optical sizing, and locale-specific rules.
+ *
+ * @property --font-sans Sans-serif font stack (`"Inter", "Instrument Sans Variable", system-ui, -apple-system, sans-serif`).
+ * @property --font-serif Serif font stack (`"Source Serif 4", "Newsreader", "Instrument Serif", serif`).
+ * @property --font-monospace Monospace font stack (`"IBM Plex Mono", ui-monospace, monospace`).
+ * @property --font-text Semantic body font family (defaults to `--font-sans`).
+ * @property --font-header Semantic heading font family (defaults to `"Inter"`).
+ * @property --font-interface Semantic UI font family (defaults to `--font-sans`).
+ * @property --font-inter-feature OpenType stylistic feature set for Inter font.
+ * @property --font-instrument-feature OpenType stylistic feature set for Instrument Sans.
+ * @property --font-weight Normal text font weight (`400`).
+ * @property --font-weight-bold Bold text font weight (`600`).
+ * @property --font-header-weight Heading font weight anchor (`700`).
+ * @property --font-weight-h1 Level 1 heading weight.
+ * @property --font-weight-h2 Level 2 heading weight.
+ * @property --font-weight-h3 Level 3 heading weight.
+ * @property --font-weight-h4 Level 4 heading weight.
+ * @property --font-weight-h5 Level 5 heading weight.
+ * @property --font-weight-h6 Level 6 heading weight.
+ * @property --font-letter-spacing Body letter spacing default (`normal`).
+ * @property --font-header-letter-spacing Heading letter spacing default (`normal`).
+ * @property --list-indent Default list item indentation (`var(--space)`).
  */
 
 #{$stnd-theme-scope} {
@@ -38,7 +59,11 @@
   --font-weight-bold: 600;
   --font-letter-spacing: normal;
   --font-header-letter-spacing: normal;
-  --font-header-line-height: 1;
+  /* Intentionally unset: leaving this undefined lets grid-line-height()'s
+     per-level $tightness (h1 1.05, h2/h3 1.15, h4-6 1.3) act as the real
+     default. A theme or note can still override by setting this explicitly —
+     but defining it here to a literal value would shadow every level's
+     tightness with the same number, which is the bug this avoids. */
   --font-header-weight: 700;
 
   /* Interface Tokens */
@@ -146,7 +171,23 @@ h6 {
   line-height: var(--line-height);
 }
 
-/* Typography Patterns */
+/**
+ * @component Typography Elements & Patterns
+ * @category Typography
+ * @description Headings, inline styling, small-caps overlines, keycaps, marks, and blockquotes.
+ *
+ * @property .overline Small-caps letterspaced kicker label with top border rule.
+ * @property .bold Strong bold text weight utility.
+ * @property .menu UI interface font role application.
+ * @property .ui UI interface font role application.
+ * @property .interface UI interface font role application.
+ * @property .font-interface Explicit interface font family utility.
+ * @property .font-mono Monospace font family utility.
+ * @property mark Highlight mark element with optical trim padding and theme tinting.
+ * @property kbd Keyboard keycap with raised shadow and monospace font.
+ * @property a:hover Color and underline accent transition for hyperlinks.
+ * @property a[target="_blank"] External link with automatic arrow indicator (`↗`).
+ */
 .overline {
   font-variant-caps: small-caps;
   letter-spacing: 0.04em;
@@ -231,67 +272,11 @@ pre,
   font-variation-settings: var(--font-monospace-variation);
 }
 
-.stnd-code-block {
-  position: relative;
-  background: var(--color-surface-low);
-  border-radius: var(--radius-sm);
-  box-shadow: var(--shadow-inset), var(--shadow-ring);
-  transition: all var(--transition);
-
-  pre {
-    margin: 0 !important;
-    background: transparent !important;
-    box-shadow: none !important;
-    border: none !important;
-    padding: var(--space-d2);
-    overflow-x: auto;
-    position: static;
-  }
-
-  &:hover .copy-button {
-    opacity: 1;
-  }
-}
-
-.copy-button {
-  position: absolute;
-  top: var(--leading);
-  right: var(--leading);
-  opacity: 0;
-
-  &:hover {
-    opacity: 1 !important;
-    color: var(--color-on-accent);
-    background-color: var(--color-accent);
-  }
-
-  &.copied {
-    color: var(--color-success, #22c55e) !important;
-  }
-
-  &.failed {
-    color: var(--color-error, #ef4444) !important;
-  }
-}
-
-pre {
-  line-height: var(--line-height-compact);
-
-  code {
-    opacity: 0.75;
-    transition: opacity var(--transition);
-  }
-
-  &:hover code {
-    opacity: 1;
-  }
-}
-
 blockquote {
   font-style: italic;
   color: var(--color-muted);
   padding: var(--space);
-  border-left: var(--stroke-width-l) solid var(--color-border);
+  border-left: var(--stroke-width-lg, 2px) solid var(--color-border);
 
   cite {
     display: block;
@@ -300,7 +285,7 @@ blockquote {
   }
 }
 
-/* Utilities */
+/* Utilities & Inline Elements */
 small {
   font-size: var(--size-sm);
 }
@@ -326,77 +311,54 @@ em {
   font-style: italic;
 }
 
+/* Mark highlighting */
+mark {
+  background: oklch(from var(--color-yellow) l c h / 0.3);
+  color: color-mix(in oklch, var(--color-yellow) 30%, var(--color-foreground));
+  padding: var(--trim);
+  padding-top: 0.1em;
+}
+
+/* Keycaps */
+kbd {
+  background-color: var(--color-surface);
+  background-image: var(--effect-grain);
+  border: none;
+  border-radius: var(--radius);
+  box-shadow: var(--shadow-raised);
+  padding: var(--space-d6) var(--space-d3);
+  font-family: var(--font-monospace);
+  font-size: var(--size-xs);
+  pointer-events: none;
+}
+
 /**
- * @component Design Tokens
- * @category Foundation
- * @description Primitive design tokens forming the foundation of the design system.
- * Includes "Self-Aware" fluid typography that scales based on the Optical Ratio.
+ * @component Heading Rhythm & Grid Snapping
+ * @category Typography
+ * @description Half-baseline rhythm snapping mixin for heading hierarchy.
  *
- * This block redeclares --font-size and --line-height, silently superseding
- * the flat --font-size: 1rem set in _standard-01-token.scss (same selector,
- * this file loads later in standard.scss's @use order, so this wins) —
- * deliberate layering (naive default → fluid enhancement), not a conflict,
- * but non-obvious without reading both files.
+ * @property @mixin grid-line-height Heading line-height mixin snapping leading to half-baseline rhythm increments.
  */
 
-#{$stnd-theme-scope} {
-  /* ===== 2. THE META-COGNITION (Fluid Slopes) =====
-     Instead of magic numbers, we use the Ratio to determine "Physics".
-
-     Slope: (Ratio - 1).
-     - Golden (0.618) -> steep slope (fast growth).
-     - Silver (0.414) -> moderate slope.
-  */
-  --physics-slope: calc(var(--optical-ratio) - 1);
-
-  /* Growth Factor: How aggressive is the resizing?
-     We multiply the slope by 1vw to create a viewport-relative unit. */
-  --fluid-growth: calc(var(--physics-slope) * 0.5vw);
-
-  /* Tension Factor: How much do we tighten leading as we grow?
-     Higher ratios need more tension to keep large text readable. */
-  --fluid-tension: calc(var(--physics-slope) * 0.3vw);
-
-  /* ===== 3. FLUID TYPOGRAPHY =====
-     Base size starts at 1rem and grows according to the Physics Slope.
-  */
-  --base-size: var(--font-text-size, 1rem);
-
-  --font-size: clamp(
-    var(--base-size),
-    calc(var(--base-size) + var(--fluid-growth)),
-    calc(var(--base-size) * 1.5)
-  );
-
-  /* ===== 4. FLUID LINE HEIGHT =====
-     This is the "Next Level" logic.
-     Start with the Optical Ratio as the base breathing room (in ems).
-     As the screen (and font) grows, SUBTRACT the Tension Factor.
-
-     Why? Large text (Desktop) needs TIGHTER leading than small text (Mobile).
-     A steep ratio (Golden) creates huge text, so it applies MORE tension.
-  */
-  --line-height: clamp(
-    1.15,
-    calc(var(--optical-ratio) - (var(--fluid-tension) / 1vw)),
-    1.65
-  );
-}
-
 @mixin grid-line-height($tightness: 1.1) {
   /* The "Target" is simply the font-size * tightness, unless a note
      overrides it via --font-header-line-height in frontmatter */
   --target-lh: calc(1em * var(--font-header-line-height, #{$tightness}));
 
-  /* The Snap: Force it to be a multiple of --baseline */
-  line-height: round(up, var(--target-lh), var(--baseline)) !important;
+  /* The Snap: force it to be a multiple of *half* a baseline, not a whole
+     one. Whole-baseline snapping wastes up to ~1 baseline in the worst case
+     (target just above a multiple) — brutal on smaller headings whose
+     font-size is close to or under one baseline (e.g. h2/h3). Half-baseline
+     halves that worst case while still landing on the page's rhythm every
+     two headings. */
+  line-height: round(up, var(--target-lh), calc(var(--baseline) / 2)) !important;
 
   /* Why 'up'?
      'nearest' might snap down and cause letters to clash.
      'up' ensures we always have *at least* enough room. */
 }
 
-/* Usage in your Header sizes */
+/* Usage in Header sizes */
 h1 {
   /* Giant text needs very tight leading (1.05x), then snap up */
   @include grid-line-height(1.05);

package/_standard-04-grid.scss

@@ -8,14 +8,18 @@
  * asymmetric layouts, gap variants (compact/normal/wide), and responsive column changes.
  * All gaps align to the vertical rhythm system.
  *
- * @prop {class} .grid 12-column grid container
- * @prop {class} .col-1 through .col-12 Column span modifiers (direct children of .grid)
- * @prop {class} .sm\:col-* Responsive columns at max-width 768px (mobile)
- * @prop {class} .lg\:col-* Responsive columns at min-width 1024px (desktop)
- * @prop {class} .start-{n} Start column position (1-12)
- * @prop {class} .grid.no-gap Removes row-gap
- * @prop {class} .grid.compact Compact gap (--trim)
- * @prop {class} .grid.relaxed Wide gap (--space)
+ * @property .grid 12-column Swiss-style responsive grid container with automatic column flow.
+ * @property .grid-row Grid container with row flow.
+ * @property .grid-{n} Explicit n-column grid container (1 to 12 columns).
+ * @property .col-{n} Column span modifiers (1 to 12 columns, direct children of .grid).
+ * @property .start-{n} Column start position (1 to 12).
+ * @property .grid.no-gap Removes grid row gap.
+ * @property .grid.compact Compact gap variant aligned to `--trim`.
+ * @property .grid.relaxed Relaxed gap variant aligned to `--space`.
+ * @property .sm:col-{n} Responsive column spans at mobile viewport (<=768px).
+ * @property .sm:grid-{n} Responsive column grid count at mobile viewport (<=768px).
+ * @property .lg:col-{n} Responsive column spans at desktop viewport (>=1024px).
+ * @property .lg:grid-{n} Responsive column grid count at desktop viewport (>=1024px).
  *
  * @example
  * // Basic 12-column grid with equal width columns

package/_standard-05-rhythm.scss

@@ -1,5 +1,27 @@
 @use "standard-00-variables" as *;
 
+/**
+ * @component Rhythm
+ * @category Layout
+ * @description Vertical rhythm for any container: apply `.rhythm` and its
+ * children get consistent `margin-block-start` spacing with no per-element
+ * classes, heavier before headings and around block-level elements
+ * (tables, blockquotes, figures — the tags this cascades to are declared
+ * once in `_standard-00-variables.scss`, not here). `.flex > *` is zeroed
+ * out automatically so rhythm margins never stack with flex `gap`.
+ *
+ * @property .rhythm The container class. Sets `display: flow-root` so child margins cannot collapse out of it.
+ * @property .no-rhythm Zeroes `margin-block-start` on every descendant — a subtree-wide rhythm opt-out.
+ * @property --gap-multiplicator Rhythm multiplier factor for block-level spacing and heading exceptions.
+ * @property .flex > * Zeroes `margin-block-start` for flex children so margins do not stack with flex gap.
+ *
+ * @example html - Turn any container into a rhythm block
+ * <article class="rhythm">
+ *   <h2>Heading</h2>
+ *   <p>Spaced automatically — no margin utility classes needed.</p>
+ * </article>
+ */
+
 /* ===== BULLETPROOF RHYTHM SYSTEM ===== */
 /* Applied to any container — cascades to children via margin-block-start */