@djangocfg/ui-core 2.1.432 → 2.1.434

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.432",
+  "version": "2.1.434",
   "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.432",
+    "@djangocfg/i18n": "^2.1.434",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -180,8 +180,8 @@
     "@chenglou/pretext": "*"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.432",
-    "@djangocfg/typescript-config": "^2.1.432",
+    "@djangocfg/i18n": "^2.1.434",
+    "@djangocfg/typescript-config": "^2.1.434",
     "@types/node": "^25.2.3",
     "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",

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

@@ -12,9 +12,9 @@ import { createPasteHandler, useSmartOTP } from './use-otp-input';
 import type { SmartOTPProps } from './types'
 
 /**
- * Size variants for OTP slots.
- * In fluid mode these only set font-size — width/height are driven by the container.
- * In fixed mode they set explicit w/h dimensions.
+ * Size variants for OTP slots — fixed square dimensions (Vercel/Linear look).
+ * The boxes never stretch to the container width: a code is a small, tidy
+ * cluster of fixed cells, centered, not a row of full-width fields.
  */
 const sizeVariants = {
   sm: 'h-10 w-10 text-base',
@@ -22,14 +22,6 @@ const sizeVariants = {
   lg: 'h-14 w-14 text-xl',
 }
 
-// Fluid mode: width is fed by flex-1, height by aspect-square. We only
-// need to size the text inside the box.
-const sizeTextVariants = {
-  sm: 'text-base',
-  default: 'text-lg',
-  lg: 'text-xl',
-}
-
 /**
  * OTP Separator Component
  */
@@ -99,7 +91,6 @@ export const OTPInput = React.forwardRef<
       size,
       error = false,
       success = false,
-      fluid = false,
       ...props
     },
     ref
@@ -160,9 +151,7 @@ export const OTPInput = React.forwardRef<
             key={i}
             index={i}
             className={cn(
-              fluid
-                ? `flex-1 min-w-0 aspect-square ${sizeTextVariants[resolvedSize]}`
-                : sizeVariants[resolvedSize],
+              sizeVariants[resolvedSize],
               error && 'border-destructive ring-destructive/20',
               success && 'border-success ring-success/20',
               slotClassName
@@ -172,7 +161,7 @@ export const OTPInput = React.forwardRef<
       }
 
       return slotElements
-    }, [length, showSeparator, separatorPosition, separatorClassName, resolvedSize, fluid, error, success, slotClassName])
+    }, [length, showSeparator, separatorPosition, separatorClassName, resolvedSize, error, success, slotClassName])
 
     return (
       <InputOTP
@@ -182,12 +171,12 @@ export const OTPInput = React.forwardRef<
         onChange={handleChange}
         onComplete={handleComplete}
         disabled={disabled}
-        containerClassName={cn('gap-2', fluid && 'w-full', containerClassName)}
+        containerClassName={cn('gap-2', containerClassName)}
         autoFocus={autoFocus}
         onPaste={pasteHandler}
         {...props}
       >
-        <InputOTPGroup className={cn('gap-2', fluid && 'w-full')}>{slots}</InputOTPGroup>
+        <InputOTPGroup className="gap-2">{slots}</InputOTPGroup>
       </InputOTP>
     )
   }

package/src/components/forms/otp/types.ts

