@djangocfg/ui-core 2.1.460 → 2.1.463

package/src/styles/README.md

@@ -1,542 +1,106 @@
-# Tailwind CSS v4 Styles Guide
+# ui-core styles
 
-CSS architecture for `@djangocfg/ui-core` — **Tailwind v4** with semantic tokens, presets, and macOS-style glass utilities.
+`@djangocfg/ui-core` owns the semantic CSS token contract used by every
+frontend. CSS is the single source of truth for colors, typography, radius,
+status surfaces, charts, and sidebar tokens.
 
-## Directory layout
+## Layout
 
-```
+```text
 styles/
-├── full.css               # Golden path (recommended) — Tailwind + tokens + base + utilities, cascade-layer-safe
-├── index.css              # Plain entry (no Tailwind, unlayered) — you own layer ordering
-├── theme.css              # Imports tokens.css → animations → light → dark
-├── base.css               # Resets + `*` border-color + body bg/color + radius scale + native focus-outline reset
-├── utilities.css          # Custom utilities entry — imports utilities/*
-│   └── utilities/         # display · divider · overlay · controls · step · animations · glass · marquee
-├── sources.css            # @source directives for monorepo class detection
-├── palette/               # JS-readable color access (Canvas/SVG/Mermaid)
-└── theme/
-    ├── tokens.css         # @theme inline { --color-X: var(--X) } + @theme { spacing/blur/z }
-    ├── light.css          # :root — full hsl(...) values
-    ├── dark.css           # .dark — full hsl(...) values
-    └── animations.css     # @keyframes (float, blob, morph, …)
-
-presets/
-├── build.ts               # buildThemeStyleSheet({preset}) → CSS string
-├── types.ts               # ThemeStylePresetId, ThemeCssVarMap
-├── presets.ts             # THEME_STYLE_PRESETS, THEME_STYLE_PRESET_ORDER
-└── themes/                # 8 preset definitions (see Presets section)
-```
-
-## Token format (Tailwind v4 `@theme inline` pattern)
-
-Tokens live in `:root` / `.dark` as **fully-wrapped CSS colors**, and `@theme inline` maps them by reference:
-
-```css
-:root  { --background: hsl(0 0% 94%); }
-.dark  { --background: hsl(0 0% 4%); }
-
-@theme inline { --color-background: var(--background); }
-```
-
-This makes opacity modifiers (`bg-card/40`, `border-foreground/20`) resolve through `color-mix(in oklab, …)` — they work for every semantic token, no helpers needed.
-
-> **Do NOT wrap tokens in `hsl(var(--X))`.** Tokens are already full colors, so `hsl(hsl(...))` is invalid and falls back to the default. Use `var(--X)` or `color-mix(in oklab, var(--X) N%, transparent)` for manual opacity.
-
-> **Do NOT set a token to a bare HSL triplet.** The utilities read the token
-> **raw** (`.bg-muted { background-color: var(--muted) }`), so `--muted: 0 0% 10%`
-> resolves to the *string* `"0 0% 10%"` — not a color — and the declaration is
-> silently dropped: **transparent fills + white-fallback borders.** Always write
-> the full color: `--muted: hsl(0 0% 10%)`. This bites most often when a component
-> overrides tokens **inline** (e.g. an old `ForceTheme` wrapper). If part of a page
-> has vanished backgrounds / white borders, that's this — see
-> [`../theme/TROUBLESHOOTING.md`](../theme/TROUBLESHOOTING.md) and prefer
-> `ThemeOverride` over inline token maps.
-
-## Semantic tokens — never use raw color scales
-
-**Rule:** never write `bg-amber-500`, `text-green-700`, `border-gray-200`. Use semantic tokens — they adapt to both themes and to whatever preset is active.
-
-### Base tokens
-
-| Class | Token | Purpose |
-|---|---|---|
-| `bg-background` / `text-foreground` | `--background` / `--foreground` | Page surface + body text |
-| `bg-card` / `text-card-foreground` | `--card` | Card surface (elevated over background) |
-| `bg-popover` / `text-popover-foreground` | `--popover` | Floating menus, tooltips, dropdowns |
-| `bg-muted` / `text-muted-foreground` | `--muted` | Subtle surface (input rest, chips, secondary text) |
-| `bg-accent` / `text-accent-foreground` | `--accent` | Hover + selected surface — **neutral gray** (no brand tint), quiet like macOS/Claude |
-| `bg-primary` / `text-primary-foreground` | `--primary` | Brand CTA (filled buttons, links) — cyan |
-| `bg-secondary` / `text-secondary-foreground` | `--secondary` | Neutral filled controls |
-| `bg-destructive` / `text-destructive-foreground` | `--destructive` | Error / delete filled controls |
-| `border-border` | `--border` | **Outlines only** — card frames, control/input edges. *Not* for separators (see Presets § Border vs divider) |
-| `border-divider` / `.divider-b` / `bg-divider` | `--divider` | **All separators** — columns, header `border-b`, list rows, resize handles. A soft hairline (translucent on dark themes) so the chrome never reads as a heavy grid |
-| `bg-overlay` | `--overlay` | Modal scrim / backdrop behind dialogs, drawers, sheets — black scrim in both themes (the token owns the opacity), **plus** a `backdrop-filter` frost via `--overlay-blur` (`utilities/overlay.css` augments this same class) |
-| `bg-input` | `--input` | Input **fill** — a notch off the panel so fields read as real controls (not flush holes). The input *border* uses `--border`, not `--input` |
-| `ring-ring` | `--ring` | Focus rings, selected outlines — **blue** (system-accent feel), independent of the cyan brand |
-
-### Status surface tokens (light + dark)
-
-Each status has the full 4-token set in **both** themes for banners and alerts:
-
-| Role | Class | Token |
-|---|---|---|
-| Icon / accent | `text-warning` | `--warning` |
-| Banner background | `bg-warning-background` | `--warning-background` |
-| Readable text | `text-warning-foreground` | `--warning-foreground` |
-| Border ring | `border-warning-border` | `--warning-border` |
-
-Available statuses: **`warning`** · **`success`** · **`destructive`** · **`info`**. Reference consumers: `feedback/banner`, `specialized/copy`, `forms/button-download`, `data/status`, `data/stat`.
-
-```tsx
-<div className="flex items-center gap-3 rounded-md border border-warning-border/40
-                bg-warning-background px-3 py-2 text-xs text-warning-foreground">
-  <Icon className="h-4 w-4 text-warning" />
-  <span>You're on a preview plan.</span>
-</div>
-```
-
-#### On-fill text — `*-foreground` vs `on-*` (read this before styling a badge)
-
-There are **two** text tokens per status and they are NOT interchangeable:
-
-| Token | Class | Sits on | Use for |
-|---|---|---|---|
-| `--{status}-foreground` | `text-success-foreground` | the tinted **`*-background`** | banner / alert copy (a *colored* tint) |
-| `--on-{status}` | `text-on-success` | the **solid `*` fill** | text/icon on a filled badge, unread pill, filled chip |
-
-`*-foreground` is a *status-colored* tint tuned for the faint banner surface — on the solid fill it produces **green-text-on-green-fill** (unreadable). `on-*` is a near-black / near-white contrast ink (the WhatsApp/Telegram pattern: dark text on the green pill) that meets WCAG AA against the fill in both themes.
-
-```tsx
-{/* ✅ unread count pill — dark ink on the green fill */}
-<span className="rounded-full bg-success px-2 py-0.5 text-xs font-semibold text-on-success">
-  {unread}
-</span>
-
-{/* ❌ green-on-green — *-foreground is for banners, not the fill */}
-<span className="bg-success text-success-foreground">{unread}</span>
-```
-
-On-fill tokens exist for **`success`** · **`warning`** · **`info`** · **`destructive`** in both themes. (`--primary-foreground` / `--secondary-foreground` / `--destructive-foreground` already play the on-fill role for those base fills — they're genuine contrast colors, not tints, so no `on-*` is needed for them.) The base `on-*` is a near-black; a preset only re-declares it when it retints a fill dark enough that near-black fails — e.g. **`windows`** light mode sets `on-success` / `on-info` to white because Fluent's light green/blue fills are very dark.
-
-The **brand presets** (`macos` / `ios` / `windows` / `django-cfg`) retint the full
-status set to their own canvas, so banners read correctly on their custom
-backgrounds. The **modifier presets** (`soft` / `dense` / `high-contrast`) and
-`default` inherit the base status surfaces. Either way the four-token set is
-always defined, so `bg-warning-background` etc. are safe everywhere. For a fully
-preset-agnostic surface you can still derive from the base color with opacity:
-
-```tsx
-<div className="rounded-md border border-warning/30 bg-warning/10 text-warning">…</div>
-```
-
-### Code & sidebar tokens
-
-| Class | Purpose |
-|---|---|
-| `bg-code` / `text-code-foreground` / `border-code-border` | Code block panels (markdown fences, terminal blocks) |
-| `bg-code-inline` / `text-code-inline-foreground` | Inline `<code>` chips |
-| `bg-sidebar` / `text-sidebar-foreground` / `border-sidebar-border` | App sidebar chrome |
-| `bg-sidebar-accent` / `text-sidebar-accent-foreground` | Sidebar hover state |
-
-### Chart tokens (categorical palette)
-
-`--chart-1 … --chart-5` are the categorical series colors (chart-1 = brand hue).
-Like every color token they are **fully-wrapped `hsl(...)`** and bound to
-Tailwind via `--color-chart-*` in `tokens.css`, so the utilities work with
-opacity modifiers:
-
-```tsx
-<div className="bg-chart-1" />          {/* solid */}
-<div className="bg-chart-3/40" />       {/* 40% via color-mix */}
-<span className="text-chart-2" />
-```
-
-For Recharts / SVG / Canvas, pass the variable directly — **never** wrap it:
-
-```tsx
-<Bar fill="var(--chart-1)" />          {/* ✅ */}
-<Bar fill="hsl(var(--chart-1))" />     {/* ❌ hsl(hsl(...)) — invalid */}
-```
-
-> **JIT-scan gotcha (charts/status).** `bg-chart-${n}` / `bg-${status}-background`
-> built from template literals are invisible to Tailwind's static scanner —
-> only literal classes get a CSS rule. Use literal class names (or inline
-> `style={{ background: 'var(--chart-N)' }}`) when the index is dynamic.
-
-### Typography tokens
-
-`--font-sans` / `--font-mono` and the size scale (`--font-size-xs … -xl`,
-`--line-height-base`, `--letter-spacing-base`) live in `base.css` and are
-**overridable per preset** (e.g. `macos` → SF Pro, `windows` → Segoe UI
-Variable). `tokens.css` bridges the size scale onto Tailwind's `--text-*` tokens,
-so `font-sans` / `font-mono` and `text-xs … text-xl` follow the active preset
-instead of Tailwind's hardcoded defaults. `body` applies font-sans + base
-size/line-height/tracking directly.
-
-#### The font-size scale → `text-*` bridge (one source of truth)
-
-The size tokens are plain rem values. The `macos` preset
-(`presets/themes/macos.ts`) sets them to the Apple HIG point scale:
-
-| Token | macos value | px (@1×) | Used for |
-|---|---|---|---|
-| `--font-size-xs` | `0.6875rem` | 11px | captions, timestamps |
-| `--font-size-sm` | `0.75rem` | 12px | footnotes, secondary labels |
-| `--font-size-base` | `0.8125rem` | 13px | HIG default body |
-| `--font-size-lg` | `0.9375rem` | 15px | subheadings |
-| `--font-size-xl` | `1.0625rem` | 17px | titles, nav bar |
-
-**The key fact:** Tailwind's `text-*` utilities don't read their own hardcoded
-sizes — they're bridged to these vars in `tokens.css` via `@theme inline`:
-
-```css
-@theme inline {
-  --text-xs:   var(--font-size-xs);
-  --text-sm:   var(--font-size-sm);
-  --text-base: var(--font-size-base);
-  --text-lg:   var(--font-size-lg);
-  --text-xl:   var(--font-size-xl);
-}
-```
-
-So `--font-size-*` is the **single source of truth** for text sizing: change one
-var and **every** `text-sm` / `text-base` / … in that scope re-sizes uniformly —
-no per-component edits, no chasing `text-[15px]` literals across the tree.
-
-#### Override recipe (a) — global bump via `buildThemeStyleSheet`
-
-To lift the whole UI a notch (e.g. a desktop consumer that wants 15px body),
-pass `vars` alongside the preset — they merge on top of the preset's values per
-mode (`buildThemeStyleSheet` → `mergeLayer`), emitting `:root` (light) and
-`.dark` blocks. Every `text-*` utility moves with them:
-
-```ts
-import { buildThemeStyleSheet } from '@djangocfg/ui-core/styles/presets';
-
-const css = buildThemeStyleSheet({
-  preset: 'macos',
-  vars: {
-    light: { 'font-size-base': '0.9375rem', 'font-size-sm': '0.8125rem' },
-    dark:  { 'font-size-base': '0.9375rem', 'font-size-sm': '0.8125rem' },
-  },
-});
-// inject `css` after ui-core/styles (cmdop does exactly this)
-```
-
-> Keys are the bare token name (no `--` prefix); `buildThemeStyleSheet` adds it.
-
-#### Override recipe (b) — scoped bump on a selector
-
-To re-size only a subtree, re-declare the font-size vars on a selector. The
-bridge re-points `text-*` for everything inside it — no preset rebuild:
-
-```css
-.compact-panel {
-  --font-size-base: 0.75rem;   /* 12px */
-  --font-size-sm:   0.6875rem; /* 11px */
-}
-```
-
-**Prefer either recipe over per-component `text-[15px]` hacks** — those drift
-from the scale and don't follow the preset or theme.
-
-## Radius tokens
-
-The radius **scale** (`--radius`, `--radius-sm`, …) is theme-independent and lives in `base.css`; presets that set a semantic `radius` regenerate the scale via `presets/build.ts`. A few named radii are fixed defaults (default preset only):
-
-| Token | Value | Used by |
-|---|---|---|
-| `--radius-control` | `0.625rem` | **Interactive controls** (inputs, nav items, search, value chips) — one shared corner so they round consistently. Class: `.rounded-control` |
-| `--radius-dialog` | `1rem` | Dialog panels. Applied at **all** sizes (was `sm:`-gated, which left phones square) |
-| `--radius-popover` | `0.75rem` | Popovers / menus |
-
-## Focus rings (Vercel / Linear pattern)
-
-Inputs use a **crisp thin accent outline**, not a blurry halo: the border turns `--ring` (blue) plus a tight `ring-1 ring-ring`, `:focus-visible` only.
-
-```
-focus-visible:border-ring focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring
-```
-
-The native browser focus outline (often white/auto, which used to pierce through on click) is reset app-wide in `base.css`:
+├── css/                     # complete CSS layer
+│   ├── full.css             # Tailwind v4 + tokens + base + utilities
+│   ├── index.css            # unlayered compatibility entry
+│   ├── globals.css          # backwards-compatible global entry
+│   ├── base.css             # resets and document defaults
+│   ├── sources.css          # Tailwind @source directives
+│   ├── theme.css            # token/animation aggregator
+│   ├── theme/               # tokens, light, dark, animations
+│   ├── utilities.css        # ui-core utility aggregator
+│   ├── utilities/            # focused utility modules
+│   └── presets/              # authoritative static preset token sheets
+│       ├── default.css
+│       ├── django-cfg.css
+│       ├── ios.css
+│       ├── macos.css
+│       ├── windows.css
+│       ├── soft.css
+│       ├── dense.css
+│       └── high-contrast.css
+├── palette/                 # runtime readers of computed CSS variables
+└── presets/                  # TypeScript names/order only
+    ├── index.ts
+    ├── presets.ts
+    └── types.ts
+```
+
+There are deliberately no TypeScript color maps and no runtime CSS generator.
+Do not add a second palette in React or TypeScript.
+
+## Consumer contract
+
+Import the golden path first, then exactly one product preset:
 
 ```css
-:where(input, textarea, select, button, a, [tabindex], [role="button"], [contenteditable]):focus { outline: none; }
-```
-
-So every interactive control relies on its own `focus-visible:ring-*` — keyboard a11y is preserved, the stray native outline is gone. The single source for input styling is `INPUT_CLASS` / `inputClass(size)` exported from `components/forms/input` and **reused by `Editable`**, so standalone inputs and inline-edits focus identically.
-
-## Scan-independent utility classes
-
-Some classes are authored as **plain CSS** in `utilities/*.css` (not Tailwind utilities):
-
-| Class | File | Why plain CSS |
-|---|---|---|
-| `.divider-b` / `.divider-t` | `utilities/divider.css` | Hairline via `--divider` |
-| `.bg-overlay` (frost) | `utilities/overlay.css` | Adds `backdrop-filter: blur(var(--overlay-blur))` onto Tailwind's own `bg-overlay` so modal backdrops frost the page. Tune via `--overlay-blur` (base.css, default 2px; `0px` disables). Attached to `.bg-overlay` — not a new class — so overlays and host forks that render `bg-overlay` all get it |
-| `.rounded-control` | `utilities/controls.css` | Shared control radius |
-
-> **JIT-scan gotcha.** Tailwind's content scan covers `ui-core/src` but **not always every consumer package** (e.g. the `layouts` package source isn't always scanned by Storybook/apps). A *new* arbitrary Tailwind class used **only** in a consumer (`border-zinc-500/25`, `border-foreground/[0.12]`, `rounded-[var(--x)]`) then produces **no CSS rule** and silently falls back to the global `* { border-color: var(--border) }` — the class is in the DOM but the computed color is wrong. **Fix pattern:** for any token-driven visual that consumers need, add a plain `.class` in `ui-core/styles/utilities/*` and `@import` it, then use that class downstream. Don't invent new Tailwind classes in the `layouts` package.
-
-## Theme presets — 8 production-ready
-
-Two families, with different coverage by design:
-
-- **Brand / OS presets** declare a *full* token set — colors, sidebar, charts,
-  status surfaces, divider, and (macos/windows) typography — so the identity is
-  self-contained and survives layering over any base.
-- **Modifier presets** override only the chrome they're about (radius / borders /
-  contrast) and **inherit** brand colors, charts, and status from whatever is
-  active beneath them — so they compose (`django-cfg` + `dense`, etc.).
-
-| ID | Family | Use case |
-|---|---|---|
-| `default` | base | Default ui-core theme — cyan brand |
-| `django-cfg` | brand | Brand identity — brand-washed accent/sidebar + on-brand `info` |
-| `macos` | brand | Pixel-accurate Apple HIG (Sequoia / Tahoe 26) — SF Pro, Wails/Electron desktop |
-| `ios` | brand | iOS app feel — 0.75rem radius, systemBlue, iOS status colors |
-| `windows` | brand | Microsoft Fluent 2 — Segoe UI Variable, 0.375rem radius |
-| `soft` | modifier | Larger radius (1rem) — friendly marketing surfaces |
-| `dense` | modifier | Smaller radius (0.25rem) — data-heavy admin UIs |
-| `high-contrast` | modifier | A11y boost — stronger borders, harder text, pure canvas |
-
-#### Border vs divider — outline weight vs translucent hairline
-
-`--border` and `--divider` are **two different roles**, not two shades of one:
-
-- **`--border`** — an OUTLINE: opaque, control-weight. Card frames, input
-  edges, panel outlines. Use `border-border` / `border border-border`.
-- **`--divider`** — a SEPARATOR: a soft hairline between things. Shell columns,
-  header `border-b` rules, list rows, resize handles. Use `border-divider` /
-  `.divider-b` / `bg-divider`, or `divide-*` on a `divide-y` stack.
-
-On the **dark** themes the separator token is now a **translucent** hairline —
-`hsl(H S 46-48% / 0.18)` — mirroring Apple's own `rgba(84,84,88,0.36)` approach:
-a light grey at low alpha that *dissolves into whatever sits behind it* instead
-of a fixed opaque line. This is deliberate. An opaque separator (even a dim one)
-read as a hard grid on a near-black canvas — every column edge and header rule
-looked heavy. A translucent hairline self-adapts: heavier where it crosses an
-elevated card, lighter on the page. Every dark preset carries it (`macos`,
-`ios`, `windows`, `dense`, `soft`, and the base `dark.css` behind
-`default`/`django-cfg`); **`high-contrast` keeps an opaque divider on purpose**
-(a11y wants the harder line). Light themes keep an opaque divider too — a
-translucent line on white gains nothing.
-
-The alpha was tuned by eye in a live cmdop-web session (0.18 is quiet-but-present;
-lower starts to vanish on the page).
-
-**If a dark surface looks too contrasty**, the culprit is almost always a
-column/row/header separator wrongly drawn with `--border` (the outline weight)
-instead of `--divider` — move it to `border-divider` / `var(--divider)`.
-
-### Apply a preset
-
-```tsx
-import { buildThemeStyleSheet } from '@djangocfg/ui-core/styles/presets';
-
-// Static: bake into your app's CSS at build time
-const css = buildThemeStyleSheet({ preset: 'macos' });
-// then write `css` to a file and `@import` it after ui-core/styles
-
-// Runtime: inject into <head> (use case: settings picker)
-useEffect(() => {
-  const el = document.createElement('style');
-  el.textContent = buildThemeStyleSheet({ preset });
-  document.head.appendChild(el);
-  return () => el.remove();
-}, [preset]);
+@import "@djangocfg/ui-core/styles/full";
+@import "@djangocfg/ui-core/styles/presets/macos";
 ```
 
