@djangocfg/ui-core 2.1.394 → 2.1.395

package/src/styles/README.md

@@ -1,55 +1,68 @@
 # Tailwind CSS v4 Styles Guide
 
-This directory contains the CSS architecture for `@djangocfg/ui-core` using **Tailwind CSS v4**.
+CSS architecture for `@djangocfg/ui-core` — **Tailwind v4** with semantic tokens, presets, and macOS-style glass utilities.
 
-## Directory Structure
+## Directory layout
 
 ```
 styles/
-├── index.css              # Main entry point (import order is critical!)
-├── theme.css              # Theme imports
-├── base.css               # Base element styles
-├── utilities.css          # Custom utility classes
-├── sources.css            # Source detection for Tailwind v4 monorepo
-├── palette/               # Theme palette hooks & utilities
-│   ├── index.ts           # Exports
-│   ├── types.ts           # ThemePalette, StylePresets, BoxColors interfaces
-│   ├── useThemePalette.ts # useThemePalette, useStylePresets, useBoxColors, alpha
-│   └── utils.ts           # hslToHex, hslToRgbString, hslToRgba
+├── index.css              # Main entry — imports the chain below
+├── theme.css              # Imports tokens.css → animations → light → dark
+├── base.css               # Resets + `*` border-color + body bg/color
+├── utilities.css          # Custom utilities (.glass-*, .step, animations)
+├── sources.css            # @source directives for monorepo class detection
+├── palette/               # JS-readable color access (Canvas/SVG/Mermaid)
 └── theme/
-    ├── tokens.css         # @theme block — registers all CSS custom properties as Tailwind utilities
-    ├── light.css          # :root — light theme HSL values
-    ├── dark.css           # .dark — dark theme HSL values
-    ├── animations.css     # Animation keyframes
-    └── theme-tokens.story.tsx  # Playground story — visual reference for all tokens
+    ├── 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)
 ```
 
-## Semantic Color Token System
+## Token format (Tailwind v4 `@theme inline` pattern)
 
-All colors are defined as HSL CSS custom properties in `light.css` / `dark.css` and
-registered in `tokens.css` so Tailwind generates utility classes.
+Tokens live in `:root` / `.dark` as **fully-wrapped CSS colors**, and `@theme inline` maps them by reference:
 
-**Rule: never use raw Tailwind color-scale classes** (`amber-500`, `green-100`, etc.) in
-components. Always use the semantic token classes — they adapt to both themes automatically.
+```css
+:root  { --background: hsl(0 0% 94%); }
+.dark  { --background: hsl(0 0% 4%); }
 
-### Base tokens
+@theme inline { --color-background: var(--background); }
+```
 
-| Tailwind class | Token | Description |
-|---|---|---|
-| `bg-background` | `--background` | Page background |
-| `bg-foreground` | `--foreground` | Inverted fill (e.g. avatar bg) |
-| `text-foreground` | `--foreground` | Primary body text |
-| `text-muted-foreground` | `--muted-foreground` | Secondary / hint text |
-| `bg-muted` | `--muted` | Subtle surface (inputs, chips) |
-| `bg-card` | `--card` | Card surface |
-| `bg-accent` | `--accent` | Hover surface |
-| `bg-border` / `border-border` | `--border` | Dividers & rings |
-| `bg-primary` / `text-primary` | `--primary` | Brand CTA color |
-| `bg-destructive` / `text-destructive` | `--destructive` | Error / delete |
+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.
+
+## Semantic tokens — never use raw color scales
 
-### Status surface tokens
+**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.
 
-Each status has **4 tokens** for building banners and alerts:
+### 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 surface |
+| `bg-primary` / `text-primary-foreground` | `--primary` | Brand CTA (filled buttons, links) |
+| `bg-secondary` / `text-secondary-foreground` | `--secondary` | Neutral filled controls |
+| `bg-destructive` / `text-destructive-foreground` | `--destructive` | Error / delete filled controls |
+| `border-border` | `--border` | Dividers, card outlines, separators |
+| `bg-input` | `--input` | Input field border / fill (theme dependent) |
+| `ring-ring` | `--ring` | Focus rings, selected outlines |
+
+### Status surface tokens (default + dark themes only)
+
+Each status has 4 tokens for banners and alerts:
 
 | Role | Class | Token |
 |---|---|---|
