@livenetworks/ashlar 2.1.12 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livenetworks/ashlar",
-  "version": "2.1.12",
+  "version": "2.2.0",
   "description": "LiveNetworks unified frontend library - CSS framework and vanilla JS components",
   "license": "GPL-3.0-or-later",
   "author": "Live Networks",
@@ -45,19 +45,21 @@
     "./dev.css": "./dist/ln-ashlar-dev.css",
     "./dev.js": "./dist/ln-ashlar-dev.js",
     "./theme/*": "./theme/*",
-    "./components/*": "./components/*"
+    "./components/*": "./components/*",
+    "./tailwind.css": "./dist/ln-ashlar-tailwind.css"
   },
   "scripts": {
     "test": "npm run sync:ln-schemas:check && npm run sync:ln-events:check && npm run sync:css-tokens:check && node --test \"tests/*.test.js\"",
     "test:p0": "node --test tests/p0-data-integrity.test.js",
     "test:headless": "node tests/headless/run-all.mjs",
     "dev": "node scripts/build.mjs --watch",
-    "build": "npm run sync:ln-schemas && npm run sync:ln-events && npm run sync:css-tokens && node scripts/build.mjs && npm run build:dev-css && npm run build:demos",
+    "build": "npm run sync:ln-schemas && npm run sync:ln-events && npm run sync:css-tokens && node scripts/build.mjs && npm run build:tailwind && npm run build:dev-css && npm run build:demos",
+    "build:tailwind": "node scripts/build-tailwind.mjs",
     "build:demos": "npm run build:demo-index && npm run build:demo-admin && npm run build:demo-docuflow && npm run build:demo-spa && npm run build:demo-landing && npm run build:demo-corporate",
     "build:dev-css": "sass theme/ln-ashlar-dev.scss demo/dist/ln-ashlar-dev.css --no-source-map --style=compressed",
     "generate:brand-assets": "powershell -ExecutionPolicy Bypass -File scripts/generate-brand-assets.ps1 && node scripts/generate-svg-favicon.mjs",
     "build:demo-index": "sass demo/index.scss demo/index.css --no-source-map --style=compressed",
-    "build:demo-admin": "sass demo/admin/src/admin.scss demo/admin/dist/admin.css --no-source-map --style=compressed && node -e \"const fs = require('fs'); fs.copyFileSync('demo/admin/src/demo.js', 'demo/admin/dist/demo.js')\" && node demo/admin/src/build-pages.mjs",
+    "build:demo-admin": "sass demo/admin/src/admin.scss demo/admin/dist/admin.css --no-source-map --style=compressed && sass demo/admin/src/admin-relaxed.scss demo/admin/dist/admin-relaxed.css --no-source-map --style=compressed && node -e \"const fs = require('fs'); fs.copyFileSync('demo/admin/src/demo.js', 'demo/admin/dist/demo.js')\" && node demo/admin/src/build-pages.mjs",
     "build:demo-docuflow": "sass demo/docuflow/docuflow.scss demo/docuflow/dist/docuflow.css --no-source-map --style=compressed",
     "build:demo-spa": "node demo/spa/build.mjs",
     "build:demo-landing": "sass demo/landing/landing.scss demo/landing/landing.css --no-source-map --style=compressed",
@@ -72,14 +74,22 @@
     "manifest": "node scripts/extract-manifest.mjs",
     "manifest:file": "node scripts/extract-manifest.mjs --output=docs/manifest.txt",
     "generate:llms": "node scripts/generate-llms.mjs",
-    "generate:llms:check": "node scripts/generate-llms.mjs --check"
+    "generate:llms:check": "node scripts/generate-llms.mjs --check",
+    "test:visual": "node tests/headless/visual-run.mjs",
+    "test:perf": "node tests/headless/perf-run.mjs",
+    "test:perf:history": "node tests/headless/perf-run.mjs --history",
+    "test:perf:compare": "node tests/headless/perf-run.mjs --compare",
+    "test:perf:density": "node tests/headless/perf-density.mjs",
+    "test:dual": "node tests/headless/dual-run.mjs"
   },
   "devDependencies": {
     "@tabler/icons": "^3.41.1",
+    "@tailwindcss/cli": "^4.3.3",
     "fake-indexeddb": "^6.2.4",
     "flag-icons": "^7.5.0",
     "puppeteer-core": "^25.1.0",
     "sass-embedded": "^1.83.0",
+    "tailwindcss": "^4.3.3",
     "vite": "^6.0.0"
   }
 }

