@djangocfg/ui-core 2.1.419 → 2.1.421

package/README.md

@@ -6,9 +6,9 @@
 
 # @djangocfg/ui-core
 
-Framework-agnostic React UI library: 70+ components on Radix + Tailwind v4, plus a router-adapter system that lets the same `<Link>` / `<Sidebar>` / `<SSRPagination>` work under Next.js, Vite, Electron, Wails, or plain React.
+Framework-agnostic React UI library: 70+ shadcn/Radix components on Tailwind v4, semantic theme tokens, palette hooks for Canvas/SVG, plus a router-adapter system that lets the same `<Link>` / `<Sidebar>` / `<SSRPagination>` work under Next.js, Vite, Electron, Wails, or plain React.
 
-**Part of [DjangoCFG](https://djangocfg.com).** **[Live demo](https://djangocfg.com/demo/)**.
+**Part of [DjangoCFG](https://djangocfg.com). [Live demo](https://djangocfg.com/demo/).**
 
 ## Install
 
@@ -16,314 +16,123 @@ Framework-agnostic React UI library: 70+ components on Radix + Tailwind v4, plus
 pnpm add @djangocfg/ui-core
 ```
 
-## Imports
+Next.js apps should import from [`@djangocfg/ui-nextjs`](../ui-nextjs) instead — it re-exports everything here plus Next-specific bindings.
 
-```tsx
-import { Button, Card, Sidebar, SSRPagination } from '@djangocfg/ui-core/components';
-import { useIsMobile, useNavigate, useQueryParams } from '@djangocfg/ui-core/hooks';
-import { cn } from '@djangocfg/ui-core/lib';
-import { UiProviders } from '@djangocfg/ui-core/providers';
-```
-
-## Root providers
-
-Mount `<UiProviders>` once at the top of your app — it bundles the overlay
-and imperative services every ui-core / ui-tools component expects:
-
-```tsx
-import { UiProviders } from '@djangocfg/ui-core/providers';
+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:
 
-export function Root({ children }: { children: React.ReactNode }) {
-  return <UiProviders>{children}</UiProviders>;
-}
+```css
+/* FIRST style import in your app entry CSS */
+@import "@djangocfg/ui-core/styles/full";   /* Tailwind v4 + tokens + base + utilities, layer-safe */
 ```
 
-Includes:
-- `<TooltipProvider>` (Radix tooltip root, `delayDuration={100}` by default)
-- `<DialogProvider>` (installs `window.dialog.*` + renders active dialogs)
-- `<Toaster>` (Sonner toast portal)
-
-Opt out per-service: `<UiProviders noToaster noDialogService>`.
-
-**Do not nest a second `<TooltipProvider>` inside library components** —
-that creates a separate context scope and breaks the tooltip↔provider link.
+The plain `@djangocfg/ui-core/styles` entry does NOT import Tailwind and emits
+its CSS unlayered — if you use it you own the layer ordering (import
+`tailwindcss` first). See `src/styles/README.md` § App setup for why. Prefer
+`…/styles/full`.
 
-## Components
-
-Organized in `components/` by category — everything re-exported from the root barrel.
-
-| Category | Examples |
-|---|---|
-| **Forms** | `Button`, `ButtonLink`, `ButtonGroup`, `Input`, `Textarea`, `Checkbox`, `RadioGroup`, `Switch`, `Slider`, `Label`, `Form`, `Field`, `InputOTP`, `PhoneInput`, `InputGroup`, `DownloadButton` |
-| **Select** | `Select`, `Combobox`, `ComboboxAsync`, `MultiSelect`, `MultiSelectPro`, `MultiSelectProAsync`, `CountrySelect`, `LanguageSelect` (all support icons + badges; `Select` accepts empty-string values; `ComboboxAsync` is the single-select counterpart to `MultiSelectProAsync` for server-side typeahead) |
-| **Overlay** | `Dialog`, `AlertDialog`, `Sheet`, `Drawer`, `Popover`, `Tooltip`, `HoverCard`, `ResponsiveSheet`, `SidePanel` |
-| **Navigation** | `Link`, `Breadcrumb`, `BreadcrumbNavigation`, `Pagination`, `StaticPagination`, `SSRPagination`, `Sidebar` (full shadcn primitives), `Tabs`, `Accordion`, `Collapsible`, `Command`, `DropdownMenu`, `ContextMenu`, `Menubar`, `NavigationMenu`, `MenuBuilder` (declarative data-driven menu) |
-| **Theme** | `ThemeProvider`, `ThemeToggle`, `ForceTheme`, `ThemeOverride`, `useThemeContext`, `useForcedTheme` — framework-agnostic theme runtime |
-| **Layout** | `Card`, `Section`, `Sticky`, `ScrollArea`, `Resizable`, `Separator`, `Skeleton`, `AspectRatio` |
-| **Data** | `Table`, `Badge`, `Avatar`, `Progress`, `Carousel`, `Calendar`, `DatePicker`, `DateRangePicker`, `Toggle`, `ToggleGroup`, `Chart*`, `BalancedText` (pretext-powered line balancing) |
-| **Feedback** | `Alert`, `Spinner`, `Empty`, `Preloader`, `Toaster` (Sonner) |
-| **Boundary** | `Boundary` (React error boundary with `silent`/`inline`/`card`/`fullscreen` variants, `resetKeys`, custom `fallback`) |
-| **Specialized** | `Kbd`, `CopyButton`, `CopyField`, `TokenIcon`, `Item`, `Portal`, `ImageWithFallback`, `Flag`, `LanguageFlag` |
-| **Effects** | `GlowBackground` |
-
-### Boundary
+## Quick start
 
 ```tsx
-import { Boundary, useBoundary } from '@djangocfg/ui-core';
+import { UiProviders, Button, Card } from '@djangocfg/ui-core';
 
-<Boundary variant="silent"><ChatLauncher /></Boundary>
-<Boundary variant="card" resetKeys={[pathname]}><Panel /></Boundary>
+<UiProviders>
+  <Card><Button>Hello</Button></Card>
+</UiProviders>
 ```
 
-Variants: `silent` / `inline` / `card` / `fullscreen`. Plus `useBoundary()` hook for async errors, `resetKeys`, `onReset`, custom `fallback` / `FallbackComponent`, and safe re-render guarantees.
+`<UiProviders>` mounts Tooltip / Dialog / Toast / Theme provider in the right order. **Mount it once at the root** — library components (and everything in `@djangocfg/ui-tools`) trust it to be there and never nest their own (a second `TooltipProvider` is the canonical "Tooltip must be used within TooltipProvider" trap).
 
-Full docs and patterns: [`src/components/boundary/README.md`](./src/components/boundary/README.md).
+## Catalogue
 
-For automatic backend reporting use `MonitorBoundary` from `@djangocfg/layouts`.
-
-
-> Pagination, breadcrumb and sidebar live here (not in ui-nextjs). `SSRPagination` reads URL state through `useLocation` + `useQueryParams`, so it works under any router adapter.
-
-## Hooks
-
-```tsx
-import { useIsMobile, useMediaQuery, useShortcutModLabel } from '@djangocfg/ui-core/hooks';
-import { useNavigate, useLocation, useQueryParams, useRouter, useIsActive } from '@djangocfg/ui-core/hooks/router';
-```
-
-| Group | Hooks |
+| Group | Examples |
+|---|---|
+| `components/data/` | Avatar · Badge · Card · Table · BalancedText · Skeleton |
+| `components/forms/` | Button · Input · Textarea · Select · Switch · Checkbox · Slider · Form |
+| `components/feedback/` | Alert · Toast · Banner · Progress · Spinner |
+| `components/overlay/` | Dialog · Drawer · Popover · Tooltip · HoverCard · Sheet · ContextMenu · DropdownMenu |
+| `components/navigation/` | Sidebar · Tabs · Breadcrumb · Pagination · NavigationMenu · Command |
+| `components/layout/` | Container · Grid · Stack · Separator · ScrollArea · Sticky |
+| `components/select/` | Combobox · MultiSelect |
+| `components/effects/` | Glass · Marquee · Backdrop |
+| `components/specialized/` | Accordion · Collapsible · Toggle · Calendar · DatePicker |
+| `components/boundary/` | ErrorBoundary |
+
+Imports stay flat — group folders are organisational.
+
+## Hooks (`/hooks`)
+
+| Topic | Hooks |
 |---|---|
-| **Router** (adapter-driven) | `useNavigate`, `useLocation`, `useLocationProperty`, `useQueryParams`, `useQueryState` (typed), `useRouter`, `useUrlBuilder`, `useSmartLink`, `useIsActive`, `useBackOrFallback` + parsers (`parseAsInteger`, `parseAsBoolean`, …) |
-| **Media** | `useIsMobile`, `useIsPhone`, `useIsTabletOrBelow`, `useMediaQuery` |
-| **Device** | `useDeviceDetect`, `useBrowserDetect`, `useShortcutModLabel` |
-| **State** | `useDebounce`, `useDebouncedCallback`, `useCountdown`, `useImageLoader`, `useMounted` |
-| **DOM** | `useEventListener`, `useResizeObserver` (shared ResizeObserver store, returns `{ width, height }`) |
-| **Theme** | `useResolvedTheme` (light/dark detection), `useThemeColor`, `useThemePalette` (palette-aware hex colors for Canvas/SVG) |
-| **Hotkey** | `useHotkey` (smart `inInput` + `preventDefault` policy), `useHotkeyChord` (sequences), `formatHotkey('mod+k') → ⌘K`, `useHotkeyHelp` (auto cheat-sheet) |
-| **Audio** | `createSoundBus`, `useNotificationSounds`, `useAudioPrefs`, `useSoundEffect` — Safari unlock, mute persist, per-event toggles + volume scale, native-host bridge |
-| **Tabs** | `useActiveTab`, `useIsTabActive`, `useIsTabLeader` — cross-tab focus + leader election via BroadcastChannel |
-| **Feedback** | `useToast`, `toast` (Sonner) |
-| **Debug** | `useDebugTools` |
+| `dom/` | `useSize` · `useResizeObserver` · `useMeasure` · `useMutationObserver` · `useIntersection` |
+| `device/` | `useIsMobile` · `useMediaQuery` · `useOnline` · `useViewportSize` · `useOrientation` |
+| `state/` | `useLocalStorage` · `useSessionStorage` · `useToggle` · `useCounter` · `useDebouncedValue` |
+| `events/` | `useEventListener` · `useClickOutside` · `useKeyPress` · `useFocusWithin` |
+| `theme/` | `useTheme` · `useResolvedTheme` · `useThemePreset` |
+| `feedback/` | `useToast` · `useDialog` · `useClipboard` · `useConfirm` |
+| `hotkey/` | `useHotkey` (single key + chord) |
+| `audio/` | `useBeep` · `useSpeak` (Web Speech) |
+| `tabs/` | `useCrossTab` (BroadcastChannel coordination) |
+| `media/` | `useMediaPermissions` · `useUserMedia` · `useDevices` |
+| `time/` | `useNow` · `useInterval` · `useTimeout` |
+| `router/` | `useLink` · `useRouter` (router-adapter consumer) |
+
+## Lib utilities (`/lib`)
+
+- `cn(...)` — `clsx` + `tailwind-merge` shortcut
+- `getIntensity(value, thresholds)` — quantise values into discrete bins (heatmaps, gauges)
+- `createLogger()` — leveled console logger
+- `dialog-service` — imperative `confirm()` / `alert()` / `prompt()` returning promises
+- `persist` — typed localStorage / sessionStorage hooks
+- `pretext` (subpath `@djangocfg/ui-core/lib/pretext`) — DOM-free text measurement via [@chenglou/pretext](https://github.com/chenglou/pretext); powers `<BalancedText>` and is the primitive for non-CSS line balancing
 
 ## Router adapters
 
-`<Link>`, `<Sidebar>`, `<SSRPagination>` and friends are wired through a small adapter system, so the same component renders correctly under any router.
-
-```tsx
-// Next.js host (e.g. apps/demo)
-import { LinkProvider } from '@djangocfg/ui-core/components';
-import NextLink from 'next/link';
-
-<LinkProvider value={NextLink}>{children}</LinkProvider>
-```
-
-When no adapter is mounted, `<Link>` falls back to a plain `<a>` and routes clicks through the History API. `@djangocfg/layouts/BaseApp` mounts the Next adapters by default.
-
-## Hotkeys
-
-```tsx
-import { useHotkey, formatHotkey, useHotkeyChord } from '@djangocfg/ui-core/hooks';
-
-// Smart defaults — auto-detects modifiers vs bare keys:
-useHotkey('mod+k', openPalette);          // ⌘K everywhere, incl. inputs; preventDefault auto
-useHotkey('/', focusSearch);              // bare key — skipped inside inputs
-useHotkey('escape', closeModal);          // always fires in inputs (blur / close pattern)
-useHotkey('?', openHelp, { description: 'Show shortcuts' });  // registers in cheat-sheet
-
-// Linear-style chords:
-useHotkeyChord(['g', 't'], () => router.push('/tasks'));
-
-// OS-aware tooltips:
-formatHotkey('mod+/')   // → '⌘/' on Mac, 'Ctrl+/' elsewhere
-formatHotkey('g t')     // → 'G then T'
-```
-
-Built on `react-hotkeys-hook` with an opinionated policy: modifier-combos and `escape` fire inside `<input>` / `<textarea>` / `[contenteditable]` by default; bare keys don't, so they won't hijack typing. Override per-call with `inInput: true | false`.
-
-`useHotkeyHelp()` reads a module-level registry populated by every `useHotkey(..., { description })` call — drop it into a `?` cheat-sheet dialog with two lines.
-
-## Audio
+The router-aware components (`Sidebar`, `Link`, `SSRPagination`) read the active router via `RouterAdapterProvider`. Ship the adapter that matches your host:
 
-Notification sounds with Safari unlock, persisted mute, and a side-channel for native hosts.
-
-```tsx
-import { useNotificationSounds, useSoundEffect } from '@djangocfg/ui-core/hooks';
-
-// Map event → URL + persisted mute + per-event toggles
-type Event = 'received' | 'mention' | 'error';
-const sounds = useNotificationSounds<Event>({
-  storageKey: 'myapp.audio',
-  sounds: { received: '/sfx/r.mp3', mention: '/sfx/m.mp3', error: '/sfx/e.mp3' },
-});
-
-onMessage = (m) => sounds.play('received');
-toggle    = () => sounds.toggleMute();
-sounds.muted    // boolean, persisted
-sounds.isSilent // true if no sounds wired or silenced
-
-// One-shot single asset (no persistence, no toggles)
-const ding = useSoundEffect('/sfx/ding.mp3');
-<Button onClick={() => { ding.play(); submit(); }} />
-```
-
-**Native-host bridge.** When a wrapper (Electron / Wails / Tauri) plays sounds outside the browser, set `silenced: true` and pipe `onSoundEvent` to your bridge — web playback stays silent while the backend gets the trigger:
-
-```tsx
-useNotificationSounds({
-  storageKey: 'cmdop.audio',
-  silenced: true,
-  onSoundEvent: (event) => window.go.playSound(event),
-});
-```
-
-**Per-event volume scale.** Master volume is multiplied by an optional per-event factor so different sounds can be balanced without juggling source files:
-
-```tsx
-useNotificationSounds<Event>({
-  storageKey: 'myapp.audio',
-  sounds: { received: '/r.mp3', error: '/e.mp3', mention: '/m.mp3' },
-  eventVolumes: {
-    error: 0.25,    // soft ack — destructive UI is the loud signal
-    mention: 1,     // personal — louder than baseline
-    received: 0.7,
-  },
-});
-```
-
-The bus respects `prefers-reduced-motion`, `prefers-reduced-data`, and `visibilityState === 'hidden'` by default (each is an opt-out). Multi-component sync: same `storageKey` from different surfaces shares the same store.
-
-Lower level: `createSoundBus<E>({ sounds, getMuted, getVolume, isEnabled })` exposes the raw bus if you need to wire your own React state. `getVolume(event)` receives the event so you can scale per-fire.
-
-For an opinionated, fully-wired example with bundled audio assets see `useChatAudio` in [`@djangocfg/ui-tools`](../../ui-tools/src/tools/Chat/README.md#audio) — it inlines six notification mp3s into the lazy chat chunk as `data:`-URLs so consumers need no asset setup.
-
-## Cross-tab coordination
-
-```tsx
-import { useActiveTab, useIsTabLeader } from '@djangocfg/ui-core/hooks';
-
-const { isActive, isLeader, tabId } = useActiveTab();
-// isActive  — this tab has user focus (visibilitychange + focus/blur)
-// isLeader  — elected leader among open tabs (stable; oldest tab wins)
-// tabId     — stable per-tab id (sessionStorage, survives in-tab reload)
-```
-
-Single shared coordinator over `BroadcastChannel` — leader election runs locally on every tab from the same peer-set view, no server. Use the leader flag to dedupe side-effects across tabs: only the leader mutates `document.title` / favicon, holds the websocket, plays a sound; followers stay silent but still read state. Zustand-backed, SSR-safe, single-tab fallback when `BroadcastChannel` is unavailable.
-
-## Schema-driven configurators
-
-`@djangocfg/ui-core/lib` exports a portable JSON Schema 7 subset (`CustomJsonSchema7`, `CustomJsonUiSchema7`, `CustomJsonUiGroup`, `CustomJsonUiDisabledWhenRule`) for packages that ship configurator schemas without taking a runtime dependency on RJSF.
-
-```tsx
-import type { CustomJsonSchema7, CustomJsonUiSchema7 } from '@djangocfg/ui-core/lib';
-```
-
-`@djangocfg/ui-tools/json-form` accepts these directly (it's a union with `RJSFSchema`).
-
-## Dialog service
-
-```tsx
-import { DialogProvider, useDialog, dialog } from '@djangocfg/ui-core/lib/dialog-service';
-
-dialog.confirm({ title: 'Delete?', description: 'This is permanent.' });
-```
-
-## Logger
-
-```tsx
-import { createLogger } from '@djangocfg/ui-core/lib';
-const log = createLogger('MyComponent');
-log.info('user logged in', { userId: 123 });
-```
-
-## Lib utilities
-
-```tsx
-import { cn, createLogger, getIntensity } from '@djangocfg/ui-core/lib';
-```
-
-| Utility | Purpose |
+| Adapter | Source |
 |---|---|
-| `cn` | Tailwind class merger (`tailwind-merge` + `clsx`). |
-| `createLogger` | Tagged console logger. |
-| `getIntensity(value, max, thresholds?)` | Quantize a value to an integer bucket (0–N). Used for heatmaps, gauges, thermal-style visualizations. Default thresholds `[0.25, 0.5, 0.75]` map ratios to four non-zero buckets. |
-| `compose-refs`, `compose-event-handlers`, `get-element-ref` | Radix-style ref/handler helpers. |
-| `dialog-service`, `persist`, `env`, `logger` | See dedicated sections. |
-
-### Pretext
-
-```tsx
-import {
-  usePretext,
-  usePretextLayout,
-  usePretextLines,
-  useBalancedWidth,
-} from '@djangocfg/ui-core/lib/pretext';
-```
-
-DOM-free text measurement hooks wrapping [`@chenglou/pretext`](https://github.com/chenglou/pretext) (optional peer dependency). `useBalancedWidth` powers `<BalancedText>`. Falls back gracefully on SSR or when `@chenglou/pretext` is not installed.
+| Next.js App Router | `@djangocfg/ui-nextjs` (auto-wired) |
+| Vite / SPA (`react-router`) | `@djangocfg/ui-core/adapters/react-router` |
+| Plain `<a>` fallback | default (no adapter) |
 
-## Styles & Theming
+## Theming (`/styles`)
 
-```css
-/* In your app's globals.css — import BEFORE @import "tailwindcss" */
-@import '@djangocfg/ui-nextjs/styles'; /* re-exports ui-core styles */
-```
-
-### Semantic color tokens
-
-All colors are CSS custom properties registered in `@theme` so Tailwind generates utility classes.
-**Never use raw Tailwind color-scale classes** (`amber-500`, `green-100`) in components — use
-semantic tokens that adapt to both light and dark themes automatically.
-
-#### Status surfaces — banners and alerts
+Tailwind v4 with semantic tokens, not raw color scales:
 
 ```tsx
-{/* Warning */}
-<div className="flex gap-2 rounded-md border border-warning-border/40
-                bg-warning-background px-3 py-2 text-xs text-warning-foreground">
-  <Icon className="text-warning" />
-  <span>You're on a preview plan.</span>
-</div>
+<Card className="bg-card border-border text-foreground" />
+<Button className="bg-primary text-primary-foreground" />
+<Alert className="bg-warning-background text-warning-foreground border-warning-border" />
 ```
 
-Each status (`warning` · `success` · `destructive` · `info`) exposes four classes:
+Tokens live in `:root` / `.dark` as fully-wrapped CSS colors; `@theme inline` exposes them as `--color-X` references, so opacity modifiers (`bg-card/40`, `border-foreground/20`) resolve via `color-mix` for **every** semantic token.
 
-| Class | Role |
-|---|---|
-| `bg-*-background` | Banner fill |
-| `text-*-foreground` | Readable body text |
-| `border-*-border` | Border ring |
-| `text-*` / `bg-*` | Icon / accent color |
-
-#### Code surface
+`@custom-variant dark (&:where(.dark, .dark *))` binds the `dark:` variant to the `.dark` class on `<html>` (not `prefers-color-scheme`) — every theme-switcher in this monorepo toggles that class.
 
-`bg-code` · `text-code-foreground` · `border-code-border` — used by PrettyCode, MarkdownMessage code fences.
-`bg-code-inline` · `text-code-inline-foreground` — for inline `<code>` chips.
+**Programmatic theme colors** for Canvas / SVG / Mermaid:
 
-### Playground
+```ts
+import { useThemeColor, alpha, useStylePresets } from '@djangocfg/ui-core/styles/palette';
 
-```bash
-pnpm playground   # opens component explorer with live theme preview
+const primary = useThemeColor('primary');           // #00d9ff (hex, not oklch)
+const dim = alpha(primary, 0.15);                   // 'rgba(0, 217, 255, 0.15)'
+const { success, warning, danger } = useStylePresets();
 ```
 
-The **Theme / Tokens** story shows every semantic token in both themes — use it to validate
-changes before syncing CSS to consumers. See `src/styles/README.md` for the full token reference
-and the manual sync workflow for local package development.
+Always hex-strings — `color-mix(...)` / `oklch(...)` syntax is rejected by Canvas2D fillStyle.
 
-### Programmatic colors (Canvas / SVG)
+[Live playground](https://djangocfg.com/demo/) covers all tokens, presets, and dark-mode pairs.
 
-```tsx
-import { useThemePalette, alpha } from '@djangocfg/ui-core/styles/palette';
+## Maintenance rule
 
-const palette = useThemePalette();
-ctx.fillStyle = alpha(palette.primary, 0.3); // hex → rgba, updates on theme switch
-```
+After any change to components or hooks — update this README and bump the package patch version. Consumers pin to npm versions; surface drift in this file is the canonical changelog.
 
 ## Requirements
 
-- React ≥ 19
-- Tailwind CSS ≥ 4
+- React 18 or 19
+- Tailwind CSS v4 (host imports `@djangocfg/ui-core/styles`)
 
----
+## License
 
-**[djangocfg.com](https://djangocfg.com)**
+MIT — © djangocfg.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.419",
+  "version": "2.1.421",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -79,6 +79,7 @@
       "require": "./src/utils/index.ts"
     },
     "./styles": "./src/styles/index.css",
+    "./styles/full": "./src/styles/full.css",
     "./styles/globals": "./src/styles/globals.css",
     "./styles/theme": "./src/styles/theme.css",
     "./styles/base": "./src/styles/base.css",
@@ -105,7 +106,7 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.419",
+    "@djangocfg/i18n": "^2.1.421",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -179,8 +180,8 @@
     "@chenglou/pretext": "*"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.419",
-    "@djangocfg/typescript-config": "^2.1.419",
+    "@djangocfg/i18n": "^2.1.421",
+    "@djangocfg/typescript-config": "^2.1.421",
     "@types/node": "^25.2.3",
     "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",

package/src/styles/README.md

@@ -6,7 +6,8 @@ CSS architecture for `@djangocfg/ui-core` — **Tailwind v4** with semantic toke
 
 ```
 styles/
-├── index.css              # Main entry — imports the chain below
+├── 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
 ├── utilities.css          # Custom utilities (.glass-*, .step, animations)
@@ -155,18 +156,55 @@ Each requires a **non-transparent parent** (something for the blur to chew on).
 
 ## App setup
 
-In your consuming app's `globals.css`:
+### Golden path (recommended) — one import, layer-safe
 
 ```css
-/* 1. ui-core theme tokens FIRST (they define every --color-*) */
-@import "@djangocfg/ui-core/styles";
+/* 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";
 
-/* 2. Other package styles after */
 @import "@djangocfg/layouts/styles";
 @import "@djangocfg/ui-tools/styles";
+```
 
-/* 3. Tailwind v4 core LAST so it sees the @theme tokens */
-@import "tailwindcss";
+`…/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).
+
+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.**
+
+### 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**:
+
+```css
+@import "tailwindcss";              /* establishes the layers first */
+@import "@djangocfg/ui-core/styles";
+@import "@djangocfg/layouts/styles";
+@import "@djangocfg/ui-tools/styles";
 ```
 
 > **No `@plugin "tailwindcss-animate"` needed** in v4 — the keyframes ship via `theme/animations.css`. Use `tw-animate-css` instead if you need extra utilities.

package/src/styles/full.css

@@ -0,0 +1,52 @@
+/**
+ * @djangocfg/ui-core — golden-path style entry (cascade-layer-safe)
+ *
+ * Import THIS file (`@djangocfg/ui-core/styles/full`) as the SINGLE,
+ * FIRST style import in a consumer app and Tailwind cascade-layer
+ * ordering cannot go wrong — regardless of build tool (Vite or Next.js)
+ * or where the consumer's own `@import "tailwindcss"` ends up.
+ *
+ * Why this file exists — the cascade-layer trap it removes
+ * --------------------------------------------------------
+ * Tailwind v4 emits its utilities inside `@layer utilities`. Any CSS
+ * that lands OUTSIDE a cascade layer beats every layered rule, because
+ * unlayered styles always win over layered ones in the cascade. So if a
+ * package's base resets (e.g. ui-core's `* { 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 resolve through CSS vars, which have no cascade conflict,
+ * so the breakage is invisible until a stricter engine (WKWebView) shows
+ * it. The plain `@djangocfg/ui-core/styles` entry imports base.css and
+ * utilities.css unlayered, which means their position relative to
+ * `@import "tailwindcss"` decides whether they get folded into a layer —
+ * a footgun for consumers.
+ *
+ * This entry removes the footgun by binding each package file to an
+ * explicit cascade layer at import time via `@import "..." layer(name)`.
+ * A `layer()`-qualified import is folded into that named layer no matter
+ * the import order or build tool, so the consumer can put their own
+ * `@import "tailwindcss"` anywhere (or omit it — this file imports it
+ * first) and the resets stay in `@layer base`, the custom utilities stay
+ * in `@layer utilities`, both correctly under Tailwind's own emissions.
+ *
+ * theme.css and sources.css are intentionally NOT layered: `@theme`
+ * token blocks and the `:root` / `.dark` CSS variables must stay global
+ * so Tailwind collects the tokens and the variables apply everywhere,
+ * and `@source` is a build directive, not a style rule.
+ */
+
+/* Tailwind v4 core first — establishes the properties/theme/base/components/utilities layer order. */
+@import "tailwindcss";
+
+/* Theme tokens + CSS variables — must stay global (unlayered) so Tailwind reads @theme and :root/.dark apply everywhere. */
+@import "./theme.css";
+
+/* @source directives for monorepo class detection — build directive, not a style rule. */
+@import "./sources.css";
+
+/* Base resets pinned to @layer base so they never escape above Tailwind's utilities. */
+@import "./base.css" layer(base);
+
+/* Custom utilities pinned to @layer utilities to sit alongside Tailwind's own. */
+@import "./utilities.css" layer(utilities);

package/src/styles/index.css

@@ -1,25 +1,34 @@
 /**
- * Unrealon UI Styles
- * Main entry point for @djangocfg/ui package styles
+ * @djangocfg/ui-core styles — token + base + utilities chain.
  *
- * Import order (critical for Tailwind v4):
- * 1. Theme variables FIRST (so Tailwind can use them)
- * 2. Tailwind CSS v4 (compiles with access to theme variables)
- * 3. Animation utilities (tw-animate-css for Tailwind v4)
- * 4. Base styles (override Tailwind defaults)
- * 5. Custom utilities (extend Tailwind utilities)
+ * IMPORTANT — this entry does NOT import Tailwind and does NOT wrap its
+ * CSS in cascade layers. base.css (the `*` border reset and the `body`
+ * background/font rules) and utilities.css are emitted UNLAYERED. In
+ * Tailwind v4 unlayered rules beat anything in `@layer utilities`, so
+ * whether these resets defeat layout utilities (gap, space-y, divide,
+ * flex, border, padding) depends entirely on where the consumer places
+ * its own `@import "tailwindcss"` and on the build tool — a real footgun
+ * (it broke a WKWebView/Vite consumer while rendering fine in Chrome).
  *
- * Usage: Import this file in your app's main CSS or _app.tsx
+ * Prefer the cascade-layer-safe golden path instead, which pins the
+ * resets/utilities to explicit layers so ordering can't go wrong:
+ *
+ *     @import "@djangocfg/ui-core/styles/full";   // see full.css
+ *
+ * This `index.css` is kept for consumers that intentionally manage their
+ * own layer ordering (e.g. the Next.js demo, which imports tailwindcss
+ * itself AFTER this chain). theme.css must stay unlayered here so the
+ * `@theme` tokens and `:root`/`.dark` variables remain global.
  */
 
-/* 1. Theme variables MUST come first */
+/* Theme variables + tokens (kept global so Tailwind reads @theme and :root/.dark apply everywhere). */
 @import "./theme.css";
 
-/* 2. Source detection for Tailwind v4 monorepo */
+/* Source detection for Tailwind v4 monorepo. */
 @import "./sources.css";
 
-/* 3. Base styles */
+/* Base styles — emitted unlayered; see header note. */
 @import "./base.css";
 
-/* 5. Custom utilities */
+/* Custom utilities — emitted unlayered; see header note. */
 @import "./utilities.css";