@@ -58,9 +71,7 @@ Each status has **4 tokens** for building banners and alerts:
 | Readable text | `text-warning-foreground` | `--warning-foreground` |
 | Border ring | `border-warning-border` | `--warning-border` |
 
-Available statuses: **`warning`** · **`success`** · **`destructive`** · **`info`**
-
-#### Banner pattern
+Available statuses: **`warning`** · **`success`** · **`destructive`** · **`info`**.
 
 ```tsx
 <div className="flex items-center gap-3 rounded-md border border-warning-border/40
@@ -70,126 +81,142 @@ Available statuses: **`warning`** · **`success`** · **`destructive`** · **`in
 </div>
 ```
 
-Change `warning` → `success` / `destructive` / `info` for other states. No raw color classes needed.
+Most presets don't override `*-background` / `*-border` / `*-foreground`. For preset-agnostic banners, use opacity-derived surfaces:
 
-### Code surface tokens
+```tsx
+<div className="rounded-md border border-warning/30 bg-warning/10 text-warning">…</div>
+```
 
-| Class | Description |
+### Code & sidebar tokens
+
+| Class | Purpose |
 |---|---|
-| `bg-code` / `text-code-foreground` | Code block panel |
-| `border-code-border` | Code block border |
+| `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 |
 
-### Sidebar tokens
+## Theme presets — 8 production-ready
 
-`bg-sidebar`, `text-sidebar-foreground`, `bg-sidebar-accent`, `text-sidebar-accent-foreground`,
-`border-sidebar-border` — used by the app sidebar chrome, defined per-theme.
+| ID | Use case |
+|---|---|
+| `default` | Default ui-core theme — cyan brand |
+| `django-cfg` | Brand override (deeper cyan-blue primary) |
+| `macos` | Pixel-accurate Apple HIG (Sequoia / Tahoe 26) — Wails/Electron desktop |
+| `ios` | iOS app feel — 0.75rem radius, systemBlue |
+| `windows` | Microsoft Fluent 2 — Segoe UI Variable, 0.375rem radius |
+| `soft` | Larger radius (1rem) — friendly marketing surfaces |
+| `dense` | Smaller radius (0.25rem) — data-heavy admin UIs |
+| `high-contrast` | A11y boost — stronger borders, harder text |
 
-## Playground Story
+### Apply a preset
 
-Run `pnpm playground` in the `ui-core` package to open the component explorer.
-The **Theme / Tokens** story (`theme-tokens.story.tsx`) shows a live visual reference of every
-semantic token — base colors, status surfaces, code surface, sidebar tokens, and typography —
-in both light and dark mode. Use it to validate token changes before syncing to consumers.
+```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]);
+```
 
-## App Setup (globals.css) — CRITICAL!
+### Override individual tokens
 
-When creating a new app that uses UI packages, your `globals.css` MUST follow this pattern:
+To re-tint only a couple of variables without copying a whole preset:
 
 ```css
-/* 1. Import UI package styles FIRST (contains @theme variables) */
-@import "@djangocfg/ui-nextjs/styles";
+:root.my-brand {
+  --primary: hsl(280 80% 55%);
+  --ring: hsl(280 80% 55%);
+}
+```
 
-/* 2. Import other package styles (layouts, tools, etc.) */
-@import "@djangocfg/layouts/styles";
-@import "@djangocfg/ui-tools/styles";
+Toggle `<html class="my-brand">` and the override applies on top of whichever preset is active.
 
-/* 3. Import Tailwind CSS v4 (AFTER theme variables!) */
-@import "tailwindcss";
+## Glass utilities — macOS / Windows / Liquid
 
