@bsuite/theme 0.10.6 → 0.11.0

package/README.md

@@ -126,6 +126,30 @@ Braden keeps separate corporate identity tokens in `@bsuite/theme/braden-css`: B
 
 WCAG AA compliance: use semantic text tokens (`text-foreground`, `text-muted-foreground`, `text-text-on-primary`, `text-text-on-accent`) rather than raw `text-white`/`text-black`. Dark-surface text is capped at L=0.94 for extended-session comfort.
 
+## Elevation (v0.11.0)
+
+`shadow-elev-0` … `shadow-elev-4` — the suite's card-elevation ramp, and the
+first release in which those classes exist at all. 25 call sites across crm7
+and business-suite-unified, four `CLAUDE.md` files and the canonical
+`bsuite-brand-system` skill had instructed `shadow-elev-*` while no rule
+matched it anywhere; every one computed `box-shadow: none`.
+
+- `shadow-elev-0` is a real reset (`0 0 0 0 transparent`), not the absence of
+  a rule. It is deliberately not `none`, which invalidates Tailwind v4's
+  composite `box-shadow` declaration and takes the focus ring with it.
+- Geometry follows Tailwind's `xs`/`md`/`lg`/`xl`; colour comes from
+  `--shadow-ink-*`, an OKLCH ladder derived from `--shadow-color` and scaled
+  by `--shadow-strength`, rebinding under `.dark`.
+- The same release rebinds Tailwind's own `--shadow-*`, `--inset-shadow-*`,
+  `--drop-shadow-*` and `--text-shadow-*` onto that ink. They ship from
+  Tailwind as `rgb(0 0 0 / a)` — pure black, banned in every role, and
+  invisible to the colour audit because the literal lives in `node_modules`.
+  292 `shadow-sm|md|lg|xl|2xl` call sites across the estate were painting it,
+  and in dark mode painting it invisibly.
+
+Geometry is unchanged, so nothing moves; light mode shifts by a hue-tint only.
+Dark mode changes materially, because dark shadows previously did not render.
+
 ## Text-role contract (v0.6.0)
 
 Six measured tiers — `--role-text-heading`, `--role-text-body`, `--role-text-secondary`, `--role-text-muted`, `--role-text-subtle`, `--role-text-disabled` — each with documented WCAG contrast in both modes. Full numbers + methodology: `docs/TOKEN-MAPPING.md` §8.1.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsuite/theme",