-### Override individual tokens
+The preset export resolves to `src/styles/css/presets/macos.css`; consumers do
+not depend on the physical path. The preset defines both `:root` (light) and
+`.dark` (dark) values. `ThemeProvider` only controls the `html.dark` class.
 
-To re-tint only a couple of variables without copying a whole preset:
+For a product-specific adjustment, add a small override after the preset:
 
 ```css
-:root.my-brand {
-  --primary: hsl(280 80% 55%);
-  --ring: hsl(280 80% 55%);
+:root, .dark {
+  --font-size-base: 0.9375rem;
+  --font-size-sm: 0.875rem;
 }
 ```
 
-Toggle `<html class="my-brand">` and the override applies on top of whichever preset is active.
-
-## Glass utilities — macOS / Windows / Liquid
-
-`utilities.css` ships four backdrop-blur classes. Each is built with `color-mix` over a token, so they work in any preset / theme.
-
-| Class | Recipe | When |
-|---|---|---|
-| `.glass-macos` | `blur(20px) saturate(180%)` · 72% `--background` | Sidebar, popovers, sheet headers |
-| `.glass-liquid` | `blur(12px) saturate(180%)` · 60% `--card` + inner highlight + border | Floating chrome (macOS 26 Dock, FAB) |
-| `.glass-header` | `blur(8px) saturate(160%)` · 80% `--background` | Nav bars, status strips |
-| `.glass-win11` | `blur(60px) saturate(125%)` · 85% `--background` | Windows Mica / Acrylic |
-
-Each requires a **non-transparent parent** (something for the blur to chew on). Avoid stacking — blur compounds.
-
-## App setup
-
-### Golden path (recommended) — one import, layer-safe
-
-```css
-/* Single line. Imports Tailwind + tokens + base + utilities in the
-   correct cascade layers. Put it FIRST; other package CSS after. */
-@import "@djangocfg/ui-core/styles/full";
-
-@import "@djangocfg/layouts/styles";
-@import "@djangocfg/ui-tools/styles";
-```
-
-`…/styles/full` (`full.css`) pins ui-core's base resets to `@layer base`
-and its custom utilities to `@layer utilities` via `@import "…" layer(name)`.
-A `layer()`-qualified import is folded into that layer **regardless of
-import order or build tool**, so you cannot get the ordering wrong, and
-you do not need to import `tailwindcss` yourself.
-
-### The cascade-layer rule (why ordering matters)
-
-Tailwind v4 emits its utilities inside `@layer utilities`. **Unlayered
-CSS beats any layered rule** in the cascade. So if a package's base
-resets (here `* { border-color }` and the `body` background/font rules in
-`base.css`) are emitted *unlayered*, they sit above `@layer utilities`
-and silently defeat layout utilities (`gap`, `space-y`, `divide`, `flex`,
-`border`, `padding`). Colors usually survive because they flow through
-CSS vars (no cascade conflict), so the breakage is invisible in Chrome
-but shows up in stricter engines (WKWebView).
+Do not create a `theme-preset.ts`, append a `<style>` tag, or call a token
+builder during application startup.
 