-/* 4. Load plugins */
-@plugin "tailwindcss-animate";
-```
+`utilities.css` ships four backdrop-blur classes. Each is built with `color-mix` over a token, so they work in any preset / theme.
 
-### Why @source is Required
+| 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 |
 
-In a Tailwind v4 monorepo, automatic class detection doesn't work across packages.
-Each package with Tailwind classes needs either:
+Each requires a **non-transparent parent** (something for the blur to chew on). Avoid stacking — blur compounds.
 
-1. A `@source` directive in the consuming app's `globals.css`
-2. Or a `sources.css` file in the package imported via the styles entry point
+## App setup
 
-## Syncing Local Packages to Consumer
+In your consuming app's `globals.css`:
 
-These packages are consumed via pinned npm versions — edits to `src/` don't automatically
-reach the consumer. After changing theme files, copy them manually:
+```css
+/* 1. ui-core theme tokens FIRST (they define every --color-*) */
+@import "@djangocfg/ui-core/styles";
 
-```bash
-CONSUMER=/path/to/carapis/solution/projects/frontend
-SRC=./src/styles/theme
+/* 2. Other package styles after */
+@import "@djangocfg/layouts/styles";
+@import "@djangocfg/ui-tools/styles";
 
-cp "$SRC/light.css"  "$CONSUMER/node_modules/@djangocfg/ui-core/src/styles/theme/light.css"
-cp "$SRC/dark.css"   "$CONSUMER/node_modules/@djangocfg/ui-core/src/styles/theme/dark.css"
-cp "$SRC/tokens.css" "$CONSUMER/node_modules/@djangocfg/ui-core/src/styles/theme/tokens.css"
+/* 3. Tailwind v4 core LAST so it sees the @theme tokens */
+@import "tailwindcss";
 ```
 
-Then restart the consumer's dev server (Next.js caches module resolution).
+> **No `@plugin "tailwindcss-animate"` needed** in v4 — the keyframes ship via `theme/animations.css`. Use `tw-animate-css` instead if you need extra utilities.
 
-## Import Order (Critical!)
+### Why `@source` is required
 
-```css
-/* 1. Theme variables MUST come first */
-@import "./theme.css";
-
-/* 2. Source detection for Tailwind v4 monorepo */
-@import "./sources.css";
+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.
 
-/* 3. Base styles */
-@import "./base.css";
+## Theme Showcase story
 
-/* 4. Custom utilities */
-@import "./utilities.css";
-```
+The `UI Core/Theme Showcase` story in djangocfg storybook renders every base token, status surface, button variant, card, form control, glass utility, and opacity sanity-check on one page. Switch the `preset` control to flip across all 8 themes; flip light/dark from the toolbar.
 
-## Gotchas
+Use it to validate any token change before publishing — every regression shows up on one screen.
 
-### Opacity with HSL colors
+## Local edits → consumer sync (debugging only)
 
-`bg-background/80` does **not** work with HSL tokens in Tailwind v4. Use inline styles:
+These packages are usually consumed via pinned npm versions. To hot-test a change without publishing:
 
-```tsx
-// ❌ Broken
-<nav className="bg-background/80">
+```bash
+CONSUMER=/path/to/consumer/frontend/node_modules/.pnpm/@djangocfg+ui-core@…/node_modules/@djangocfg/ui-core/src/styles/theme
+SRC=./src/styles/theme
 
-// ✅ Works
-<nav style={{ backgroundColor: 'hsl(var(--background) / 0.8)' }}>
+cp "$SRC/light.css"  "$CONSUMER/light.css"
+cp "$SRC/dark.css"   "$CONSUMER/dark.css"
+cp "$SRC/tokens.css" "$CONSUMER/tokens.css"
 ```
 
-**Exception**: `border-warning-border/40` works because `--color-warning-border` is resolved
-to a full `hsl()` value, making the `/` opacity modifier valid.
+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.
 
-### Arbitrary values
+## Gotchas
 
-Arbitrary values like `h-[80px]`, `z-[100]` may not work in v4. Prefer tokens:
+### Arbitrary Tailwind values
 
-```css
-@theme {
-  --spacing-80: 20rem;
-  --z-index-100: 100;
-}
-```
+`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-*`.
 
-Or use inline styles for one-off fixed sizes.
+### Opacity in arbitrary classes
 
-### Spacing & z-index
+`shadow-[0_0_0_1px_var(--ring)]` works (underscores get parsed as spaces). For nested `color-mix`, use underscores everywhere:
 
-Spacing utilities (`h-20`, `p-4`) require `--spacing-*` in `@theme`.
-Z-index utilities (`z-50`, `z-100`) require `--z-index-*` in `@theme`.
-Both are already defined in `tokens.css`.
+```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.
 