package/theme/README.md

@@ -0,0 +1,74 @@
+# 🎨 ln-ashlar Theme & CSS Architecture
+
+`ln-ashlar` provides a high-performance visual layer with **Dual CSS Engine Support**:
+1. **Ashlar SCSS (Native):** Semantic class-free, design token-driven stylesheet system optimized for minimal CSSOM invalidation and modern W3C standards.
+2. **Tailwind CSS v4:** Utility-first engine compiling into a standalone bundle (`dist/ln-ashlar-tailwind.css`) with comprehensive layout and interaction parity verified across all 67 demo pages.
+
+---
+
+## 🏛️ Directory Structure
+
+```
+theme/
+├── base/                      # Global HTML5 element resets, typography, and defaults
+├── components/                # Layer 2 component styling (card, table, form, modal, nav, etc.)
+├── config/                    # Design tokens, density scales, color themes, and mixins
+│   ├── mixins/                # Reusable SCSS mixins for semantic styling
+│   ├── _tokens.scss           # Master CSS custom properties (colors, spacing, radius, shadows)
+│   ├── _theme.scss            # Theme definitions (Default, Glass, Flat, Minimal)
+│   └── _density.scss          # Density scale rebinds (compact, default, spacious)
+├── tailwind/                  # Tailwind CSS v4 source definitions
+│   ├── theme.css              # Design token mappings to Tailwind v4 @theme directive
+│   ├── components.css         # Component utility recipes
+│   └── entry.css              # Entrypoint bundle
+├── ln-ashlar.scss             # Master bundle (Core + Theme)
+├── ln-ashlar-relaxed.scss     # Relaxed design bundle (Core + Theme + designs/relaxed/*)
+└── ln-ashlar-theme.scss       # Theme-only visual design system bundle
+```
+
+---
+
+## ⚡ SCSS Performance & Selector Best Practices
+
+To prevent browser style invalidation storms during interactive DOM mutations, all SCSS mixins and components adhere to the following rules:
+
+1. **Consolidate Compound `:has()` Queries via `:is(...)`:**
+   - Within structural mixins (such as `panel-body` in `_card.scss`, `pills` in `_form.scss`, and numeric table cells in `_table.scss`), collapse chained `:has()` checks into a single `:has(> :is(...))` selector rather than authoring sequential `:has()` rules.
+
+2. **Prefer Natural Cascade over `:not(:has(...))`:**
+   - Negative `:not(:has(...))` selectors force the browser layout engine into exhaustive negative ancestor traversals.
+   - Use CSS source-order cascade instead:
+     ```scss
+     // ✅ RECOMMENDED: Natural cascade override
+     &:hover { border-color: var(--color-accent); }
+     &:has(> input:checked) {
+       border-color: var(--color-accent);
+       color: var(--color-accent);
+     }
+     ```
+   - For multi-action stacking (e.g. table header sorting and filtering in `_table.scss`), declare base single-action rules with `:has(:is(...))` and override with double-action `:has(...):has(...)` rather than mutual `:not(:has(...))` exclusions.
+
+3. **Use Logical Properties for Sizing and Spacing:**
+   - Mixins for padding and margin use modern CSS logical properties (`padding-inline`, `padding-block`, `margin-inline`, `margin-block`), reducing generated rules by 50% compared to separate physical properties (`-left`, `-right`, `-top`, `-bottom`).
+
+4. **Scope Container State Checks to Direct Children:**
+   - For container-level state indicators (e.g. navigation item active/hover lines on `li::before`), scope state queries strictly to direct children using `>` (e.g. `li:has(> a:hover)::before`, `li:has(> a.active)::before`). This avoids recursive descendant tree searches while preserving full-item indicator positioning and animations.
+
+---
+
+## 💨 Tailwind CSS v4 Engine
+
+To compile the Tailwind v4 bundle:
+```sh
+npm run build:tailwind
+```
+
+The output bundle is generated at:
+- `dist/ln-ashlar-tailwind.css`
+- `demo/admin/dist/admin-tailwind.css`
+- `demo/dist/ln-ashlar-tailwind.css`
+
+Consumers can toggle between engines dynamically in the browser or via:
+```javascript
+localStorage.setItem('ln-demo-engine', 'tailwind'); // or 'ashlar'
+```

