@djangocfg/ui-core 2.1.364 → 2.1.365

package/README.md

@@ -101,10 +101,61 @@ const log = createLogger('MyComponent');
 log.info('user logged in', { userId: 123 });
 ```
 
-## Styles
+## Styles & Theming
 
 ```css
-@import '@djangocfg/ui-core/styles/globals.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
+
+```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>
+```
+
+Each status (`warning` · `success` · `destructive` · `info`) exposes four classes:
+
+| Class | Role |
+|---|---|
+| `bg-*-background` | Banner fill |
+| `text-*-foreground` | Readable body text |
+| `border-*-border` | Border ring |
+| `text-*` / `bg-*` | Icon / accent color |
+
+#### Code surface
+
+`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.
+
+### Playground
+
+```bash
+pnpm playground   # opens component explorer with live theme preview
+```
+
+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.
+
+### Programmatic colors (Canvas / SVG)
+
+```tsx
+import { useThemePalette, alpha } from '@djangocfg/ui-core/styles/palette';
+
+const palette = useThemePalette();
+ctx.fillStyle = alpha(palette.primary, 0.3); // hex → rgba, updates on theme switch
 ```
 
 ## Requirements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.364",
+  "version": "2.1.365",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -96,7 +96,7 @@
     "playground": "playground dev"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.364",
+    "@djangocfg/i18n": "^2.1.365",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -166,9 +166,9 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.364",
+    "@djangocfg/i18n": "^2.1.365",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.364",
+    "@djangocfg/typescript-config": "^2.1.365",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

package/src/styles/README.md

@@ -6,80 +6,134 @@ This directory contains the CSS architecture for `@djangocfg/ui-core` using **Ta
 
 ```
 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 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
 └── theme/
-    ├── tokens.css   # @theme block with CSS custom properties
-    ├── light.css    # Light theme variables
-    ├── dark.css     # Dark theme variables
-    └── animations.css # Animation keyframes
+    ├── 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
 ```
 
-## Key Changes in Tailwind v4
+## Semantic Color Token System
 
-1. **CSS-First Configuration**: Theme is now defined using CSS custom properties in an `@theme` block instead of JavaScript
-2. **New Import Syntax**: Use `@import "tailwindcss"` instead of `@tailwind` directives
-3. **Simplified PostCSS Setup**: Use `@tailwindcss/postcss` plugin
-4. **Performance Improvements**: 10x faster build times, significantly smaller CSS bundles
-5. **Modern Browser Support**: Optimized for Safari 16.4+, Chrome 111+, Firefox 128+
-6. **Source Detection Required**: Tailwind v4 requires explicit `@source` directives to scan files in monorepo packages
+All colors are defined as HSL CSS custom properties in `light.css` / `dark.css` and
+registered in `tokens.css` so Tailwind generates utility classes.
 
-## App Setup (globals.css) - CRITICAL!
+**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.
+
+### Base tokens
+
+| 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 |
+
+### Status surface tokens
+
+Each status has **4 tokens** for building banners and alerts:
+
+| Role | Class | Token |
+|---|---|---|
+| Icon / accent | `text-warning` | `--warning` |
+| Banner background | `bg-warning-background` | `--warning-background` |
+| Readable text | `text-warning-foreground` | `--warning-foreground` |
+| Border ring | `border-warning-border` | `--warning-border` |
+
+Available statuses: **`warning`** · **`success`** · **`destructive`** · **`info`**
+
+#### Banner pattern
+
+```tsx
+<div className="flex items-center gap-3 rounded-md border border-warning-border/40
+                bg-warning-background px-3 py-2 text-xs text-warning-foreground">
+  <Icon className="h-4 w-4 text-warning" />
+  <span>You're on a preview plan.</span>
+</div>
+```
+
+Change `warning` → `success` / `destructive` / `info` for other states. No raw color classes needed.
+
+### Code surface tokens
+
+| Class | Description |
+|---|---|
+| `bg-code` / `text-code-foreground` | Code block panel |
+| `border-code-border` | Code block border |
+| `bg-code-inline` / `text-code-inline-foreground` | Inline `<code>` chips |
+
+### Sidebar tokens
+
+`bg-sidebar`, `text-sidebar-foreground`, `bg-sidebar-accent`, `text-sidebar-accent-foreground`,
+`border-sidebar-border` — used by the app sidebar chrome, defined per-theme.
+
+## Playground Story
+
+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.
+
+## App Setup (globals.css) — CRITICAL!
 
 When creating a new app that uses UI packages, your `globals.css` MUST follow this pattern:
 
 ```css
