@carbonid1/design-system 4.0.1 → 4.2.0

package/README.md

@@ -1,11 +1,11 @@
 # @carbonid1/design-system
 
-Shared React UI primitives themed via [`@carbonid1/tailwind-config`](../tailwind-config).
+Shared React UI primitives + Tailwind v4 theme presets (`reader`, `dashboard`) + postcss config.
 
 ## Install
 
 ```sh
-pnpm add @carbonid1/design-system @carbonid1/tailwind-config react react-dom @base-ui/react class-variance-authority clsx tailwind-merge lucide-react sonner next-themes react-hotkeys-hook
+pnpm add @carbonid1/design-system react react-dom @base-ui/react class-variance-authority clsx tailwind-merge lucide-react sonner next-themes react-hotkeys-hook
 ```
 
 And Tailwind CSS v4 (with `tw-animate-css` + `shadcn/tailwind.css` if you want matching utilities/base):
@@ -24,7 +24,7 @@ In your entry CSS (Next.js: `src/app/globals.css`):
 @import 'tailwindcss';
 @import 'tw-animate-css';
 @import 'shadcn/tailwind.css';
-@import '@carbonid1/tailwind-config/reader';
+@import '@carbonid1/design-system/themes/reader';
 ```
 
 ### 2. Transpile the package in Next.js
@@ -84,8 +84,8 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 
 ## Theming
 
-Components use semantic color utilities (`bg-primary`, `text-muted-foreground`, etc.) that resolve via `@carbonid1/tailwind-config`. Switching theme → swap the tailwind-config import. Dark mode is toggled by adding `class="dark"` to a root ancestor (`ThemeProvider` handles this).
+Components use semantic color utilities (`bg-primary`, `text-muted-foreground`, etc.) that resolve via the imported theme preset. Switching theme → swap the `@carbonid1/design-system/themes/*` import. Dark mode is toggled by adding `class="dark"` to a root ancestor (`ThemeProvider` handles this).
 
 ## Build
 
-No build step — package ships raw `.tsx` via `files: ["src"]`. Consumers transpile at build time. Stories (`*.stories.tsx`) and tests (`*.vi.{ts,tsx}`) are excluded from the published tarball.
+No build step — package ships raw `.tsx`. Consumers transpile at build time. Stories (`*.stories.tsx`) and tests (`*.test.{ts,tsx}`) are excluded from the published tarball.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carbonid1/design-system",
-  "version": "4.0.1",
+  "version": "4.2.0",
   "description": "Shared React UI primitives + design tokens (themes, postcss config)",
   "repository": {
     "type": "git",
@@ -10,6 +10,9 @@
   "license": "MIT",
   "author": "Andrew Korin",
   "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
   "exports": {
     ".": "./src/index.ts",
     "./themes/reader": "./themes/reader.css",
@@ -19,7 +22,9 @@
   "files": [
     "src",
     "themes",
-    "postcss.mjs"
+    "postcss.mjs",
+    "skills",
+    "scripts"
   ],
   "dependencies": {
     "@tailwindcss/postcss": "^4.2.0",
@@ -67,12 +72,13 @@
     "tailwindcss": "^4.2.2",
     "vite": "^8.0.8",
     "vitest": "^4.1.4",
-    "@carbonid1/tsconfig": "0.2.0"
+    "@carbonid1/tsconfig": "0.2.1"
   },
   "scripts": {
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
     "test": "vitest --run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "postinstall": "node scripts/install-skill.mjs"
   }
 }

package/scripts/install-skill.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { mkdir, rm, symlink } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+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' ? '\\' : '/'}`)) {
+  process.exit(0)
+}
+
+const consumerRoot = process.env.INIT_CWD || process.cwd()
+const skillDest = join(consumerRoot, '.claude', 'skills', 'design-system')
+
+try {
+  await mkdir(dirname(skillDest), { recursive: true })
+  await rm(skillDest, { recursive: true, force: true })
+  await symlink(SKILL_SRC, skillDest, 'dir')
+  console.log(`[@carbonid1/design-system] linked skill → ${skillDest}`)
+} catch (err) {
+  console.warn(`[@carbonid1/design-system] could not link skill: ${err.message}`)
+}

package/skills/design-system/SKILL.md

@@ -0,0 +1,65 @@
+---
+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.'
+---
+
+# Design System
+
+Primitives live in `@carbonid1/design-system`. **Check the package's exports and types before building anything new.** This file is direction and taste, not API reference — the types are the docs.
+
+```ts
+import {
+  Button, Kbd, ProgressRing, Slider, Switch,
+  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.
+
+## Core rules
+
+- Never use native `<select>` — use `Select`
+- Never build a tooltip, context menu, or toast from scratch — use `Tooltip`, `ContextMenu`, `toast()`
+- All icons from `lucide-react` — search `lucide.dev/icons` before creating anything custom. If nothing fits, build via Lucide's `Icon` + `iconNode`, don't reach for another library.
+- All color through semantic tokens — no hardcoded Tailwind color classes. See [references/theming.md](references/theming.md).
+- Tooltip: rely on defaults (`position="top"`, `delay={200}`). Only override when the default is wrong (e.g. header → `position="bottom"`, data-viz progressive disclosure → `delay={600}`). When a tooltip trigger also opens a popover, pass `disabled={open}`.
+- Icon toggle state: `<Icon fill={active ? 'currentColor' : 'none'} />` — not two different components.
+
+## Visual Language
+
+- **Discrete elements** — rows/cards use `rounded-lg` with `space-y-1` gaps, never flat lists with hairline dividers
+- **Selection** — `bg-primary/10` tint + `ring-1 ring-primary/20`, never border-left accents
+- **Hover reveal** — action buttons use `opacity-0 group-hover:opacity-100 group-focus-within:opacity-100` with outer row `hover:bg-accent`. The `group-focus-within` is required — without it, keyboard users tab to an invisible button.
+- **Metadata** — badge/chip components, never comma-separated text
+- **Touch targets** — icon buttons `p-1.5` minimum, icons `w-4 h-4` minimum
+- **Avatars** — only with real images, no letter/initial placeholders
+
+## Destructive Actions
+
+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            |
+
+**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.
+
+## Layout Stability
+
+Skeleton → real UI transitions must not shift layout. The skeleton is a dimensional contract.
+
+- Skeletons match real UI structure, counts, heights, spacing. Update the skeleton when the real UI changes.
+- Async elements that always render (selectors, user controls) show a same-sized placeholder while loading — never `null`.
+- Doesn't apply to user-triggered UI (modals, drawers, toasts) or conditional banners — these are unpredictable by nature.
+
+## Theming
+
+`ThemeProvider` wraps the app (toggles `.dark` via `next-themes`). `ThemeCycler` mounts once to register `Shift+T` for cycling system → light → dark. `useTheme` is the next-themes re-export for programmatic access.
+
+Both palettes define the same token names on `:root` + `.dark`, so primitive code and consumer code don't care which palette is active.

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

@@ -0,0 +1,91 @@
+# Color & Theming
+
+## Philosophy
+
+Tokens represent semantic roles, not fixed hues. Each theme picks the best hue for that role in its own context — light and dark themes may use entirely different hue families for the same token. The design system is app-agnostic: swap the token values, everything updates.
+
+We use shadcn's token naming convention but own all color values. When pulling a new shadcn component, replace any generated color values with our hand-tuned tokens. This follows shadcn's own approach (~99% token-driven) as validation, not as a dependency.
+
+## Palettes
+
+`@carbonid1/design-system` ships multiple palettes — currently `reader` (InkVoice) and `dashboard` (CoI Calculator, admin-style UIs). Both define the same token names on `:root` + `.dark`; consumers choose one by importing the matching CSS:
+
+```ts
+import '@carbonid1/design-system/themes/reader'
+// or
+import '@carbonid1/design-system/themes/dashboard'
+```
+
+Primitives must render correctly under every palette × light/dark combination — that's the contract. Because both palettes hit the same token names, primitive code stays palette-agnostic and consumer code doesn't change when switching.
+
+## Rules
+
+- **All color through tokens.** Every color that appears in themed UI must reference a CSS variable. No hardcoded Tailwind color classes (`blue-500`, `amber-400`, `gray-300`) for meaning-bearing colors.
+- **Hardcoded only when physically fixed.** The only exception: values that must be constant regardless of theme (e.g. `bg-black/10` for modal backdrops). These are rare — 2-3 cases in the entire app.
+- **Opacity modifiers work natively.** Tailwind v4 supports `bg-token/20` on any color format including oklch CSS variables. No `color-mix()` workarounds needed.
+- **Use enough sub-variants for depth.** Don't squeeze a semantic color into just 2 tokens (base + foreground) when it serves distinct roles — text, background, and border often need different values to look intentional. Use 4-5 sub-variants (e.g. `foreground`, `muted`, `border`) when it gives the area more visual depth. Opacity modifiers on a single base color are a poor substitute for dedicated tokens tuned per role.
+
+## Token Inventory
+
+Tokens are defined in `globals.css` (`:root` + `.dark`), bridged in `@theme inline` block, consumed as Tailwind utilities.
+
+### 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                                                     | —            |
+
+### Custom tokens
+
+| 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                |
+
+## How to Add a New Semantic Token
+
+1. **Define values** in `globals.css` — both `:root` (light) and `.dark`. Use oklch for perceptual uniformity. Light and dark values may use different hues if the role reads better that way.
+
+   ```css
+   :root {
+     --my-token: oklch(0.65 0.15 45);
+     --my-token-foreground: oklch(0.25 0.05 40);
+   }
+   .dark {
+     --my-token: oklch(0.7 0.12 200);
+     --my-token-foreground: oklch(0.95 0.02 195);
+   }
+   ```
+
+2. **Bridge in `@theme inline`** in `globals.css` so Tailwind generates utilities:
+
+   ```css
+   @theme inline {
+     --color-my-token: var(--my-token);
+     --color-my-token-foreground: var(--my-token-foreground);
+   }
+   ```
+
+3. **Use in components** via Tailwind classes:
+   ```tsx
+   <div className="bg-my-token text-my-token-foreground">
+   <span className="bg-my-token/10">  // opacity modifier for tints
+   ```
+
+## Notes
+
+- **`::selection`** uses solid oklch values, not opacity modifiers — semi-transparent backgrounds create visible seams at line boundaries.
+- **Tooltip** uses inverted tokens (`bg-foreground text-background`) since it's a dark-on-light / light-on-dark surface. Kbd badge: `bg-background/15`.
+- **DebugPanel** is excluded from token migration — physically fixed terminal aesthetic.

package/src/ContextMenu/ContextMenu.tsx

@@ -0,0 +1,159 @@
+'use client'
+
+import { ContextMenu as BaseContextMenu } from '@base-ui/react/context-menu'
+import { ChevronRight } from 'lucide-react'
+import type { ComponentPropsWithoutRef, Ref } from 'react'
+import { cn } from '../helpers/cn/cn'
+
+type BasePopupProps = ComponentPropsWithoutRef<typeof BaseContextMenu.Popup>
+type BasePositionerProps = ComponentPropsWithoutRef<typeof BaseContextMenu.Positioner>
+type BaseItemProps = ComponentPropsWithoutRef<typeof BaseContextMenu.Item>
+type BaseSeparatorProps = ComponentPropsWithoutRef<typeof BaseContextMenu.Separator>
+type BaseGroupLabelProps = ComponentPropsWithoutRef<typeof BaseContextMenu.GroupLabel>
+type BaseSubmenuTriggerProps = ComponentPropsWithoutRef<typeof BaseContextMenu.SubmenuTrigger>
+type BaseCheckboxItemProps = ComponentPropsWithoutRef<typeof BaseContextMenu.CheckboxItem>
+type BaseRadioItemProps = ComponentPropsWithoutRef<typeof BaseContextMenu.RadioItem>
+
+type ItemVariant = 'default' | 'destructive'
+
+type PositionerProps = BasePositionerProps & { ref?: Ref<HTMLDivElement> }
+type PopupProps = BasePopupProps & { ref?: Ref<HTMLDivElement> }
+type SeparatorProps = BaseSeparatorProps & { ref?: Ref<HTMLDivElement> }
+type GroupLabelProps = BaseGroupLabelProps & { ref?: Ref<HTMLDivElement> }
+type ItemProps = BaseItemProps & { ref?: Ref<HTMLDivElement>; variant?: ItemVariant }
+type CheckboxItemProps = BaseCheckboxItemProps & { ref?: Ref<HTMLDivElement> }
+type RadioItemProps = BaseRadioItemProps & { ref?: Ref<HTMLDivElement> }
+type SubmenuTriggerProps = BaseSubmenuTriggerProps & { ref?: Ref<HTMLDivElement> }
+
+const popupClasses =
+  'bg-popover text-popover-foreground border-border z-50 min-w-45 origin-[var(--transform-origin)] rounded-lg border py-1 shadow-lg outline-hidden transition-[transform,opacity] data-[ending-style]:scale-95 data-[ending-style]:opacity-0 data-[starting-style]:scale-95 data-[starting-style]:opacity-0'
+
+const itemBaseClasses =
+  'relative flex h-7 cursor-default items-center gap-1.5 px-2.5 text-[0.8rem] outline-hidden select-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4 data-[disabled]:pointer-events-none data-[disabled]:opacity-50'
+
+const itemVariantClasses: Record<ItemVariant, string> = {
+  default:
+    'data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground',
+  destructive:
+    'text-destructive data-[highlighted]:bg-destructive/10 data-[highlighted]:text-destructive',
+}
+
+const Positioner = ({ className, sideOffset = 4, ...props }: PositionerProps) => (
+  <BaseContextMenu.Positioner
+    sideOffset={sideOffset}
+    className={cn('z-50 outline-hidden', className)}
+    {...props}
+  />
+)
+
+const Popup = ({ className, ...props }: PopupProps) => (
+  <BaseContextMenu.Popup className={cn(popupClasses, className)} {...props} />
+)
+
+const Item = ({ className, variant = 'default', ...props }: ItemProps) => (
+  <BaseContextMenu.Item
+    className={cn(itemBaseClasses, itemVariantClasses[variant], className)}
+    {...props}
+  />
+)
+
+const Separator = ({ className, ...props }: SeparatorProps) => (
+  <BaseContextMenu.Separator
+    className={cn('bg-border my-1 h-px', className)}
+    {...props}
+  />
+)
+
+const GroupLabel = ({ className, ...props }: GroupLabelProps) => (
+  <BaseContextMenu.GroupLabel
+    className={cn('text-muted-foreground px-2.5 py-1 text-xs', className)}
+    {...props}
+  />
+)
+
+const CheckboxItem = ({ className, children, ...props }: CheckboxItemProps) => (
+  <BaseContextMenu.CheckboxItem
+    className={cn(itemBaseClasses, itemVariantClasses.default, 'pl-7', className)}
+    {...props}
+  >
+    <span
+      aria-hidden
+      className="absolute left-2 flex size-3.5 items-center justify-center"
+    >
+      <BaseContextMenu.CheckboxItemIndicator className="size-3.5">
+        <CheckIcon />
+      </BaseContextMenu.CheckboxItemIndicator>
+    </span>
+    {children}
+  </BaseContextMenu.CheckboxItem>
+)
+
+const RadioItem = ({ className, children, ...props }: RadioItemProps) => (
+  <BaseContextMenu.RadioItem
+    className={cn(itemBaseClasses, itemVariantClasses.default, 'pl-7', className)}
+    {...props}
+  >
+    <span
+      aria-hidden
+      className="absolute left-2 flex size-3.5 items-center justify-center"
+    >
+      <BaseContextMenu.RadioItemIndicator className="size-3.5">
+        <DotIcon />
+      </BaseContextMenu.RadioItemIndicator>
+    </span>
+    {children}
+  </BaseContextMenu.RadioItem>
+)
+
+const SubmenuTrigger = ({ className, children, ...props }: SubmenuTriggerProps) => (
+  <BaseContextMenu.SubmenuTrigger
+    className={cn(
+      itemBaseClasses,
+      itemVariantClasses.default,
+      'data-popup-open:bg-accent data-popup-open:text-accent-foreground pr-2',
+      className,
+    )}
+    {...props}
+  >
+    {children}
+    <ChevronRight className="ml-auto size-4 opacity-60" aria-hidden />
+  </BaseContextMenu.SubmenuTrigger>
+)
+
+const CheckIcon = () => (
+  <svg viewBox="0 0 14 14" fill="none" className="size-3.5">
+    <path
+      d="M3 7.5 6 10.5 11 4.5"
+      stroke="currentColor"
+      strokeWidth="1.75"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+)
+
+const DotIcon = () => (
+  <svg viewBox="0 0 14 14" className="size-3.5">
+    <circle cx="7" cy="7" r="3" fill="currentColor" />
+  </svg>
+)
+
+export const ContextMenu = {
+  Root: BaseContextMenu.Root,
+  Trigger: BaseContextMenu.Trigger,
+  Portal: BaseContextMenu.Portal,
+  Backdrop: BaseContextMenu.Backdrop,
+  Positioner,
+  Popup,
+  Arrow: BaseContextMenu.Arrow,
+  Group: BaseContextMenu.Group,
+  GroupLabel,
+  Separator,
+  Item,
+  LinkItem: BaseContextMenu.LinkItem,
+  CheckboxItem,
+  RadioGroup: BaseContextMenu.RadioGroup,
+  RadioItem,
+  SubmenuRoot: BaseContextMenu.SubmenuRoot,
+  SubmenuTrigger,
+}

package/src/ProgressRing/ProgressRing.test.tsx

@@ -0,0 +1,51 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { ProgressRing } from './ProgressRing'
+import { CIRCUMFERENCE } from './ProgressRing.consts'
+
+describe('ProgressRing', () => {
+  it('renders zero dashoffset at 0% progress', () => {
+    render(<ProgressRing progress={0} colorClass="text-primary" label="Empty" testId="ring" />)
+    const circle = screen.getByTestId('ring')
+    const offset = Number(circle.getAttribute('stroke-dashoffset'))
+    expect(offset).toBeCloseTo(CIRCUMFERENCE, 1)
+  })
+
+  it('renders correct dashoffset at 50% progress', () => {
+    render(<ProgressRing progress={0.5} colorClass="text-primary" label="Half" testId="ring" />)
+    const circle = screen.getByTestId('ring')
+    const offset = Number(circle.getAttribute('stroke-dashoffset'))
+    expect(offset).toBeCloseTo(CIRCUMFERENCE * 0.5, 1)
+  })
+
+  it('renders zero dashoffset at 100% progress', () => {
+    render(<ProgressRing progress={1} colorClass="text-success" label="Full" testId="ring" />)
+    const circle = screen.getByTestId('ring')
+    const offset = Number(circle.getAttribute('stroke-dashoffset'))
+    expect(offset).toBeCloseTo(0, 1)
+  })
+
+  it('applies colorClass to fill circle', () => {
+    render(<ProgressRing progress={0.5} colorClass="text-success" label="Test" testId="ring" />)
+    const circle = screen.getByTestId('ring')
+    expect(circle.classList.toString()).toContain('text-success')
+  })
+
+  it('applies pulse animation when animate is true', () => {
+    render(<ProgressRing progress={0.5} colorClass="text-primary" label="Pulsing" animate />)
+    const svg = screen.getByRole('img', { hidden: true })
+    expect(svg.classList.toString()).toContain('animate-buffer-pulse')
+  })
+
+  it('does not apply pulse animation when animate is false', () => {
+    render(<ProgressRing progress={0.5} colorClass="text-primary" label="Idle" />)
+    const svg = screen.getByRole('img', { hidden: true })
+    expect(svg.classList.toString()).not.toContain('animate-buffer-pulse')
+  })
+
+  it('sets aria-label from label prop', () => {
+    render(<ProgressRing progress={0.5} colorClass="text-primary" label="42 paragraphs ready" />)
+    const svg = screen.getByRole('img', { hidden: true })
+    expect(svg.getAttribute('aria-label')).toBe('42 paragraphs ready')
+  })
+})

package/src/Select/Select.test.tsx

@@ -0,0 +1,129 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { StrictMode } from 'react'
+import { describe, expect, it, vi } from 'vitest'
+import { Select } from './Select'
+import type { SelectGroup } from './Select.types'
+
+const options = [
+  { value: 'a', label: 'Alpha' },
+  { value: 'b', label: 'Bravo' },
+  { value: 'c', label: 'Charlie' },
+]
+
+const groups: SelectGroup[] = [
+  {
+    label: 'Letters',
+    options: [
+      { value: 'a', label: 'Alpha' },
+      { value: 'b', label: 'Bravo' },
+    ],
+  },
+  {
+    label: 'Numbers',
+    options: [
+      { value: '1', label: 'One' },
+      { value: '2', label: 'Two' },
+    ],
+  },
+]
+
+const renderWith = (ui: React.ReactElement) => render(<StrictMode>{ui}</StrictMode>)
+
+describe('Select', () => {
+  it('renders selected label and chevron in button', () => {
+    renderWith(<Select options={options} value="b" onChange={vi.fn()} />)
+
+    const button = screen.getByRole('button', { name: /bravo/i })
+    expect(button).toBeInTheDocument()
+    expect(button.querySelector('svg')).toBeInTheDocument()
+  })
+
+  it('opens menu on click showing all options', () => {
+    renderWith(<Select options={options} value="a" onChange={vi.fn()} />)
+
+    fireEvent.click(screen.getByRole('button', { name: /alpha/i }))
+
+    expect(screen.getByRole('listbox')).toBeInTheDocument()
+    expect(screen.getByRole('option', { name: /alpha/i })).toBeInTheDocument()
+    expect(screen.getByRole('option', { name: /bravo/i })).toBeInTheDocument()
+    expect(screen.getByRole('option', { name: /charlie/i })).toBeInTheDocument()
+  })
+
+  it('calls onChange and closes menu when an option is selected', () => {
+    const onChange = vi.fn()
+    renderWith(<Select options={options} value="a" onChange={onChange} />)
+
+    fireEvent.click(screen.getByRole('button', { name: /alpha/i }))
+    fireEvent.click(screen.getByRole('option', { name: /charlie/i }))
+
+    expect(onChange).toHaveBeenCalledWith('c')
+    expect(screen.queryByRole('listbox')).not.toBeInTheDocument()
+  })
+
+  it('closes on Escape key', () => {
+    renderWith(<Select options={options} value="a" onChange={vi.fn()} />)
+
+    const button = screen.getByRole('button', { name: /alpha/i })
+    fireEvent.click(button)
+    expect(screen.getByRole('listbox')).toBeInTheDocument()
+
+    fireEvent.keyDown(button, { key: 'Escape' })
+    expect(screen.queryByRole('listbox')).not.toBeInTheDocument()
+  })
+
+  it('closes on click outside', () => {
+    renderWith(<Select options={options} value="a" onChange={vi.fn()} />)
+
+    fireEvent.click(screen.getByRole('button', { name: /alpha/i }))
+    expect(screen.getByRole('listbox')).toBeInTheDocument()
+
+    fireEvent.mouseDown(document.body)
+    expect(screen.queryByRole('listbox')).not.toBeInTheDocument()
+  })
+
+  it('navigates with arrow keys and selects with Enter', () => {
+    const onChange = vi.fn()
+    renderWith(<Select options={options} value="a" onChange={onChange} />)
+
+    const button = screen.getByRole('button', { name: /alpha/i })
+    fireEvent.click(button)
+
+    fireEvent.keyDown(button, { key: 'ArrowDown' })
+    fireEvent.keyDown(button, { key: 'ArrowDown' })
+    fireEvent.keyDown(button, { key: 'Enter' })
+
+    expect(onChange).toHaveBeenCalledWith('b')
+  })
+
+  it('renders groups with headers', () => {
+    renderWith(<Select groups={groups} value="a" onChange={vi.fn()} />)
+
+    fireEvent.click(screen.getByRole('button', { name: /alpha/i }))
+
+    expect(screen.getByText('Letters')).toBeInTheDocument()
+    expect(screen.getByText('Numbers')).toBeInTheDocument()
+    expect(screen.getByRole('option', { name: /one/i })).toBeInTheDocument()
+  })
+
+  it('uses renderOption for custom item rendering', () => {
+    renderWith(
+      <Select
+        options={options}
+        value="a"
+        onChange={vi.fn()}
+        renderOption={option => <span data-testid="custom">{option.label.toUpperCase()}</span>}
+      />,
+    )
+
+    fireEvent.click(screen.getByRole('button', { name: /alpha/i }))
+
+    expect(screen.getAllByTestId('custom')).toHaveLength(3)
+    expect(screen.getByText('BRAVO')).toBeInTheDocument()
+  })
+
+  it('shows placeholder when value does not match any option', () => {
+    renderWith(<Select options={options} value="x" onChange={vi.fn()} placeholder="Pick one" />)
+
+    expect(screen.getByRole('button', { name: /pick one/i })).toBeInTheDocument()
+  })
+})

package/src/Slider/Slider.test.tsx

@@ -0,0 +1,29 @@
+import { cleanup, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Slider } from './Slider'
+
+afterEach(cleanup)
+
+describe('Slider', () => {
+  it('renders a slider with the correct value', () => {
+    render(<Slider value={50} onChange={() => {}} min={0} max={100} aria-label="Volume" />)
+    const slider = screen.getByRole('slider')
+    expect(slider).toHaveAttribute('aria-valuenow', '50')
+  })
+
+  it('calls onCommit when interaction ends', () => {
+    const onCommit = vi.fn()
+    render(
+      <Slider
+        value={50}
+        onChange={() => {}}
+        onCommit={onCommit}
+        min={0}
+        max={100}
+        aria-label="Volume"
+      />,
+    )
+    // Just verify it renders without error — slider drag testing is unreliable in jsdom
+    expect(screen.getByRole('slider')).toBeInTheDocument()
+  })
+})

package/src/Switch/Switch.test.tsx

@@ -0,0 +1,31 @@
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Switch } from './Switch'
+
+afterEach(cleanup)
+
+describe('Switch', () => {
+  it('renders as a switch with the correct checked state', () => {
+    render(<Switch checked={true} onChange={() => {}} aria-label="Toggle" />)
+    expect(screen.getByRole('switch')).toBeChecked()
+  })
+
+  it('calls onChange when clicked', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(<Switch checked={false} onChange={onChange} aria-label="Toggle" />)
+
+    await user.click(screen.getByRole('switch'))
+    expect(onChange).toHaveBeenCalledWith(true)
+  })
+
+  it('does not call onChange when disabled', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(<Switch checked={false} onChange={onChange} disabled aria-label="Toggle" />)
+
+    await user.click(screen.getByRole('switch'))
+    expect(onChange).not.toHaveBeenCalled()
+  })
+})

package/src/helpers/getModKey/getModKey.test.ts

@@ -0,0 +1,23 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { getModKey } from './getModKey'
+
+describe('getModKey', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('returns "Cmd" on Mac', () => {
+    vi.stubGlobal('navigator', { userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)' })
+    expect(getModKey()).toBe('Cmd')
+  })
+
+  it('returns "Ctrl" on Windows', () => {
+    vi.stubGlobal('navigator', { userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)' })
+    expect(getModKey()).toBe('Ctrl')
+  })
+
+  it('returns "Ctrl" when navigator is undefined', () => {
+    vi.stubGlobal('navigator', undefined)
+    expect(getModKey()).toBe('Ctrl')
+  })
+})

package/src/index.ts

@@ -10,6 +10,8 @@ export { Slider } from './Slider/Slider'
 
 export { Switch } from './Switch/Switch'
 
+export { ContextMenu } from './ContextMenu/ContextMenu'
+
 export { Select } from './Select/Select'
 export type {
   SelectOption,

package/themes/dashboard.css

@@ -121,6 +121,18 @@
   --success-foreground: oklch(0.82 0.1 149);
 }
 
+/* Global focus-visible ring for raw interactive elements. Primitives (Button,
+ * etc.) override this with their own tuned focus styling. */
+@layer base {
+  button:focus-visible,
+  [role='button']:focus-visible,
+  a:focus-visible {
+    outline: 2px solid var(--primary);
+    outline-offset: 2px;
+    border-radius: 0.375rem;
+  }
+}
+
 /* Keyframes referenced by the theme's --animate-* tokens */
 @keyframes ring-spin {
   to {

package/themes/reader.css

@@ -123,6 +123,18 @@
   --success-foreground: oklch(0.82 0.1 149);
 }
 
+/* Global focus-visible ring for raw interactive elements. Primitives (Button,
+ * etc.) override this with their own tuned focus styling. */
+@layer base {
+  button:focus-visible,
+  [role='button']:focus-visible,
+  a:focus-visible {
+    outline: 2px solid var(--primary);
+    outline-offset: 2px;
+    border-radius: 0.375rem;
+  }
+}
+
 /* Keyframes referenced by the theme's --animate-* tokens */
 @keyframes ring-spin {
   to {