-Whether a *plain*, unlayered `@import` lands in a layer depends on its
-position relative to `@import "tailwindcss"` **and** on the build tool
-(Vite vs Next.js resolve `@import` differently). `full.css` removes that
-dependency by binding each file to a layer explicitly. **Use `…/styles/full`
-and this whole class of bug cannot occur.**
+## Token format
 
-### Manual ordering (only if you manage layers yourself)
-
-The plain `@djangocfg/ui-core/styles` entry imports `theme.css` +
-`sources.css` + `base.css` + `utilities.css` **unlayered** (it does not
-import Tailwind). If you use it, you own the layer ordering. The Next.js
-demo does this and works because PostCSS folds the trailing
-`@import "tailwindcss"` such that the resets still end up benign — but a
-Vite consumer that puts `@import "tailwindcss"` last hit exactly the bug
-above. If you must hand-order, import `tailwindcss` **first**:
+Color variables are complete CSS colors, never bare HSL triplets:
 
 ```css
-@import "tailwindcss";              /* establishes the layers first */
-@import "@djangocfg/ui-core/styles";
-@import "@djangocfg/layouts/styles";
-@import "@djangocfg/ui-tools/styles";
+:root { --background: hsl(240 17% 97%); }
+.dark  { --background: hsl(240 5% 8%); }
 ```
 