-## Theme Palette (Programmatic Color Access)
+## Programmatic palette access (JS / Canvas / SVG)
 
-For Canvas, SVG, Mermaid, and other contexts that don't support CSS variables:
+For contexts that can't read CSS vars (Canvas 2D, Mermaid, react-pdf, SVG fill attrs):
 
 ```tsx
 import {
@@ -200,12 +227,11 @@ import {
 } from '@djangocfg/ui-core/styles/palette';
 
 const palette = useThemePalette();
-ctx.fillStyle = palette.primary;               // '#0989aa'
-ctx.fillStyle = alpha(palette.warning, 0.15); // 'rgba(..., 0.15)'
+ctx.fillStyle = palette.primary;              // '#0989aa'
+ctx.fillStyle = alpha(palette.warning, 0.15); // 'rgba(…, 0.15)'
 
 const presets = useStylePresets();
-presets.success // { fill: '#...', stroke: '#...', color: '#fff' }
-
-const boxes = useBoxColors();
-boxes.primary  // semi-transparent brand, adapts to light/dark
+presets.success // { fill: '#…', stroke: '#…', color: '#fff' }
 ```
+
+These hooks resolve the live CSS values via `getComputedStyle` and re-run on theme changes.

package/src/styles/base.css

@@ -26,7 +26,7 @@
 
 /* Base element styles */
 * {
-  border-color: hsl(var(--border));
+  border-color: var(--border);
 }
 
 html {
@@ -34,8 +34,8 @@ html {
 }
 
 body {
-  background-color: hsl(var(--background));
-  color: hsl(var(--foreground));
+  background-color: var(--background);
+  color: var(--foreground);
   font-family: var(--font-sans);
   font-size: var(--font-size-base);
   line-height: var(--line-height-base);

package/src/styles/presets/presets.ts

@@ -10,15 +10,6 @@ export const THEME_STYLE_PRESET_ORDER = [
   'soft',
   'dense',
   'high-contrast',
-  'catppuccin',
-  'dracula',
-  'github',
-  'gruvbox',
-  'material',
-  'nord',
-  'one-dark',
-  'solarized',
-  'tokyo-night',
 ] as const satisfies readonly ThemeStylePresetId[];
 
 export const THEME_STYLE_PRESETS = THEME_PRESETS;

package/src/styles/presets/themes/dense.ts

@@ -3,18 +3,18 @@ import type { ThemePreset } from './types';
 export const densePreset: ThemePreset = {
   light: {
     radius: '0.25rem',
-    border: '0 0% 82%',
-    input: '0 0% 82%',
-    muted: '0 0% 94%',
-    card: '0 0% 100%',
-    accent: '0 0% 93%',
+    border: 'hsl(0 0% 82%)',
+    input: 'hsl(0 0% 82%)',
+    muted: 'hsl(0 0% 94%)',
+    card: 'hsl(0 0% 100%)',
+    accent: 'hsl(0 0% 93%)',
   },
   dark: {
     radius: '0.25rem',
-    border: '0 0% 24%',
-    input: '0 0% 24%',
-    muted: '0 0% 12%',
-    card: '0 0% 10%',
-    accent: '0 0% 14%',
+    border: 'hsl(0 0% 24%)',
+    input: 'hsl(0 0% 24%)',
+    muted: 'hsl(0 0% 12%)',
+    card: 'hsl(0 0% 10%)',
+    accent: 'hsl(0 0% 14%)',
   },
 };

package/src/styles/presets/themes/django-cfg.ts

@@ -2,20 +2,20 @@ import type { ThemePreset } from './types';
 
 export const djangoCfgPreset: ThemePreset = {
   light: {
-    primary: '192 90% 35%',
-    'primary-foreground': '0 0% 100%',
-    ring: '192 90% 35%',
-    'sidebar-primary': '192 90% 35%',
-    'sidebar-ring': '192 90% 35%',
-    'chart-1': '192 90% 35%',
+    primary: 'hsl(192 90% 35%)',
+    'primary-foreground': 'hsl(0 0% 100%)',
+    ring: 'hsl(192 90% 35%)',
+    'sidebar-primary': 'hsl(192 90% 35%)',
+    'sidebar-ring': 'hsl(192 90% 35%)',
+    'chart-1': 'hsl(192 90% 35%)',
   },
   dark: {
-    primary: '189 100% 50%',
-    'primary-foreground': '0 0% 9%',
-    ring: '189 100% 50%',
-    'sidebar-primary': '189 100% 50%',
-    'sidebar-primary-foreground': '0 0% 9%',
-    'sidebar-ring': '189 100% 50%',
-    'chart-1': '189 100% 50%',
+    primary: 'hsl(189 100% 50%)',
+    'primary-foreground': 'hsl(0 0% 9%)',
+    ring: 'hsl(189 100% 50%)',
+    'sidebar-primary': 'hsl(189 100% 50%)',
+    'sidebar-primary-foreground': 'hsl(0 0% 9%)',
+    'sidebar-ring': 'hsl(189 100% 50%)',
+    'chart-1': 'hsl(189 100% 50%)',
   },
 };

package/src/styles/presets/themes/high-contrast.ts

@@ -2,18 +2,18 @@ import type { ThemePreset } from './types';
 
 export const highContrastPreset: ThemePreset = {
   light: {
-    border: '0 0% 72%',
-    input: '0 0% 72%',
-    'muted-foreground': '0 0% 32%',
-    foreground: '0 0% 6%',
-    ring: '0 0% 20%',
+    border: 'hsl(0 0% 72%)',
+    input: 'hsl(0 0% 72%)',
+    'muted-foreground': 'hsl(0 0% 32%)',
+    foreground: 'hsl(0 0% 6%)',
+    ring: 'hsl(0 0% 20%)',
   },
   dark: {
-    border: '0 0% 38%',
-    input: '0 0% 38%',
-    'muted-foreground': '0 0% 78%',
-    foreground: '0 0% 100%',
-    background: '0 0% 6%',
-    ring: '0 0% 85%',
+    border: 'hsl(0 0% 38%)',
+    input: 'hsl(0 0% 38%)',
+    'muted-foreground': 'hsl(0 0% 78%)',
+    foreground: 'hsl(0 0% 100%)',
+    background: 'hsl(0 0% 6%)',
+    ring: 'hsl(0 0% 85%)',
   },
 };

package/src/styles/presets/themes/index.ts

@@ -9,15 +9,6 @@ import { windowsPreset } from './windows';
 import { softPreset } from './soft';
 import { densePreset } from './dense';
 import { highContrastPreset } from './high-contrast';
-import { catppuccinPreset } from './catppuccin';
-import { draculaPreset } from './dracula';
-import { githubPreset } from './github';
-import { gruvboxPreset } from './gruvbox';
-import { materialPreset } from './material';
-import { nordPreset } from './nord';
-import { oneDarkPreset } from './one-dark';
-import { solarizedPreset } from './solarized';
-import { tokyoNightPreset } from './tokyo-night';
 
 export type { ThemePreset };
 
@@ -30,13 +21,4 @@ export const THEME_PRESETS: Record<ThemeStylePresetId, ThemePreset> = {
   'soft':           softPreset,
   'dense':          densePreset,
   'high-contrast':  highContrastPreset,
-  'catppuccin':     catppuccinPreset,
-  'dracula':        draculaPreset,
-  'github':         githubPreset,
-  'gruvbox':        gruvboxPreset,
-  'material':       materialPreset,
-  'nord':           nordPreset,
-  'one-dark':       oneDarkPreset,
-  'solarized':      solarizedPreset,
-  'tokyo-night':    tokyoNightPreset,
 };