@djangocfg/ui-core 2.1.427 → 2.1.429

package/README.md

@@ -16,7 +16,10 @@ Framework-agnostic React UI library: 70+ shadcn/Radix components on Tailwind v4,
 pnpm add @djangocfg/ui-core
 ```
 
-Next.js apps should import from [`@djangocfg/ui-nextjs`](../ui-nextjs) instead — it re-exports everything here plus Next-specific bindings.
+Works in any React host. Next.js apps import components from here directly and
+add the Next router adapter from `@djangocfg/ui-core/adapters/nextjs` (see
+**Router adapters** below); Next-specific *server* utilities (sitemap, health,
+OG images, config) live in the separate [`@djangocfg/nextjs`](../nextjs) package.
 
 Import styles once at the app root — use the golden path, which pins everything
 to the right cascade layers so import order can't break layout utilities:
@@ -92,8 +95,7 @@ The router-aware components (`Sidebar`, `Link`, `SSRPagination`) read the active
 
 | Adapter | Source |
 |---|---|
-| Next.js App Router | `@djangocfg/ui-nextjs` (auto-wired) |
-| Vite / SPA (`react-router`) | `@djangocfg/ui-core/adapters/react-router` |
+| Next.js App Router | `@djangocfg/ui-core/adapters/nextjs` |
 | Plain `<a>` fallback | default (no adapter) |
 
 ## Theming (`/styles`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.427",
+  "version": "2.1.429",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -106,7 +106,7 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.427",
+    "@djangocfg/i18n": "^2.1.429",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -180,8 +180,8 @@
     "@chenglou/pretext": "*"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.427",
-    "@djangocfg/typescript-config": "^2.1.427",
+    "@djangocfg/i18n": "^2.1.429",
+    "@djangocfg/typescript-config": "^2.1.429",
     "@types/node": "^25.2.3",
     "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",

package/src/components/feedback/banner/index.tsx

@@ -311,8 +311,11 @@ const bannerVariants = cva(
           "bg-success-background text-success-foreground border-success-border",
         warning:
           "bg-warning-background text-warning-foreground border-warning-border",
+        // `--destructive-foreground` is white (text on a filled red button), so
+        // use the red itself as the surface text — readable on the pale red
+        // banner bg, consistent with how Alert tints status text.
         destructive:
-          "bg-destructive-background text-destructive-foreground border-destructive-border",
+          "bg-destructive-background text-destructive border-destructive-border",
       },
     },
     defaultVariants: {

package/src/components/forms/button/index.tsx

@@ -119,6 +119,14 @@ Button.displayName = "Button"
  * cmd-click, and the Next.js adapter (if mounted) all work out of the box.
  * Drop-in replacement for the previous native-`<a>` version.
  */
+/**
+ * ButtonLink — anchor styled as a Button.
+ *
+ * **Disabled / loading.** An `<a>` has no native `disabled`, so we emulate it
+ * the shadcn-recommended way: `aria-disabled` + `tabIndex={-1}` +
+ * `pointer-events-none opacity-50`, and we cancel the click. `loading` adds the
+ * same inert state plus a spinner — keeping parity with `<Button>`.
+ */
 export interface ButtonLinkProps
   extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href'>,
     VariantProps<typeof buttonVariants> {
@@ -129,21 +137,46 @@ export interface ButtonLinkProps
   scroll?: boolean
   /** Hint for the host framework's prefetcher (Next.js). */
   prefetch?: boolean | null
+  /** Inert + dimmed; click is cancelled and it's removed from tab order. */
+  disabled?: boolean
+  /** Inert + dimmed + spinner (e.g. while an action resolves). */
+  loading?: boolean
 }
 
 const ButtonLink = React.forwardRef<HTMLAnchorElement, ButtonLinkProps>(
-  ({ className, variant, size, elevated, href, replace, scroll, prefetch, children, ...props }, ref) => {
+  (
+    { className, variant, size, elevated, href, replace, scroll, prefetch, disabled = false, loading = false, onClick, children, ...props },
+    ref,
+  ) => {
+    // `<a>` can't be natively disabled — emulate it (aria + tab-order + no
+    // pointer events) and hard-cancel the click so navigation can't fire.
+    const inert = disabled || loading
+    const handleClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
+      if (inert) {
+        e.preventDefault()
+        return
+      }
+      onClick?.(e)
+    }
+
     return (
       <Link
         href={href}
         replace={replace}
         scroll={scroll}
         prefetch={prefetch}
-        className={cn(buttonVariants({ variant, size, elevated, className }))}
+        className={cn(
+          buttonVariants({ variant, size, elevated, className }),
+          inert && 'pointer-events-none opacity-50',
+        )}
         ref={ref}
+        onClick={handleClick}
+        aria-disabled={inert || undefined}
+        tabIndex={inert ? -1 : undefined}
         {...props}
       >
-        {children}
+        {loading && <Loader2 className="size-4 animate-spin" />}
+        {loading ? filterIcons(children) : children}
       </Link>
     )
   }

package/src/components/forms/setting-row/index.tsx

@@ -115,7 +115,11 @@ export const SettingRow = React.forwardRef<HTMLDivElement, SettingRowProps>(
       <div className={cn('min-w-0', stacked ? 'w-full' : 'flex-1')}>
         <div className="text-sm text-foreground">{label}</div>
         {description && (
-          <p className="mt-0.5 text-[13px] leading-relaxed text-muted-foreground">{description}</p>
+          // `div`, not `p`: `description` is arbitrary ReactNode and consumers
+          // legitimately embed block-level nodes (e.g. a `<Badge>` status pill,
+          // which renders a `<div>`) — a `<p>` cannot contain a `<div>` and
+          // triggers an invalid-nesting hydration error.
+          <div className="mt-0.5 text-[13px] leading-relaxed text-muted-foreground">{description}</div>
         )}
       </div>
     );

package/src/hooks/router/README.md

@@ -38,12 +38,15 @@ import { NextRouterAdapter, NextLinkProvider } from '@djangocfg/ui-core/adapters
 <I18nProvider locale={locale} messages={messages}>
   <NextRouterAdapter>
     <NextLinkProvider>
-      <AppLayout>{children}</AppLayout>
+      {children}
     </NextLinkProvider>
   </NextRouterAdapter>
 </I18nProvider>
 ```
 