-> **No `@plugin "tailwindcss-animate"` needed** in v4 — the keyframes ship via `theme/animations.css`. Use `tw-animate-css` instead if you need extra utilities.
-
-### Why `@source` is required
-
-Tailwind v4 doesn't scan across npm packages automatically. Each consumer needs either a `@source` directive or to import a `sources.css` from the package — `@djangocfg/ui-core/styles` already chains its own `sources.css`, so importing `…/styles` is enough.
-
-### Wiring a custom display font (consumer recipe)
-
-`ui-core` ships `.font-display` and a display type ramp (`.text-display-xl` / `.text-display-lg` / `.text-display`) that read from a `--font-display` CSS variable. The variable itself is **not** set — apps pick the font.
-
-In a Next.js app with `next/font`:
+Tailwind maps semantic utilities to these variables through `@theme inline`.
+Use `var(--background)` or `bg-background`; do not write
+`hsl(var(--background))`.
 
-```tsx
-// app/layout.tsx
-import { Plus_Jakarta_Sans } from 'next/font/google';
-
-const display = Plus_Jakarta_Sans({
-  subsets: ['latin'],
-  weight: ['700', '800'],
-  variable: '--font-display',  // exposes as CSS var
-  display: 'swap',
-});
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en" className={display.variable}>
-      <body>{children}</body>
-    </html>
-  );
-}
-```
-
-Then in `globals.css` register it as a Tailwind token so the `font-display` utility class works:
+Typography variables are ordinary CSS values:
 
 ```css
-@theme {
-  --font-display: var(--font-display), ui-sans-serif, system-ui, sans-serif;
+:root, .dark {
+  --font-size-base: 0.8125rem;
+  --font-size-sm: 0.75rem;
 }
 ```
 