-  "version": "0.10.6",
+  "version": "0.11.0",
   "type": "module",
   "license": "UNLICENSED",
   "publishConfig": {

package/src/css/braden.css

@@ -260,6 +260,33 @@
   --shadow-sm:       0 1px 3px oklch(0.30 0.03 250 / 0.08), 0 1px 2px oklch(0.30 0.03 250 / 0.04);
   --shadow-md:       0 4px 10px -3px oklch(0.30 0.03 250 / 0.10), 0 2px 4px -2px oklch(0.30 0.03 250 / 0.06);
   --shadow-lg:       0 14px 26px -8px oklch(0.28 0.04 250 / 0.14), 0 5px 10px -5px oklch(0.28 0.04 250 / 0.07);
+
+  /* ============================================================
+     SHADOW INK — Corporate. Added 2026-08-12 alongside the elevation ramp.
+     ============================================================
+     braden imports BOTH braden-css and preset-v4.css, so it receives the
+     `shadow-elev-0..4` utilities and the rebound `--shadow-*` namespace.
+     Those resolve through --shadow-ink-*, which lived only in the D2C
+     vars.css — without these four lines every one of them would resolve to
+     an undefined colour, the browser would drop the layer, and the utility
+     would render nothing. That is the exact phantom-utility bug the ramp
+     was added to fix, so shipping it for D2C only would have re-created it
+     here. braden/CLAUDE.md already instructs `shadow-elev-*`.
+
+     The four --shadow-xs/sm/md/lg above are UNTOUCHED. They are corporate's
+     own bespoke soft geometry and remain correct for direct
+     `box-shadow: var(--shadow-md)` call sites; they never fed a Tailwind
+     utility, because a `:root` custom property registers no v4 utility.
+
+     Tint is corporate's own shadow colour, not the D2C navy. Base opacity
+     0.10 keeps the light ramp inside the 0.06-0.14 band the values above
+     already use — "subtle professional shadows, no neon glow". */
+  --shadow-strength:  1;
+  --shadow-color:     oklch(0.30 0.03 250 / 0.10);
+  --shadow-ink-faint: oklch(from var(--shadow-color) l c h / calc(alpha * 0.4 * var(--shadow-strength)));
+  --shadow-ink-soft:  oklch(from var(--shadow-color) l c h / calc(alpha * 0.6 * var(--shadow-strength)));
+  --shadow-ink:       oklch(from var(--shadow-color) l c h / calc(alpha * 1.0 * var(--shadow-strength)));
+  --shadow-ink-deep:  oklch(from var(--shadow-color) l c h / calc(alpha * 1.6 * var(--shadow-strength)));
   --glow-card:       none;
   --glow-card-hover: none;
   --panel-hairline:  transparent;
@@ -337,6 +364,19 @@
   --shadow-sm:           0 1px 3px oklch(0.07 0.01 252 / 0.55);
   --shadow-md:           0 6px 16px -6px oklch(0.07 0.01 252 / 0.6);
   --shadow-lg:           0 18px 34px -12px oklch(0.07 0.01 252 / 0.68);
+
+  /* Corporate dark ink. Re-declared here, not inherited: a var() inside a
+     custom property resolves at the element where it is DECLARED, so the
+     :root ladder would freeze to its light value and every dark shadow
+     would silently be a light-mode shadow. Measured, both a plain alias and
+     a computed form freeze this way. Base 0.70 lands the main layer at 0.56
+     after --shadow-strength, inside the 0.5-0.68 band above. */
+  --shadow-strength:  0.8;
+  --shadow-color:     oklch(0.07 0.01 252 / 0.70);
+  --shadow-ink-faint: oklch(from var(--shadow-color) l c h / calc(alpha * 0.4 * var(--shadow-strength)));
+  --shadow-ink-soft:  oklch(from var(--shadow-color) l c h / calc(alpha * 0.6 * var(--shadow-strength)));
+  --shadow-ink:       oklch(from var(--shadow-color) l c h / calc(alpha * 1.0 * var(--shadow-strength)));
+  --shadow-ink-deep:  oklch(from var(--shadow-color) l c h / calc(alpha * 1.6 * var(--shadow-strength)));
   --glow-card:           0 0 0 1px color-mix(in oklch, var(--braden-gold) 18%, transparent), 0 0 10px -4px color-mix(in oklch, var(--braden-gold) 20%, transparent);
   --glow-card-hover:     0 0 0 1px color-mix(in oklch, var(--braden-gold) 30%, transparent), 0 0 16px -4px color-mix(in oklch, var(--braden-gold) 32%, transparent);
   --panel-hairline:      color-mix(in oklch, var(--braden-gold) 26%, transparent);

package/src/css/vars.css

@@ -77,8 +77,28 @@
   --light-bg-tertiary:  oklch(0.963 0.003 228.9);
   /* bg-panel. theme-audit-ok: prose. Was oklch(1 0 0.5) — pure white, and since --card and
      --popover bridge to it, every shadcn card and popover in all five D2C
-     apps rendered pure white in light mode from this one line. */
-  --light-bg-accent:    oklch(0.994 0.002 260);
+     apps rendered pure white in light mode from this one line.
+
+     2026-08-10: that first fix moved it to oklch(0.994) — 0.6 lightness points
+     off pure white. It passed the audit, which matches on literal white, and it
+     did not pass the operator, who looked at a rendered page and said "pure
+     white displayed, which is forbidden". He was right: 0.6 points is below any
+     perceptual threshold, so the panel still READ as white even though it no
+     longer WAS white. A colour rule enforced by string match will keep accepting
+     values like that.
+
+     Now oklch(0.98 0.006 260) — 2.0 points below white and 1.9 above
+     --light-bg-primary (0.961), so the panel reads as a raised surface from both
+     directions. Three times the chroma of the old value, which is what actually
+     stops it reading as white: at this lightness the tint does more work than
+     the lightness step.
+
+     CHOSEN FROM THE CONTRACT, NOT INVENTED. The first attempt here used
+     oklch(0.976 0.003 260) and the palette gate rejected it — correctly. Only
+     colours in packages/theme/docs/d2c-theme-source-of-truth.html are permitted
+     (operator ruling 2026-08-03): the document is the source of truth, not the
+     code. This value is already in it. */
+  --light-bg-accent:    oklch(0.98 0.006 260);
 
   /* D2C light text scale — hue 260 (cool blue-grey), capped L=0.22.
      Measured WCAG contrast vs --light-bg-primary oklch(0.961 0 0.5), OKLCH ->
@@ -352,6 +372,57 @@
   --glow-strength:   0.4;
   --shadow-strength: 1;
 
+  /* ============================================================
+     SHADOW INK — the paint every elevation is made of.
+     ============================================================
+     Added 2026-08-12. Until now --shadow-strength had ZERO consumers
+     anywhere in the monorepo or the six apps: a dial wired to nothing.
+     The elevation ramp in preset-v4.css is now the thing it turns.
+
+     WHY A TOKEN AND NOT A LITERAL PER SHADOW
+     theme-audit-ok: prose. Quoting the upstream default this ink replaces.
+     Tailwind's own shadow scale is built on `rgb(0 0 0 / a)` — pure black,
+     which the contract bans in EVERY role, alpha forms included. That ban
+     was silently unenforced for shadows because the value lives inside
+     Tailwind's dist, not in our source, so no scanner here could ever see
+     it. preset-v4.css now rebinds the whole --shadow-* namespace onto this
+     ink, which is how the ban starts applying to the 292 `shadow-sm/md/lg`
+     call sites that were painting pure black.
+
+     --shadow-color carries BOTH the hue and the mode's BASE opacity. The
+     ladder below multiplies that base; `alpha` in relative-colour syntax
+     reads it back, so one token sets a mode's whole shadow density and the
+     four steps keep their relationship to each other.
+
+     WHY THE BASE DIFFERS SO MUCH BETWEEN MODES (0.10 vs 0.70)
+     A shadow is only visible as a difference from the surface under it. In
+     light mode the surface is L 0.96 and the ink is L 0.166, so 10% alpha
+     already reads. In dark mode the surface IS L 0.166 — ink at 10% would
+     be invisible, which is exactly what shipped. The dark ink therefore
+     goes BELOW the page (L 0.08) and much denser. These are not invented
+     numbers: they are the values crm7 and business-suite-unified had each
+     hand-tuned in their own local copies of this ramp, reconciled.
+
+     NOT pure black at either end — L 0.166 is the estate's near-black
+     (--dark-bg-primary), L 0.08 the contract's deepest surface tone. Both
+     are hue-matched to the surface family (~268), so a shadow reads as the
+     page's own shade rather than a grey hole punched in it.
+
+     ⚠ THE FOUR STEPS ARE RE-DECLARED VERBATIM UNDER .dark, AND MUST BE.
+     This looks like duplication begging to be removed. It is not. A var()
+     inside a custom property is substituted at the element where THAT
+     PROPERTY is declared, and the resolved value is what inherits. Declared
+     only here, --shadow-ink resolves against :root's --shadow-color — the
+     LIGHT one — and every .dark descendant inherits that already-resolved
+     light value. Measured: with the ladder at :root alone, all five
+     elevations rendered identical oklch(0.166 … / 0.1) in dark mode.
+     Deleting the .dark copy silently restores that bug. */
+  --shadow-color:     oklch(0.166 0.026 269.4 / 0.10);
+  --shadow-ink-faint: oklch(from var(--shadow-color) l c h / calc(alpha * 0.4 * var(--shadow-strength)));
+  --shadow-ink-soft:  oklch(from var(--shadow-color) l c h / calc(alpha * 0.6 * var(--shadow-strength)));
+  --shadow-ink:       oklch(from var(--shadow-color) l c h / calc(alpha * 1.0 * var(--shadow-strength)));
+  --shadow-ink-deep:  oklch(from var(--shadow-color) l c h / calc(alpha * 1.6 * var(--shadow-strength)));
+
   /* ============================================================
      CARD SURFACE GLOW — subtle neon separation, dark mode only.
      Light mode keeps the existing border-only treatment (--role-border);
@@ -496,6 +567,24 @@
   --glow-strength:   0.6;
   --shadow-strength: 0.8;
 
+  /* Shadow ink for the dark surface. Only the SOURCE rebinds — the four
+     --shadow-ink-* steps are declared once at :root and resolve per element
+     through this token and --shadow-strength, so they follow .dark for free.
+     L 0.08 sits BELOW --dark-bg-primary (L 0.166); a shadow at or above the
+     page's own lightness is not a shadow. Base opacity 0.70, which after
+     --shadow-strength 0.8 puts the main layer at 0.56 — inside the 0.5-0.8
+     band crm7 and BSU had each arrived at independently.
+
+     The four steps below are textually identical to their :root twins and
+     are NOT redundant — see the substitution-timing note at the :root
+     declaration. Only --shadow-color above differs; the ladder is repeated
+     so it re-resolves against it. */
+  --shadow-color:     oklch(0.08 0.02 268 / 0.70);
+  --shadow-ink-faint: oklch(from var(--shadow-color) l c h / calc(alpha * 0.4 * var(--shadow-strength)));
+  --shadow-ink-soft:  oklch(from var(--shadow-color) l c h / calc(alpha * 0.6 * var(--shadow-strength)));
+  --shadow-ink:       oklch(from var(--shadow-color) l c h / calc(alpha * 1.0 * var(--shadow-strength)));
+  --shadow-ink-deep:  oklch(from var(--shadow-color) l c h / calc(alpha * 1.6 * var(--shadow-strength)));
+
   /*
    * Card glow — subtle neon separation for card surfaces, dark mode only.
    * Derived from the app's accent colour (--app-accent, falling back to

package/src/preset-v4.css

@@ -205,6 +205,100 @@
   --font-display: var(--font-display);
   --font-mono:    var(--font-mono);
 
+  /* ============================================================
+     ELEVATION — `shadow-elev-0` .. `shadow-elev-4`
+     ============================================================
+     Added 2026-08-12. Before this, `shadow-elev-*` was a PHANTOM: 25 call
+     sites across crm7 and business-suite-unified, four CLAUDE.md files and
+     the canonical bsuite-brand-system skill all instructed it, and no rule
+     existed anywhere to match. Every one of them computed
+     `box-shadow: none`. Cards drawn as elevated had no elevation.
+
+     crm7 and BSU had each noticed and each written `--shadow-elev-0..4` into
+     their own `:root` — but a `:root` custom property registers no Tailwind
+     v4 utility, so the class still did not exist. Two divergent copies of the
+     ramp, both inert. They are now redundant and should be deleted from both
+     apps (see the rollout note in the PR); this block is the single source.
+
+     WHY DEFINE IT RATHER THAN MIGRATE THE CALL SITES
+     The alternative was rewriting 25 sites onto `shadow-sm/md/lg`. That scale
+     block exists to override; the value is Tailwind's, not ours.
+     theme-audit-ok: prose — the next line quotes the upstream default.
+     is Tailwind's default, which is `rgb(0 0 0 / a)` — the pure black the
+     contract bans in every role. Migrating would have moved working-as-
+     intended markup onto a banned value, and left the docs to be rewritten
+     too. A five-step ramp with an explicit 0 is also the right primitive for
+     a card system whose cards are draggable and resizable: "resting" needs a
+     name, not the absence of a class.
+
+     GEOMETRY is Tailwind's xs/md/lg/xl, which is what crm7 and BSU had both
+     chosen. COLOUR is --shadow-ink-* (vars.css): OKLCH, hue-matched to the
+     surface, never pure black, and scaled by --shadow-strength in both modes.
+
+     `@theme inline`, per this file's doctrine, for a second reason here: the
+     apps still carry their own `:root --shadow-elev-*`. Plain `@theme` would
+     emit ours at :root too, where the app's later copy would silently win and
+     the package would appear to have no effect. `inline` puts the resolved
+     value inside the utility, out of reach of that collision.
+
+     elev-0 is `0 0 0 0 transparent` and NOT `none`. `none` inside the v4
+     composite (`box-shadow: var(--tw-inset-shadow), …, var(--tw-shadow)`)
+     makes the whole declaration invalid, so the browser drops it — taking
+     --tw-ring-shadow with it. Measured: `shadow-elev-0 ring-2` rendered NO
+     FOCUS RING. Tailwind's own `shadow-none` sidesteps this with `0 0 #0000`;
+     `transparent` is the same trick without a pure-black alpha form. */
+  --shadow-elev-0: 0 0 0 0 transparent;
+  --shadow-elev-1: 0 1px 2px 0 var(--shadow-ink-soft);
+  --shadow-elev-2: 0 4px 6px -1px var(--shadow-ink), 0 2px 4px -2px var(--shadow-ink-soft);
+  --shadow-elev-3: 0 10px 15px -3px var(--shadow-ink), 0 4px 6px -4px var(--shadow-ink-soft);
+  --shadow-elev-4: 0 20px 25px -5px var(--shadow-ink), 0 8px 10px -6px var(--shadow-ink-faint);
+
+  /* ------------------------------------------------------------
+     Tailwind's OWN shadow scale, rebound onto the same ink.
+     ------------------------------------------------------------
+     Not cosmetic. `--shadow-*`, `--inset-shadow-*`, `--drop-shadow-*` and
+     theme-audit-ok: prose — the next line quotes the upstream default.
+     `--text-shadow-*` ship from Tailwind as `rgb(0 0 0 / a)`, and 292
+     `shadow-sm|md|lg|xl|2xl` call sites across the five D2C apps and
+     packages/ were painting exactly that. Pure black is banned in every
+     role, alpha forms included — and the theme-conformance scanner could
+     never catch these, because the literal is in node_modules, not in any
+     file it reads. Same class of blind spot as the HSL sidebar tokens.
+
+     In dark mode this is also a correctness fix, not a tint: black at 10%
+     alpha over an L 0.166 navy page is invisible, so every one of those 292
+     sites had no shadow in dark mode at all.
+
+     GEOMETRY IS UNCHANGED from Tailwind's defaults, so nothing shifts
+     position; only the paint changes. The one deliberate departure is 2xl,
+     which drops from 0.25 to 0.16 base alpha (--shadow-ink-deep): at a 50px
+     blur, contract ink at Tailwind's density reads as a smudge rather than
+     a lift. */
+  --shadow-2xs: 0 1px var(--shadow-ink-soft);
+  --shadow-xs:  0 1px 2px 0 var(--shadow-ink-soft);
+  --shadow-sm:  0 1px 3px 0 var(--shadow-ink), 0 1px 2px -1px var(--shadow-ink);
+  --shadow-md:  0 4px 6px -1px var(--shadow-ink), 0 2px 4px -2px var(--shadow-ink);
+  --shadow-lg:  0 10px 15px -3px var(--shadow-ink), 0 4px 6px -4px var(--shadow-ink);
+  --shadow-xl:  0 20px 25px -5px var(--shadow-ink), 0 8px 10px -6px var(--shadow-ink);
+  --shadow-2xl: 0 25px 50px -12px var(--shadow-ink-deep);
+
+  --inset-shadow-2xs: inset 0 1px var(--shadow-ink-soft);
+  --inset-shadow-xs:  inset 0 1px 1px var(--shadow-ink-soft);
+  --inset-shadow-sm:  inset 0 2px 4px var(--shadow-ink-soft);
+
+  --drop-shadow-xs:  0 1px 1px var(--shadow-ink-soft);
+  --drop-shadow-sm:  0 1px 2px var(--shadow-ink);
+  --drop-shadow-md:  0 3px 3px var(--shadow-ink);
+  --drop-shadow-lg:  0 4px 4px var(--shadow-ink);
+  --drop-shadow-xl:  0 9px 7px var(--shadow-ink);
+  --drop-shadow-2xl: 0 25px 25px var(--shadow-ink-deep);
+
+  --text-shadow-2xs: 0px 1px 0px var(--shadow-ink);
+  --text-shadow-xs:  0px 1px 1px var(--shadow-ink-deep);
+  --text-shadow-sm:  0px 1px 0px var(--shadow-ink-soft), 0px 1px 1px var(--shadow-ink-soft), 0px 2px 2px var(--shadow-ink-soft);
+  --text-shadow-md:  0px 1px 1px var(--shadow-ink), 0px 1px 2px var(--shadow-ink), 0px 2px 4px var(--shadow-ink);
+  --text-shadow-lg:  0px 1px 2px var(--shadow-ink), 0px 3px 2px var(--shadow-ink), 0px 4px 8px var(--shadow-ink);
+
   /* ============================================================
      ANIMATIONS
      ============================================================ */