package/theme/base/_global.scss

@@ -22,11 +22,11 @@ body {
 
 a {
 	// Derive hover from --color-accent at this scope. Same hue/saturation,
-	// lightness reduced by 8 (number form — see _btn.scss for the syntax
+	// lightness shifted by --accent-hover-shift (number form — see _btn.scss for the syntax
 	// rationale). Local derivation means a semantic-color parent (.error,
 	// .success, etc.) that rebinds --color-primary cascades to the hover
 	// because var(--color-accent) re-resolves on the anchor element.
-	--color-accent-hover: hsl(from var(--color-accent) h s calc(l - 8));
+	--color-accent-hover: hsl(from var(--color-accent) h s calc(l + var(--accent-hover-shift)));
 
 	color: var(--color-accent);
 	text-decoration: none;

package/theme/base/_reset.scss

@@ -15,3 +15,14 @@ ul, ol {
 html {
 	font-size: 16px;
 }
+
+// Form controls do not inherit typography by default — textarea falls back
+// to the UA monospace face and buttons/inputs to the system UI font.
+button,
+input,
+select,
+textarea {
+	font: inherit;
+	letter-spacing: inherit;
+	color: inherit;
+}

package/theme/components/_app-shell.scss

@@ -13,11 +13,3 @@
 .header-right     { @include app-header-right; }
 .header-actions   { @include app-header-actions; }
 .header-avatar    { @include header-avatar; }
-
-// Lock root scroll exclusively for administrative shells
-html:has(.app-wrapper),
-body:has(.app-wrapper),
-.app-shell {
-	height: 100%;
-	overflow: hidden;
-}

package/theme/components/_form.scss

@@ -71,6 +71,12 @@ $icon-group-test: ':has(> .ln-icon):has(> :is(input[type="text"], input[type="se
 	@include form-input-icon-group-parts;
 }
 
+// ─── Field wrapper ──────────────────────────────────────────────
+
+.form-element {
+	@include form-element;
+}
+
 // ─── Label & Actions ────────────────────────────────────────────
 
 // Non-wrapping labels only — the label sits above/beside its input, not
@@ -138,9 +144,3 @@ search:has(> input[type="search"]) {
 	@include form-validate-errors;
 }
 
-// Any trailing feedback/metadata element inside .form-element automatically gets slot treatment with zero-specificity base styling
-:where(.form-element > :is(input, select, textarea, [data-ln-date-field], search, [class*="group"]) ~ :not(input)) {
-	@include form-slot;
-	color: var(--fg-muted);
-}
-

package/theme/components/_ln-table.scss

@@ -13,6 +13,12 @@
 	@include ln-table-toolbar;
 }
 
+// Toolbar sibling of the table: pin the thead under the toolbar.
+:is(main, section, article):has(> .ln-table__toolbar + :is(table, [data-ln-table])),
+[data-ln-table]:has(> header + table) {
+	@include ln-table-toolbar-stack;
+}
+
 .ln-table__toolbar :is(label, search):has(> input[type="search"]) {
 	@include ln-table-toolbar-search;
 }
@@ -21,9 +27,6 @@
 	@include ln-table-count;
 }
 
-.table-container {
-	@include ln-table-card-mode;
-}
 [data-ln-table] > footer,
 .ln-table__footer {
 	@include ln-table-footer;

package/theme/components/_scrollbar.scss

@@ -5,13 +5,14 @@
 	height: 8px;
 }
 
