@livenetworks/ashlar 2.0.6 → 2.0.8

package/theme/config/_tokens.scss

@@ -1,285 +1,285 @@
-@use 'mixins/breakpoints' as *;
-
-// ==========================================================================
-// Design Tokens — ln-ashlar
-// ==========================================================================
-// Single source of truth for theme-invariant design values (sizes, spacing,
-// radii, typography scales, transitions, and z-index).
-//
-// Color and shadow values reside in `_palette.scss` and `_theme.scss`.
-// ==========================================================================
-
-:root {
-
-	// -----------------------------------------------------------------------
-	// Size scale — canonical spacing primitives
-	// -----------------------------------------------------------------------
-	// Public API surface — full scale exposed. All padding, margin, gap,
-	// inset, and positional-offset spacing references one of these steps.
-	// Intermediate steps use t-shirt + `-up` suffix.
-	//
-	// Mixin bodies read --size-* only when a logical token (--padding-x,
-	// --padding-y, --gap) is not semantically appropriate. Otherwise they
-	// read the logical token, which is re-bound under density / theme /
-	// region scopes (see Logical tokens block below).
-	// -----------------------------------------------------------------------
-	--size-0:      0;
-	--size-2xs:    0.125rem;   // 2px
-	--size-xs:     0.25rem;    // 4px
-	--size-xs-up:  0.375rem;   // 6px
-	--size-sm:     0.5rem;     // 8px
-	--size-sm-up:  0.75rem;    // 12px
-	--size-md:     1rem;       // 16px
-	--size-md-up:  1.25rem;    // 20px
-	--size-lg:     1.5rem;     // 24px
-	--size-xl:     2rem;       // 32px
-	--size-2xl:    3rem;       // 48px
-	--size-3xl:    4rem;       // 64px
-	--size-4xl:    6rem;
-	--size-5xl:    8rem;
-
-	// -----------------------------------------------------------------------
-	// Border Width
-	// -----------------------------------------------------------------------
-	// Public API surface — full scale exposed; internal usage may skip levels.
-	--border-width: 1px;
-	--border-width-strong: 2px;
-
-	// -----------------------------------------------------------------------
-	// Content widths
-	// -----------------------------------------------------------------------
-	// Public API surface — full scale exposed; internal usage may skip levels.
-	--max-w-prose:     65ch;
-	--max-w-form:      32rem;
-	--max-w-content:   48rem;
-	--max-w-container: 80rem;
-
-	// -----------------------------------------------------------------------
-	// Border Radius
-	// -----------------------------------------------------------------------
-	--radius-none: 0;
-	--radius-xs:   0.125rem;   // 2px
-	--radius-sm:   0.25rem;    // 4px
-	--radius-md:   0.375rem;   // 6px
-	--radius-lg:   0.5rem;     // 8px
-	--radius-xl:   0.75rem;    // 12px
-	--radius-2xl:  1rem;       // 16px
-	--radius-full: 9999px;
-
-	// -----------------------------------------------------------------------
-	// Transitions — durations
-	// -----------------------------------------------------------------------
-	--transition-base: 0.2s cubic-bezier(0.4, 0, 0.2, 1);
-	--transition-fast: 0.15s cubic-bezier(0.4, 0, 0.2, 1);
-	--transition-slow: 0.3s cubic-bezier(0.4, 0, 0.2, 1);
-
-	// -----------------------------------------------------------------------
-	// Easings — curves only (no duration)
-	// -----------------------------------------------------------------------
-	// Public API surface — full scale exposed; internal usage may skip levels.
-	--easing-standard:   cubic-bezier(0.4, 0, 0.2, 1);
-	--easing-decelerate: cubic-bezier(0, 0, 0.2, 1);
-	--easing-accelerate: cubic-bezier(0.4, 0, 1, 1);
-	--easing-spring:     cubic-bezier(0.34, 1.56, 0.64, 1);
-
-	// -----------------------------------------------------------------------
-	// Typography
-	// -----------------------------------------------------------------------
-	--font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
-	--font-mono: 'JetBrains Mono', ui-monospace, 'Cascadia Code', 'Source Code Pro', monospace;
-	--font-features: "cv02", "cv03", "cv04", "cv11", "tnum";
-
-	--text-xs: 0.75rem;      // 12px
-	--text-sm: 0.875rem;     // 14px
-	--text-base: 1rem;       // 16px
-	--text-lg: 1.125rem;     // 18px
-	--text-xl: 1.25rem;      // 20px
-	--text-2xl: 1.5rem;      // 24px
-
-	// -----------------------------------------------------------------------
-	// Typography — semantic role tokens (v1.1) — VOCABULARY
-	// -----------------------------------------------------------------------
-	// Public API surface — full scale exposed; internal usage may skip levels.
-	// Vocabulary: density + themes rebind these; mixins read the
-	// --font-size/--line-height primitives via @include typography(role),
-	// never these tokens directly.
-	--text-display-lg: 3.75rem;   --lh-display-lg: 1.1;
-	--text-display-md: 3rem;      --lh-display-md: 1.1;
-	--text-display-sm: 1.875rem;  --lh-display-sm: 1.1;
-
-	--text-heading-lg: 1.75rem;   --lh-heading-lg: 1.15;
-	--text-heading-md: 1.25rem;   --lh-heading-md: 1.2;
-	--text-heading-sm: 1.125rem;  --lh-heading-sm: 1.25;
-
-	--text-title-md:   1rem;      --lh-title-md:   1.3;
-	--text-title-sm:   0.875rem;  --lh-title-sm:   1.3;
-
-	--text-body-lg:    1.125rem;  --lh-body-lg:    1.6;
-	--text-body-md:    0.875rem;  --lh-body-md:    1.5;   // 14px / 1.5 — DocuFlow body
-	--text-body-sm:    0.8125rem; --lh-body-sm:    1.45;  // 13px
-
-	--text-label-md:   0.8125rem; --lh-label-md:   1.4;   // 13px
-	--text-label-sm:   0.75rem;   --lh-label-sm:   1.4;
-
-	--text-caption:    0.75rem;   --lh-caption:    1.4;
-
-	// -----------------------------------------------------------------------
-	// Letter spacing (optical tracking scale)
-	// -----------------------------------------------------------------------
-	--tracking-tighter: -0.035em;
-	--tracking-tight:   -0.02em;
-	--tracking-normal:  0;
-	--tracking-wide:    0.025em;
-	--tracking-wider:   0.05em;
-
-	--font-normal: 400;
-	--font-medium: 500;
-	--font-semibold: 600;
-	--font-bold: 700;
-
-	// -----------------------------------------------------------------------
-	// Z-Index Scale
-	// -----------------------------------------------------------------------
-	--z-sticky: 10;
-	--z-dropdown: 20;
-	--z-overlay: 30;
-	--z-modal: 40;
-	--z-toast: 50;
-
-	// -----------------------------------------------------------------------
-	// App shell — intrinsic dimensions (not spacing rhythm)
-	// -----------------------------------------------------------------------
-	--app-header-height: 3.25rem;   // 52px — DocuFlow topbar height
-	--app-sidebar-width: 14.5rem;   // 232px — DocuFlow sidebar width
-
-	// -----------------------------------------------------------------------
-	// Logical tokens — the public contract mixins read
-	// -----------------------------------------------------------------------
-	// Rule: mixin bodies reference ONLY these tokens. Typography mixins read
-	// --font-size/--line-height ONLY (via @include typography(role), which
-	// rebinds the primitive per role on the consuming element's scope).
-	// --text-*/--lh-* role scale is VOCABULARY: density + themes rebind it,
-	// mixins never read it directly. --radius-*/--shadow-*/--transition-*/
-	// --easing-* role scales remain directly readable (not yet primitived).
-	// Back-end scales (--size-*, --color-neutral-*) are re-bound here and in
-	// context scopes (density, theme, region overrides) — never read directly
-	// inside a component mixin.
-	//
-	// See .claude/plans/refactor-logical-tokens-architecture.md for the
-	// full contract.
-	// -----------------------------------------------------------------------
-
-	// -- Structure & rhythm -----------------------------------------------
-	--padding-x:       var(--size-sm-up);
-	--padding-y:       var(--size-xs-up);   // 6px — dense base (DocuFlow 7px rounds to 6px)
-	--gap:             var(--size-xs-up);   // 6px — dense base
-	// --radius sits with the other primitives in _palette.scss. Declared here it
-	// would resolve once at <html> and inherit frozen through every theme island.
-
-	// Accent-wash strengths. Ratios, not colors — color-mix() stays at the
-	// declaration site so --color-accent / --color-bg resolve locally and the
-	// semantic-color cascade keeps working. Ladder taken from _dropdown.scss,
-	// the only component that had all three states.
-	--tint-hover:    7%;
-	--tint-selected: 12%;
-	--tint-active:   14%;
-
-	// Translucent accent surface — companions for themes that opt in to a
-	// non-solid accent button. NO defaults — `@mixin btn` reads these via
-	// fallback to `--color-accent` / `--color-accent-fg`, so the default
-	// theme stays solid + white.
-	//
-	// IMPORTANT — declare at theme :root ONLY when the value is a literal
-	// (no nested var(--color-primary)). If a theme needs the translucent
-	// fill computed FROM --color-primary, the rebind must happen at
-	// consumer scope (e.g. `[data-skin="..."] button[type="submit"], .btn
-	// { --btn-bg: ...; }`) so the nested var() resolves at the button —
-	// otherwise the .success/.error/.warning/.info status cascade breaks on
-	// elements using semantic-color overrides. Glass uses the consumer-scope
-	// pattern; see theme/config/_theme.scss.
-	// --color-accent-bg
-	// --color-accent-bg-hover
-	// --color-accent-bg-fg
-
-	// Nav surface — companions for themes that opt in to a bordered/inset
-	// nav appearance (e.g. Glass). NO defaults — `@mixin nav` reads these
-	// via fallback to no-op values (transparent border, zero bleed), so
-	// the default theme renders unchanged. Themes rebind at theme :root.
-	// --nav-link-border-color
-	// --nav-link-border-color-hover
-	// --nav-link-border-color-active
-	// --nav-list-bleed
-
-	// Button padding tokens
-	--btn-padding-x:    var(--size-sm-up);
-	--btn-padding-y:    var(--size-xs-up);
-
-	// -- Typography — primitives -----------------------------------------
-	// Mixins read these two primitives ONLY (via @include typography(role),
-	// which rebinds them per role on the consuming element's scope — mirror
-	// of how @mixin card rebinds --color-bg). The --text-{role}/--lh-{role}
-	// role scale (lines ~202-220) is VOCABULARY: density + themes rebind it,
-	// mixins never read it directly. These :root values are the default for
-	// text that does not pass through a typography mixin.
-	--font-size:    var(--text-body-md);
-	--line-height:  var(--lh-body-md);
-
-	// -- Motion & depth --------------------------------------------------
-	--transition: var(--transition-base);
-
-	// -- Per-side borders (SOFT — no default) ----------------------------
-	// --border-block-start, --border-block-end,
-	// --border-inline-start, --border-inline-end
-	//
-	// Read by structural mixins (card, section-card, floating-panel,
-	// stat-card, app-header, app-footer, accordion items, table cells,
-	// tab-nav, sidebar edges, page-header, etc.) with a per-mixin
-	// fallback. NOT defined here — that is intentional. A scope that
-	// re-binds e.g. `--border-block-start: none` flattens the top edge
-	// of the matched element so siblings can join with a shared rule.
-	//
-	// Joining example:
-	//   .joined-stack > * + * { --border-block-start: none; }
-
-	// -- Margin (SOFT — no default) --------------------------------
-	// --margin-block, --margin-inline
-	//
-	// Read by structural rhythm rules (label-to-input gap, section
-	// margin, header→body separation, sibling stacking,
-	// element-pushing horizontal offsets) with a per-mixin rebind.
-	// NOT defined here — the value varies too widely across
-	// consumers for a single :root default to be useful. Each
-	// consumer rebinds locally:
-	//
-	//   @mixin section {
-	//       --margin-block: var(--size-xl);
-	//       margin-bottom: var(--margin-block);
-	//   }
-	//
-	// NOTE: [data-density] scopes rebind type roles, logical
-	// --padding-y/--gap, and control sizing — NOT the --size-* scale.
-	// So --margin-block (reading --size-*) is constant across density
-	// tiers for now; making structural margins reactive is a Phase 3 item.
-	//
-	// --margin-inline is the horizontal companion. Used for
-	// element-pushing structural offsets (icon→text gap inside a
-	// row, sibling element offsets). NOT for flex/grid sibling
-	// spacing — that is --gap.
-}
-
-// ---------------------------------------------------------------------------
-// Mobile rhythm — logical tokens tighten at ≤ md viewport.
-// Not the same as `[data-density]` (that's a user opt-in).
-// This is viewport-driven structural compression: content dominates chrome
-// at narrow widths. Components reading --padding-x/--padding-y/--gap
-// react via the cascade.
-//
-// Interaction with [data-density]: stacks. Compact density + mobile viewport =
-// both apply; the underlying --padding-y tightens further from the mobile rebind.
-// ---------------------------------------------------------------------------
-@include mq-down(md) {
-	:root {
-		--padding-y: var(--size-xs);     // 6px → 4px
-		--gap:       var(--size-xs-up);  // 6px → 6px (already tight)
-	}
-}
+@use 'mixins/breakpoints' as *;
+
+// ==========================================================================
+// Design Tokens — ln-ashlar
+// ==========================================================================
+// Single source of truth for theme-invariant design values (sizes, spacing,
+// radii, typography scales, transitions, and z-index).
+//
+// Color and shadow values reside in `_palette.scss` and `_theme.scss`.
+// ==========================================================================
+
+:root {
+
+	// -----------------------------------------------------------------------
+	// Size scale — canonical spacing primitives
+	// -----------------------------------------------------------------------
+	// Public API surface — full scale exposed. All padding, margin, gap,
+	// inset, and positional-offset spacing references one of these steps.
+	// Intermediate steps use t-shirt + `-up` suffix.
+	//
+	// Mixin bodies read --size-* only when a logical token (--padding-x,
+	// --padding-y, --gap) is not semantically appropriate. Otherwise they
+	// read the logical token, which is re-bound under density / theme /
+	// region scopes (see Logical tokens block below).
+	// -----------------------------------------------------------------------
+	--size-0:      0;
+	--size-2xs:    0.125rem;   // 2px
+	--size-xs:     0.25rem;    // 4px
+	--size-xs-up:  0.375rem;   // 6px
+	--size-sm:     0.5rem;     // 8px
+	--size-sm-up:  0.75rem;    // 12px
+	--size-md:     1rem;       // 16px
+	--size-md-up:  1.25rem;    // 20px
+	--size-lg:     1.5rem;     // 24px
+	--size-xl:     2rem;       // 32px
+	--size-2xl:    3rem;       // 48px
+	--size-3xl:    4rem;       // 64px
+	--size-4xl:    6rem;
+	--size-5xl:    8rem;
+
+	// -----------------------------------------------------------------------
+	// Border Width
+	// -----------------------------------------------------------------------
+	// Public API surface — full scale exposed; internal usage may skip levels.
+	--border-width: 1px;
+	--border-width-strong: 2px;
+
+	// -----------------------------------------------------------------------
+	// Content widths
+	// -----------------------------------------------------------------------
+	// Public API surface — full scale exposed; internal usage may skip levels.
+	--max-w-prose:     65ch;
+	--max-w-form:      32rem;
+	--max-w-content:   48rem;
+	--max-w-container: 80rem;
+
+	// -----------------------------------------------------------------------
+	// Border Radius
+	// -----------------------------------------------------------------------
+	--radius-none: 0;
+	--radius-xs:   0.125rem;   // 2px
+	--radius-sm:   0.25rem;    // 4px
+	--radius-md:   0.375rem;   // 6px
+	--radius-lg:   0.5rem;     // 8px
+	--radius-xl:   0.75rem;    // 12px
+	--radius-2xl:  1rem;       // 16px
+	--radius-full: 9999px;
+
+	// -----------------------------------------------------------------------
+	// Transitions — durations
+	// -----------------------------------------------------------------------
+	--transition-base: 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+	--transition-fast: 0.15s cubic-bezier(0.4, 0, 0.2, 1);
+	--transition-slow: 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+
+	// -----------------------------------------------------------------------
+	// Easings — curves only (no duration)
+	// -----------------------------------------------------------------------
+	// Public API surface — full scale exposed; internal usage may skip levels.
+	--easing-standard:   cubic-bezier(0.4, 0, 0.2, 1);
+	--easing-decelerate: cubic-bezier(0, 0, 0.2, 1);
+	--easing-accelerate: cubic-bezier(0.4, 0, 1, 1);
+	--easing-spring:     cubic-bezier(0.34, 1.56, 0.64, 1);
+
+	// -----------------------------------------------------------------------
+	// Typography
+	// -----------------------------------------------------------------------
+	--font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+	--font-mono: 'JetBrains Mono', ui-monospace, 'Cascadia Code', 'Source Code Pro', monospace;
+	--font-features: "cv02", "cv03", "cv04", "cv11", "tnum";
+
+	--text-xs: 0.75rem;      // 12px
+	--text-sm: 0.875rem;     // 14px
+	--text-base: 1rem;       // 16px
+	--text-lg: 1.125rem;     // 18px
+	--text-xl: 1.25rem;      // 20px
+	--text-2xl: 1.5rem;      // 24px
+
+	// -----------------------------------------------------------------------
+	// Typography — semantic role tokens (v1.1) — VOCABULARY
+	// -----------------------------------------------------------------------
+	// Public API surface — full scale exposed; internal usage may skip levels.
+	// Vocabulary: density + themes rebind these; mixins read the
+	// --font-size/--line-height primitives via @include typography(role),
+	// never these tokens directly.
+	--text-display-lg: 3.75rem;   --lh-display-lg: 1.1;
+	--text-display-md: 3rem;      --lh-display-md: 1.1;
+	--text-display-sm: 1.875rem;  --lh-display-sm: 1.1;
+
+	--text-heading-lg: 1.75rem;   --lh-heading-lg: 1.15;
+	--text-heading-md: 1.25rem;   --lh-heading-md: 1.2;
+	--text-heading-sm: 1.125rem;  --lh-heading-sm: 1.25;
+
+	--text-title-md:   1rem;      --lh-title-md:   1.3;
+	--text-title-sm:   0.875rem;  --lh-title-sm:   1.3;
+
+	--text-body-lg:    1.125rem;  --lh-body-lg:    1.6;
+	--text-body-md:    0.875rem;  --lh-body-md:    1.5;   // 14px / 1.5 — DocuFlow body
+	--text-body-sm:    0.8125rem; --lh-body-sm:    1.45;  // 13px
+
+	--text-label-md:   0.8125rem; --lh-label-md:   1.4;   // 13px
+	--text-label-sm:   0.75rem;   --lh-label-sm:   1.4;
+
+	--text-caption:    0.75rem;   --lh-caption:    1.4;
+
+	// -----------------------------------------------------------------------
+	// Letter spacing (optical tracking scale)
+	// -----------------------------------------------------------------------
+	--tracking-tighter: -0.035em;
+	--tracking-tight:   -0.02em;
+	--tracking-normal:  0;
+	--tracking-wide:    0.025em;
+	--tracking-wider:   0.05em;
+
+	--font-normal: 400;
+	--font-medium: 500;
+	--font-semibold: 600;
+	--font-bold: 700;
+
+	// -----------------------------------------------------------------------
+	// Z-Index Scale
+	// -----------------------------------------------------------------------
+	--z-sticky: 10;
+	--z-dropdown: 20;
+	--z-overlay: 30;
+	--z-modal: 40;
+	--z-toast: 50;
+
+	// -----------------------------------------------------------------------
+	// App shell — intrinsic dimensions (not spacing rhythm)
+	// -----------------------------------------------------------------------
+	--app-header-height: 3.25rem;   // 52px — DocuFlow topbar height
+	--app-sidebar-width: 14.5rem;   // 232px — DocuFlow sidebar width
+
+	// -----------------------------------------------------------------------
+	// Logical tokens — the public contract mixins read
+	// -----------------------------------------------------------------------
+	// Rule: mixin bodies reference ONLY these tokens. Typography mixins read
+	// --font-size/--line-height ONLY (via @include typography(role), which
+	// rebinds the primitive per role on the consuming element's scope).
+	// --text-*/--lh-* role scale is VOCABULARY: density + themes rebind it,
+	// mixins never read it directly. --radius-*/--shadow-*/--transition-*/
+	// --easing-* role scales remain directly readable (not yet primitived).
+	// Back-end scales (--size-*, --color-neutral-*) are re-bound here and in
+	// context scopes (density, theme, region overrides) — never read directly
+	// inside a component mixin.
+	//
+	// See .claude/plans/refactor-logical-tokens-architecture.md for the
+	// full contract.
+	// -----------------------------------------------------------------------
+
+	// -- Structure & rhythm -----------------------------------------------
+	--padding-x:       var(--size-sm-up);
+	--padding-y:       var(--size-xs-up);   // 6px — dense base (DocuFlow 7px rounds to 6px)
+	--gap:             var(--size-xs-up);   // 6px — dense base
+	// --radius sits with the other primitives in _palette.scss. Declared here it
+	// would resolve once at <html> and inherit frozen through every theme island.
+
+	// Accent-wash strengths. Ratios, not colors — color-mix() stays at the
+	// declaration site so --color-accent / --color-bg resolve locally and the
+	// semantic-color cascade keeps working. Ladder taken from _dropdown.scss,
+	// the only component that had all three states.
+	--tint-hover:    7%;
+	--tint-selected: 12%;
+	--tint-active:   14%;
+
+	// Translucent accent surface — companions for themes that opt in to a
+	// non-solid accent button. NO defaults — `@mixin btn` reads these via
+	// fallback to `--color-accent` / `--color-accent-fg`, so the default
+	// theme stays solid + white.
+	//
+	// IMPORTANT — declare at theme :root ONLY when the value is a literal
+	// (no nested var(--color-primary)). If a theme needs the translucent
+	// fill computed FROM --color-primary, the rebind must happen at
+	// consumer scope (e.g. `[data-skin="..."] button[type="submit"], .btn
+	// { --btn-bg: ...; }`) so the nested var() resolves at the button —
+	// otherwise the .success/.error/.warning/.info status cascade breaks on
+	// elements using semantic-color overrides. Glass uses the consumer-scope
+	// pattern; see theme/config/_theme.scss.
+	// --color-accent-bg
+	// --color-accent-bg-hover
+	// --color-accent-bg-fg
+
+	// Nav surface — companions for themes that opt in to a bordered/inset
+	// nav appearance (e.g. Glass). NO defaults — `@mixin nav` reads these
+	// via fallback to no-op values (transparent border, zero bleed), so
+	// the default theme renders unchanged. Themes rebind at theme :root.
+	// --nav-link-border-color
+	// --nav-link-border-color-hover
+	// --nav-link-border-color-active
+	// --nav-list-bleed
+
+	// Button padding tokens
+	--btn-padding-x:    var(--size-sm-up);
+	--btn-padding-y:    var(--size-xs-up);
+
+	// -- Typography — primitives -----------------------------------------
+	// Mixins read these two primitives ONLY (via @include typography(role),
+	// which rebinds them per role on the consuming element's scope — mirror
+	// of how @mixin card rebinds --color-bg). The --text-{role}/--lh-{role}
+	// role scale (lines ~202-220) is VOCABULARY: density + themes rebind it,
+	// mixins never read it directly. These :root values are the default for
+	// text that does not pass through a typography mixin.
+	--font-size:    var(--text-body-md);
+	--line-height:  var(--lh-body-md);
+
+	// -- Motion & depth --------------------------------------------------
+	--transition: var(--transition-base);
+
+	// -- Per-side borders (SOFT — no default) ----------------------------
+	// --border-block-start, --border-block-end,
+	// --border-inline-start, --border-inline-end
+	//
+	// Read by structural mixins (card, section-card, floating-panel,
+	// stat-card, app-header, app-footer, accordion items, table cells,
+	// tab-nav, sidebar edges, page-header, etc.) with a per-mixin
+	// fallback. NOT defined here — that is intentional. A scope that
+	// re-binds e.g. `--border-block-start: none` flattens the top edge
+	// of the matched element so siblings can join with a shared rule.
+	//
+	// Joining example:
+	//   .joined-stack > * + * { --border-block-start: none; }
+
+	// -- Margin (SOFT — no default) --------------------------------
+	// --margin-block, --margin-inline
+	//
+	// Read by structural rhythm rules (label-to-input gap, section
+	// margin, header→body separation, sibling stacking,
+	// element-pushing horizontal offsets) with a per-mixin rebind.
+	// NOT defined here — the value varies too widely across
+	// consumers for a single :root default to be useful. Each
+	// consumer rebinds locally:
+	//
+	//   @mixin section {
+	//       --margin-block: var(--size-xl);
+	//       margin-bottom: var(--margin-block);
+	//   }
+	//
+	// NOTE: [data-density] scopes rebind type roles, logical
+	// --padding-y/--gap, and control sizing — NOT the --size-* scale.
+	// So --margin-block (reading --size-*) is constant across density
+	// tiers for now; making structural margins reactive is a Phase 3 item.
+	//
+	// --margin-inline is the horizontal companion. Used for
+	// element-pushing structural offsets (icon→text gap inside a
+	// row, sibling element offsets). NOT for flex/grid sibling
+	// spacing — that is --gap.
+}
+
+// ---------------------------------------------------------------------------
+// Mobile rhythm — logical tokens tighten at ≤ md viewport.
+// Not the same as `[data-density]` (that's a user opt-in).
+// This is viewport-driven structural compression: content dominates chrome
+// at narrow widths. Components reading --padding-x/--padding-y/--gap
+// react via the cascade.
+//
+// Interaction with [data-density]: stacks. Compact density + mobile viewport =
+// both apply; the underlying --padding-y tightens further from the mobile rebind.
+// ---------------------------------------------------------------------------
+@include mq-down(md) {
+	:root {
+		--padding-y: var(--size-xs);     // 6px → 4px
+		--gap:       var(--size-xs-up);  // 6px → 6px (already tight)
+	}
+}