@@ -118,13 +118,6 @@ export interface SmartOTPProps {
    * Success state
    */
   success?: boolean
-
-  /**
-   * Fluid mode — slots stretch to fill the full container width.
-   * Useful for responsive layouts where fixed slot widths would overflow.
-   * @default false
-   */
-  fluid?: boolean
 }
 
 /**

package/src/components/select/index.ts

@@ -65,7 +65,13 @@ export type { TCountryCode } from 'countries-list';
 
 // LanguageSelect
 export { LanguageSelect } from './language-select';
-export type { LanguageSelectProps, LanguageOption, TLanguageCode } from './language-select';
+export type {
+  LanguageSelectProps,
+  LanguageSelectSize,
+  LanguageSelectVariant,
+  LanguageOption,
+  TLanguageCode,
+} from './language-select';
 
 // Shared types
 export type {

package/src/components/select/language-select.tsx

@@ -25,6 +25,10 @@ export interface LanguageOption {
 
 export type LanguageSelectVariant = 'dropdown' | 'inline';
 
+/** Trigger size for the dropdown variant — mirrors Button/Input sizing.
+ *  `default` = 40px form control; `sm` = 32px compact (settings rows, chips). */
+export type LanguageSelectSize = 'default' | 'sm';
+
 export interface LanguageSelectProps {
   /** Selected language codes (ISO 639-1) */
   value?: string[];
@@ -34,6 +38,8 @@ export interface LanguageSelectProps {
   multiple?: boolean;
   /** Display variant: dropdown (popover) or inline (scrollable list) */
   variant?: LanguageSelectVariant;
+  /** Trigger size for the dropdown variant (default | sm). Mirrors Button. */
+  size?: LanguageSelectSize;
   /** Placeholder text (default: "Select language...") */
   placeholder?: string;
   /** Search placeholder text (default: "Search...") */
@@ -121,6 +127,7 @@ export function LanguageSelect({
   onChange,
   multiple = false,
   variant = 'dropdown',
+  size = 'default',
   placeholder,
   searchPlaceholder,
   emptyText,
@@ -363,10 +370,17 @@ export function LanguageSelect({
       <PopoverTrigger asChild>
         <Button
           variant="outline"
+          size={size === 'sm' ? 'sm' : 'default'}
           role="combobox"
           aria-expanded={open}
           className={cn(
-            "w-full justify-between min-h-10 h-auto py-2",
+            "w-full justify-between",
+            // Single-select: a fixed-height pill (the Button size sets height).
+            // Multiple: allow growth so wrapped badges aren't clipped — keep the
+            // auto-height min behaviour, scaled to the chosen size.
+            multiple
+              ? (size === 'sm' ? "min-h-8 h-auto py-1" : "min-h-10 h-auto py-2")
+              : (size === 'sm' ? "text-xs" : "h-10"),
             className
           )}
           disabled={disabled}
@@ -374,17 +388,25 @@ export function LanguageSelect({
           <div className="flex-1 text-left overflow-hidden">
             {displayValue}
           </div>
-          <ChevronsUpDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />
+          <ChevronsUpDown className={cn("ml-2 shrink-0 opacity-50", size === 'sm' ? "h-3.5 w-3.5" : "h-4 w-4")} />
         </Button>
       </PopoverTrigger>
-      <PopoverContent className="w-[var(--radix-popover-trigger-width)] p-0" align="start">
+      {/* The list must stay readable even when the trigger is a narrow
+          status-bar/settings pill: grow to the trigger width but never below a
+          legible min, so language names aren't clipped to "En…". */}
+      <PopoverContent
+        className="w-auto min-w-[var(--radix-popover-trigger-width)] p-0 [--lang-min:11rem] [min-width:max(var(--radix-popover-trigger-width),var(--lang-min))]"
+        align="start"
+      >
         <Command shouldFilter={false} className="flex flex-col">
-          <CommandInput
-            placeholder={resolvedSearchPlaceholder}
-            className="shrink-0"
-            value={search}
-            onValueChange={setSearch}
-          />
+          {showSearch && (
+            <CommandInput
+              placeholder={resolvedSearchPlaceholder}
+              className="shrink-0"
+              value={search}
+              onValueChange={setSearch}
+            />
+          )}
           <CommandList className="max-h-[300px] overflow-y-auto">
             {filteredLanguages.length === 0 ? (
               <CommandEmpty>{resolvedEmptyText}</CommandEmpty>

package/src/styles/README.md

@@ -42,6 +42,16 @@ This makes opacity modifiers (`bg-card/40`, `border-foreground/20`) resolve thro
 
 > **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.

package/src/theme/ForceTheme.tsx

@@ -18,88 +18,59 @@ interface ForceThemeProps {
   className?: string;
 }
 
-// Dark theme CSS variables
+/**
+ * Token contract (ui-core Tailwind v4): base tokens are **full CSS colors**,
+ * never bare HSL triplets. The utilities consume them raw — `.bg-muted {
+ * background-color: var(--muted) }` — so `--muted: 0 0% 10%` (a triplet) is an
+ * invalid color and the declaration is dropped (transparent fills, white
+ * borders). Every value here is therefore wrapped in `hsl(...)`. The separate
+ * `--color-*` block is intentionally gone: ui-core's `@theme inline` already
+ * maps `--color-X: var(--X)`, so re-declaring it here is redundant and was the
+ * only reason this component half-worked before. See ui-core styles README
+ * §"Token format".
+ */
 const darkThemeVars = {
-  // Base HSL values
-  '--background': '0 0% 4%',
-  '--foreground': '0 0% 98%',
-  '--card': '0 0% 8%',
-  '--card-foreground': '0 0% 98%',
-  '--popover': '0 0% 12%',
-  '--popover-foreground': '0 0% 98%',
-  '--primary': '217 91% 60%',
-  '--primary-foreground': '0 0% 100%',
-  '--secondary': '0 0% 98%',
-  '--secondary-foreground': '0 0% 9%',
-  '--muted': '0 0% 10%',
-  '--muted-foreground': '0 0% 60%',
-  '--accent': '0 0% 15%',
-  '--accent-foreground': '0 0% 98%',
-  '--destructive': '0 84% 60%',
-  '--destructive-foreground': '0 0% 98%',
-  '--border': '0 0% 15%',
-  '--input': '0 0% 15%',
-  '--ring': '217 91% 60%',
-  // Tailwind color tokens (used by bg-*, text-*, etc)
-  '--color-background': 'hsl(0 0% 4%)',
-  '--color-foreground': 'hsl(0 0% 98%)',
-  '--color-card': 'hsl(0 0% 8%)',
-  '--color-card-foreground': 'hsl(0 0% 98%)',
-  '--color-primary': 'hsl(217 91% 60%)',
-  '--color-primary-foreground': 'hsl(0 0% 100%)',
-  '--color-secondary': 'hsl(0 0% 98%)',
-  '--color-secondary-foreground': 'hsl(0 0% 9%)',
-  '--color-muted': 'hsl(0 0% 10%)',
-  '--color-muted-foreground': 'hsl(0 0% 60%)',
-  '--color-accent': 'hsl(0 0% 15%)',
-  '--color-accent-foreground': 'hsl(0 0% 98%)',
-  '--color-destructive': 'hsl(0 84% 60%)',
-  '--color-destructive-foreground': 'hsl(0 0% 98%)',
-  '--color-border': 'hsl(0 0% 15%)',
-  '--color-input': 'hsl(0 0% 15%)',
-  '--color-ring': 'hsl(217 91% 60%)',
+  '--background': 'hsl(0 0% 4%)',
+  '--foreground': 'hsl(0 0% 98%)',
+  '--card': 'hsl(0 0% 8%)',
+  '--card-foreground': 'hsl(0 0% 98%)',
+  '--popover': 'hsl(0 0% 12%)',
+  '--popover-foreground': 'hsl(0 0% 98%)',
+  '--primary': 'hsl(217 91% 60%)',
+  '--primary-foreground': 'hsl(0 0% 100%)',
+  '--secondary': 'hsl(0 0% 98%)',
+  '--secondary-foreground': 'hsl(0 0% 9%)',
+  '--muted': 'hsl(0 0% 10%)',
+  '--muted-foreground': 'hsl(0 0% 60%)',
+  '--accent': 'hsl(0 0% 15%)',
+  '--accent-foreground': 'hsl(0 0% 98%)',
+  '--destructive': 'hsl(0 84% 60%)',
+  '--destructive-foreground': 'hsl(0 0% 98%)',
+  '--border': 'hsl(0 0% 15%)',
+  '--input': 'hsl(0 0% 15%)',
+  '--ring': 'hsl(217 91% 60%)',
 } as React.CSSProperties;
 
-// Light theme CSS variables
 const lightThemeVars = {
-  // Base HSL values
-  '--background': '0 0% 96%',
-  '--foreground': '0 0% 9%',
-  '--card': '0 0% 100%',
-  '--card-foreground': '0 0% 9%',
-  '--popover': '0 0% 100%',
-  '--popover-foreground': '0 0% 9%',
-  '--primary': '217 91% 60%',
-  '--primary-foreground': '0 0% 100%',
-  '--secondary': '0 0% 9%',
-  '--secondary-foreground': '0 0% 98%',
-  '--muted': '0 0% 96%',
-  '--muted-foreground': '0 0% 40%',
-  '--accent': '0 0% 92%',
-  '--accent-foreground': '0 0% 9%',
-  '--destructive': '0 84% 60%',
-  '--destructive-foreground': '0 0% 98%',
-  '--border': '0 0% 90%',
-  '--input': '0 0% 90%',
-  '--ring': '217 91% 60%',
-  // Tailwind color tokens (used by bg-*, text-*, etc)
-  '--color-background': 'hsl(0 0% 96%)',
-  '--color-foreground': 'hsl(0 0% 9%)',
-  '--color-card': 'hsl(0 0% 100%)',
-  '--color-card-foreground': 'hsl(0 0% 9%)',
-  '--color-primary': 'hsl(217 91% 60%)',
-  '--color-primary-foreground': 'hsl(0 0% 100%)',
-  '--color-secondary': 'hsl(0 0% 9%)',
-  '--color-secondary-foreground': 'hsl(0 0% 98%)',
-  '--color-muted': 'hsl(0 0% 96%)',
-  '--color-muted-foreground': 'hsl(0 0% 40%)',
-  '--color-accent': 'hsl(0 0% 92%)',
-  '--color-accent-foreground': 'hsl(0 0% 9%)',
-  '--color-destructive': 'hsl(0 84% 60%)',
-  '--color-destructive-foreground': 'hsl(0 0% 98%)',
-  '--color-border': 'hsl(0 0% 90%)',
-  '--color-input': 'hsl(0 0% 90%)',
-  '--color-ring': 'hsl(217 91% 60%)',
+  '--background': 'hsl(0 0% 96%)',
+  '--foreground': 'hsl(0 0% 9%)',
+  '--card': 'hsl(0 0% 100%)',
+  '--card-foreground': 'hsl(0 0% 9%)',
+  '--popover': 'hsl(0 0% 100%)',
+  '--popover-foreground': 'hsl(0 0% 9%)',
+  '--primary': 'hsl(217 91% 60%)',
+  '--primary-foreground': 'hsl(0 0% 100%)',
+  '--secondary': 'hsl(0 0% 9%)',
+  '--secondary-foreground': 'hsl(0 0% 98%)',
+  '--muted': 'hsl(0 0% 96%)',
+  '--muted-foreground': 'hsl(0 0% 40%)',
+  '--accent': 'hsl(0 0% 92%)',
+  '--accent-foreground': 'hsl(0 0% 9%)',
+  '--destructive': 'hsl(0 84% 60%)',
+  '--destructive-foreground': 'hsl(0 0% 98%)',
+  '--border': 'hsl(0 0% 90%)',
+  '--input': 'hsl(0 0% 90%)',
+  '--ring': 'hsl(217 91% 60%)',
 } as React.CSSProperties;
 
 export function ForceTheme({ theme, children, className }: ForceThemeProps) {

package/src/theme/README.md

@@ -0,0 +1,85 @@
+# Theme — providers, switches, and forced themes
+
+The runtime side of the design system. `styles/` ships the **tokens** (CSS
+variables) and the Tailwind utilities that read them; `theme/` is the **React**
+layer that decides *which* token set is live (light / dark / a preset) and lets
+you switch or pin it.
+
+> Read [`../styles/README.md`](../styles/README.md) first for the **token
+> contract** — it is load-bearing for everything here. The one rule that bites:
+> **base tokens are full CSS colors (`hsl(...)`), never bare triplets.**
+
+## Exports
+
+| Export | What it does |
+|---|---|
+| `ThemeProvider` / `useThemeContext` | Wraps `next-themes`. Owns the `html.dark` class + the user's light/dark/system choice. Mount once at the app root (via `BaseApp` in `@djangocfg/layouts`, which mounts it for you). |
+| `ThemeToggle` | A light/dark toggle button. |
+| `ThemeSegmented` | A segmented light/dark/system control. |
+| `ThemeOverride` | **Pathname-aware forced theme.** Mutates the real `next-themes` value while the route matches a rule, restores the user's pick when it leaves. Globs (`*`, `**`) supported. This is the **correct** way to force a route's theme. |
+| `resolveForcedTheme` | Pure helper — first matching rule → forced theme (or `null`). Pair with `ForcedThemeProvider`. |
+| `ForcedThemeProvider` / `useForcedTheme` | Lets descendants read the currently-forced theme. |
+| `ForceTheme` | **Scoped, inline-var theme for a subtree.** A `<div class={theme}>` that re-declares the token vars inline. Use sparingly — see the trap below. |
+
+## Choosing: `ThemeOverride` vs `ForceTheme`
+
+They look similar; they are not interchangeable.
+
+| | `ThemeOverride` (preferred) | `ForceTheme` (last resort) |
+|---|---|---|
+| How | mutates the real `next-themes` value → toggles `html.dark` | wraps children in `<div class={theme} style={inline vars}>` |
+| Scope | the **whole app** while the route matches | just that **subtree** |
+| Tokens | the real preset/`theme.css` tokens cascade — **always valid** | re-declares a hardcoded token map inline |
+| Active preset | **respected** (macos/ios/django-cfg/…) | **ignored** — ships its own generic palette |
+| Risk | none | bare-triplet trap (below); also overrides your brand accent |
+
+**Default to `ThemeOverride`** for "this route is always dark" (the common case —
+a marketing landing, a docs section). It's how the cmdop site forces its homepage
+dark:
+
+```tsx
+// in the app shell (RootAppLayout)
+<BaseApp theme={{ defaultTheme: 'dark' }}>
+  <ThemeOverride pathname={pathnameWithoutLocale} rules={[{ path: '/', theme: 'dark' }]} />
+  {children}
+</BaseApp>
+```
+
+Reach for `ForceTheme` **only** when you need a single subtree in the opposite
+theme of the rest of the page (e.g. a dark preview card on a light page) and you
+cannot drive it through the router.
+
+## ⚠️ The `ForceTheme` bare-triplet trap
+
+`ForceTheme` re-declares tokens inline. Under the **Tailwind v4 token contract**,
+base tokens are **full colors** and the utilities read them raw:
+
+```css
+.bg-muted    { background-color: var(--muted); }
+.border-border { border-color: var(--border); }
+```
+
+So a token set to a **bare HSL triplet** is a broken color:
+
+```css
+--muted: 0 0% 10%;     /* ❌ var(--muted) → "0 0% 10%" → not a color → declaration dropped */
+--muted: hsl(0 0% 10%);/* ✅ valid color */
+```
+
+The failure is **silent and confusing**: inside the `ForceTheme` subtree
+`bg-muted` renders **transparent** and `border-border` renders the inherited
+fallback (≈ white), while `border-divider` (a token `ForceTheme` doesn't
+re-declare) still works — so it looks like "random borders are white and some
+fills vanished." It is NOT a Tailwind content-scan problem; the utilities exist,
+their *input* is invalid. Full write-up + how to diagnose:
+[`TROUBLESHOOTING.md`](TROUBLESHOOTING.md).
+
+`ForceTheme`'s token map is wrapped in `hsl(...)` as of this version, so the trap
+is closed for the values it ships. But the lesson stands for **any** inline token
+override you write: wrap in `hsl(...)`, or prefer `ThemeOverride` so the real
+(already-valid) preset tokens cascade and you never hand-maintain a palette.
+
+## Maintenance rule
+
+After changing a component or the token map here, update this README and bump the
+package patch version (consumers pin npm versions; this file is the changelog).

package/src/theme/TROUBLESHOOTING.md

@@ -0,0 +1,89 @@
+# Theme & token troubleshooting
+
+Symptom-first. Each entry: what you see → why → the fix.
+
+---
+
+## "Random white borders + transparent fills on part of the page"
+
+### What you see
+- Some surfaces render with **no background** (`bg-muted` / `bg-card` / a custom
+  `bg-bubble-*` come out transparent).
+- Some borders render **bright white / light grey** instead of the hairline token
+  — `border-border` looks white, but `border-divider` next to it looks correct.
+- It only happens in **one region** of the page (often a marketing landing or a
+  card), not the whole app. A sibling app/route with the same components is fine.
+
+### Why (the actual mechanism)
+A subtree is wrapped in **`<ForceTheme>`** (or any hand-written element that sets
+token CSS vars inline) where a token is declared as a **bare HSL triplet**:
+
+```css
+--muted: 0 0% 10%;     /* ❌ */
+--border: 0 0% 15%;    /* ❌ */
+```
+
+ui-core's utilities consume tokens **raw** (`@theme inline` maps
+`--color-muted: var(--muted)`, and `.bg-muted { background-color: var(--muted) }`).
+So `var(--muted)` resolves to the **string** `"0 0% 10%"`, which is not a valid
+color → the browser **drops the declaration**:
+
+- `background-color` drop → falls back to `transparent`.
+- `border-color` drop → falls back to the inherited `currentColor` (≈ the light
+  text color on a dark UI → "white border").
+
+`border-divider` keeps working because that subtree doesn't *re-declare*
+`--divider`, so it still inherits the valid preset value.
+
+**This is NOT a Tailwind content-scan / `@source` problem.** The `.bg-muted`
+rule exists in the built CSS; its *input variable* is the broken thing.
+
+### How to confirm (60 seconds in the browser console)
+```js
+// 1) is the utility rule transparent on a real element?
+getComputedStyle($0).backgroundColor          // rgba(0,0,0,0) on a bg-muted node = bug
+
+// 2) is there a ForceTheme div with bare-triplet vars above it?
+[...document.querySelectorAll('div[style*="--muted"]')]
+  .map(d => d.style.getPropertyValue('--muted'))   // "0 0% 10%" (no hsl) = the culprit
+
+// 3) sanity: a probe OUTSIDE the subtree works
+const p = document.createElement('div'); p.className='bg-muted';
+document.body.appendChild(p);
+getComputedStyle(p).backgroundColor               // rgb(57,57,60) → proves the utility is fine
+p.remove();
+```
+If (1) is transparent but (3) is a real color, the input var is broken, not the
+utility — look up the tree for an inline token override.
+
+### Fix (in order of preference)
+1. **Stop forcing the theme with `ForceTheme`.** If the goal was just "this route
+   is dark", drive it through the router with **`ThemeOverride`** in the app shell
+   (`rules={[{ path: '/', theme: 'dark' }]}`) and delete the wrapper. The real
+   preset tokens (already valid `hsl(...)`) cascade and the bug is gone. This is
+   the right fix 90% of the time.
+2. **If you genuinely need `ForceTheme`** (a subtree in the opposite theme), make
+   sure every inline token value is a **full color**: `--muted: hsl(0 0% 10%)`,
+   not `0 0% 10%`. ui-core's shipped `ForceTheme` already does this.
+3. **Never** "fix" it by adding plain `.bg-x { background: var(--x) }` overrides in
+   the app's `globals.css` — that masks the broken input and rots.
+
+---
+
+## "ALL utilities missing (only @theme vars load)" — a different bug
+
+If `bg-*` / `border-*` are missing **everywhere** (not just one subtree) while the
+`--token` variables are present, that IS a content-scan problem, not this one:
+Tailwind v4 didn't scan your app source. See
+[`../styles/README.md`](../styles/README.md) §"Why `@source` is required" — add
+`@source "../../app"` (path relative to the CSS file) or check the app dir isn't
+`.gitignore`d. Distinguish the two: **scan bug = global**, **token bug = one
+subtree under an inline override.**
+
+---
+
+## "`hsl(var(--x))` shows the default / no color"
+
+Tokens are already full colors. `hsl(hsl(0 0% 10%))` is invalid. Use
+`var(--x)` directly, or `color-mix(in oklab, var(--x) N%, transparent)` for
+opacity. See `styles/README.md` §"Token format".