-Now any of these work:
-
-```tsx
-<h1 className="text-7xl text-display-xl">Hero title</h1>
-<h2 className="text-4xl text-display-lg">Section title</h2>
-<h3 className="text-xl text-display">Card title</h3>
-<span className="font-display">Plain display family</span>
-```
-
-## Theme Showcase story
-
-The `UI Core/Theme Showcase` story in djangocfg storybook renders every base
-token (incl. `divider`), the real status surfaces (`*-background`/`*-foreground`/
-`*-border`), the chart palette (solid + /40 opacity), the typography scale,
-button variants, cards, form controls, glass utilities, and an opacity
-sanity-check on one page. Switch the `preset` control to flip across all 8
-themes; flip light/dark from the toolbar.
+## Preset rules
 
-Use it to validate any token change before publishing — every regression shows up on one screen.
+- Presets are authored directly in `presets/css/`.
+- Every preset must define valid `hsl(...)`, `color-mix(...)`, or other complete
+  CSS color values.
+- Keep light and dark pairs together in the same file.
+- A preset may omit tokens that intentionally inherit from `theme.css`.
+- Changes to a preset require checking both light and dark modes.
+- Product density overrides belong in the consuming app's CSS, not in a copied
+  TypeScript map.
 
-## Local edits → consumer sync (debugging only)
-
-These packages are usually consumed via pinned npm versions. To hot-test a change without publishing:
+## Verification
 
 ```bash
-CONSUMER=/path/to/consumer/frontend/node_modules/.pnpm/@djangocfg+ui-core@…/node_modules/@djangocfg/ui-core/src/styles/theme
-SRC=./src/styles/theme
-
-cp "$SRC/light.css"  "$CONSUMER/light.css"
-cp "$SRC/dark.css"   "$CONSUMER/dark.css"
-cp "$SRC/tokens.css" "$CONSUMER/tokens.css"
-```
-
-Restart the consumer's dev server (Next.js / Vite cache module resolution). Revert before committing — `file:` paths in `package.json` cause `@types/react` dedup failures.
-
-## Gotchas
-
-### Arbitrary Tailwind values
-
-`h-[80px]`, `z-[100]` etc. may not work in v4. Prefer scaled tokens (`h-20`, `z-100`) — they're already registered in `tokens.css` under `--spacing-*` / `--z-index-*`.
-
-### Opacity in arbitrary classes
-
-`shadow-[0_0_0_1px_var(--ring)]` works (underscores get parsed as spaces). For nested `color-mix`, use underscores everywhere:
-
-```tsx
-className="bg-[color-mix(in_oklab,var(--primary)_30%,transparent)]"
-```
-
-### Glass over transparent background
-
-`.glass-*` needs an opaque parent to blur. On a fully transparent canvas (e.g. Wails translucent window) put a base layer first or the blur is invisible.
-
-## Programmatic palette access (JS / Canvas / SVG)
-
-For contexts that can't read CSS vars (Canvas 2D, Mermaid, react-pdf, SVG fill attrs):
-
-```tsx
-import {
-  useThemePalette,
-  useStylePresets,
-  useBoxColors,
-  alpha,
-} from '@djangocfg/ui-core/styles/palette';
-
-const palette = useThemePalette();
-ctx.fillStyle = palette.primary;              // '#0989aa'
-ctx.fillStyle = alpha(palette.warning, 0.15); // 'rgba(…, 0.15)'
-
-const presets = useStylePresets();
-presets.success // { fill: '#…', stroke: '#…', color: '#fff' }
+pnpm check
 ```
 
-These hooks resolve the live CSS values via `getComputedStyle` and re-run on theme changes.
+At the consumer, build the app that imports the preset and verify both modes.
+The important invariant is that changing a preset requires editing one CSS
+file, and no React runtime code is involved in applying it.

package/src/styles/{base.css → css/base.css}

@@ -23,7 +23,7 @@
    * / sheet) blurs the page behind it. Theme-agnostic (same both modes);
    * a preset can override for a heavier/lighter frost, or set `0px` to disable
    * the blur while keeping the `--overlay` dimming scrim. 2px = a subtle frost. */
-  --overlay-blur: 2px;
+  --overlay-blur: 5px;
 
   /* Typography tokens — overridable per preset */
   --font-sans: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;

package/src/styles/css/presets/default.css

@@ -0,0 +1 @@
+/* Authoritative static preset: default. */