-/**
- * CRITICAL: Import order matters for Tailwind CSS v4!
- * 1. Theme variables MUST come BEFORE @import "tailwindcss"
- * 2. @source directives MUST be added for each package with Tailwind classes
- */
-
 /* 1. Import UI package styles FIRST (contains @theme variables) */
 @import "@djangocfg/ui-nextjs/styles";
 
-/* 2. Import other package styles (layouts, etc.) */
+/* 2. Import other package styles (layouts, tools, etc.) */
 @import "@djangocfg/layouts/styles";
+@import "@djangocfg/ui-tools/styles";
 
 /* 3. Import Tailwind CSS v4 (AFTER theme variables!) */
 @import "tailwindcss";
 
 /* 4. Load plugins */
 @plugin "tailwindcss-animate";
-
-/* 5. Source detection for packages NOT included in ui-nextjs/styles */
-/* This tells Tailwind where to scan for utility classes */
-@source "../../../packages/your-package/src/**/*.{ts,tsx}";
 ```
 
 ### Why @source is Required
 
-In Tailwind v4 monorepo, automatic class detection doesn't work across packages. Each package with Tailwind classes needs:
+In a Tailwind v4 monorepo, automatic class detection doesn't work across packages.
+Each package with Tailwind classes needs either:
 
-1. **Either** a `@source` directive in the consuming app's `globals.css`
-2. **Or** a `sources.css` file in the package that's imported via the styles entry point
+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
 
-**Example**: If you have `playground-ui` package with components using `pb-20`, `grid-cols-5`, etc., and these classes don't work:
+## Syncing Local Packages to Consumer
 
-```css
-/* Add this to your app's globals.css */
-@source "../../../packages/playground-ui/src/**/*.{ts,tsx}";
-```
+These packages are consumed via pinned npm versions — edits to `src/` don't automatically
+reach the consumer. After changing theme files, copy them manually:
 
-### Common Symptoms of Missing @source
+```bash
+CONSUMER=/path/to/carapis/solution/projects/frontend
+SRC=./src/styles/theme
+
+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"
+```
 
-- Tailwind classes don't apply (but inline styles work)
-- Grid classes like `grid-cols-3`, `grid-cols-5` don't work
-- Spacing classes like `pb-20`, `mt-10` have no effect
-- Classes work in some packages but not others
+Then restart the consumer's dev server (Next.js caches module resolution).
 
 ## Import Order (Critical!)
 
@@ -97,121 +151,45 @@ In Tailwind v4 monorepo, automatic class detection doesn't work across packages.
 @import "./utilities.css";
 ```
 
-## Best Practices
+## Gotchas
 
-### Spacing & Sizing
+### Opacity with HSL colors
 
-- Use standard Tailwind classes: `py-16 sm:py-20 md:py-24 lg:py-32`
-- Responsive patterns: `px-4 sm:px-6 lg:px-8`
-- Container pattern: `container max-w-7xl mx-auto`
-
-### Arbitrary Values
-
-**IMPORTANT**: Arbitrary values like `h-[80px]`, `z-[100]` may NOT work in v4!
+`bg-background/80` does **not** work with HSL tokens in Tailwind v4. Use inline styles:
 
 ```tsx
-// ❌ May not work in Tailwind v4
-<div className="h-[80px] z-[100]">
-
-// ✅ Define tokens in @theme instead
-@theme {
-  --spacing-80: 20rem;
-  --z-index-100: 100;
-}
-
-// ✅ Or use inline styles (always reliable)
-<div style={{ height: '80px', zIndex: 100 }}>
-```
-
-### Opacity with HSL Colors
+// ❌ Broken
+<nav className="bg-background/80">
 