+// Overlay-style scrollbars: no gutter track; the thumb uses the strong
+// border tone so it stays findable without competing with content.
 ::-webkit-scrollbar-track {
-	--color-bg: var(--bg-sunken);
-	background: var(--color-bg);
+	background: transparent;
 }
 
 ::-webkit-scrollbar-thumb {
-	background-color: var(--color-border);
+	background-color: var(--border-strong);
 	border-radius: 4px;
 	border: 2px solid transparent;
 	background-clip: content-box;
@@ -28,5 +29,5 @@
 
 * {
 	scrollbar-width: thin;
-	scrollbar-color: var(--color-border) var(--bg-sunken);
+	scrollbar-color: var(--border-strong) transparent;
 }

package/theme/components/_sortable.scss

@@ -1,19 +1,19 @@
-@use '../config/mixins' as *;
-
-[data-ln-sortable] {
-	list-style: none;
-	padding: 0;
-	margin: 0;
-
-	> * {
-		transition: box-shadow var(--transition-fast) var(--easing-standard), opacity var(--transition-fast) var(--easing-standard);
-
-		&.ln-sortable--drop-before {
-			box-shadow: inset 0 2px 0 0 var(--color-accent);
-		}
-
-		&.ln-sortable--drop-after {
-			box-shadow: inset 0 -2px 0 0 var(--color-accent);
-		}
-	}
-}
+@use '../config/mixins' as *;
+
+[data-ln-sortable] {
+	list-style: none;
+	padding: 0;
+	margin: 0;
+
+	> * {
+		transition: box-shadow var(--transition-fast) var(--easing-standard), opacity var(--transition-fast) var(--easing-standard);
+
+		&.ln-sortable--drop-before {
+			box-shadow: inset 0 2px 0 0 var(--color-accent);
+		}
+
+		&.ln-sortable--drop-after {
+			box-shadow: inset 0 -2px 0 0 var(--color-accent);
+		}
+	}
+}

package/theme/components/_stat-card.scss

@@ -2,4 +2,5 @@
 
 [data-ln-stat-card] {
 	@include stat-card;
+	@include stat-card-tone;
 }

package/theme/components/_table.scss

@@ -9,8 +9,7 @@ table {
 
 	td.numeric,
 	td.num,
-	td:has(time),
-	td:has([data-ln-number]) {
+	td:has(:is(time, [data-ln-number])) {
 		@include font-tabular;
 	}
 
@@ -26,52 +25,29 @@ table {
 
 .table-container {
 	@include container(table);
-	overflow-x: auto;
-	overscroll-behavior-x: contain;
+	// `clip`, not `auto` — keeps the thead pinned to the page scroller;
+	// narrow containers stack records instead (below).
+	overflow-x: clip;
 
-	@container table (max-width: 640px) {
+	// Narrow container (e.g. a side column on desktop) — same card mode.
+	@include cq-down(md, table) {
 		table { @include table-responsive; }
-
-		.table-row-actions {
-			position: static !important;
-			opacity: 1 !important;
-			visibility: visible !important;
-			pointer-events: auto !important;
-			transform: none !important;
-			background: transparent !important;
-			padding-left: 0 !important;
-			justify-content: flex-end;
-			margin-top: var(--size-xs);
-
-			&::before {
-				display: none !important;
-			}
-		}
 	}
 }
 
 // ─── Shared Column Filter Button ─────────────────────────────────
-// CSS targets the unprefixed structural helper class on the button, NOT the data-ln-* JS
-// hook. .table-filter is a thin binding that mirrors the mixin; a consumer may instead
-// @include table-filter on their own selector (the class is a convenience, not a mandate).
+// Binding of @mixin table-filter to the column-filter hook; the th stack keys on the same attribute.
 // Sort lives in scss/components/_sort.scss — see [data-ln-sort].
 
-.table-filter { @include table-filter; }
-th:hover .table-filter { opacity: 0.7; }
-
-// Active filter — JS-state class set DIRECTLY on the button (self-selector), combined with
-// the structural helper class. Fixes the latent ln-data-table bug: JS toggles
-// .ln-filter-active on the button itself, but the old CSS used a descendant combinator
-// (.ln-filter-active [data-ln-col-filter]) that never matched, so the dot never rendered.
-// See D2.
-.table-filter.ln-filter-active { @include table-filter-active; }
+[data-ln-table-col-filter] { @include table-filter; }
 
 
 
 // ─── Data Table JS-State Classes ───────────────────────────────
 // JS-added state classes only. Row chrome (clickable cursor/hover, action
-// buttons, sticky header) is a CONSUMER concern — applied via semantic
-// selectors in project SCSS, never keyed off the data-ln-* JS hooks.
+// buttons) is a CONSUMER concern — applied via semantic selectors in project
+// SCSS, never keyed off the data-ln-* JS hooks. The sticky header is library
+// default (table-base).
 
 .ln-row-selected {
 	@include table-row-selected;

package/theme/config/_density.scss

@@ -1,33 +1,30 @@
+@use 'mixins/breakpoints' as *;
+
 // ==========================================================================
-// Density — ln-ashlar v2.0
+// Density — ln-ashlar
 // ==========================================================================
-// Inverted density system. The :root default is DENSE (DocuFlow scale:
-// 14px body, 52px header, 232px sidebar). Density goes UP via the
-// [data-density] attribute, mirroring how [data-mode] / [data-theme] works.
+// The :root default is COMFORTABLE (16px body, 44px controls, 56px header,
+// 256px sidebar). Density goes down or up via [data-density]:
 //
-// Activation:
-//   <html>                              ← default: dense (DocuFlow look)
-//   <html data-density="compact">       ← explicit dense handle (same as base)
-//   <html data-density="comfortable">   ← pre-v2 default (16px / roomier)
+//   <html>                              ← default: comfortable
+//   <html data-density="compact">       ← dense DocuFlow scale (14px / 36px)
+//   <html data-density="comfortable">   ← explicit handle (same as default)
 //   <html data-density="spacious">      ← large type, generous padding
-//   <main data-density="compact">       ← scope dense within comfortable page
+//   <table data-density="compact">      ← scope dense within a page
 //
-// Density is an explicit user choice (settings toggle).
-// It is NEVER auto-switched by viewport — viewport breakpoints handle
-// layout, density handles information density inside that layout.
+// _tokens.scss declares the dense values as the raw base; the comfortable
+// block re-binds them at :root, so they surface through
+// [data-density="compact"].
 //
-// What reacts: everything reading --padding-y, --gap, --text-body-*,
-// --text-label-*, --text-title-*, --text-heading-*, --text-display-sm,
-// --lh-*, --app-header-height, --app-sidebar-width, --density-row-h,
-// --btn-padding-y, --input-padding-y.
+// Density is an explicit user choice (settings toggle). It is NEVER
+// auto-switched by viewport; the mobile rhythm block at the end of this
+// file tightens padding/gap at narrow widths independently.
 //
-// Interactive controls (buttons, inputs, pills): density-reactive UPWARD.
-// Base (~38px) = WCAG AA. Comfortable (≥46px) and Spacious (≥54px) = AAA.
-// Controls rebind --btn-padding-y and --input-padding-y in up-tier scopes.
-// See docs-mcp/css/density.md §wcag for the height math.
+// What reacts: the type roles, spatial rhythm, shell geometry, control
+// sizing, and card/table padding. Each tier owns its own type scale.
 //
-// No parallel --density-* token scale. Density overrides existing base
-// tokens at the scope root, exactly like theme color overrides.
+// Interactive controls: compact 36px = WCAG AA; comfortable 44px and
+// spacious 54px = AAA. All controls share --control-line-height.
 // ==========================================================================
 
 :root {
@@ -41,39 +38,18 @@
 }
 
 // ---------------------------------------------------------------------------
-// [data-density="compact"] — explicit handle for the dense base.
-//
-// Identical to :root. Exists so:
-//   (a) a switcher can write a single attribute across all tiers including
-//       returning to base (rather than removing the attribute)
-//   (b) a region inside a comfortable page can be scoped dense:
-//       <table data-density="compact">
+// :root / [data-density="comfortable"] — the default.
 //
-// Rebinds --density-row-h so a compact-scoped region keeps the dense row
-// floor inside a comfortable/spacious page. NOTE: only row-h is restored —
-// full dense region-scoping (type, padding) would re-declare the base
-// surface; deferred. The global switcher returns to base via :root (dense).
-// ---------------------------------------------------------------------------
-[data-density="compact"] {
-	--density-row-h:    2.25rem;  // 36px — restore dense base in scoped context
-}
-
-// ---------------------------------------------------------------------------
-// [data-density="comfortable"] — pre-v2 default, now an explicit opt-in.
-//
-// Restores the roomy 16px / lh 1.6 scale that was the :root default before
-// design-v2. WCAG 2.5.5 AAA: buttons 46px, inputs/pills ≥44px.
-//
-// <html data-density="comfortable">   ← global comfortable
-// <aside data-density="comfortable">  ← scoped comfortable sidebar
+// WCAG 2.5.5 AAA: buttons, inputs and pills 44px.
 // ---------------------------------------------------------------------------
+:root,
 [data-density="comfortable"] {
 
 	// -- Logical rhythm --------------------------------------------------
-	--padding-y:          var(--size-sm);       // 8px (was dense 6px)
-	--gap:                var(--size-sm);       // 8px (was dense 6px)
+	--padding-y:          var(--size-sm);       // 8px
+	--gap:                var(--size-sm);       // 8px
 
-	// -- Body text (restore 16px / 1.6 scale) ----------------------------
+	// -- Body text -------------------------------------------------------
 	--text-body-md:       1rem;
 	--lh-body-md:         1.6;
 
@@ -89,7 +65,7 @@
 	--text-label-md:      0.875rem;
 	--lh-label-md:        1.4;
 
-	--text-label-sm:      0.8125rem;   // 13px (was dense 12px) — form-label, table th
+	--text-label-sm:      0.8125rem;   // 13px — form-label, table th
 	--lh-label-sm:        1.4;
 
 	// -- Caption ---------------------------------------------------------
@@ -112,24 +88,76 @@
 	--text-display-sm:    2.25rem;   --lh-display-sm:  1.15;
 
 	// -- App shell -------------------------------------------------------
-	--app-header-height:  3.5rem;    // 56px (was dense 3.25rem)
-	--app-sidebar-width:  16rem;     // 256px (was dense 14.5rem)
+	--app-header-height:  3.5rem;    // 56px
+	--app-sidebar-width:  16rem;     // 256px
 
 	// -- Row height ------------------------------------------------------
-	--density-row-h:      2.75rem;   // 44px (was dense 2.25rem)
+	--density-row-h:      2.75rem;   // 44px
 
-	// -- Interactive controls — Tailwind / shadcn standard (38px height) ---
-	--btn-padding-y:      var(--size-sm);       // 8px → buttons 38px
+	// -- Interactive controls — WCAG 2.5.5 AAA ≥44px --------------------
+	// Shared control contract: 26px line box + 2×8px + 2px borders = 44px
+	// for buttons, inputs, selects and pills alike.
+	--control-line-height: 1.625rem;            // 26px
+	--btn-padding-y:      var(--size-sm);       // 8px → buttons 44px
 	--btn-padding-x:      var(--size-md);       // 16px
-	--input-padding-y:    var(--size-sm);       // 8px → inputs/selects 38px
+	--input-padding-y:    var(--size-sm);       // 8px → inputs/pills 44px
+
+	// -- Card and table padding ------------------------------------------
+	--card-padding-y:        var(--size-md);       // 16px
+	--card-padding-x:        var(--size-lg);       // 24px
+	--table-cell-padding-y:  var(--size-sm-up);    // 12px
+	--table-cell-padding-x:  var(--size-lg);       // 24px
+}
+
+// ---------------------------------------------------------------------------
+// [data-density="compact"] — the dense DocuFlow scale.
+//
+// Declared after the :root default so it wins on <html>; also scopes a
+// dense region inside a comfortable/spacious page.
+// ---------------------------------------------------------------------------
+[data-density="compact"] {
+	--padding-y:          var(--size-xs-up);    // 6px
+	--gap:                var(--size-xs-up);    // 6px
+
+	--text-body-md:       0.875rem;  --lh-body-md:    1.5;
+	--text-body-sm:       0.8125rem; --lh-body-sm:    1.45;
+	--font-size:          var(--text-body-md);
+	--line-height:        var(--lh-body-md);
+
+	--text-label-md:      0.8125rem; --lh-label-md:   1.4;
+	--text-label-sm:      0.75rem;   --lh-label-sm:   1.4;
+	--text-caption:       0.75rem;   --lh-caption:    1.4;
+
+	--text-title-md:      1rem;      --lh-title-md:   1.3;
+	--text-title-sm:      0.875rem;  --lh-title-sm:   1.3;
+
+	--text-heading-sm:    1.125rem;  --lh-heading-sm: 1.25;
+	--text-heading-md:    1.25rem;   --lh-heading-md: 1.2;
+	--text-heading-lg:    1.75rem;   --lh-heading-lg: 1.15;
+	--text-display-sm:    1.875rem;  --lh-display-sm: 1.1;
+
+	--app-header-height:  3.25rem;   // 52px
+	--app-sidebar-width:  14.5rem;   // 232px
+	--density-row-h:      2.25rem;   // 36px
+
+	// Control contract — 22px line box + 2×6px + 2px = 36px
+	--control-line-height: 1.375rem;
+	--btn-padding-y:       var(--size-xs-up);
+	--btn-padding-x:       var(--size-sm-up);
+	--input-padding-y:     var(--size-xs-up);
+
+	--card-padding-y:        var(--size-sm-up);   // 12px
+	--card-padding-x:        var(--size-md);      // 16px
+	--table-cell-padding-y:  var(--size-sm);      // 8px
+	--table-cell-padding-x:  var(--size-md);      // 16px
 }
 
 // ---------------------------------------------------------------------------
-// [data-density="spacious"] — NEW tier above comfortable.
+// [data-density="spacious"] — the tier above comfortable.
 //
 // For low-vision, touch-primary, or presentation contexts.
 // Body 18px, generous padding, larger shell. WCAG 2.5.5 AAA:
-// buttons 54px, inputs/pills ≥48px.
+// buttons 54px, inputs/pills 54px.
 //
 // <html data-density="spacious">
 // ---------------------------------------------------------------------------
@@ -153,7 +181,7 @@
 	--text-label-md:      1rem;
 	--lh-label-md:        1.5;
 
-	--text-label-sm:      0.9375rem;   // 15px (was dense 12px) — form-label, table th
+	--text-label-sm:      0.9375rem;   // 15px — form-label, table th
 	--lh-label-sm:        1.45;
 
 	// -- Caption ---------------------------------------------------------
@@ -182,10 +210,27 @@
 	// -- Row height ------------------------------------------------------
 	--density-row-h:      3rem;      // 48px
 
-	// -- Interactive controls — WCAG 2.5.5 AAA ≥48px --------------------
-	// btn-padding-y: 2×16px + 20px line-height + 2px borders = 54px
-	// input-padding-y: indirection token read by form-input + pill-outline
-	--btn-padding-y:      var(--size-md);       // 16px → buttons 54px
-	--btn-padding-x:      var(--size-lg);       // 24px — spacious width
-	--input-padding-y:    var(--size-md);       // 16px → inputs/pills ≥48px
+	// -- Interactive controls --------------------------------------------
+	// Shared control contract: 28px line box + 2×12px + 2px borders = 54px
+	--control-line-height: 1.75rem;             // 28px
+	--btn-padding-y:      var(--size-sm-up);    // 12px → buttons 54px
+	--btn-padding-x:      var(--size-lg);       // 24px
+	--input-padding-y:    var(--size-sm-up);    // 12px → inputs/pills 54px
+
+	// -- Card and table padding ------------------------------------------
+	--card-padding-y:        var(--size-lg);       // 24px
+	--card-padding-x:        var(--size-xl);       // 32px
+	--table-cell-padding-y:  var(--size-md);       // 16px
+	--table-cell-padding-x:  var(--size-xl);       // 32px
+}
+
+// ---------------------------------------------------------------------------
+// Mobile rhythm — logical tokens tighten at ≤ md viewport, whatever the
+// density tier (declared last so it stacks on top of every tier).
+// ---------------------------------------------------------------------------
+@include mq-down(md) {
+	:root {
+		--padding-y: var(--size-xs);
+		--gap:       var(--size-xs-up);
+	}
 }