@carbonid1/design-system 5.0.2 → 5.1.0

package/README.md

@@ -66,13 +66,16 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 
 | Component | Use for |
 | --- | --- |
+| `Badge` | Compact status/label chip with variants |
 | `Button` | Standard button primitive with variants (`ghost`, `primary`, `outline`, `destructive`, `attention`, `subtle`, `danger`, `link`) |
 | `Kbd` | Keyboard key display (`⌘K`, `⇧B`) |
 | `ProgressRing` | Circular progress indicator |
 | `Slider` | Range slider |
+| `ContextMenu` | Right-click / long-press menu (compound API) |
 | `Select` | Custom dropdown — never use native `<select>` |
 | `Tooltip` | Hover/focus tooltip (wraps a single child) |
 | `Toaster` | Toast notification root (renders once in layout) |
+| `toast` | Imperative toast trigger (re-export from `sonner`) |
 | `ThemeProvider` | Wraps `next-themes` — provides dark/light mode |
 | `ThemeCycler` | `shift+t` hotkey cycles `system → light → dark` with toast |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carbonid1/design-system",
-  "version": "5.0.2",
+  "version": "5.1.0",
   "description": "Shared React UI primitives + design tokens (themes, postcss config)",
   "repository": {
     "type": "git",

package/skills/design-system/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design-system
-description: 'Shared UI components and design patterns for carbonid1 apps built on @carbonid1/design-system. ALWAYS use when building UI, creating components, adding dropdowns, selects, tooltips, icons, toasts, context menus, or any interactive element. Use when choosing between native HTML elements and custom components. Also use when working with skeletons, loading states, layout shifts, or async-loaded UI elements. Triggers on: dropdown, select, tooltip, tag, badge, icon, component, UI, design system, shared component, skeleton, loading state, layout shift, context menu, right-click menu, button, theme, palette.'
+description: 'Shared UI components and design patterns for carbonid1 apps built on @carbonid1/design-system. ALWAYS use when building UI, creating components, adding dropdowns, selects, tooltips, icons, toasts, context menus, badges, or any interactive element. Use when choosing between native HTML elements and custom components. Also covers visual conventions for layout stability when wiring async UI (skeletons are consumer-owned, but the rules for them live here). Triggers on: dropdown, select, tooltip, tag, badge, icon, component, UI, design system, shared component, layout shift, context menu, right-click menu, button, theme, palette.'
 ---
 
 # Design System
@@ -9,7 +9,7 @@ Primitives live in `@carbonid1/design-system`. **Check the package's exports and
 
 ```ts
 import {
-  Button, Kbd, ProgressRing, Slider,
+  Badge, Button, Kbd, ProgressRing, Slider,
   ContextMenu, Select, Tooltip,
   Toaster, toast,
   ThemeProvider, ThemeCycler, useTheme,
@@ -39,6 +39,23 @@ If you're editing `@carbonid1/design-system` itself (adding a primitive, changin
 - **Touch targets** — icon buttons `p-1.5` minimum, icons `w-4 h-4` minimum
 - **Avatars** — only with real images, no letter/initial placeholders
 
+## Elevation
+
+Four-tier contract — every themed surface picks one of these tokens. Layering is recessed: cards are sheets on the desk, controls are carved INTO sheets, popovers lift OFF the desk.
+
+| Token              | Role                                     | Pair with              |
+| ------------------ | ---------------------------------------- | ---------------------- |
+| `bg-background`    | Page (the desk)                          | —                      |
+| `bg-card`          | Raised paper on the desk — peak surface  | `shadow-card`          |
+| `bg-surface-inset` | Inset block carved into a card           | `inset-shadow-surface` |
+| `bg-popover`       | Floating layer above everything          | `shadow-popover`       |
+
+`bg-surface-inset` covers form inputs, preview boxes, quote blocks, and language tabs. `bg-popover` covers drawers, menus, and command palettes.
+
+**`bg-muted`, `bg-accent`, `bg-secondary` are RESERVED for interaction states** — hover backgrounds, skeleton placeholders, badge fills, soft tints. They are never the background of a card or an inset block. Mixing them in breaks the layering contract; see [references/theming.md](references/theming.md) for the deeper rationale.
+
+**Empty placeholders** — when a slot is meant to be filled (`AddBookCard`, file drop zone, audio preview slot before recording), render a transparent or background-matched surface with `border-dashed`. The empty state reads as a missing piece on its parent surface — never as a recessed input or a card. Once filled, swap to a solid border and the surface adopts its real elevation.
+
 ## Destructive Actions
 
 Two tiers. Pick by how hard the action is to redo, not how scary it feels.

package/skills/design-system/references/theming.md

@@ -31,20 +31,33 @@ Tokens are defined in `globals.css` (`:root` + `.dark`), bridged in `@theme inli
 
 ### Base tokens (from shadcn naming)
 
-| Token           | Role                                                            | Sub-variants |
-| --------------- | --------------------------------------------------------------- | ------------ |
-| `--background`  | Page background                                                 | —            |
-| `--foreground`  | Default text                                                    | —            |
-| `--card`        | Card surfaces                                                   | foreground   |
-| `--popover`     | Popover surfaces                                                | foreground   |
-| `--primary`     | Interactive color (buttons, links, selections, focus, progress) | foreground   |
-| `--secondary`   | Supporting surfaces                                             | foreground   |
-| `--muted`       | De-emphasized surfaces and text                                 | foreground   |
-| `--accent`      | Hover/expanded tints                                            | foreground   |
-| `--destructive` | Errors, danger                                                  | —            |
-| `--border`      | Default borders                                                 | —            |
-| `--input`       | Input borders                                                   | —            |
-| `--ring`        | Focus rings                                                     | —            |
+| Token              | Role                                                            | Sub-variants |
+| ------------------ | --------------------------------------------------------------- | ------------ |
+| `--background`     | Page background (the desk)                                      | —            |
+| `--foreground`     | Default text                                                    | —            |
+| `--card`           | Raised card surfaces                                            | foreground   |
+| `--popover`        | Floating popover/drawer/menu surfaces                           | foreground   |
+| `--surface-inset`  | Inset blocks carved into a card (inputs, preview boxes)         | —            |
+| `--primary`        | Interactive color (buttons, links, selections, focus, progress) | foreground   |
+| `--secondary`      | Supporting surfaces                                             | foreground   |
+| `--muted`          | De-emphasized surfaces and text                                 | foreground   |
+| `--accent`         | Hover/expanded tints                                            | foreground   |
+| `--destructive`    | Errors, danger                                                  | —            |
+| `--border`         | Default borders                                                 | —            |
+| `--input`          | Input borders                                                   | —            |
+| `--ring`           | Focus rings                                                     | —            |
+
+### Elevation shadows
+
+Each elevated surface pairs with a tuned shadow. Tailwind utilities: `shadow-card`, `inset-shadow-surface`, `shadow-popover`.
+
+| Token                    | Pairs with         | Notes                                                |
+| ------------------------ | ------------------ | ---------------------------------------------------- |
+| `--card-shadow`          | `bg-card`          | Subtle drop, neutral or hue-tinted per theme         |
+| `--surface-inset-shadow` | `bg-surface-inset` | Hairline inset top in light, `none` in dark          |
+| `--popover-shadow`       | `bg-popover`       | Stronger drop with larger geometry in dark           |
+
+Why dark mode skips the inset shadow: top-edge highlights fake a "light source from above" convention that reads as a sharp border artifact on dark surfaces, not as a soft recess. Tonal contrast (a wider inset-vs-card lightness delta) carries the elevation instead.
 
 ### Custom tokens
 
@@ -84,6 +97,32 @@ Tokens are defined in `globals.css` (`:root` + `.dark`), bridged in `@theme inli
    <span className="bg-my-token/10">  // opacity modifier for tints
    ```
 
+## Surfaces & Elevation
+
+Four-tier contract that every themed surface picks from. Layering is *recessed* (cards are sheets on the desk; inputs are carved INTO sheets; popovers lift OFF the desk) — the inverse of Material's monotonic stack.
+
+```
+bg-background      page (the desk)
+bg-card            raised paper on the desk      → shadow-card
+bg-surface-inset   inset INTO a card             → inset-shadow-surface (light only)
+bg-popover         floats above everything       → shadow-popover
+```
+
+**`bg-muted`, `bg-accent`, `bg-secondary` are RESERVED for interaction states** — hover backgrounds, skeleton placeholders, badge fills, soft tints. They are NEVER the background of a card or an inset block. The four tokens above are the only source of truth for surface elevation; mixing the interaction-state tokens in breaks the layering contract.
+
+### Empty-slot convention
+
+When a region is meant to be filled (`AddBookCard`, audio drop zone, preview slot before recording), render it as a *background-matched or transparent* surface with `border-dashed` and a foreground border token (`border-border` or similar). The slot reads as a missing piece on its parent surface — never as a recessed input or a card. Once filled, the dashed border switches to solid and the surface adopts its real elevation.
+
+```tsx
+// Empty slot on a card surface
+<div className="border-border bg-card rounded-lg border-2 border-dashed p-4">
+  <PlusIcon /> Add a book
+</div>
+```
+
+Don't use `bg-surface-inset` for empty placeholders — that signals "a control lives here", not "a slot is missing".
+
 ## Notes
 
 - **`::selection`** uses solid oklch values, not opacity modifiers — semi-transparent backgrounds create visible seams at line boundaries.

package/src/Toaster/Toaster.tsx

@@ -3,5 +3,5 @@
 import { Toaster as Sonner, type ToasterProps } from 'sonner'
 
 export const Toaster = (props: ToasterProps) => (
-  <Sonner theme="system" className="toaster group" position="bottom-right" {...props} />
+  <Sonner theme="system" position="bottom-right" {...props} />
 )

package/themes/dashboard.css

@@ -1,9 +1,14 @@
 /* @carbonid1/tailwind-config/dashboard
  *
- * Dashboard theme: semantic color tokens for data-dense UIs (calculators,
- * admin panels, production-chain visualizers). Currently identical tokens
- * to `reader` — distinct palette pending visual design work.
- * Pulls in tailwindcss itself so consumers only need this single import.
+ * Dashboard theme — for data-dense UIs (CoI Calculator, admin panels,
+ * production-chain visualizers). Visual register: neutral-cool surfaces
+ * with subtle elevation (high-information UIs benefit from low-noise
+ * chrome that lets data take focus).
+ *
+ * Same elevation contract as reader.css — see that file for the full table.
+ * Surfaces here are neutral (chroma 0 in light, ~hue 260 in dark) instead
+ * of warm paper, but the layering rules (background < card; surface-inset
+ * recessed into card; popover floats with shadow) are identical.
  *
  * Consumer responsibilities:
  *   - Optionally import tw-animate-css for animate utilities.
@@ -25,6 +30,10 @@
   --color-card-foreground: var(--card-foreground);
   --color-popover: var(--popover);
   --color-popover-foreground: var(--popover-foreground);
+  --color-surface-inset: var(--surface-inset);
+  --shadow-card: var(--card-shadow);
+  --shadow-popover: var(--popover-shadow);
+  --inset-shadow-surface: var(--surface-inset-shadow);
   --color-primary: var(--primary);
   --color-primary-foreground: var(--primary-foreground);
   --color-primary-muted: var(--primary-muted);
@@ -63,6 +72,11 @@
   --card-foreground: oklch(0.145 0 0);
   --popover: oklch(1 0 0);
   --popover-foreground: oklch(0.145 0 0);
+  --surface-inset: oklch(0.965 0 0);
+  --card-shadow: 0 1px 2px 0 oklch(0.2 0 0 / 0.06);
+  --popover-shadow:
+    0 8px 24px -4px oklch(0.2 0 0 / 0.1), 0 4px 8px -2px oklch(0.2 0 0 / 0.06);
+  --surface-inset-shadow: inset 0 1px 1px 0 oklch(0.2 0 0 / 0.04);
   --primary: oklch(0.546 0.245 262.881);
   --primary-foreground: oklch(1 0 0);
   --primary-muted: oklch(0.97 0.014 254);
@@ -96,6 +110,10 @@
   --card-foreground: oklch(0.967 0.003 265);
   --popover: oklch(0.278 0.03 257);
   --popover-foreground: oklch(0.967 0.003 265);
+  --surface-inset: oklch(0.225 0.028 261);
+  --card-shadow: 0 1px 2px 0 oklch(0 0 0 / 0.2);
+  --popover-shadow: 0 12px 32px -4px oklch(0 0 0 / 0.4), 0 4px 8px -2px oklch(0 0 0 / 0.2);
+  --surface-inset-shadow: none;
   --primary: oklch(0.78 0.13 256);
   --primary-foreground: oklch(1 0 0);
   --primary-muted: oklch(0.282 0.091 267 / 0.2);

package/themes/reader.css

@@ -1,8 +1,33 @@
 /* @carbonid1/tailwind-config/reader
  *
- * Reader theme: semantic color tokens, dark variant, @theme bridge.
- * Includes the keyframes required by the theme's --animate-* tokens.
- * Pulls in tailwindcss itself so consumers only need this single import.
+ * Reader theme — for reading-app consumers (InkVoice, future longform/journal
+ * apps). Visual register: warm paper layered on a desk. Light mode is a
+ * hue-75 warm-paper palette with tonal layering and recessed inputs; dark
+ * mode is a cool ink palette (~hue 260) with the same elevation hierarchy.
+ *
+ * --- Elevation contract (use this to pick the right surface token) --------
+ *
+ *   Token              Role                                    Light      Dark
+ *   ─────────────────  ──────────────────────────────────────  ─────────  ─────────
+ *   bg-background      page (the desk)                         warm off   cool dark
+ *   bg-card            raised paper on the desk                brightest  peak
+ *   bg-surface-inset   inset block carved INTO a card          darker     darker than card
+ *                      (form inputs, preview boxes,
+ *                       quote blocks, language tabs)
+ *   bg-popover         floating layer above everything         = card     = card
+ *                      (drawers, menus, command palette)       + shadow   + shadow
+ *
+ * --- Shadow contract (paired with the surface above) ----------------------
+ *
+ *   shadow-card               on bg-card           subtle drop
+ *   inset-shadow-surface      on bg-surface-inset  hairline inset top (light only)
+ *   shadow-popover            on bg-popover        strong drop
+ *
+ * Usage rules (which tokens are surfaces, empty-slot convention, etc.) live
+ * in the design-system skill — see SKILL.md / references/theming.md.
+ *
+ * TODO: dark mode currently mirrors the existing cool palette. A dedicated
+ *       warm-dark "ink on cream" pass is deferred — separate visual decision.
  *
  * Consumer responsibilities:
  *   - Import tw-animate-css and shadcn base layer separately if needed.
@@ -27,6 +52,10 @@
   --color-card-foreground: var(--card-foreground);
   --color-popover: var(--popover);
   --color-popover-foreground: var(--popover-foreground);
+  --color-surface-inset: var(--surface-inset);
+  --shadow-card: var(--card-shadow);
+  --shadow-popover: var(--popover-shadow);
+  --inset-shadow-surface: var(--surface-inset-shadow);
   --color-primary: var(--primary);
   --color-primary-foreground: var(--primary-foreground);
   --color-primary-muted: var(--primary-muted);
@@ -59,12 +88,19 @@
 
 /* Light mode tokens */
 :root {
-  --background: oklch(1 0 0);
+  --background: oklch(0.985 0.005 75);
   --foreground: oklch(0.145 0 0);
-  --card: oklch(1 0 0);
+  --card: oklch(0.995 0.003 75);
   --card-foreground: oklch(0.145 0 0);
-  --popover: oklch(1 0 0);
+  --popover: oklch(0.995 0.003 75);
   --popover-foreground: oklch(0.145 0 0);
+  --surface-inset: oklch(0.962 0.007 75);
+  /* Shadows tinted with the warm hue so they read as ambient occlusion on
+   * paper, not pure black smudges. */
+  --card-shadow: 0 1px 2px 0 oklch(0.2 0.02 75 / 0.06);
+  --popover-shadow:
+    0 8px 24px -4px oklch(0.2 0.02 75 / 0.1), 0 4px 8px -2px oklch(0.2 0.02 75 / 0.06);
+  --surface-inset-shadow: inset 0 1px 1px 0 oklch(0.2 0.02 75 / 0.04);
   --primary: oklch(0.546 0.245 262.881);
   --primary-foreground: oklch(1 0 0);
   --primary-muted: oklch(0.97 0.014 254);
@@ -98,6 +134,15 @@
   --card-foreground: oklch(0.967 0.003 265);
   --popover: oklch(0.278 0.03 257);
   --popover-foreground: oklch(0.967 0.003 265);
+  /* Inset/card delta is wider than light mode — lightness differences read
+   * as weaker in the dark range, so the recess needs more room to land. */
+  --surface-inset: oklch(0.225 0.028 261);
+  /* Inset shadow disabled: top-edge highlights fake a light-source-from-above
+   * convention that reads as a sharp border artifact on dark surfaces rather
+   * than a soft recess. The tonal delta above carries the elevation instead. */
+  --card-shadow: 0 1px 2px 0 oklch(0 0 0 / 0.2);
+  --popover-shadow: 0 12px 32px -4px oklch(0 0 0 / 0.4), 0 4px 8px -2px oklch(0 0 0 / 0.2);
+  --surface-inset-shadow: none;
   --primary: oklch(0.78 0.13 256);
   --primary-foreground: oklch(1 0 0);
   --primary-muted: oklch(0.282 0.091 267 / 0.2);