-**CRITICAL**: `bg-background/80` does NOT work with HSL colors in v4!
-
-```tsx
-// ❌ BROKEN - does not work in Tailwind v4
-<nav className="bg-background/80 border-border/30">
-
-// ✅ WORKING - use inline styles for opacity
-<nav
-  className="sticky top-0 z-100 backdrop-blur-xl"
-  style={{
-    backgroundColor: 'hsl(var(--background) / 0.8)',
-    borderColor: 'hsl(var(--border) / 0.3)'
-  }}
->
+// ✅ Works
+<nav style={{ backgroundColor: 'hsl(var(--background) / 0.8)' }}>
 ```
 
-### Fixed Sizes
-
-```tsx
-// ✅ Inline styles for fixed sizes (always reliable)
-<Avatar
-  className="aspect-square rounded-full overflow-hidden"
-  style={{ width: '80px', height: '80px' }}
->
-  <AvatarImage src={avatar} alt="User" />
-</Avatar>
-```
+**Exception**: `border-warning-border/40` works because `--color-warning-border` is resolved
+to a full `hsl()` value, making the `/` opacity modifier valid.
 
-### Spacing Requirements
+### Arbitrary values
 
-Spacing utilities (`h-20`, `p-4`, etc.) require `--spacing-*` variables defined in `@theme` block:
+Arbitrary values like `h-[80px]`, `z-[100]` may not work in v4. Prefer tokens:
 
 ```css
 @theme {
-  --spacing: 0.25rem; /* Base unit: 4px */
-  --spacing-0: 0;
-  --spacing-1: 0.25rem;   /* 4px */
-  --spacing-2: 0.5rem;    /* 8px */
-  --spacing-4: 1rem;      /* 16px */
-  --spacing-8: 2rem;      /* 32px */
-  --spacing-13: 3.25rem;  /* 52px - for min-h-13 */
-  /* ... */
-}
-```
-
-### Z-Index Requirements
-
-Z-index utilities (`z-50`, `z-100`) require `--z-index-*` variables:
-
-```css
-@theme {
-  --z-index-50: 50;
+  --spacing-80: 20rem;
   --z-index-100: 100;
-  --z-index-9999: 9999;
 }
 ```
 
-## Common Patterns
-
-### Responsive Design (Mobile-First)
-
-```tsx
-<div className="px-4 sm:px-6 lg:px-8">
-  <div className="py-16 sm:py-20 md:py-24 lg:py-32">
-    Content
-  </div>
-</div>
-```
-
-### Breakpoints
-
-- `sm:` - 640px (40rem)
-- `md:` - 768px (48rem)
-- `lg:` - 1024px (64rem)
-- `xl:` - 1280px (80rem)
-- `2xl:` - 1536px (96rem)
+Or use inline styles for one-off fixed sizes.
 
-### Circles
+### Spacing & z-index
 
