@stnd/styles 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @stnd/styles
 
+## 0.5.3
+
+### Patch Changes
+
+- Auto-bumped @stnd/styles due to modified code.
+
+## 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,36 @@
 ---
 title: "@stnd/styles"
-status: active
+aliases: []
+created: 2026-07-04 23:27
+modified: 2026-09-16T18:33:44.496Z
+last_audited: 2026-07-14
+audit_interval_days: 90
+next_audit: 2026-10-12
+audit_priority: 3
 maturity: tree
-type: package
+mode: read
+publish: true
+status: active
 tags:
   - package
   - stnd
+theme: kernel
+type: package
+visibility: public
+garden-url: https://standard.garden/@francis/readme
+garden-short: https://stnd.gd/Yl18ps
+permalink: readme
+---
+
+# @[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 +42,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 +69,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 +94,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 +106,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 +122,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-adapter` 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-adapter` (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,18 @@
+---
+aliases: []
+created: 2026-03-16 08:07
+modified: 2026-09-16T18:33:41.605Z
+mode: read
+publish: true
+tags: []
+theme:
+type: note
+visibility: public
+garden-url: https://standard.garden/@francis/tokens
+permalink: tokens
+garden-short: https://stnd.gd/jb29Tu
+---
+
 # Standard Design Tokens
 
 > Canonical reference for all CSS custom properties exposed by `@stnd/styles`.
@@ -32,7 +47,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 +97,18 @@ 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 |
+| `--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)                |
@@ -318,8 +340,8 @@ box-shadow: var(--shadow-inset), var(--shadow-ambient);
 
 | Token                  | Default                         | Description        |
 | ---------------------- | ------------------------------- | ------------------ |
-| `--tooltip-background` | `#1a1a1a`                       | Tooltip background |
-| `--tooltip-text`       | `#ffffff`                       | Tooltip text       |
+| `--tooltip-background` | `var(--color-dark, #1a1a1a)`    | Tooltip background |
+| `--tooltip-text`       | `var(--color-light, #ffffff)`   | Tooltip text       |
 | `--tooltip-ease`       | `cubic-bezier(0.25, 1, 0.5, 1)` | Tooltip animation  |
 
 ---

package/_standard-00-reset.scss

@@ -1,8 +1,30 @@
+/**
+ * @component Reset
+ * @category Foundation
+ * @description A deliberately narrow reset — no classes, nothing to apply.
+ * Box-sizing and thin scrollbars go on everything; margin/padding zeroing
+ * is scoped via `:where()` to standard typographic and layout elements
+ * only, so embedded editors (CodeMirror, Obsidian) and third-party widgets
+ * keep their native spacing instead of losing it to a blanket reset. List
+ * markers are removed, media elements become block-level and responsive by
+ * @property * Universal box-sizing (`border-box`), zero default border width, and thin scrollbars.
+ * @property :where(...) Targeted margin/padding zeroing on standard typographic and layout elements, protecting embedded editors.
+ * @property ol,ul,menu List-style unsetting for clean typographic lists.
+ * @property img,video Block display, vertical centering, and responsive max-width.
+ * @property svg Inline-block display for inline icons and symbols.
+ * @property [hidden] Defensive display hiding while preserving `hidden="until-found"` for find-in-page.
+ * @property script Enforced `display: none !important` guarding against aggressive global style overrides.
+ */
+
 /* =========================== */
 /* RESET                       */
 /* =========================== */
 
 /* 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 +44,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 +105,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 +118,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,20 +5,27 @@
  * 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} $small Small screen breakpoint (768px)
- * @prop {variable} $large Large screen breakpoint (1024px)
- * @prop {variable} $wide Wide screen breakpoint (1440px)
+ * @property $mobile Mobile breakpoint boundary (600px).
+ * @property $small Small screen/tablet breakpoint boundary (768px).
+ * @property $large Large desktop screen breakpoint boundary (1024px).
+ * @property $wide Ultra-wide display breakpoint boundary (1440px).
+ * @property $text-elements Selector list of inline and text elements receiving text-box-trim for baseline grid alignment.
+ * @property $rhythm-simple-tags Selector list of standard flow elements spaced by single rhythm gap.
+ * @property $rhythm-double-tags Selector list of heavier block elements spaced by multiplied rhythm margin.
+ * @property $rhythm-tags Union selector list of all rhythm-managed elements.
+ * @property %surface Placeholder selector applying card/surface elevation, radius, and background.
+ * @property %padding-text Placeholder selector applying standard text control padding.
+ * @property $stnd-theme-scope CSS selector scope for theme token assignment (`:root` by default).
  *
- * @example
+ * @example scss
  * // Using breakpoint variables
  * @media (min-width: $small) {
  *   font-size: 1.2rem;
  * }
  *
- * // Using rhythm mixin
- * @include apply-rhythm {
- *   margin-bottom: var(--space);
+ * // Extending surface placeholder
+ * .my-panel {
+ *   @extend %surface;
  * }
  *
  * @since 0.1.0
@@ -30,14 +37,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 +69,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;