@livenetworks/ashlar 1.6.1 → 2.0.1

package/{scss → theme}/config/_tokens.scss

@@ -1,441 +1,285 @@
-@use 'mixins/breakpoints' as *;
-
-// ==========================================================================
-// Design Tokens — ln-ashlar
-// ==========================================================================
-// Single source of truth for all design values.
-// All components reference these CSS variables.
-// For theming: override at :root or scope to an element.
-//
-// Colors are stored as bare HSL triplets to enable alpha transparency:
-//   hsl(var(--color-primary))          → solid color
-//   hsl(var(--color-primary) / 0.5)    → 50% transparent
-//
-// Theming example:
-//   .dark-theme { --color-bg: ...; }
-// ==========================================================================
-
-:root {
-
-	// -----------------------------------------------------------------------
-	// Colors — Primary
-	// -----------------------------------------------------------------------
-	--color-primary: 232 75% 52%;
-	--color-primary-light: 232 75% 93%;
-	--color-primary-lighter: 232 75% 97%;
-
-	// -----------------------------------------------------------------------
-	// Colors — Secondary (brand accent — surface/element color, NOT text)
-	// For subdued text color, see --fg-muted in the logical token section.
-	// -----------------------------------------------------------------------
-	--color-secondary: 160 76% 40%;
-	--color-secondary-light:   160 76% 93%;
-	--color-secondary-lighter: 160 76% 97%;
-
-	// -----------------------------------------------------------------------
-	// Colors — Status
-	// -----------------------------------------------------------------------
-	--color-success:         142 76% 36%;
-	--color-success-light:   142 76% 93%;
-	--color-success-lighter: 142 76% 97%;
-
-	--color-error:           0 84% 50%;
-	--color-error-light:     0 84% 93%;
-	--color-error-lighter:   0 84% 97%;
-
-	--color-warning:         32 95% 44%;
-	--color-warning-light:   32 95% 93%;
-	--color-warning-lighter: 32 95% 97%;
-
-	--color-info:            217 91% 60%;
-	--color-info-light:      217 91% 93%;
-	--color-info-lighter:    217 91% 97%;
-
-	// -----------------------------------------------------------------------
-	// Colors — Neutral scale (canonical greys)
-	// -----------------------------------------------------------------------
-	// Mixins may reach into the neutral scale directly when no semantic
-	// token matches the intent. Every such reference must be verified
-	// during dark-mode audits -- semantic tokens inherit dark adjustments
-	// automatically, direct-neutral references do not.
-	//
-	--color-neutral-50:  220 20% 98%;
-	--color-neutral-100: 220 16% 96%;
-	--color-neutral-150: 220 14% 93%;
-	--color-neutral-200: 220 13% 91%;
-	--color-neutral-300: 220 13% 83%;
-	--color-neutral-400: 218 11% 65%;
-	--color-neutral-500: 220  9% 46%;
-	--color-neutral-600: 220 11% 34%;
-	--color-neutral-700: 220 14% 24%;
-	--color-neutral-800: 220 20% 15%;
-	--color-neutral-900: 221 39% 11%;
-
-	// -----------------------------------------------------------------------
-	// Colors — Backgrounds
-	// -----------------------------------------------------------------------
-	--color-white: 0 0% 100%;
-
-	// -----------------------------------------------------------------------
-	// 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-sm:   0.25rem;    // 4px
-	--radius-md:   0.5rem;     // 8px
-	--radius-lg:   0.75rem;    // 12px
-	--radius-xl:   1rem;       // 16px
-	--radius-full: 9999px;
-
-	// -----------------------------------------------------------------------
-	// Shadows — cool-tinted, dual-layer (v1.1)
-	// -----------------------------------------------------------------------
-	// Public API surface — full scale exposed; internal usage may skip levels.
-	--shadow-none: none;
-
-	--shadow-xs:
-		0 1px 2px 0 hsl(220 40% 15% / 0.04);
-
-	--shadow-sm:
-		0 1px 3px 0 hsl(220 40% 15% / 0.08),
-		0 1px 2px -1px hsl(220 40% 15% / 0.04);
-
-	--shadow-md:
-		0 4px 12px -2px hsl(220 40% 15% / 0.10),
-		0 2px 4px -2px hsl(220 40% 15% / 0.06);
-
-	--shadow-lg:
-		0 12px 24px -6px hsl(220 40% 15% / 0.12),
-		0 8px 12px -4px hsl(220 40% 15% / 0.08);
-
-	--shadow-xl:
-		0 24px 48px -12px hsl(220 40% 15% / 0.16),
-		0 12px 24px -6px hsl(220 40% 15% / 0.10);
-
-	--shadow-2xl:
-		0 36px 72px -18px hsl(220 40% 15% / 0.20),
-		0 18px 36px -9px hsl(220 40% 15% / 0.12);
-
-	--shadow-inner:
-		inset 0 2px 4px 0 hsl(220 40% 15% / 0.06);
-
-	// Color-aware shadows (for focus halos and coloured CTAs)
-	--shadow-primary: 0 8px 24px -6px hsl(var(--color-primary) / 0.28);
-	--shadow-success: 0 8px 24px -6px hsl(var(--color-success) / 0.28);
-	--shadow-error:   0 8px 24px -6px hsl(var(--color-error)   / 0.28);
-
-	// -----------------------------------------------------------------------
-	// 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;
-
-	--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
-	// -----------------------------------------------------------------------
-	--tracking-tight:  -0.025em;
-	--tracking-normal: 0;
-	--tracking-wide:    0.025em;
-
-	--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
-	--app-scrim-bg: hsl(var(--color-neutral-900) / 0.4);
-
-	// -----------------------------------------------------------------------
-	// 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:          var(--radius-md);
-
-	// -----------------------------------------------------------------------
-	// Value vocabulary — what bg/fg/border/shadow values exist
-	// -----------------------------------------------------------------------
-	// Mixins read primitives (--color-bg, --color-fg, --color-border,
-	// --shadow). Vocabulary provides the value choices. Components rebind
-	// the primitive on their own scope to pick a different vocabulary
-	// value. Themes override vocabulary at theme :root.
-	// -----------------------------------------------------------------------
-
-	--bg-base:     hsl(var(--color-white));
-	--bg-elevated: var(--bg-base);
-	--bg-sunken:   hsl(var(--color-neutral-100));
-	--bg-recessed: hsl(var(--color-neutral-50));
-
-	--fg-default: hsl(var(--color-neutral-900));
-	--fg-muted:   hsl(var(--color-neutral-500));
-	--fg-subtle:  hsl(var(--color-neutral-400));
-
-	--border-subtle:       hsl(var(--color-neutral-200));
-	--border-strong:       hsl(var(--color-neutral-300));
-	--border-strong-hover: hsl(var(--color-neutral-400));
-
-	--shadow-resting:  var(--shadow-sm);
-	--shadow-floating: var(--shadow-md);
-	--shadow-overlay:  var(--shadow-xl);
-
-	// -- Surface colors — primitives -------------------------------------
-	// Mixins read these four primitives. Vocabulary provides the value
-	// choices (--bg-*, --fg-*, --border-*, --shadow-*). Components rebind
-	// a primitive on their own scope to pick a different vocabulary entry.
-	--color-bg:     var(--bg-base);
-	--color-fg:     var(--fg-default);
-	--color-border: var(--border-subtle);
-	--shadow:       var(--shadow-resting);
-	--color-scrim:  hsl(var(--color-neutral-900) / 0.5);
-
-	// -- Accent -----------------------------------------------------------
-	--color-accent:        hsl(var(--color-primary));
-	--color-accent-fg:     hsl(var(--color-white));
-	--color-accent-tint:         hsl(var(--color-primary-lighter));
-	--color-accent-tint-strong:  hsl(var(--color-primary-light));
-
-	// 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-theme="..."] button[type="submit"], .btn
-	// { --btn-bg: ...; }`) so the nested var() resolves at the button —
-	// otherwise --color-primary freezes at theme :root and the
-	// .success/.error/.warning/.info status cascade breaks. Glass uses
-	// the consumer-scope pattern; see scss/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 surface (neutral default) --------------------------------
-	// Read by @mixin button-base across idle + hover + active. The
-	// neutral default wires here. Accent variants (submit + @mixin btn)
-	// REBIND --btn-* on the consumer element (not at :root) — this
-	// preserves the .success/.error/.warning/.info semantic-color
-	// cascade because var() resolves at the declaration site. A
-	// companion --btn-accent-* surface AT :ROOT would freeze
-	// --color-accent at :root and break that cascade; the fix is
-	// consumer-scoped rebinding, not a parallel :root surface. See
-	// scss/config/mixins/_btn.scss header for the full rationale.
-	--btn-bg:           var(--color-bg);
-	--btn-fg:           var(--color-fg);
-	--btn-border:       var(--border-strong);
-	--btn-bg-hover:     var(--bg-sunken);
-	--btn-fg-hover:     var(--color-fg);
-	--btn-border-hover: var(--border-strong-hover);
-
-	// Button padding tokens
-	--btn-padding-x:    var(--size-sm-up);
-	--btn-padding-y:    var(--size-xs-up);
-
-	// Card padding tokens — roomier than base rhythm; density-reactive via _density.scss
-	--card-padding-y:        var(--size-sm-up);    // 12px dense base
-	--card-padding-x:        var(--size-md);       // 16px dense base
-
-	// Table cell padding tokens — roomier than base rhythm; density-reactive via _density.scss
-	--table-cell-padding-y:  var(--size-sm);       // 8px dense base (DocuFlow th: 9px / td: 10px)
-	--table-cell-padding-x:  var(--size-md);       // 16px dense base
-
-	// -- 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)
+	}
+}