-```tsx
-// ✅ Perfect circle
-<div className="aspect-square rounded-full overflow-hidden w-10 h-10">
-```
+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`.
 
 ## Theme Palette (Programmatic Color Access)
 
-For Canvas, SVG, Mermaid, and other contexts that don't support CSS variables, use the palette hooks:
+For Canvas, SVG, Mermaid, and other contexts that don't support CSS variables:
 
 ```tsx
 import {
@@ -221,59 +199,13 @@ import {
   alpha,
 } from '@djangocfg/ui-core/styles/palette';
 
-// Hex colors from CSS variables (updates on theme switch)
 const palette = useThemePalette();
-ctx.fillStyle = palette.primary;              // '#a855f7'
-ctx.fillStyle = alpha(palette.primary, 0.3); // 'rgba(168, 85, 247, 0.3)'
+ctx.fillStyle = palette.primary;               // '#0989aa'
+ctx.fillStyle = alpha(palette.warning, 0.15); // 'rgba(..., 0.15)'
 
-// Pre-built { fill, stroke, color } for diagrams
 const presets = useStylePresets();
-presets.success // { fill: '#22c55e', stroke: '#22c55e', color: '#fff' }
-presets.danger  // { fill: '#ef4444', stroke: '#ef4444', color: '#fff' }
+presets.success // { fill: '#...', stroke: '#...', color: '#fff' }
 
-// Semi-transparent backgrounds (adapts opacity to light/dark)
 const boxes = useBoxColors();
-boxes.primary // 'rgba(168, 85, 247, 0.15)' in light, 0.3 in dark
-```
-
-### `alpha(hex, opacity)`
-
-Convert any hex color to `rgba()` — works with any value from `ThemePalette`:
-
-```tsx
-alpha(palette.primary, 0.3)    // 'rgba(168, 85, 247, 0.3)'
-alpha(palette.destructive, 0.1) // useful for error backgrounds
-```
-
-### Raw HSL Utilities
-
-```tsx
-import { hslToHex, hslToRgbString, hslToRgba } from '@djangocfg/ui-core/styles/palette';
-
-hslToHex('265 89% 78%')        // '#c084fc'
-hslToRgba('265 89% 78%', 0.2) // 'rgba(192, 132, 252, 0.2)'
-```
-
-## What to Avoid
-
-- Custom utilities like: `section-padding`, `animate-*`, `shadow-brand`
-- Arbitrary values without checking if they work: `h-[53px]`, `min-h-[100px]`
-- Opacity modifiers with HSL colors: `bg-background/80`
-- Assuming spacing values exist without defining them in `@theme`
-
-## CSS Variables
-
-Use CSS variables for dynamic values:
-
-```tsx
-<div style={{ color: 'var(--color-primary)' }}>
-```
-
-Or in CSS:
-
-```css
-.my-class {
-  background-color: hsl(var(--background));
-  color: hsl(var(--foreground));
-}
+boxes.primary  // semi-transparent brand, adapts to light/dark
 ```

package/src/styles/theme/dark.css

@@ -60,6 +60,34 @@
   --sidebar-border: 0 0% 15%;
   --sidebar-ring: 189 100% 50%;
 
+  /* ── Status surfaces (dark) ──────────────────────────────────────
+   * Dark variants: dim backgrounds (~8-12% lightness) so banners
+   * don't blow out against the near-black page. Foreground raised
+   * to ~70-80% lightness for contrast. Borders kept muted.
+   * ─────────────────────────────────────────────────────────────── */
+
+  /* Warning — amber */
+  --warning: 38 92% 50%;
+  --warning-background: 38 80% 10%;
+  --warning-foreground: 38 90% 75%;
+  --warning-border: 38 60% 30%;
+
+  /* Success — green */
+  --success: 142 60% 45%;
+  --success-background: 142 60% 8%;
+  --success-foreground: 142 70% 70%;
+  --success-border: 142 50% 25%;
+
+  /* Destructive surface */
+  --destructive-background: 0 80% 10%;
+  --destructive-border: 0 70% 30%;
+
+  /* Info — blue-cyan */
+  --info: 200 80% 55%;
+  --info-background: 200 80% 8%;
+  --info-foreground: 200 80% 75%;
+  --info-border: 200 60% 25%;
+
   /* Surface gradient dark */
   --surface-gradient: linear-gradient(to bottom, hsl(var(--background)), hsl(var(--background) / 0.8));
 

package/src/styles/theme/light.css

@@ -60,6 +60,35 @@
   --sidebar-border: 0 0% 90%;
   --sidebar-ring: 192 90% 35%;
 
+  /* ── Status surfaces ─────────────────────────────────────────────
+   * Each status has 4 tokens: icon/accent color, page background,
+   * readable foreground text, and border ring.
+   * Use bg-warning-background / text-warning-foreground / border-warning-border
+   * in components — never raw amber-* or green-* classes.
+   * ─────────────────────────────────────────────────────────────── */
+
+  /* Warning — amber */
+  --warning: 38 92% 50%;
+  --warning-background: 48 100% 96%;
+  --warning-foreground: 26 90% 25%;
+  --warning-border: 38 70% 65%;
+
+  /* Success — green */
+  --success: 142 71% 45%;
+  --success-background: 138 76% 97%;
+  --success-foreground: 140 60% 20%;
+  --success-border: 142 60% 65%;
+
+  /* Destructive surface (separate from the filled button token) */
+  --destructive-background: 0 100% 97%;
+  --destructive-border: 0 84% 70%;
+
+  /* Info — blue-cyan (brand-adjacent) */
+  --info: 200 90% 40%;
+  --info-background: 200 100% 97%;
+  --info-foreground: 200 80% 20%;
+  --info-border: 200 80% 65%;
+
   /* Surface gradient */
   --surface-gradient: linear-gradient(to bottom, hsl(var(--background)), hsl(var(--background) / 0.8));
 

package/src/styles/theme/theme-tokens.story.tsx

@@ -0,0 +1,157 @@
+import { defineStory } from '@djangocfg/playground';
+
+export default defineStory({
+  title: 'Theme/Tokens',
+  description: 'Visual reference for all semantic CSS color tokens. Use these classes — never raw Tailwind color-scale classes (amber-500 etc).',
+});
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function TokenRow({ label, bg, text, border }: { label: string; bg: string; text: string; border: string }) {
+  return (
+    <div className={`flex items-center justify-between rounded-md border px-4 py-3 ${bg} ${border}`}>
+      <span className={`text-sm font-medium ${text}`}>{label}</span>
+      <div className="flex gap-2 font-mono text-xs opacity-70">
+        <code className={text}>{bg}</code>
+        <code className={text}>{text}</code>
+        <code className={text}>{border}</code>
+      </div>
+    </div>
+  );
+}
+
+function Section({ title, children }: { title: string; children: React.ReactNode }) {
+  return (
+    <div className="space-y-2">
+      <h3 className="text-xs font-semibold uppercase tracking-widest text-muted-foreground">{title}</h3>
+      <div className="space-y-2">{children}</div>
+    </div>
+  );
+}
+
+function SwatchRow({ name, bgClass }: { name: string; bgClass: string }) {
+  return (
+    <div className="flex items-center gap-3">
+      <div className={`h-8 w-16 rounded border border-border ${bgClass}`} />
+      <code className="text-xs text-foreground">{name}</code>
+    </div>
+  );
+}
+
+// ─── Stories ──────────────────────────────────────────────────────────────────
+
+export const StatusSurfaces = () => (
+  <div className="space-y-6 max-w-2xl">
+    <p className="text-sm text-muted-foreground">
+      Status banners — use <code className="text-xs bg-code text-code-foreground rounded px-1">bg-*-background</code>,{' '}
+      <code className="text-xs bg-code text-code-foreground rounded px-1">text-*-foreground</code>,{' '}
+      <code className="text-xs bg-code text-code-foreground rounded px-1">border-*-border</code>
+    </p>
+
+    <Section title="Warning">
+      <TokenRow
+        label="⚠ You're seeing a preview. Subscribe for full access."
+        bg="bg-warning-background"
+        text="text-warning-foreground"
+        border="border border-warning-border/50"
+      />
+    </Section>
+
+    <Section title="Success">
+      <TokenRow
+        label="✓ Operation completed successfully."
+        bg="bg-success-background"
+        text="text-success-foreground"
+        border="border border-success-border/50"
+      />
+    </Section>
+
+    <Section title="Destructive">
+      <TokenRow
+        label="✕ Something went wrong. Please try again."
+        bg="bg-destructive-background"
+        text="text-destructive"
+        border="border border-destructive-border/50"
+      />
+    </Section>
+
+    <Section title="Info">
+      <TokenRow
+        label="ℹ New features are available in your plan."
+        bg="bg-info-background"
+        text="text-info-foreground"
+        border="border border-info-border/50"
+      />
+    </Section>
+  </div>
+);
+
+export const BaseColors = () => (
+  <div className="space-y-6 max-w-xl">
+    <Section title="Base">
+      <div className="grid grid-cols-2 gap-3">
+        <SwatchRow name="bg-background" bgClass="bg-background" />
+        <SwatchRow name="bg-foreground" bgClass="bg-foreground" />
+        <SwatchRow name="bg-card" bgClass="bg-card" />
+        <SwatchRow name="bg-muted" bgClass="bg-muted" />
+        <SwatchRow name="bg-accent" bgClass="bg-accent" />
+        <SwatchRow name="bg-border" bgClass="bg-border" />
+      </div>
+    </Section>
+
+    <Section title="Brand">
+      <div className="grid grid-cols-2 gap-3">
+        <SwatchRow name="bg-primary" bgClass="bg-primary" />
+        <SwatchRow name="bg-secondary" bgClass="bg-secondary" />
+      </div>
+    </Section>
+
+    <Section title="Status accents (icon color)">
+      <div className="grid grid-cols-2 gap-3">
+        <SwatchRow name="bg-warning" bgClass="bg-warning" />
+        <SwatchRow name="bg-success" bgClass="bg-success" />
+        <SwatchRow name="bg-destructive" bgClass="bg-destructive" />
+        <SwatchRow name="bg-info" bgClass="bg-info" />
+      </div>
+    </Section>
+  </div>
+);
+
+export const CodeSurface = () => (
+  <div className="space-y-4 max-w-xl">
+    <Section title="Code tokens">
+      <div className="rounded-md border border-code-border bg-code text-code-foreground p-4 font-mono text-sm">
+        <div>bg-code / text-code-foreground / border-code-border</div>
+        <div className="mt-2 text-xs opacity-60">Used by PrettyCode, MarkdownMessage code fences</div>
+      </div>
+      <div className="text-sm">
+        Inline:{' '}
+        <code className="rounded bg-code-inline px-1.5 py-0.5 text-code-inline-foreground text-xs">
+          const x = 42
+        </code>
+      </div>
+    </Section>
+
+    <Section title="Sidebar tokens">
+      <div className="rounded-md border border-sidebar-border bg-sidebar p-4 space-y-1 text-sidebar-foreground text-sm">
+        <div className="font-semibold">bg-sidebar / text-sidebar-foreground</div>
+        <div className="text-xs opacity-60">Used by the app sidebar chrome</div>
+        <div className="mt-2 rounded bg-sidebar-accent px-2 py-1 text-sidebar-accent-foreground text-xs">
+          bg-sidebar-accent — hover state
+        </div>
+      </div>
+    </Section>
+  </div>
+);
+
+export const TypographyTokens = () => (
+  <div className="space-y-3 max-w-md">
+    <p className="text-foreground text-sm font-medium">text-foreground — primary body</p>
+    <p className="text-muted-foreground text-sm">text-muted-foreground — secondary / hints</p>
+    <p className="text-primary text-sm">text-primary — brand links / accents</p>
+    <p className="text-destructive text-sm">text-destructive — error messages</p>
+    <p className="text-warning text-sm">text-warning — warning labels</p>
+    <p className="text-success text-sm">text-success — success labels</p>
+    <p className="text-info text-sm">text-info — info labels</p>
+  </div>
+);

package/src/styles/theme/tokens.css

@@ -35,7 +35,24 @@
   --color-ring: hsl(var(--ring));
   --color-black: #000000;
   --color-white: #ffffff;
+  /* Status surfaces — warning / success / destructive / info */
   --color-warning: hsl(var(--warning));
+  --color-warning-background: hsl(var(--warning-background));
+  --color-warning-foreground: hsl(var(--warning-foreground));
+  --color-warning-border: hsl(var(--warning-border));
+
+  --color-success: hsl(var(--success));
+  --color-success-background: hsl(var(--success-background));
+  --color-success-foreground: hsl(var(--success-foreground));
+  --color-success-border: hsl(var(--success-border));
+
+  --color-destructive-background: hsl(var(--destructive-background));
+  --color-destructive-border: hsl(var(--destructive-border));
+
+  --color-info: hsl(var(--info));
+  --color-info-background: hsl(var(--info-background));
+  --color-info-foreground: hsl(var(--info-foreground));
+  --color-info-border: hsl(var(--info-border));
 
   /* Code surface tokens — single source of truth for any "this is
    * code, not prose" panel (markdown fences, inline code, terminal