@carbonid1/design-system 5.2.3 → 5.3.0

package/README.md

@@ -64,20 +64,20 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 
 ## Components
 
-| 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 |
+| 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                                                                      |
 
 ## Helpers
 

package/dist/Text/Text.d.ts

@@ -0,0 +1,16 @@
+import type { ElementType } from 'react';
+import type { TextProps } from './Text.types';
+/**
+ * `variant` owns the type *scale* only (size + weight + line-height + tracking).
+ * Font family (`font`) and `color` are kept orthogonal to it, so a single scale
+ * composes with any font family or color context.
+ */
+declare const textVariants: (props?: ({
+    variant?: "title" | "heading" | "display" | "body" | "caption" | "label" | "subheading" | "bodyLg" | "overline" | null | undefined;
+    color?: "default" | "primary" | "success" | "attention" | "destructive" | "highlight" | "muted" | null | undefined;
+    font?: "sans" | "serif" | "mono" | null | undefined;
+    weight?: "bold" | "regular" | "medium" | "semibold" | null | undefined;
+    align?: "end" | "center" | "start" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+declare const Text: <E extends ElementType = "p">({ as, variant, color, font, weight, align, numeric, truncate, className, ...props }: TextProps<E>) => import("react/jsx-runtime").JSX.Element;
+export { Text, textVariants };

package/dist/Text/Text.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from '../helpers/cn/cn';
+import { cva } from 'class-variance-authority';
+/**
+ * `variant` owns the type *scale* only (size + weight + line-height + tracking).
+ * Font family (`font`) and `color` are kept orthogonal to it, so a single scale
+ * composes with any font family or color context.
+ */
+const textVariants = cva('', {
+    variants: {
+        variant: {
+            display: 'text-2xl font-semibold tracking-tight leading-tight',
+            title: 'text-xl font-semibold tracking-tight leading-tight',
+            heading: 'text-lg font-semibold leading-snug',
+            subheading: 'text-base font-medium leading-snug',
+            body: 'text-sm leading-normal',
+            bodyLg: 'text-base leading-relaxed',
+            label: 'text-sm font-medium leading-normal',
+            caption: 'text-xs leading-normal',
+            overline: 'text-xs font-medium uppercase tracking-wide leading-normal',
+        },
+        // Semantic tokens only. `destructive` has no `-foreground` token; the others do.
+        color: {
+            default: 'text-foreground',
+            muted: 'text-muted-foreground',
+            primary: 'text-primary',
+            destructive: 'text-destructive',
+            success: 'text-success-foreground',
+            attention: 'text-attention-foreground',
+            highlight: 'text-highlight-foreground',
+        },
+        // Left unset by default so an ancestor font-family cascades.
+        font: {
+            sans: 'font-sans',
+            serif: 'font-serif',
+            mono: 'font-mono',
+        },
+        // Optional override of the weight baked into `variant`.
+        weight: {
+            regular: 'font-normal',
+            medium: 'font-medium',
+            semibold: 'font-semibold',
+            bold: 'font-bold',
+        },
+        align: {
+            start: 'text-start',
+            center: 'text-center',
+            end: 'text-end',
+        },
+    },
+    // No default `color`/`font` — color is resolved per-variant below, font is inherited.
+    defaultVariants: { variant: 'body' },
+});
+/** Variants that read as secondary chrome and default to the muted token. */
+const MUTED_VARIANTS = new Set(['caption', 'overline']);
+const Text = ({ as, variant = 'body', color, font, weight, align, numeric, truncate, className, ...props }) => {
+    const Component = (as ?? 'p');
+    const resolvedColor = color ?? (variant && MUTED_VARIANTS.has(variant) ? 'muted' : 'default');
+    return (_jsx(Component, { className: cn(textVariants({ variant, color: resolvedColor, font, weight, align }), numeric && 'tabular-nums', truncate && 'truncate', className), ...props }));
+};
+export { Text, textVariants };

package/dist/Text/Text.types.d.ts

@@ -0,0 +1,20 @@
+import type { ElementType, ComponentPropsWithoutRef } from 'react';
+import type { VariantProps } from 'class-variance-authority';
+import type { textVariants } from './Text';
+type TextOwnProps<E extends ElementType = 'p'> = VariantProps<typeof textVariants> & {
+    /** Override the rendered element. Defaults to `p`. Decoupled from `variant` — pick `as` for semantics (`h1`–`h6`, `span`, `label`), `variant` for the look. Element-specific props follow (e.g. `href` when `as="a"`). */
+    as?: E;
+    /** Tabular (fixed-width) digits for numeric columns, timers, and metrics. */
+    numeric?: boolean;
+    /** Clamp to a single line with an ellipsis (Tailwind's `truncate`). */
+    truncate?: boolean;
+    className?: string;
+};
+/**
+ * Props for `<Text>`. Generic over the rendered element so element-specific
+ * attributes resolve correctly (e.g. `href` is available when `as="a"`).
+ */
+type TextProps<E extends ElementType = 'p'> = TextOwnProps<E> & Omit<ComponentPropsWithoutRef<E>, keyof TextOwnProps<E>>;
+/** Concrete, non-generic alias for contexts that need a fixed props type (e.g. Storybook args). */
+type TextPropsDefault = TextProps<'p'>;
+export type { TextProps, TextPropsDefault };

package/dist/Text/Text.types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export { Button, buttonVariants } from './Button/Button';
 export type { ButtonProps } from './Button/Button.types';
 export { Kbd, kbdVariants } from './Kbd/Kbd';
 export type { KbdProps } from './Kbd/Kbd.types';
+export { Text, textVariants } from './Text/Text';
+export type { TextProps, TextPropsDefault } from './Text/Text.types';
 export { ProgressRing } from './ProgressRing/ProgressRing';
 export { Slider } from './Slider/Slider';
 export { ContextMenu } from './ContextMenu/ContextMenu';

package/dist/index.js

@@ -1,6 +1,7 @@
 export { Badge, badgeVariants } from './Badge/Badge';
 export { Button, buttonVariants } from './Button/Button';
 export { Kbd, kbdVariants } from './Kbd/Kbd';
+export { Text, textVariants } from './Text/Text';
 export { ProgressRing } from './ProgressRing/ProgressRing';
 export { Slider } from './Slider/Slider';
 export { ContextMenu } from './ContextMenu/ContextMenu';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carbonid1/design-system",
-  "version": "5.2.3",
+  "version": "5.3.0",
   "description": "Shared React UI primitives + design tokens (themes, postcss config)",
   "repository": {
     "type": "git",
@@ -52,6 +52,7 @@
   "devDependencies": {
     "@base-ui/react": "^1.4.1",
     "@storybook/addon-docs": "^10.3.5",
+    "@storybook/addon-mcp": "^0.6.0",
     "@storybook/addon-themes": "^10.3.5",
     "@storybook/addon-vitest": "^10.3.5",
     "@storybook/react-vite": "^10.3.5",
@@ -76,7 +77,7 @@
   },
   "scripts": {
     "build": "tsc",
-    "storybook": "storybook dev -p 6006",
+    "storybook": "storybook dev -p 7006",
     "build-storybook": "storybook build",
     "test": "vitest --run",
     "test:watch": "vitest",

package/scripts/install-skill.mjs

@@ -6,7 +6,11 @@ import { fileURLToPath } from 'node:url'
 const PKG_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..')
 const SKILL_SRC = join(PKG_DIR, 'skills', 'design-system')
 
-if (!PKG_DIR.includes(`${process.platform === 'win32' ? '\\' : '/'}node_modules${process.platform === 'win32' ? '\\' : '/'}`)) {
+if (
+  !PKG_DIR.includes(
+    `${process.platform === 'win32' ? '\\' : '/'}node_modules${process.platform === 'win32' ? '\\' : '/'}`,
+  )
+) {
   process.exit(0)
 }
 

package/skills/design-system/SKILL.md

@@ -9,17 +9,27 @@ Primitives live in `@carbonid1/design-system`. **Check the package's exports and
 
 ```ts
 import {
-  Badge, Button, Kbd, ProgressRing, Slider,
-  ContextMenu, Select, Tooltip,
-  Toaster, toast,
-  ThemeProvider, ThemeCycler, useTheme,
-  cn, getModKey,
+  Badge,
+  Button,
+  Kbd,
+  ProgressRing,
+  Slider,
+  ContextMenu,
+  Select,
+  Tooltip,
+  Toaster,
+  toast,
+  ThemeProvider,
+  ThemeCycler,
+  useTheme,
+  cn,
+  getModKey,
 } from '@carbonid1/design-system'
 ```
 
 Palettes are chosen by importing one theme CSS per app: `@carbonid1/design-system/themes/reader` (InkVoice) or `/themes/dashboard` (CoI Calculator).
 
-If you're editing `@carbonid1/design-system` itself (adding a primitive, changing a token), read that package's `CLAUDE.md` — this file is for *using* the design system, not building it.
+If you're editing `@carbonid1/design-system` itself (adding a primitive, changing a token), read that package's `CLAUDE.md` — this file is for _using_ the design system, not building it.
 
 ## Core rules
 
@@ -43,12 +53,12 @@ If you're editing `@carbonid1/design-system` itself (adding a primitive, changin
 
 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`       |
+| 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.
 
@@ -60,10 +70,10 @@ Four-tier contract — every themed surface picks one of these tokens. Layering
 
 Two tiers. Pick by how hard the action is to redo, not how scary it feels.
 
-| Severity         | Pattern                             | Example                              |
-| ---------------- | ----------------------------------- | ------------------------------------ |
-| **Hard to redo** | Undo toast (5s + Cmd/Ctrl+Z)        | Delete a record, remove history item |
-| **Easy to redo** | No confirmation                     | Toggle flag, remove a tag            |
+| Severity         | Pattern                      | Example                              |
+| ---------------- | ---------------------------- | ------------------------------------ |
+| **Hard to redo** | Undo toast (5s + Cmd/Ctrl+Z) | Delete a record, remove history item |
+| **Easy to redo** | No confirmation              | Toggle flag, remove a tag            |
 
 **Undo toast:** action executes immediately → toast with description `${getModKey()}+Z to undo` + "Undo" action button (5s auto-dismiss) → store holds `lastDeleted` for restoration → global `mod+z` hotkey via `react-hotkeys-hook` → sequential deletes overwrite the buffer (only latest is undoable). Never add a modal confirmation for hard-to-redo actions — the undo toast is the confirmation.
 

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

@@ -31,41 +31,41 @@ Tokens are defined in `globals.css` (`:root` + `.dark`), bridged in `@theme inli
 
 ### Base tokens (from shadcn naming)
 
-| 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                                                     | —            |
+| 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           |
+| 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
 
-| Token         | Role                                          | Sub-variants              |
-| ------------- | --------------------------------------------- | ------------------------- |
+| Token         | Role                                                      | Sub-variants              |
+| ------------- | --------------------------------------------------------- | ------------------------- |
 | `--highlight` | Emphasis accent (e.g. live cursors, selection highlights) | foreground, muted         |
 | `--attention` | Warnings, notices, saved-for-later — "look at this"       | foreground, muted, border |
-| `--success`   | Completion, positive outcomes                 | foreground                |
+| `--success`   | Completion, positive outcomes                             | foreground                |
 
 ## How to Add a New Semantic Token
 
@@ -99,7 +99,7 @@ Why dark mode skips the inset shadow: top-edge highlights fake a "light source f
 
 ## 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.
+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)
@@ -112,7 +112,7 @@ bg-popover         floats above everything       → shadow-popover
 
 ### 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.
+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

package/themes/dashboard.css

@@ -21,7 +21,7 @@
  * Button/Kbd/etc. — Tailwind v4 skips node_modules by default. Point at the
  * shipped `dist/` (the only source that lands in installed `node_modules`),
  * not `src/` which isn't in the published `files`. */
-@source "../dist/**/*.js";
+@source '../dist/**/*.js';
 
 @custom-variant dark (&:is(.dark *));
 
@@ -59,7 +59,38 @@
   --color-border: var(--border);
   --color-input: var(--input);
   --color-ring: var(--ring);
-  --font-serif: var(--font-literata), Georgia, Cambria, 'Times New Roman', Times, serif;
+  /* Font families. Override a role by setting its `--font-*-custom` variable;
+   * each falls back to a system stack. */
+  --font-sans: var(
+    --font-sans-custom,
+    ui-sans-serif,
+    system-ui,
+    sans-serif,
+    'Apple Color Emoji',
+    'Segoe UI Emoji',
+    'Segoe UI Symbol',
+    'Noto Color Emoji'
+  );
+  --font-serif: var(
+    --font-serif-custom,
+    ui-serif,
+    Georgia,
+    Cambria,
+    'Times New Roman',
+    Times,
+    serif
+  );
+  --font-mono: var(
+    --font-mono-custom,
+    ui-monospace,
+    SFMono-Regular,
+    Menlo,
+    Monaco,
+    Consolas,
+    'Liberation Mono',
+    'Courier New',
+    monospace
+  );
   --radius: 0.625rem;
   --animate-buffer-pulse: buffer-pulse 3s ease-in-out infinite;
   --animate-ring-spin: ring-spin 5s linear infinite;
@@ -76,8 +107,7 @@
   --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);
+  --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);

package/themes/reader.css

@@ -43,7 +43,7 @@
  * Button/Kbd/etc. — Tailwind v4 skips node_modules by default. Point at the
  * shipped `dist/` (the only source that lands in installed `node_modules`),
  * not `src/` which isn't in the published `files`. */
-@source "../dist/**/*.js";
+@source '../dist/**/*.js';
 
 @custom-variant dark (&:is(.dark *));
 
@@ -81,7 +81,38 @@
   --color-border: var(--border);
   --color-input: var(--input);
   --color-ring: var(--ring);
-  --font-serif: var(--font-literata), Georgia, Cambria, 'Times New Roman', Times, serif;
+  /* Font families. Override a role by setting its `--font-*-custom` variable;
+   * each falls back to a system stack. */
+  --font-sans: var(
+    --font-sans-custom,
+    ui-sans-serif,
+    system-ui,
+    sans-serif,
+    'Apple Color Emoji',
+    'Segoe UI Emoji',
+    'Segoe UI Symbol',
+    'Noto Color Emoji'
+  );
+  --font-serif: var(
+    --font-serif-custom,
+    var(--font-literata),
+    Georgia,
+    Cambria,
+    'Times New Roman',
+    Times,
+    serif
+  );
+  --font-mono: var(
+    --font-mono-custom,
+    ui-monospace,
+    SFMono-Regular,
+    Menlo,
+    Monaco,
+    Consolas,
+    'Liberation Mono',
+    'Courier New',
+    monospace
+  );
   --radius: 0.625rem;
   --animate-buffer-pulse: buffer-pulse 3s ease-in-out infinite;
   --animate-ring-spin: ring-spin 5s linear infinite;