@stnd/styles 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @stnd/styles
 
+## 0.5.2
+
+### Patch Changes
+
+- Mariage theme fix
+
 ## 0.5.0
 
 ### Minor Changes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Francis Fontaine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,16 +1,33 @@
 ---
 title: "@stnd/styles"
-status: active
+aliases: []
+created: 2026-07-04 23:27
+modified: 2026-07-05 19:16
+last_audited: 2026-07-14
+audit_interval_days: 90
+next_audit: 2026-10-12
+audit_priority: 3
 maturity: tree
-type: package
+mode: read
+publish: false
+status: active
 tags:
   - package
   - stnd
+theme: kernel
+type: package
+visibility: private
+---
+
+# @[stnd](../README)/styles
+
+> The CSS typography and design system framework for the Standard Ecosystem.
+
 ---
 
-# @stnd/styles
+This is the CSS. One seed color in, a whole harmonious palette out; one base font size in, a whole readable type scale out. You almost never touch this package directly — it’s on automatically (see `@stnd/modules/styles` in the Gold Standard). You touch it when you want to *change* the numbers behind the look (the golden-ratio scale, the OKLCH color math) rather than a specific theme’s colors (that’s `@stnd/themes`).
 
-The CSS typography and design system framework for the Standard Ecosystem.
+**You’re already using it.** Nothing to install or configure for a normal site.
 
 ## Overview
 
@@ -22,9 +39,9 @@ The CSS typography and design system framework for the Standard Ecosystem.
 
 The system rejects arbitrary pixel coordinates. All spacing, font scaling, and line heights are tied to three mathematical constants:
 
-*   **Golden Ratio** ($\phi \approx 1.618$): Governs structural widths, block margins, and main layout columns.
-*   **Silver Ratio** ($\theta \approx 1.414$): Governs the typographic scale and base vertical rhythm.
-*   **Halfstep** ($\sqrt{\phi} \approx 1.272$): Square root of the Golden Ratio, used for subheadings, margins, and inline gaps.
+- **Golden Ratio** ($\phi \approx 1.618$): Governs structural widths, block margins, and main layout columns.
+- **Silver Ratio** ($\theta \approx 1.414$): Governs the typographic scale and base vertical rhythm.
+- **Halfstep** ($\sqrt{\phi} \approx 1.272$): Square root of the Golden Ratio, used for subheadings, margins, and inline gaps.
 
 ---
 
@@ -49,12 +66,12 @@ Standard applies a strict modular font scale to prevent typographic clashes. Bod
 
 Vertical rhythm is managed through a base unit `--space` (usually $1\text{rem}$ / $16\text{px}$). Multiples and fractions are locked:
 
-*   **Standard Spacing (Multiples)**:
-    *   `--space-2`, `--space-4`, `--space-8`, `--space-12`
-*   **Sub-units (Fractions)**:
-    *   `--space-half` (0.5x), `--space-third` (0.33x), `--space-d4` (0.25x), `--space-d8` (0.125x)
+- **Standard Spacing (Multiples)**:
+    - `--space-2`, `--space-4`, `--space-8`, `--space-12`
+- **Sub-units (Fractions)**:
+    - `--space-half` (0.5x), `--space-third` (0.33x), `--space-d4` (0.25x), `--space-d8` (0.125x)
 
-Elements align to this grid through a strict rule: *the sum of an element's font-size, line-height, and margins must always be a multiple of `--space`.*
+Elements align to this grid through a strict rule: *the sum of an element’s font-size, line-height, and margins must always be a multiple of `--space`.*
 
 ---
 
@@ -74,9 +91,9 @@ Instead of hardcoding colors, the system generates complete color palettes dynam
 
 Specialized styling rules load automatically depending on document attributes:
 
-*   **Prose Mode** (`.prose`): Restricts reading width to an optimal measure ($\approx 65\text{ch}$) to prevent eye strain.
-*   **Dark Mode**: Evaluated via system settings (`prefers-color-scheme`) or overridden with the `.theme-dark` class.
-*   **E-Ink Mode** (`.standard-eink`): Strips out all transforms, blurs, and animations, switching colors to pure high-contrast black and white to prevent ghosting on e-readers.
+- **Prose Mode** (`.prose`): Restricts reading width to an optimal measure ($\approx 65\text{ch}$) to prevent eye strain.
+- **Dark Mode**: Evaluated via system settings (`prefers-color-scheme`) or overridden with the `.theme-dark` class.
+- **E-Ink Mode** (`.standard-eink`): Strips out all transforms, blurs, and animations, switching colors to pure high-contrast black and white to prevent ghosting on e-readers.
 
 ---
 