+> Using `@djangocfg/layouts`? `BaseApp` already mounts both adapters — you don't
+> need this manual wiring.
+
 `next` is an **optional peer dependency** — the package never imports from `next/*` from the main entry. The Next adapter lives behind the `/adapters/nextjs` sub-path entry, so non-Next consumers don't pull `next` into their bundle.
 
 For other routers (TanStack Router, wouter, Remix, custom transports) — write a ~20-line custom adapter:

package/src/lib/env.ts

@@ -1,5 +1,10 @@
 /**
- * Environment constants — shared across all @djangocfg packages.
+ * Pure environment constants — shared across all @djangocfg UI packages.
+ *
+ * Keep this to framework-agnostic env primitives only. Feature flags that carry
+ * domain meaning (e.g. DPoP auth, static-build behaviour) live in the package
+ * that owns them — `dpopEnabled` / `isStaticBuild` are exported from
+ * `@djangocfg/api` (the lowest shared package, which implements DPoP).
  */
 
 export const nodeEnv = process.env.NODE_ENV || 'development';

package/src/styles/README.md

@@ -84,7 +84,12 @@ Available statuses: **`warning`** · **`success`** · **`destructive`** · **`in
 </div>
 ```
 
-Most presets don't override `*-background` / `*-border` / `*-foreground`. For preset-agnostic banners, use opacity-derived surfaces:
+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>
@@ -99,6 +104,41 @@ Most presets don't override `*-background` / `*-border` / `*-foreground`. For pr
 | `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.
+
 ## 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):
@@ -138,16 +178,25 @@ Some classes are authored as **plain CSS** in `utilities/*.css` (not Tailwind ut
 
 ## Theme presets — 8 production-ready
 
-| 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 |
+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 |
 
 ### Apply a preset
 
@@ -297,7 +346,12 @@ Now any of these work:
 
 ## Theme Showcase story
 
-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.
+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.
 
 Use it to validate any token change before publishing — every regression shows up on one screen.
 

package/src/styles/presets/index.ts

@@ -5,6 +5,7 @@ export type {
   ThemeCssVarKey,
   ThemeCssVarMap,
   ThemeCssVarSidebarKey,
+  ThemeCssVarStatusKey,
   ThemeCssVarTypographyKey,
   ThemeStyleConfig,
   ThemeStylePresetId,

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

@@ -1,3 +1,12 @@
+/**
+ * dense — density modifier (NOT a full color theme).
+ *
+ * Tight radius (0.25rem) + slightly stronger neutral chrome for data-heavy
+ * admin tables/grids where rows need crisp separation. Overrides only neutral
+ * surfaces (radius/border/input/divider/muted/card/accent) and inherits brand
+ * colors from the active base/brand preset, so it composes with `django-cfg`.
+ * Light and dark are symmetric.
+ */
 import type { ThemePreset } from './types';
 
 export const densePreset: ThemePreset = {
@@ -5,6 +14,7 @@ export const densePreset: ThemePreset = {
     radius: '0.25rem',
     border: 'hsl(0 0% 82%)',
     input: 'hsl(0 0% 82%)',
+    divider: 'hsl(0 0% 88%)',
     muted: 'hsl(0 0% 94%)',
     card: 'hsl(0 0% 100%)',
     accent: 'hsl(0 0% 93%)',
@@ -13,6 +23,7 @@ export const densePreset: ThemePreset = {
     radius: '0.25rem',
     border: 'hsl(0 0% 24%)',
     input: 'hsl(0 0% 24%)',
+    divider: 'hsl(0 0% 18%)',
     muted: 'hsl(0 0% 12%)',
     card: 'hsl(0 0% 10%)',
     accent: 'hsl(0 0% 14%)',

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

@@ -1,21 +1,62 @@
+/**
+ * django-cfg brand preset.
+ *
+ * The default ui-core theme already uses the django-cfg cyan family, so this
+ * preset is the *explicit, self-contained* brand declaration: it re-states the
+ * full brand-bearing token set (primary, ring, accent wash, sidebar, charts,
+ * info status) so the identity survives even when layered over a non-default
+ * base, and tints the neutral hover/accent surfaces with a faint brand wash
+ * instead of the base's pure grey.
+ *
+ * Brand cyan: #0989aa (light, `192 90% 35%`) / #00d9ff (dark, `189 100% 50%`).
+ * Only color tokens are set — radius/typography inherit base so the brand can
+ * be combined with `soft`/`dense` density modifiers downstream.
+ */
 import type { ThemePreset } from './types';
 
 export const djangoCfgPreset: ThemePreset = {
   light: {
     primary: 'hsl(192 90% 35%)',
     'primary-foreground': 'hsl(0 0% 100%)',
-    ring: 'hsl(192 90% 35%)',
+    // Faint brand wash on hover/selected surfaces (vs base's neutral grey)
+    accent: 'hsl(192 60% 94%)',
+    'accent-foreground': 'hsl(192 90% 22%)',
+    ring: 'hsl(192 90% 40%)',
     'sidebar-primary': 'hsl(192 90% 35%)',
-    'sidebar-ring': 'hsl(192 90% 35%)',
+    'sidebar-primary-foreground': 'hsl(0 0% 100%)',
+    'sidebar-accent': 'hsl(192 55% 93%)',
+    'sidebar-accent-foreground': 'hsl(192 90% 22%)',
+    'sidebar-ring': 'hsl(192 90% 40%)',
+    // Info status routed to the brand hue so banners read as on-brand
+    info: 'hsl(192 90% 35%)',
+    'info-background': 'hsl(192 100% 96%)',
+    'info-foreground': 'hsl(192 90% 22%)',
+    'info-border': 'hsl(192 80% 78%)',
     'chart-1': 'hsl(192 90% 35%)',
+    'chart-2': 'hsl(142 76% 36%)',
+    'chart-3': 'hsl(262 83% 58%)',
+    'chart-4': 'hsl(26 90% 57%)',
+    'chart-5': 'hsl(346 77% 50%)',
   },
   dark: {
     primary: 'hsl(189 100% 50%)',
     'primary-foreground': 'hsl(0 0% 9%)',
+    accent: 'hsl(189 40% 18%)',
+    'accent-foreground': 'hsl(189 100% 78%)',
     ring: 'hsl(189 100% 50%)',
     'sidebar-primary': 'hsl(189 100% 50%)',
     'sidebar-primary-foreground': 'hsl(0 0% 9%)',
+    'sidebar-accent': 'hsl(189 35% 16%)',
+    'sidebar-accent-foreground': 'hsl(189 100% 78%)',
     'sidebar-ring': 'hsl(189 100% 50%)',
+    info: 'hsl(189 100% 55%)',
+    'info-background': 'hsl(189 70% 10%)',
+    'info-foreground': 'hsl(189 90% 75%)',
+    'info-border': 'hsl(189 50% 28%)',
     'chart-1': 'hsl(189 100% 50%)',
+    'chart-2': 'hsl(142 76% 50%)',
+    'chart-3': 'hsl(262 83% 65%)',
+    'chart-4': 'hsl(26 90% 60%)',
+    'chart-5': 'hsl(346 77% 58%)',
   },
 };

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

@@ -1,19 +1,35 @@
+/**
+ * high-contrast — accessibility modifier (NOT a full color theme).
+ *
+ * Pushes border/divider/text contrast to meet stronger WCAG ratios: harder
+ * borders, darker (light) / brighter (dark) text, a stronger focus ring, and a
+ * pure white / near-black canvas so foreground separation is maximal. Brand
+ * colors (primary/charts/status) are inherited so the a11y boost stacks on top
+ * of any base or brand preset. Light and dark are symmetric.
+ */
 import type { ThemePreset } from './types';
 
 export const highContrastPreset: ThemePreset = {
   light: {
-    border: 'hsl(0 0% 72%)',
-    input: 'hsl(0 0% 72%)',
-    'muted-foreground': 'hsl(0 0% 32%)',
+    background: 'hsl(0 0% 100%)',
     foreground: 'hsl(0 0% 6%)',
-    ring: 'hsl(0 0% 20%)',
+    card: 'hsl(0 0% 100%)',
+    'card-foreground': 'hsl(0 0% 6%)',
+    border: 'hsl(0 0% 62%)',
+    input: 'hsl(0 0% 62%)',
+    divider: 'hsl(0 0% 68%)',
+    'muted-foreground': 'hsl(0 0% 28%)',
+    ring: 'hsl(0 0% 12%)',
   },
   dark: {
-    border: 'hsl(0 0% 38%)',
-    input: 'hsl(0 0% 38%)',
-    'muted-foreground': 'hsl(0 0% 78%)',
+    background: 'hsl(0 0% 4%)',
     foreground: 'hsl(0 0% 100%)',
-    background: 'hsl(0 0% 6%)',
-    ring: 'hsl(0 0% 85%)',
+    card: 'hsl(0 0% 8%)',
+    'card-foreground': 'hsl(0 0% 100%)',
+    border: 'hsl(0 0% 48%)',
+    input: 'hsl(0 0% 48%)',
+    divider: 'hsl(0 0% 42%)',
+    'muted-foreground': 'hsl(0 0% 82%)',
+    ring: 'hsl(0 0% 92%)',
   },
 };

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

@@ -21,6 +21,7 @@ export const iosPreset: ThemePreset = {
     border: 'hsl(220 9% 88%)',
     input: 'hsl(220 9% 88%)',
     ring: 'hsl(211 100% 50%)',
+    divider: 'hsl(220 9% 84%)',  // hairline, a touch lighter than border
     radius: '0.75rem',
     'sidebar-background': 'hsl(0 0% 99%)',
     'sidebar-foreground': 'hsl(220 9% 12%)',
@@ -35,6 +36,21 @@ export const iosPreset: ThemePreset = {
     'chart-3': 'hsl(262 83% 58%)',
     'chart-4': 'hsl(35 100% 50%)',
     'chart-5': 'hsl(346 77% 50%)',
+    // Status surfaces — iOS system colors
+    warning: 'hsl(35 100% 50%)',
+    'warning-background': 'hsl(35 100% 95%)',
+    'warning-foreground': 'hsl(28 80% 30%)',
+    'warning-border': 'hsl(35 90% 78%)',
+    success: 'hsl(145 63% 42%)',
+    'success-background': 'hsl(145 60% 95%)',
+    'success-foreground': 'hsl(145 60% 24%)',
+    'success-border': 'hsl(145 55% 76%)',
+    'destructive-background': 'hsl(0 100% 96%)',
+    'destructive-border': 'hsl(0 90% 80%)',
+    info: 'hsl(211 100% 50%)',
+    'info-background': 'hsl(211 100% 96%)',
+    'info-foreground': 'hsl(211 80% 30%)',
+    'info-border': 'hsl(211 90% 80%)',
   },
   dark: {
     background: 'hsl(240 6% 10%)',
@@ -56,6 +72,7 @@ export const iosPreset: ThemePreset = {
     border: 'hsl(240 5% 22%)',
     input: 'hsl(240 5% 22%)',
     ring: 'hsl(211 100% 55%)',
+    divider: 'hsl(240 5% 18%)',  // hairline, softer than border
     radius: '0.75rem',
     'sidebar-background': 'hsl(240 6% 8%)',
     'sidebar-foreground': 'hsl(0 0% 96%)',
@@ -70,5 +87,20 @@ export const iosPreset: ThemePreset = {
     'chart-3': 'hsl(262 83% 65%)',
     'chart-4': 'hsl(35 100% 58%)',
     'chart-5': 'hsl(346 77% 58%)',
+    // Status surfaces (dark)
+    warning: 'hsl(35 100% 58%)',
+    'warning-background': 'hsl(35 90% 10%)',
+    'warning-foreground': 'hsl(35 100% 72%)',
+    'warning-border': 'hsl(35 80% 28%)',
+    success: 'hsl(145 65% 52%)',
+    'success-background': 'hsl(145 60% 9%)',
+    'success-foreground': 'hsl(145 60% 70%)',
+    'success-border': 'hsl(145 50% 26%)',
+    'destructive-background': 'hsl(0 80% 11%)',
+    'destructive-border': 'hsl(0 70% 30%)',
+    info: 'hsl(211 100% 55%)',
+    'info-background': 'hsl(211 90% 11%)',
+    'info-foreground': 'hsl(211 100% 74%)',
+    'info-border': 'hsl(211 80% 30%)',
   },
 };

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

@@ -56,6 +56,8 @@ export const macosPreset: ThemePreset = {
     // Kept intentionally light — Apple hairline, not a thick rule
     border: 'hsl(240 3% 78%)',
     input: 'hsl(240 8% 93%)',
+    // Row hairline — a touch lighter than border so it reads on white cards
+    divider: 'hsl(240 4% 85%)',
     ring: 'hsl(211 100% 50%)',
     radius: '0.625rem',
     // Sidebar: slighly darker than page, matches macOS sidebar material
@@ -73,6 +75,22 @@ export const macosPreset: ThemePreset = {
     'chart-3': 'hsl(262 60% 56%)',
     'chart-4': 'hsl(35 100% 48%)',
     'chart-5': 'hsl(2 100% 59%)',
+    // Status surfaces — Apple system colors (systemOrange/Green/Red/Blue) with
+    // faint tinted banner fills that sit on the #F2F2F7 grouped canvas.
+    warning: 'hsl(35 100% 48%)',            // systemOrange #FF9500
+    'warning-background': 'hsl(35 100% 95%)',
+    'warning-foreground': 'hsl(28 80% 30%)',
+    'warning-border': 'hsl(35 90% 78%)',
+    success: 'hsl(142 71% 45%)',            // systemGreen #34C759
+    'success-background': 'hsl(142 60% 95%)',
+    'success-foreground': 'hsl(142 60% 24%)',
+    'success-border': 'hsl(142 55% 76%)',
+    'destructive-background': 'hsl(2 100% 96%)',
+    'destructive-border': 'hsl(2 90% 80%)',
+    info: 'hsl(211 100% 50%)',              // systemBlue #007AFF
+    'info-background': 'hsl(211 100% 96%)',
+    'info-foreground': 'hsl(211 80% 30%)',
+    'info-border': 'hsl(211 90% 80%)',
     ...appleTypography,
   },
   dark: {
@@ -103,6 +121,8 @@ export const macosPreset: ThemePreset = {
     // Separator dark: rgba(84,84,88,0.36) — ultra-thin, almost invisible
     border: 'hsl(240 3% 22%)',
     input: 'hsl(240 3% 19%)',
+    // Row hairline — softer than border so dark rows don't read as a hard rule
+    divider: 'hsl(240 3% 18%)',
     ring: 'hsl(211 100% 58%)',
     radius: '0.625rem',
     // Sidebar: near-black floor — #0D0D0F
@@ -120,6 +140,22 @@ export const macosPreset: ThemePreset = {
     'chart-3': 'hsl(262 60% 65%)',
     'chart-4': 'hsl(35 100% 56%)',
     'chart-5': 'hsl(3 100% 62%)',
+    // Status surfaces (dark) — Apple dark system colors, dim banner fills on the
+    // #141414 canvas with raised foregrounds for contrast.
+    warning: 'hsl(35 100% 56%)',            // systemOrange dark #FF9F0A
+    'warning-background': 'hsl(35 70% 10%)',
+    'warning-foreground': 'hsl(35 95% 70%)',
+    'warning-border': 'hsl(35 50% 26%)',
+    success: 'hsl(142 60% 50%)',            // systemGreen dark #30D158
+    'success-background': 'hsl(142 50% 9%)',
+    'success-foreground': 'hsl(142 65% 68%)',
+    'success-border': 'hsl(142 40% 24%)',
+    'destructive-background': 'hsl(3 70% 11%)',
+    'destructive-border': 'hsl(3 55% 30%)',
+    info: 'hsl(211 100% 58%)',              // systemBlue dark #0A84FF
+    'info-background': 'hsl(211 70% 11%)',
+    'info-foreground': 'hsl(211 90% 72%)',
+    'info-border': 'hsl(211 50% 30%)',
     ...appleTypography,
   },
 };

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

@@ -1,3 +1,13 @@
+/**
+ * soft — density/feel modifier (NOT a full color theme).
+ *
+ * Larger radius (1rem) + gently lifted neutral surfaces for friendly marketing
+ * UIs. It deliberately only overrides the neutral chrome (background/card/muted/
+ * accent/border/input/divider/radius + sidebar surfaces) and inherits brand
+ * colors (primary/ring/charts/status) from whatever base or brand preset is
+ * active, so `soft` composes with `django-cfg` etc. Light and dark are kept
+ * symmetric — every key set in one mode is set in the other.
+ */
 import type { ThemePreset } from './types';
 
 export const softPreset: ThemePreset = {
@@ -12,7 +22,9 @@ export const softPreset: ThemePreset = {
     'accent-foreground': 'hsl(240 6% 10%)',
     border: 'hsl(240 5% 91%)',
     input: 'hsl(240 5% 91%)',
+    divider: 'hsl(240 5% 93%)',
     radius: '1rem',
+    'sidebar-background': 'hsl(0 0% 99%)',
     'sidebar-accent': 'hsl(240 5% 94%)',
     'sidebar-border': 'hsl(240 5% 91%)',
   },
@@ -27,6 +39,7 @@ export const softPreset: ThemePreset = {
     'accent-foreground': 'hsl(0 0% 96%)',
     border: 'hsl(240 5% 20%)',
     input: 'hsl(240 5% 20%)',
+    divider: 'hsl(240 5% 16%)',
     radius: '1rem',
     'sidebar-background': 'hsl(240 6% 6%)',
     'sidebar-accent': 'hsl(240 5% 14%)',

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

@@ -44,6 +44,8 @@ export const windowsPreset: ThemePreset = {
     // ControlStrokeColorDefault: rgba(0,0,0,0.0578)
     border: 'hsl(0 0% 87%)',
     input: 'hsl(0 0% 90%)',
+    // Hairline between rows — slightly lighter than border
+    divider: 'hsl(0 0% 84%)',
     ring: 'hsl(210 100% 45%)',
     // WinUI 3: 4px controls, 8px cards/dialogs
     radius: '0.375rem',
@@ -60,6 +62,21 @@ export const windowsPreset: ThemePreset = {
     'chart-3': 'hsl(262 83% 55%)',
     'chart-4': 'hsl(35 100% 48%)',
     'chart-5': 'hsl(346 77% 50%)',
+    // Status surfaces — Fluent system colors
+    warning: 'hsl(38 92% 50%)',
+    'warning-background': 'hsl(38 100% 95%)',
+    'warning-foreground': 'hsl(30 80% 28%)',
+    'warning-border': 'hsl(38 85% 78%)',
+    success: 'hsl(120 78% 27%)',
+    'success-background': 'hsl(120 55% 95%)',
+    'success-foreground': 'hsl(120 60% 28%)',
+    'success-border': 'hsl(120 45% 78%)',
+    'destructive-background': 'hsl(0 90% 96%)',
+    'destructive-border': 'hsl(0 85% 78%)',
+    info: 'hsl(210 100% 38%)',
+    'info-background': 'hsl(210 100% 95%)',
+    'info-foreground': 'hsl(210 90% 28%)',
+    'info-border': 'hsl(210 80% 78%)',
     ...fluentTypography,
   },
   dark: {
@@ -86,6 +103,8 @@ export const windowsPreset: ThemePreset = {
     // ControlStrokeColorDefault dark: rgba(255,255,255,0.0837)
     border: 'hsl(0 0% 28%)',
     input: 'hsl(0 0% 24%)',
+    // Hairline between rows — softer than border
+    divider: 'hsl(0 0% 22%)',
     ring: 'hsl(200 100% 69%)',
     radius: '0.375rem',
     // NavigationView pane background
@@ -102,6 +121,21 @@ export const windowsPreset: ThemePreset = {
     'chart-3': 'hsl(262 83% 65%)',
     'chart-4': 'hsl(35 100% 58%)',
     'chart-5': 'hsl(346 77% 58%)',
+    // Status surfaces — Fluent system colors
+    warning: 'hsl(38 95% 58%)',
+    'warning-background': 'hsl(38 60% 10%)',
+    'warning-foreground': 'hsl(38 90% 72%)',
+    'warning-border': 'hsl(38 50% 28%)',
+    success: 'hsl(120 60% 55%)',
+    'success-background': 'hsl(120 40% 10%)',
+    'success-foreground': 'hsl(120 55% 72%)',
+    'success-border': 'hsl(120 35% 28%)',
+    'destructive-background': 'hsl(0 60% 11%)',
+    'destructive-border': 'hsl(0 50% 30%)',
+    info: 'hsl(200 100% 69%)',
+    'info-background': 'hsl(200 60% 11%)',
+    'info-foreground': 'hsl(200 90% 74%)',
+    'info-border': 'hsl(200 50% 30%)',
     ...fluentTypography,
   },
 };

package/src/styles/presets/types.ts

@@ -31,8 +31,35 @@ export type ThemeCssVarColorKey =
   | 'destructive'
   | 'destructive-foreground';
 
-/** Layout / focus tokens — `radius` is a CSS length, rest are HSL */
-export type ThemeCssVarChromeKey = 'border' | 'input' | 'ring' | 'radius';
+/**
+ * Layout / focus tokens — `radius` is a CSS length, the rest are wrapped colors.
+ * `divider` is the hairline-between-rows token (deliberately *lighter* than
+ * `--card` so it stays visible on elevated surfaces — see styles README).
+ */
+export type ThemeCssVarChromeKey = 'border' | 'input' | 'divider' | 'ring' | 'radius';
+
+/**
+ * Status surfaces — each role has a 4-token set (icon/accent, banner background,
+ * readable foreground, border ring) used by banners/alerts. Presets with a
+ * custom `background` should re-tint these so banners don't clash with the
+ * canvas; presets that keep the default canvas can omit them. All are
+ * **fully-wrapped CSS colors** (same rule as `ThemeCssVarColorKey`).
+ */
+export type ThemeCssVarStatusKey =
+  | 'warning'
+  | 'warning-background'
+  | 'warning-foreground'
+  | 'warning-border'
+  | 'success'
+  | 'success-background'
+  | 'success-foreground'
+  | 'success-border'
+  | 'destructive-background'
+  | 'destructive-border'
+  | 'info'
+  | 'info-background'
+  | 'info-foreground'
+  | 'info-border';
 
 /**
  * Typography tokens — override system font stack and scale per preset.
@@ -59,12 +86,19 @@ export type ThemeCssVarSidebarKey =
   | 'sidebar-border'
   | 'sidebar-ring';
 
+/**
+ * Categorical chart colors. **Fully-wrapped CSS colors** (`hsl(...)`) — same
+ * rule as every color key. Consume via the Tailwind utility (`bg-chart-1`,
+ * backed by `--color-chart-N` in tokens.css) or `var(--chart-N)`; never wrap as
+ * `hsl(var(--chart-N))` (that double-wraps to `hsl(hsl(...))` and is invalid).
+ */
 export type ThemeCssVarChartKey = 'chart-1' | 'chart-2' | 'chart-3' | 'chart-4' | 'chart-5';
 
 /** All keys that map to `--${key}` in ui-core CSS files */
 export type ThemeCssVarKey =
   | ThemeCssVarColorKey
   | ThemeCssVarChromeKey
+  | ThemeCssVarStatusKey
   | ThemeCssVarTypographyKey
   | ThemeCssVarSidebarKey
   | ThemeCssVarChartKey;

package/src/styles/theme/dark.css

@@ -99,10 +99,12 @@
   /* Surface gradient dark */
   --surface-gradient: linear-gradient(to bottom, var(--background), color-mix(in oklab, var(--background) 80%, transparent));
 
-  /* Chart colors — chart-1 aligned with brand */
-  --chart-1: 189 100% 50%;
-  --chart-2: 142 76% 36%;
-  --chart-3: 262 83% 58%;
-  --chart-4: 26 90% 57%;
-  --chart-5: 346 77% 50%;
+  /* Chart colors — chart-1 aligned with brand.
+   * Fully-wrapped hsl() like every other token (consume via `bg-chart-N` or
+   * `var(--chart-N)`, never `hsl(var(--chart-N))`). */
+  --chart-1: hsl(189 100% 50%);
+  --chart-2: hsl(142 76% 36%);
+  --chart-3: hsl(262 83% 58%);
+  --chart-4: hsl(26 90% 57%);
+  --chart-5: hsl(346 77% 50%);
 }

package/src/styles/theme/light.css

@@ -92,10 +92,12 @@
   /* Surface gradient */
   --surface-gradient: linear-gradient(to bottom, var(--background), color-mix(in oklab, var(--background) 80%, transparent));
 
-  /* Chart colors — chart-1 aligned with brand hue */
-  --chart-1: 192 90% 35%;
-  --chart-2: 142 76% 36%;
-  --chart-3: 262 83% 58%;
-  --chart-4: 26 90% 57%;
-  --chart-5: 346 77% 50%;
+  /* Chart colors — chart-1 aligned with brand hue.
+   * Fully-wrapped hsl() like every other token (consume via `bg-chart-N` or
+   * `var(--chart-N)`, never `hsl(var(--chart-N))`). */
+  --chart-1: hsl(192 90% 35%);
+  --chart-2: hsl(142 76% 36%);
+  --chart-3: hsl(262 83% 58%);
+  --chart-4: hsl(26 90% 57%);
+  --chart-5: hsl(346 77% 50%);
 }

package/src/styles/theme/tokens.css

@@ -83,6 +83,28 @@
   --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
   --color-sidebar-border: var(--sidebar-border);
   --color-sidebar-ring: var(--sidebar-ring);
+
+  /* Charts — categorical series. `--chart-N` are fully-wrapped colors in
+   * light/dark/preset, so this is a plain reference (NOT `hsl(var(...))`).
+   * Backs the `bg-chart-1` / `text-chart-2` / `border-chart-3` utilities and
+   * their opacity modifiers (`bg-chart-1/40`). For Recharts/shadcn `color:`
+   * props pass `var(--chart-N)` directly. */
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+
+  /* Typography — `font-sans` / `font-mono` utilities read `--font-sans` /
+   * `--font-mono` directly (those live in base.css, retinted per preset), so
+   * no binding is needed for them. Tailwind's text scale reads `--text-*`,
+   * which we bridge to the preset-overridable `--font-size-*` tokens so
+   * `text-xs…text-xl` follow the active preset instead of Tailwind defaults. */
+  --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);
 }
 
 @theme {