@@ -86,9 +103,11 @@ In your main SCSS stylesheet or Astro entry point:
 
 ```scss
 // Load standard variables and layouts
-import "@stnd/styles/standard.scss";
+@use "@stnd/styles/standard.scss";
 ```
 
+> Most apps never need this — the Gold Standard `@stnd/modules/styles` module injects the stylesheet automatically. Import it manually only when composing your own SCSS entry point.
+
 ### Style Files Anatomy
 - `standard.scss`: Framework index.
 - `_standard-01-token.scss`: Variable dictionary.
@@ -100,17 +119,91 @@ import "@stnd/styles/standard.scss";
 
 ---
 
-## What's next — open
-
-- [ ] **CSS framework audit / cleanup** — verify that everything is still up to our standard (the initial draft is old; a cleanup is likely possible).
+## Notes / Observations
+
+*(jot down anything noticed here — quirks, gotchas, ideas)*
+
+### Audit log (2026-07-14 → ongoing)
+
+File-by-file pass, adding WHY-comments and checking for cascade/scope bugs. Fixed vs. flagged-only noted per item.
+
+**Fixed:**
+- **`$stnd-scope: ":root, body"` silently blocked frontmatter overrides.**
+  A token declared on both `:root` and `body` always resolves to `body`'s   own copy for anything read by a non-inherited property at-or-below   `<body>` (its own `max-width`/`padding`) — inheritance never kicks in   because `body` already has an explicit declaration. Any `:root`-only   override (exactly what a note's frontmatter `inlineStyle` produces) was   silently ineffective for `--body-max-width`, `--line-width`,   `--gap-body`/`--gap-header`/`--gap-footer`. Root cause fixed at the   scope itself (`$stnd-scope` → `:root`-only) rather than patched   per-token. Caught via a live production repro on francisfontaine.com.
+- **`$stnd-scope` vs `$stnd-theme-scope`** — two SCSS variables, always set
+  to the identical selector in every build config (`:root` on web,   `body.stnd-theme` in Obsidian) since the fix above. Pure redundancy —   consolidated to one (`$stnd-theme-scope`, the more widely-used name).
+- **`$elements-boxed`** (`_standard-00-variables.scss`) — defined, never
+  consumed anywhere. Deleted.
+- **Duplicate `--ease-aggressive`** — identical value declared twice in
+  `_standard-01-token.scss`. Deleted the redundant copy.
+- **`$mobile` docblock drift** — comment claimed `480px`, actual value is
+  `600px` (confirmed correct). Comment fixed to match code.
+- **`obsidian.scss` docblock drift** — claimed tokens live "inside :root";
+  actually scoped to `body.stnd-theme` (deliberately, for namespacing in   Obsidian's shared window). Comment corrected.
+- **`body`'s own dead `--max-width` fallback** (`_standard-07-base.scss`)
+  — `max-width: var(--body-max-width, var(--max-width))`, left over from   *my own* `--max-width` removal earlier this session (missed this one   file at the time). `--body-max-width` always has a value, so the   fallback never fired — harmless, but stale. Now matches `.prose`'s   equivalent rule (`var(--body-max-width)`, no fallback).
+- **Garbled leftover comment** (`_standard-07-base.scss`) — a `[id]`
+  block's comment repeated the same incomplete CSS fragment   (`background: var(--color-surface-highest);`) four times, pure noise.   Replaced with an actual explanation of what `scroll-margin-top` there   is for (keeps anchor-linked headings clear of the sticky header).
+- **`.negate-body-padding*` docblock described a nonexistent API**
+  (`_standard-07-base.scss`) — those three class names, and the usage   example, don't match the real implementation (`.no-body-margin`, and   far more restrictive: only `<footer>`/`<header>` that are direct   children of `<body>` and first/last-of-type). Neither name is used   anywhere in `apps/` today, so nothing broke in practice, but the docs   would have misled whoever reached for it next. Rewrote to match reality.
+- **Duplicate identical `font-family` on `select`** (`_standard-11-forms.scss`)
+  — same line twice, zero behavior difference either way. Removed one.
+- **Stale file reference** (`_standard-12-code.scss`) — comment pointed to
+  `standard-98-utilities.scss`, which doesn't exist; real file is   `_standard-50-utilities.scss`. Corrected.
+- **`.bg-surface` defined three times, identically** (`_standard-50-utilities.scss`) — same declaration, zero behavior difference. Consolidated to one; verified the computed color is unchanged.
+
+**Fixed — round 2 (2026-07-14, same day, follow-up pass on everything round 1 had flagged):**
+Every flagged item below got fixed except three, which are real judgment calls and stayed open on purpose (see the next section). Grouped by file:
+- `_standard-01-token.scss`: `--z-launher` → `--z-launcher` (typo fixed; still unused, but spelled correctly).
+- `_standard-02-color.scss`: dark-mode purple/pink/brown now reassign to their `--color-dark-*` counterparts (in both the `prefers-color-scheme: dark` block and the `[data-color-mode="dark"]` blocks); added the missing Stage 8 non-OKLCH fallback hex for all three; deleted the dead `0 solid transparent` `--border` line (kept `none` — see deferred items, the *value* wasn't touched); collapsed `--shadow`'s duplicated `--shadow-ambient` layer to one.
+- `_standard-03-typography.scss`: `grid-line-height` mixin now reads `var(--font-header-line-height, ...)` instead of ignoring the token outright — headings actually respond to the frontmatter token now; deleted the dead hardcoded second `.font-interface` block.
+- `_standard-04-grid.scss`: deleted the dead `--grid-gap` copy of `.grid.compact`/`.relaxed`; replaced every `[class^="grid-"]`/`[class|="grid"]` attribute selector with an explicit, order-independent `$grid-selectors` list (confirmed fix against real markup: `apps/stnd.build/modules/core/routes/index.astro`'s `class="cover grid-12"`).
+- `_standard-06-prose.scss`: `.mycelial-graft` now uses real tokens (`--color-muted`, `--color-accent`, `--color-surface-high`); deleted the stale `h1:first-child` comment.
+- `_standard-07-base.scss`: mobile header padding-negation now sets `margin-block-start` (matching the desktop rule and the footer's symmetric block), not `margin-block-end`.
+- `_standard-08-media.scss`: deleted the dead `--gap-body` padding line on `.image-zoom-overlay`; hardcoded `768px` → `#{$small}`.
+- `_standard-09-lists.scss` / `_standard-50-utilities.scss`: removed all 5 dead `--base-gap` lines; `.display-flex` → `.flex` (the real class).
+- `_standard-10-tables.scss`: `min-height: var(--line-height)` (invalid, unitless) → `min-height: calc(1em * var(--line-height-compact))`.
+- `_standard-11-forms.scss`: `--color-on-cce` typo → `--color-on-accent`; deleted the flat `background` override that was silently killing "THE FILL MAGIC" slider gradient (confirmed live: `Slider.astro` sets `--slider-value` via JS), added a `50%` fallback to both gradient stops.
+- `_standard-13-components.scss`: deleted the pointless `@each $type` badge loop (zero effect on output); `--alert-border-color` → `--color-alert`.
+- `_standard-14-analog.scss`: hardcoded `z-index: 9999` → `var(--z-image-zoom)`.
+- `_standard-30-contrast.scss` / `_standard-32-eink.scss`: added `html::after` to both grain-hiding selector lists (the overlay actually lives there, not on `body::before/after`).
+- `_standard-31-print.scss`: dead `--body-padding` → real `--gap-body`/`--gap-header`/`--gap-footer` overrides.
+- `_standard-32-eink.scss`: added the missing `@use "standard-00-variables" as *;`; `.card, .button, .image` → `.card, :where(button), a.btn, img` (real selectors); `--text-accent` → `--color-accent`.
+- `_standard-50-utilities.scss`: `.line-s`/`.line-l`/`.columns-auto` → `--line-width-sm`/`--line-width-lg`; `.purple`/`.pink`/`.bg-purple`/`.bg-pink` → their real distinct tokens (no longer both rendering as magenta); `@supports not (display: grid)` fallback → `var(--gap)`; deleted the dead `[class|="columns"].compact`/`.relaxed` pair; removed dead `--color-msg` lines from all 4 alert variants.
+- `_standard-99-debug.scss`: `--gap-grid` (undefined) → `var(--gap)` everywhere (the debug overlay's own column math now actually works); `--z-tooltip` (undefined) → hardcoded `10000` matching the file's own baseline.
+
+All 17 files verified via a running dev server (both `stnd.gd` and `stnd.build`): zero compile errors, pixel-identical baseline screenshots, plus targeted computed-style spot-checks on the trickiest fixes (purple/pink/brown dark-mode switching, the grid attribute-selector fix against real production markup, the slider gradient rendering, `--font-header-line-height` genuinely driving heading line-height).
+
+**Flagged — deliberately left as judgment calls, not bugs to silently fix:**
+- **`--border` currently resolves to `none` sitewide** (`_standard-02-color.scss`) — affects cards, buttons, inputs, tables. The dead duplicate declaration is gone, but the final value was left alone: making it visible would be a real, sitewide visual design change (dozens of components), not a bug fix.
+- **`.rhythm`'s base 1x-spacing rule has no `>` combinator; every other rule in the same block does** (`_standard-05-rhythm.scss`) — applies at any nesting depth instead of direct children only. Left alone: adding `>` risks a real regression on nested content (e.g. a paragraph inside a `.callout` inside `.rhythm`) that's impossible to fully rule out without a visual pass over every place `.rhythm` is used.
+- **`.compact`/`.relaxed` are unnamespaced and collide across `_standard-09-lists.scss` and `_standard-50-utilities.scss`** — resolving this properly means renaming part of the framework's public class API, which is an architectural decision, not a mechanical fix.
+
+**Documented, not a bug:**
+- The `generate-scale` mixin's `"trim"`/`"leading"` scale keys (feeding `.mt-trim`, `.p-leading`, etc.) use `--size-2xs`/`--size-xs` — not the real `--trim`/`--leading` rhythm tokens that happen to share the same words. `.mt-trim` does not use `--trim`. A naming collision worth knowing about, not something to change.
+
+**Where the mechanism is real but the hook is currently unused:**
+- `--corner` (theme override for `--radius`) — documented, no theme sets
+  it yet. Not dead, just unclaimed.
+
+### How to keep this going
+
+Batches (see `packages/styles/*.scss`, foundation → layout → elements → components → modes → utilities): work through in dependency order, add WHY-comments for anything non-obvious, append findings above as they surface. Ask before silently fixing anything with real blast radius; docblock drift / dead code / pure redundancy are safe to just fix inline.
+
+**Gotcha for whoever writes the comments**: Sass block comments (`/* */`) are interpolation-aware — `#{$i}` (or any `#{...}`) written literally inside a comment, describing a `@for` loop's output, gets evaluated as real Sass and breaks the build with "Undefined variable" if that variable isn't in scope at the comment's location. Learned this the hard way auditing `_standard-04-grid.scss` (2026-07-14) — write `.grid-N`, not `.grid-#{$i}`, when a comment needs to describe generated class names.
+
+## Todo
+
+- [x] **CSS framework audit / cleanup** *(completed 2026-07-14 — all 8 batches, foundation through utilities/debug, plus a same-day round-2 fix pass — see Audit log above. ~15 items fixed inline during the audit itself, then ~33 more of the ~36 flagged findings fixed in round 2 (undefined/typo'd custom properties, dead code, the grid attribute-selector footgun, several "duplicate declaration silently kills the first" cases). 3 left as deliberate judgment calls (`--border`'s value, `.rhythm`'s missing `>` combinator, `.compact`/`.relaxed` naming collision) — real behavior/API changes, not obviously safe to auto-fix. Every edit verified against a running dev server on both `stnd.gd` and `stnd.build`; nothing here changed the site's actual rendered output except the two root-cause bugs fixed early on (the `:root, body` scope bug and its `--max-width` cleanup) and the intentional restorations listed above (e.g. `--font-header-line-height` and the slider gradient now actually work).)*
+- [ ] Feeds into the future theme creation/editing UX (see `@stnd/themes` Todo) — that UX will need to expose these tokens live. [priority:: 3] [token_scale:: 3] [created:: 2026-07-14] [area:: framework]
 
 ---
 
 ## 🔗 Liens & Normes
 
-Ce paquet de styles implémente la charte visuelle et les tokens de l'écosystème Standard. Pour plus de détails sur les spécifications graphiques et de code, consultez :
+Ce paquet de styles implémente la charte visuelle et les tokens de l’écosystème Standard. Pour plus de détails sur les spécifications graphiques et de code, consultez :
 - **Architecture Système** : [4.1 Architecture](../../apps/stnd.build/modules/manual/content/4-system/4.1-architecture.md)
 - **Principes de Code** : [4.2 Code Standards](../../apps/stnd.build/modules/manual/content/4-system/4.2-code-standards.md)
 - **Normes de Documentation** : [4.9 Normes README](../../apps/stnd.build/modules/manual/content/4-system/4.9-readme-standard.md)
-- **Pilier Central** : [STANDARD.md](../../STANDARD.md)
+- **Le Standard** : [packages/README.md](../README.md)
 - **Charte Graphique** : [3.1 Color System](../../apps/stnd.build/modules/manual/content/3-graphics/3.1-color-system.md) et [3.2 Typography](../../apps/stnd.build/modules/manual/content/3-graphics/3.2-typography-and-typefaces.md)

package/TOKENS.md

@@ -1,3 +1,15 @@
+---
+aliases: []
+created: 2026-03-16 08:07
+modified: 2026-07-03 16:26
+mode: read
+publish: false
+tags: []
+theme: 
+type: note
+visibility: private
+---
+
 # Standard Design Tokens
 
 > Canonical reference for all CSS custom properties exposed by `@stnd/styles`.
@@ -32,7 +44,6 @@ For example, `foreground: "#1a1a1a"` becomes `--foreground: #1a1a1a`. See `packa
 | `--leading`          | `calc((line-height - 1) * font-size)` | Space between cap-height and next baseline |
 | `--nl`               | `calc(leading * line-height)`         | Newline — full vertical unit               |
 | `--trim`             | `calc(leading / 2)`                   | Half-leading trim                          |
-| `--max-width`        | `1024px`                              | Maximum content width                      |
 | `--font-size-mobile` | `1.1rem`                              | Font size override on mobile               |
 
 ## Spacing Scale
@@ -83,10 +94,17 @@ Powered by `pow(var(--optical-ratio), N)`.
 | `--size-5xl`  | `--scale-7`  |
 | `--size-6xl`  | `--scale-8`  |
 
-## Line Widths
+## Layout Widths
+
+Two independent scopes. `.prose`'s own box reads `--body-max-width`
+directly, so `.hero`/`.full` breakout elements grow all the way to the page
+shell. `.feature` and tables/`.editorial` don't reference either width
+token — they break out by a fixed rhythm increment off `--line-width`
+(`--space-2` / `--space-4` each side).
 
 | Token               | Default                           | Description                                   |
 | ------------------- | --------------------------------- | --------------------------------------------- |
+| `--body-max-width`  | `900px`                           | The whole page shell — header, footer, content, and the ceiling `.hero`/`.full` grow into |
 | `--line-width-xs`   | `24rem`                           | Extra small                                   |
 | `--line-width-sm`   | `32rem`                           | Small                                         |
 | `--line-width-md`   | `42rem`                           | Medium (default reading width)                |

package/_standard-00-reset.scss

@@ -3,6 +3,10 @@
 /* =========================== */
 
 /* Disable view transition animations - instant page swaps
+   Superseded by the fade in/out ::view-transition-old(root) /
+   ::view-transition-new(root) rules in _standard-01-token.scss — kept here
+   commented out as the "instant, no animation" alternative if that fade
+   is ever reverted.
 ::view-transition {
   animation-duration: 0s !important;
 }
@@ -22,19 +26,48 @@
   scrollbar-width: thin;
 }
 
-/* 
+/*
  * Modern targeted reset (replaces the old `* { margin: 0; padding: 0 }`).
- * This prevents the framework from destroying the native margins/paddings of complex 
- * embedded editors (like CodeMirror/Obsidian) or third-party web widgets, while still 
+ * This prevents the framework from destroying the native margins/paddings of complex
+ * embedded editors (like CodeMirror/Obsidian) or third-party web widgets, while still
  * perfectly resetting the standard web typography and layout elements.
  */
-html, body, p, ol, ul, li, dl, dt, dd, blockquote, figure, fieldset, legend, textarea, pre, iframe, hr, h1, h2, h3, h4, h5, h6, img, span, a {
+:where(
+  html,
+  body,
+  p,
+  ol,
+  ul,
+  li,
+  dl,
+  dt,
+  dd,
+  blockquote,
+  figure,
+  fieldset,
+  legend,
+  textarea,
+  pre,
+  iframe,
+  hr,
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6,
+  img,
+  span,
+  a
+) {
   margin: 0;
   padding: 0;
   border: 0 solid;
 }
 
-button, input, select {
+button,
+input,
+select {
   margin: 0;
 }
 
@@ -54,6 +87,8 @@ object {
   display: block;
   vertical-align: middle;
 }
+/* inline-block, not block like img/video above — svgs are used inline
+   within text/buttons/icons far more often than as standalone media. */
 svg {
   display: inline-block;
   vertical-align: middle;
@@ -65,10 +100,16 @@ video {
   height: auto;
 }
 
+/* [hidden] forced off, but hidden="until-found" is deliberately excluded —
+   that's the browser's native find-in-page reveal mechanism (Ctrl/Cmd+F);
+   force-hiding it here would break the browser's ability to un-hide it. */
 [hidden]:where(:not([hidden="until-found"])) {
   display: none !important;
 }
 
+/* Browsers never render <script> content by default — this guards against
+   some other broad selector (a component lib, a CMS export) accidentally
+   setting display on everything and making inline script text visible. */
 script {
   display: none !important;
 }

package/_standard-00-variables.scss

@@ -5,7 +5,7 @@
  * vertical rhythm and spacing across all elements. These mixins ensure proper
  * spacing application for rhythm-aware components.
  *
- * @prop {variable} $mobile Mobile breakpoint (480px)
+ * @prop {variable} $mobile Mobile breakpoint (600px)
  * @prop {variable} $small Small screen breakpoint (768px)
  * @prop {variable} $large Large screen breakpoint (1024px)
  * @prop {variable} $wide Wide screen breakpoint (1440px)
@@ -30,14 +30,26 @@ $small: 768px;
 $large: 1024px;
 $wide: 1440px;
 
+// Text elements needing text-box-trim (removes leading/trailing font
+// ascender/descender space so line-height math lines up with the baseline
+// grid) — consumed once in _standard-01-token.scss's #{$text-elements} rule.
 $text-elements: "a, kbd, div, span, mark, callout-title::before, span, li::before, button, legend, fieldset, label, li, h1, h2, h3, h4, h5, h6, p:not(:has(img)), figcaption, dt, dd, label, td, th, .callout, code, .lined, aside";
 
+// Vertical rhythm system (_standard-05-rhythm.scss): consecutive "simple"
+// elements get 1x --gap margin between them; the moment either neighbor is
+// a "double" (heavier block-level: tables, cards, figures, sections...) the
+// margin becomes --gap * --gap-multiplicator (2x by default) — extra
+// breathing room around visually heavier blocks. $rhythm-tags is the union,
+// used for the heading-follows-anything spacing rules.
 $rhythm-simple-tags: ".alert, #comments, h1, h2, h3, h4, h5, h6, blockquote, ul, ol, li, dl, dt, dd, p, pre, figure, hr, form, fieldset, button, aside, .callout, .card, .box, .btn, .grid";
 $rhythm-double-tags: "table,  blockquote, div:has(.video), section, article, header, footer, hr, #comments, .callout,  pre, figure, p:has(img), section, .box, .card, .small, .editorial, .feature, .hero, .full, .scroll, hr, aside, .stnd-code-block";
 $rhythm-tags: $rhythm-simple-tags + ", div, " + $rhythm-double-tags;
 
-$elements-boxed: "blockquote, pre, .alert, aside, .card, .callout, img, iframe, .outset";
-
+// Reusable style fragments via @extend (not applied directly — SCSS
+// placeholder selectors emit no CSS of their own until extended).
+// %surface: card/panel look — _standard-13-components.scss.
+// %padding-text: form-control text padding — _standard-11-forms.scss,
+// _standard-13-components.scss.
 %surface {
   border: none;
   /* Raised effect for all surfaces */
@@ -50,5 +62,14 @@ $elements-boxed: "blockquote, pre, .alert, aside, .card, .callout, img, iframe,
   padding: var(--space-d4) var(--space-d2);
 }
 
-$stnd-scope: ":root, body" !default;
+// Single-target on purpose (not ":root, body") — a token declared on both
+// would always win on <body>'s own cascade resolution over anything set at
+// :root/html, silently blocking any :root-only override (which is exactly
+// what a note's frontmatter inlineStyle produces). See _standard-01-token.scss.
+//
+// Used to be two variables ($stnd-scope + $stnd-theme-scope) with different
+// defaults (":root, body" vs ":root"). Consolidated to one (2026-07-14) once
+// $stnd-scope became single-target too — nothing ever set them to different
+// selectors (obsidian.scss configures both identically), so the split was
+// pure redundancy.
 $stnd-theme-scope: ":root" !default;

package/_standard-01-token.scss

@@ -7,7 +7,7 @@
  * Includes mathematical ratios, modular scales, spacing system, and animation curves.
  */
 
-#{$stnd-scope} {
+#{$stnd-theme-scope} {
   /* ===== COLOR SEEDS =====
      The two primary seeds from which everything grows.
      Set these and the color file (_standard-02-color.scss) does the rest:
@@ -36,7 +36,13 @@
   --tooltip-background: #1a1a1a;
   --tooltip-text: #ffffff;
 
-  /* Base measurements & ratios */
+  /* Base measurements & ratios. --font-ratio / --font-density are the
+     theme-authoring hooks (set by ~a dozen packages/themes/*.scss files,
+     e.g. --font-ratio: 1.414) — --optical-ratio / --line-height are the
+     resolved, framework-consumed values. A note's frontmatter can also
+     override --optical-ratio directly (it's the registered token name),
+     which bypasses --font-ratio entirely since the more specific
+     declaration wins regardless of this fallback chain. */
   --font-size: 1rem;
   --optical-ratio: var(--font-ratio, var(--ratio-silver));
   --line-height: var(--font-density, var(--optical-ratio));
@@ -50,7 +56,7 @@
   --nl: calc(var(--leading) * var(--line-height));
 
   /* Gap, space between blocks in rhythm, goes to --space in mobile */
-  --gap: var(--space);
+  --gap: calc(var(--space) * var(--optical-ratio));
   --gap-body: var(--space-2);
   --gap-header: var(--space-8);
   --gap-footer: calc(var(--gap-body) * 1.5);
@@ -62,7 +68,6 @@
   --breakpoint-lg: #{$large};
   --breakpoint-wide: #{$wide};
 
-  --content-width: min(var(--line-width), 100%);
   --content-width-sm: max(calc(var(--space-2) - var(--space)), var(--space));
   --content-width-editorial: minmax(0, var(--space-2));
   --content-width-feature: minmax(0, var(--space-4));
@@ -73,6 +78,9 @@
   --filter-glass: blur(20px);
   --stroke-width: max(1px, 0.06rem);
   --stroke-width-lg: calc(var(--stroke-width) * 2);
+  /* --corner is a documented theme-authoring hook (TOKENS.md) — no theme
+     currently sets it, so --radius always resolves through --leading
+     (proportional to line-height/font-size) today. Not dead, just unused. */
   --radius: var(--corner, var(--leading));
   --radius-sm: min(8px, var(--radius));
 
@@ -83,29 +91,39 @@
   --ratio-quarterstep: 1.128;
   --ratio-eighthstep: 1.062;
 
-  /* Content area tokens */
+  /* Layout width — body-max-width is the whole page shell (header, footer,
+     content); .prose's own box reads it directly, so .hero/.full breakout
+     elements grow into it too. line-width is a single line of readable
+     text — .feature and tables/.editorial break out by a fixed rhythm
+     increment off this (space-2 / space-4 each side), not off
+     body-max-width. */
+  --body-max-width: 900px;
+
   --line-width-xs: 24rem;
   --line-width-sm: 32rem;
   --line-width-md: 42rem;
   --line-width-lg: 50rem;
   --line-width-xl: 60rem;
   --line-width-full: calc(100vw - (var(--space) * 2));
+  /* --font-line-width is the theme-authoring hook (e.g. humanist, book,
+     2064 themes); --measure is a second, editor-specific override read by
+     apps/stnd.gd's Writer component. Same override-ladder shape as
+     --font-ratio above — a note's frontmatter can also set --line-width
+     directly, bypassing both. */
   --line-width: var(--font-line-width, var(--measure, var(--line-width-md)));
 
+  --content-width: min(var(--line-width), 100%);
+
   --line-height-compact: calc(1 + (var(--line-height) - 1) / 2);
   --line-height-relaxed: calc(1 + (var(--line-height) - 1) * 1.5);
 
-  --max-width: 900px;
-
-  /* Named width tokens */
-  --body-max-width: var(--max-width);
-  --prose-max-width: var(--max-width);
-
   --tracking-tight: -0.01em;
   --tracking-neutral: 0em;
   --tracking-open: 0.01em;
 
-  /* Spacing scale (derived from baseline) */
+  /* Spacing scale (derived from baseline). "d" prefix = divide (space-d4 =
+     space / 4), plain number = multiply (space-4 = space * 4) — same "d"
+     convention repeats below in the type scale. */
   --space: var(--baseline);
   --space-half: calc(var(--baseline)/2);
 
@@ -114,12 +132,18 @@
     --space-#{$i}: calc(var(--space) * #{$i});
   }
 
-  /* Optical harmony scale */
-  --scale-d5: max(calc(var(--font-size) / (var(--optical-ratio) * var(--optical-ratio))), 11px);
-  --scale-d4: max(
-    calc(var(--font-size) / (var(--optical-ratio) * 1.25)),
+  /* Optical harmony scale. --scale-2 upward is a clean geometric progression
+     (each step = previous * --optical-ratio). Below base (d5..d2) the
+     divisor is deliberately NOT the mirrored geometric inverse (ratio^-1,
+     ratio^-2...) — it's flattened (ratio*1.25, then a 0.5-blended exponent
+     for d2) so small text doesn't shrink as aggressively as a pure
+     geometric scale would, staying legible; each step also floors at 11px
+     regardless of ratio math. */
+  --scale-d5: max(
+    calc(var(--font-size) / (var(--optical-ratio) * var(--optical-ratio))),
     11px
   );
+  --scale-d4: max(calc(var(--font-size) / (var(--optical-ratio) * 1.25)), 11px);
   --scale-d3: max(calc(var(--font-size) / var(--optical-ratio)), 11px);
   --scale-d2: max(
     calc(var(--font-size) / (1 + (var(--optical-ratio) - 1) * 0.5)),
@@ -160,7 +184,9 @@
   --z-modal: 1200;
   --z-toast: 2000;
   --z-header: 900;
-  --z-launher: 1000;
+  /* Fixed 2026-07-14 — was --z-launher (typo for launcher), renamed. Still
+     unused/unreferenced anywhere, but at least spelled correctly now. */
+  --z-launcher: 1000;
   --z-image-zoom: 9999;
 
   /* The *“Snappy”* - for small icons or toggles (Short duration) */
@@ -186,7 +212,10 @@
   /* Analog : It starts with a burst of energy (the push) and spends 80% of its time slowly losing that energy. */
   --ease-friction: cubic-bezier(0.22, 1, 0.36, 1);
 
-  /* Animation
+  /* Reference notes only, not live code — mixes prose with invalid CSS
+     (e.g. "Soft Fade Out" as a bare declaration) on purpose, scratch
+     rationale for the eases defined around it, not meant to be uncommented.
+  Animation
   a {
     text-decoration-color: rgba(0,0,0,0);
     transition: text-decoration-color 0.4s cubic-bezier(0.4, 0, 0.2, 1);
@@ -245,6 +274,14 @@ a {
   text-box-edge: cap alphabetic;
 }
 
+/* Table cells opt back out of text-box-trim — vertical-align/padding math
+   in table cells doesn't play well with the trimmed ascender/descender
+   box, so cells keep normal line-box sizing instead. */
+td,
+th {
+  text-box-trim: none;
+}
+
 /* Responsive adjustments */
 @media only screen and (max-width: #{$small}) {
   #{$stnd-theme-scope} {
@@ -255,10 +292,6 @@ a {
   }
 }
 
-#{$stnd-theme-scope} {
-  --ease-aggressive: cubic-bezier(0.7, 0, 0.3, 1);
-}
-
 ::view-transition-old(root),
 ::view-transition-new(root) {
   animation-duration: 500ms;