cooterlabs 2.0.0 → 2.2.0

package/README.md

@@ -1,124 +1,263 @@
 # CooterLabs UI Library CLI
 
-A blazingly fast, standalone CLI tool for scaffolding beautiful, accessible, and highly customizable UI components built strictly for React, Vite, and Next.js applications directly into your project via the terminal!
+A standalone CLI for scaffolding the **Aeon Product Design System** — beautiful, accessible, highly customizable React components — directly into your React, Vite, or Next.js project.
 
-It brings components directly to you. We do not provide a generic NPM library package to import elements from. Instead, the actual React TS/JS code is scaffolded straight into your `src/components/ui` folder, meaning you completely own the implementation, styles, and markup.
+It brings components directly to you. This is **not** an importable NPM package: the actual React TS/JS source is scaffolded straight into your `src/components/ui` folder, so you completely own the implementation, styles, and markup. Think shadcn/ui, but for the Aeon design system.
+
+```bash
+npx cooterlabs init        # set up the theme
+npx cooterlabs add button  # scaffold a component
+```
+
+---
+
+## Table of contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Commands](#commands)
+  - [`init` — theme setup](#init--theme-setup)
+  - [`add` — scaffold components](#add--scaffold-components)
+- [The shared `cn()` utility](#the-shared-cn-utility)
+- [The Aeon theme](#the-aeon-theme)
+  - [Semantic colors](#semantic-colors)
+  - [Primitive color scales](#primitive-color-scales)
+  - [Typography ramp](#typography-ramp)
+  - [Radius, elevation & focus ring](#radius-elevation--focus-ring)
+- [Component reference](#component-reference)
+- [How it works under the hood](#how-it-works-under-the-hood)
+- [Changelog](#changelog)
+- [License](#license)
+
+---
 
 ## Features
 
-- **✅ Project Detection**: Auto-detects your ecosystem (Next.js App router/Pages router, Vite, Create React App).
-- **✅ TypeScript vs. JavaScript**: Installs `.tsx` component files if you use TypeScript, gracefully falling back to stripped `.jsx` components for vanilla JS environments.
-- **✅ Tailwind Awareness**: Verifies you have Tailwind appropriately installed.
-- **✅ Dependency Auto-Install**: If the component you want needs `framer-motion`, `@radix-ui/react-checkbox` or even just `clsx`, the CLI automatically resolves these dependencies silently for you.
-- **✅ Prettier Formatting**: Uses your project's Prettier settings statically against our components before file creation so the component matches your exact code-style.
-- **✅ Interactive Interface**: Employs interactive menus to let you visually pick the component you want to build inside your project.
+- **Project detection** — auto-detects your ecosystem: Next.js (App router or Pages router), Vite, or Create React App, plus your package manager (`npm`, `pnpm`, `yarn`, `bun`) from lockfiles.
+- **TypeScript vs. JavaScript** — installs `.tsx` component files when TypeScript is detected (via `typescript` dependency or `tsconfig.json`), falling back to `.jsx` otherwise.
+- **Tailwind awareness** — warns if Tailwind CSS isn't detected, since all components are styled with Tailwind utilities.
+- **Dependency auto-install** — each component's runtime dependencies (`@radix-ui/*`, `lucide-react`, `clsx`, `tailwind-merge`) are resolved and installed automatically, collectively, in one pass.
+- **Component dependencies** — components that build on other components (e.g. `select` reuses `input`'s variant styles) automatically pull in what they need.
+- **Shared `cn()` helper** — a single `src/lib/utils.ts` is scaffolded once and shared by every component, with a tailwind-merge config that understands the Aeon type ramp (see [below](#the-shared-cn-utility)).
+- **Prettier formatting** — components are formatted with *your* project's Prettier config before being written, so they match your code style from the first commit.
+- **Interactive interface** — run without arguments to get an autocomplete multi-select of every available component.
 
-## Installation / Usage
+## Requirements
 
-1. Open your terminal at the root of your project directory.
-2. Ensure you have `tailwind-merge` and `clsx` properly configured in a central utility path or installed manually (some components will auto-detect and install these).
+- **React 18+** project (Vite, Next.js, or CRA).
+- **Tailwind CSS v4** for the default `aeon` theme (it's emitted as a v4 `@theme` block). The legacy `zinc` / `slate` themes target Tailwind v3 / shadcn-style HSL variables.
+- Node 18+ (the CLI is an ES module).
 
-### Initialization (Themes & CSS Base)
+---
 
-To swiftly set up a cohesive Tailwind theme and properly configure your base CSS file (e.g. `index.css` or `globals.css`), run:
+## Commands
+
+### `init` — theme setup
+
+Sets up the design-system CSS variables in your base stylesheet (`src/index.css`, `app/globals.css`, or `styles/globals.css` — resolved automatically per framework):
 
 ```bash
-npx cooterlabs init
+npx cooterlabs init          # interactive theme picker
+npx cooterlabs init aeon     # non-interactive, applies the default theme
 ```
 
-This will give you a list of carefully curated designer themes to apply global default variables (background, foreground, primary borders, etc.) out-of-the-box.
+What it does:
+
+1. Locates (or creates) your base CSS file.
+2. Ensures the Tailwind entry point exists — `@import "tailwindcss";` for v4 themes, the classic `@tailwind base/components/utilities` trio for legacy themes.
+3. Appends the theme block. For **aeon** this is a Tailwind v4 `@theme static { … }` block plus the `alert-timer` keyframes used by the Alert component's auto-dismiss countdown.
+4. If theme variables already exist in the file, it prints the block for you to merge manually instead of clobbering your file.
 
-The default theme is **`aeon`** — the complete Aeon Product Design System as a Tailwind CSS v4 `@theme` block. It ships:
+Available themes:
 
-- **Semantic colors**: `primary` (deep teal `#0d3435`), `secondary`, `muted`, `accent`, `destructive`, `border`, `ring`, plus `success` / `info` / `warning` / `error` — each with a full 50–900 primitive scale (`primary-50`…`primary-900`, `grey-*`, `success-*`, …).
-- **Text sizes as Tailwind CSS variables**: the full Aeon type ramp is exposed as `--text-*` theme variables, giving you utilities like `text-h1`…`text-h5` (headings), `text-s1`/`text-s2` (subtitles), `text-b1`…`text-b4` (body), `text-c1`…`text-c3` (captions), `text-label`, and button sizes `text-btn-giant`…`text-btn-tiny` — each with the correct size, line-height, and weight baked in.
-- **Radius scale**: `rounded-xxs` (4px) through `rounded-xl` (24px).
-- **Elevation**: `shadow-100` through `shadow-800`.
-- **Font**: Inter.
+| Theme | Format | Description |
+|---|---|---|
+| `aeon` *(default)* | Tailwind v4 `@theme` | The full Aeon Product Design System — colors, type ramp, radii, elevation, focus ring. |
+| `zinc` | v3 / shadcn HSL `:root` vars | Legacy neutral theme. |
+| `slate` | v3 / shadcn HSL `:root` vars | Legacy cool-grey theme. |
 
-To apply it non-interactively:
+### `add` — scaffold components
 
 ```bash
-npx cooterlabs init aeon
+npx cooterlabs add             # interactive multi-select
+npx cooterlabs add button      # one component
+npx cooterlabs add card badge  # ⚠️ one at a time — run twice, or use the picker
+npx cooterlabs add --all       # everything
 ```
 
-Legacy `zinc` and `slate` themes (Tailwind v3 / shadcn HSL format) remain available.
+What it does, per run:
 
-### Adding Components
+1. Detects framework, TypeScript, Tailwind, and package manager.
+2. Expands component requirements — e.g. `add select` also scaffolds `input`, because `select.tsx` imports its shared variant styles from `./input`.
+3. Scaffolds `src/lib/utils.ts` (the shared `cn()` helper) if it doesn't exist yet.
+4. Copies each component into `src/components/ui/` (or `components/ui/` for Next.js without `src/`), formatted with your Prettier config.
+5. Installs the union of all required runtime dependencies in a single package-manager invocation.
 
-Run the CLI tool without arguments to get an interactive autocomplete prompt:
+Existing files with the same name are overwritten — re-running `add` is also how you *update* a component to the latest version (diff your local changes first if you've customized it).
 
-```bash
-npx cooterlabs add
+---
+
+## The shared `cn()` utility
+
+Every component imports one helper:
+
+```ts
+import { cn } from "../../lib/utils"
 ```
 
-If you know exactly what component you want, bypass the interactive wizard and supply the name:
+The CLI scaffolds this file once, at `src/lib/utils.ts` (or `lib/utils.js`). It is **not** the stock shadcn two-liner — it uses `extendTailwindMerge` to teach tailwind-merge the Aeon font-size ramp:
 
-```bash
-# Example: Adding a Button
-npx cooterlabs add button
+```ts
+import { clsx, type ClassValue } from "clsx"
+import { extendTailwindMerge } from "tailwind-merge"
+
+const twMerge = extendTailwindMerge({
+    extend: {
+        classGroups: {
+            "font-size": [{ text: ["h1", …, "b4", …, "btn-tiny"] }],
+        },
+    },
+})
 
-# Example: Adding an Avatar
-npx cooterlabs add avatar
+export function cn(...inputs: ClassValue[]) {
+    return twMerge(clsx(inputs))
+}
 ```
 
-### Install All Components At Once
+**Why this matters:** without it, tailwind-merge treats custom utilities like `text-b4` as text *colors* and silently drops real color classes like `text-white` when they appear together. If you already have your own `lib/utils`, the CLI won't overwrite it — but make sure it includes this classGroups extension or component styles will subtly break.
 
-Need a complete starting block? Add the `--all` flag to scaffold the entire library in one go:
+---
 
-```bash
-npx cooterlabs add --all
+## The Aeon theme
+
+Running `npx cooterlabs init aeon` gives you the complete design system as CSS variables, which Tailwind v4 turns into utilities automatically.
+
+### Semantic colors
+
+`background`, `foreground`, `card`, `popover`, `primary` (deep teal `#0d3435`), `secondary`, `muted`, `accent`, `destructive`, `border`, `input`, `ring` — plus status colors `success`, `info`, `warning`, `error`, each with a `-foreground` pair. Use them as `bg-primary`, `text-muted-foreground`, `border-border`, etc.
+
+### Primitive color scales
+
+Full 50–900 scales for `primary-*`, `grey-*`, `success-*`, `error-*`, `warning-*`, and `info-*` — e.g. `bg-primary-50`, `text-grey-500`, `border-error-200`. Components use these for hover/active/disabled states, so keep them if you retheme.
+
+### Typography ramp
+
+The entire Aeon type ramp ships as `--text-*` variables, each with size, line-height, **and weight** baked in:
+
+| Utilities | Role |
+|---|---|
+| `text-h1` … `text-h5` | Headings (48px/600 → 24px/600) |
+| `text-s1`, `text-s2` | Subtitles |
+| `text-b1` … `text-b4` | Body (regular & medium, 16px & 14px) |
+| `text-c1` … `text-c3` | Captions (12px & 10px) |
+| `text-label` | Form labels |
+| `text-btn-giant` … `text-btn-tiny` | Button text sizes |
+
+Font family: **Inter** (`--font-sans`). Load the font yourself (e.g. via Google Fonts or `@fontsource/inter`) — the theme only declares the stack.
+
+### Radius, elevation & focus ring
+
+- **Radius:** `rounded-xxs` (4px) → `rounded-xl` (24px).
+- **Elevation:** `shadow-100` → `shadow-800`.
+- **Focus ring:** `--shadow-focus` (a 3px `#c2f5f6` halo) — every interactive component uses `focus-visible:shadow-focus` for a consistent, accessible focus style.
+- **`@keyframes alert-timer`:** powers the Alert component's auto-dismiss countdown bar; emitted alongside the theme block.
+
+---
+
+## Component reference
+
+All components live in `components/ui/`, are fully typed, and follow the Aeon size ramp (`giant / large / medium / small / tiny`) where applicable. Radix-based components keep the full Radix composition API.
+
+### Form controls
+
+| Component | Exports | Key props / notes |
+|---|---|---|
+| `button` | `Button` | `variant`: `filled` \| `outline` \| `clear` · `size`: giant→tiny · `iconOnly` · `asChild` (Radix `Slot`). |
+| `button-group` | `ButtonGroup`, `ButtonGroupItem` | Segmented control matching the button size ramp. |
+| `input` | `Input` (+ exported style maps reused by `select`) | `variant`: `outline` \| `filled` · `size`: `large` \| `medium` · `status`: success/info/warning/error · `helperText` · `icon`. |
+| `textarea` | `Textarea` | Multiline input matching `input` styling. |
+| `select` | `Select`, `SelectTrigger`, `SelectContent`, `SelectItem`, `SelectValue`, `SelectGroup`, … | Radix select styled as an Aeon input; **requires `input`** (auto-installed). |
+| `label` | `Label` | Radix label. |
+| `checkbox` | `Checkbox` | Radix checkbox with indeterminate support. |
+| `radio` | `RadioGroup`, `RadioGroupItem` | Radix radio group. |
+| `toggle` | `Toggle` | Radix switch. |
+
+### Feedback
+
+| Component | Exports | Key props / notes |
+|---|---|---|
+| `alert` | `Alert`, `AlertTitle`, `AlertDescription`, `AlertActions` | `severity`: default/success/info/warning/error · `variant`: `filled` \| `outline` · `position` (fixed placements) · `duration` (auto-dismiss seconds, pauses on hover, animated countdown) · `onDismiss`. |
+| `badge` | `Badge` | `type`: `badge` \| `chip` (chips are dismissible/selectable) · `variant`: `filled` \| `outline` · `color`: default/success/info/warning/error · `size`: medium/small/tiny · `iconOnly`. |
+| `avatar` | `Avatar`, `AvatarImage`, `AvatarFallback` | Radix avatar, `size`: giant→tiny. |
+| `progress` | `Progress` | Radix progress; `label`: `left` \| `right` percentage label · `disabled`. |
+| `loader` | `Loader` | CSS spinner, `size`: giant→tiny. |
+| `tooltip` | `TooltipProvider`, `Tooltip`, `TooltipTrigger`, `TooltipContent` | Radix dark tooltip. |
+
+### Overlays
+
+| Component | Exports | Key props / notes |
+|---|---|---|
+| `dialog` | `Dialog`, `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogFooter`, … | Radix dialog (Pop-Up). |
+| `action-sheet` | `ActionSheet`, `ActionSheetTrigger`, `ActionSheetContent`, … | Mobile bottom sheet built on Radix dialog. |
+| `context-menu` | `ContextMenu`, `ContextMenuTrigger`, `ContextMenuContent`, `ContextMenuItem`, checkbox/radio items, … | Radix context menu. |
+| `dropdown` | `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem`, … | Radix dropdown menu. |
+
+### Navigation
+
+| Component | Exports | Key props / notes |
+|---|---|---|
+| `tabs` | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` | Radix tabs. |
+| `breadcrumb` | `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, … | Accessible breadcrumb trail. |
+| `pagination` | `Pagination`, `PaginationContent`, `PaginationItem`, `PaginationLink`, `PaginationPrevious`, `PaginationNext`, … | Page navigation. |
+| `page-control` | `PageControl` | Mobile page-indicator dots. |
+| `stepper` | `Stepper`, `StepperItem`, `StepperSeparator` | Horizontal step indicator. |
+| `navbar-top` | `NavbarTop`, `NavbarTopLeft`, `NavbarTopTitle`, `NavbarTopRight` | Mobile top app bar. |
+| `navbar-bottom` | `NavbarBottom`, `NavbarBottomItem` | Mobile bottom tab bar. |
+| `list` | `List`, `ListHeader`, `ListItem` | Mobile list rows with leading/trailing slots. |
+
+### Layout
+
+| Component | Exports | Key props / notes |
+|---|---|---|
+| `card` | `Card`, `CardImage`, `CardHeader`, `CardFooter`, `CardTitle`, `CardDescription`, … | Composable card wrappers. |
+
+### Example
+
+```tsx
+import { Button } from "@/components/ui/button"
+import { Alert, AlertTitle, AlertDescription } from "@/components/ui/alert"
+
+export function Example() {
+    return (
+        <>
+            <Button variant="filled" size="large">Save changes</Button>
+            <Alert severity="success" duration={5} onDismiss={() => {}}>
+                <AlertTitle>Saved</AlertTitle>
+                <AlertDescription>Your changes are live.</AlertDescription>
+            </Alert>
+        </>
+    )
+}
 ```
 
-## Available Components
-
-The full Aeon Product Design System, scaffolded as owned code:
-
-**Form controls**
-- `button` - Filled / outline / clear styles in five sizes (giant → tiny), icon-only mode, Radix `Slot` support.
-- `button-group` - Segmented control matching the button size ramp.
-- `input` - Aeon-styled HTML `<input />` with error and disabled states.
-- `textarea` - Matching multiline input.
-- `label` - Accessible Radix-backed `<label />`.
-- `checkbox` - Radix checkbox with indeterminate support.
-- `radio` - Radix radio group.
-- `toggle` - Radix switch.
-
-**Feedback**
-- `alert` - Filled and soft appearances across default / success / info / warning / error severities.
-- `badge` - Status pills plus dismissible `Chip`.
-- `avatar` - Radix avatar with the Aeon size ramp.
-- `progress` - Radix progress bar.
-- `loader` - CSS spinner in five sizes.
-- `tooltip` - Radix dark tooltip.
-
-**Overlays**
-- `dialog` - Radix dialog (Pop-Up).
-- `action-sheet` - Mobile bottom sheet built on Radix dialog.
-- `context-menu` - Radix context menu.
-- `dropdown` - Radix dropdown menu.
-- `list` - Mobile list rows with leading/trailing slots.
-
-**Navigation**
-- `tabs` - Radix tabs.
-- `breadcrumb` - Accessible breadcrumb trail.
-- `pagination` - Page navigation.
-- `page-control` - Mobile page-indicator dots.
-- `stepper` - Horizontal step indicator.
-- `navbar-top` - Mobile top app bar.
-- `navbar-bottom` - Mobile bottom tab bar.
-
-**Layout**
-- `card` - Header, footer, body, title, and description wrappers.
-
-## How it works under-the-hood
-
-1. When you run `npx cooterlabs add [component]`, the script analyzes your filesystem looking for `pnpm-lock.yaml`, `bun.lockb`, `yarn.lock`, etc., and detects package managers.
-2. It looks for `tsconfig.json` to see if it should copy the raw `.tsx` component files or use regex parsers to strip types for a standard `.jsx` output.
-3. It recursively creates target folders, usually resolving to `src/components/ui` or `components/ui`.
-4. Formatting is applied.
-5. Child dependencies (e.g., `lucide-react`, Radix UI dependencies) required *exclusively* for that component are installed so the codebase isn't overwhelmed with useless imported libraries.
+---
+
+## How it works under the hood
+
+1. `npx cooterlabs add [component]` inspects your filesystem: lockfiles for the package manager, `package.json` deps for the framework, `tsconfig.json` for TypeScript, and Tailwind config/deps for styling support.
+2. Component requirements are expanded (`select` → `input`), then the shared `lib/utils` helper is scaffolded if missing.
+3. Templates are copied from the CLI package into `src/components/ui/` (or `components/ui/`), run through your Prettier config, and written with the right extension.
+4. The union of every selected component's runtime dependencies is installed in one package-manager call, so you only get libraries the components actually use.
+
+## Changelog
+
+### 2.1.0
+
+- **Synced all 28 component templates** with the latest Aeon implementations (updated button/badge/alert variants, refined focus states using `shadow-focus`, tailwind-merge-safe type-ramp classes).
+- **New component: `select`** — Radix select styled as an Aeon input; auto-installs `input`, whose variant styles it reuses.
+- **Shared `cn()` helper** — components now import from `lib/utils` instead of inlining `cn` per file; the CLI scaffolds it (with the type-ramp-aware tailwind-merge config) on first `add`.
+- **Theme update** — the `aeon` theme now ships `--shadow-focus` (shared focus ring) and the `alert-timer` keyframes for Alert auto-dismiss.
 
 ## License
 
-MIT - Grab it, use it, scale it!
+MIT — Grab it, use it, scale it!

package/bin/index.js

@@ -174,8 +174,26 @@ const REGISTRY = {
     ],
     dev_dependencies: [],
   },
+  select: {
+    name: "Select",
+    dependencies: [
+      "@radix-ui/react-select",
+      "lucide-react",
+      "clsx",
+      "tailwind-merge",
+    ],
+    dev_dependencies: [],
+    requires: ["input"], // select.tsx imports shared variants from ./input
+  },
 };
 
+// Shared cn() helper scaffolded to src/lib/utils — components import it
+// from "../../lib/utils" instead of inlining it per file.
+const UTILS_TEMPLATE = fs.readFileSync(
+  path.join(__dirname, "../templates/_lib/utils.ts"),
+  "utf-8",
+);
+
 const THEMES = {
   aeon: `@theme static {
   /* ——— Aeon Product Design System ——— */
@@ -194,7 +212,7 @@ const THEMES = {
   --color-secondary-foreground: #1c222a;
   --color-muted: #e7e9ec;
   --color-muted-foreground: #475569;
-  --color-accent: #f1f3f3;
+  --color-accent: #0F3D3E;
   --color-accent-foreground: #0a2b2b;
   --color-destructive: #821717;
   --color-destructive-foreground: #ffffff;
@@ -271,6 +289,7 @@ const THEMES = {
   --color-info-700: #053e5d;
   --color-info-800: #04314a;
   --color-info-900: #032435;
+  --color-disabled: #7e8896
 
   /* Typography — Aeon text ramp (text-h1 … text-c3, text-label, text-btn-*) */
   --text-h1: 3rem;
@@ -351,6 +370,15 @@ const THEMES = {
   --shadow-600: 0 12px 42px -4px #1319271f, 0 8px 18px -6px #1319271f;
   --shadow-700: 0 14px 64px -4px #1319271f, 0 8px 22px -6px #1319271f;
   --shadow-800: 0 18px 88px -4px #13192724, 0 8px 28px -6px #1319271f;
+
+  /* Focus ring — shared by every interactive component (focus-visible:shadow-focus) */
+  --shadow-focus: 0px 0px 0px 3px #c2f5f6;
+}
+
+/* Alert auto-dismiss timeline */
+@keyframes alert-timer {
+  from { width: 100%; }
+  to { width: 0%; }
 }`,
   zinc: `:root {
   --background: 0 0% 100%;
@@ -516,6 +544,7 @@ const main = async () => {
   if (fs.existsSync(templatesDir)) {
     const dirs = fs
       .readdirSync(templatesDir)
+      .filter((f) => !f.startsWith("_")) // _lib etc. are support files, not components
       .filter((f) => fs.statSync(path.join(templatesDir, f)).isDirectory());
     if (dirs.length > 0) availableComponents = dirs;
   }
@@ -633,12 +662,33 @@ const main = async () => {
       process.exit(1);
     }
 
+    // Pull in components required by selected ones (e.g. select imports from ./input)
+    for (const comp of [...componentsToAdd]) {
+      for (const req of REGISTRY[comp]?.requires || []) {
+        if (!componentsToAdd.includes(req)) componentsToAdd.push(req);
+      }
+    }
+
     // Create target dir
     const targetDir = path.join(cwd, env.componentsDir);
     if (!fs.existsSync(targetDir)) {
       fs.mkdirSync(targetDir, { recursive: true });
     }
 
+    // Components import cn() from "../../lib/utils" — scaffold it once
+    const utilsPath = path.join(
+      targetDir,
+      "../../lib",
+      `utils.${env.typescript ? "ts" : "js"}`,
+    );
+    if (!fs.existsSync(utilsPath)) {
+      fs.mkdirSync(path.dirname(utilsPath), { recursive: true });
+      fs.writeFileSync(utilsPath, UTILS_TEMPLATE, "utf-8");
+      console.log(
+        chalk.green(`✅ Created ${path.relative(cwd, utilsPath)}`),
+      );
+    }
+
     let allDependencies = new Set();
 
     for (const comp of componentsToAdd) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cooterlabs",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Component library CLI for CooterLabs apps",
   "files": [
     "bin",

package/templates/_lib/utils.ts

@@ -0,0 +1,28 @@
+import { clsx, type ClassValue } from "clsx"
+import { extendTailwindMerge } from "tailwind-merge"
+
+// The custom font-size ramp from index.css (--text-h1 … --text-btn-tiny) is
+// unknown to tailwind-merge, so it treats text-b4 etc. as text COLORS and
+// silently drops real color classes like text-white. Teach it the ramp.
+const twMerge = extendTailwindMerge({
+    extend: {
+        classGroups: {
+            "font-size": [
+                {
+                    text: [
+                        "h1", "h2", "h3", "h4", "h5",
+                        "s1", "s2",
+                        "b1", "b2", "b3", "b4",
+                        "c1", "c2", "c3",
+                        "label",
+                        "btn-giant", "btn-large", "btn-medium", "btn-small", "btn-tiny",
+                    ],
+                },
+            ],
+        },
+    },
+})
+
+export function cn(...inputs: ClassValue[]) {
+    return twMerge(clsx(inputs))
+}

package/templates/action-sheet/action-sheet.tsx

@@ -1,11 +1,6 @@
 import * as React from "react"
 import * as DialogPrimitive from "@radix-ui/react-dialog"
-import { clsx, type ClassValue } from "clsx"
-import { twMerge } from "tailwind-merge"
-
-export function cn(...inputs: ClassValue[]) {
-    return twMerge(clsx(inputs))
-}
+import { cn } from "../../lib/utils"
 
 const ActionSheet = DialogPrimitive.Root
 
@@ -75,7 +70,7 @@ const ActionSheetItem = React.forwardRef<
     <button
         ref={ref}
         className={cn(
-            "flex h-12 w-full items-center justify-center gap-2 text-b2 transition-colors hover:bg-secondary active:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 [&_svg]:size-5 [&_svg]:shrink-0",
+            "flex h-12 w-full items-center justify-center gap-2 text-b2 transition-colors hover:bg-secondary active:bg-muted focus-visible:outline-none focus-visible:shadow-focus disabled:pointer-events-none disabled:opacity-50 [&_svg]:size-5 [&_svg]:shrink-0",
             variant === "destructive" ? "text-error" : "text-foreground",
             className
         )}
@@ -92,7 +87,7 @@ const ActionSheetCancel = React.forwardRef<
         <button
             ref={ref}
             className={cn(
-                "mt-2 flex h-12 w-full items-center justify-center rounded-xs border border-border bg-background text-b2 text-foreground transition-colors hover:bg-secondary active:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+                "mt-2 flex h-12 w-full items-center justify-center rounded-xs border border-border bg-background text-b2 text-foreground transition-colors hover:bg-secondary active:bg-muted focus-visible:outline-none focus-visible:shadow-focus",
                 className
             )}
             {...props}

package/templates/alert/alert.tsx

@@ -1,23 +1,19 @@
 import * as React from "react"
-import { clsx, type ClassValue } from "clsx"
-import { twMerge } from "tailwind-merge"
-
-export function cn(...inputs: ClassValue[]) {
-    return twMerge(clsx(inputs))
-}
+import { X } from "lucide-react"
+import { cn } from "../../lib/utils"
 
 const alertVariants = {
     filled: {
         default:
-            "bg-primary-600 text-white [&_[data-slot=alert-description]]:text-white/80",
+            "bg-primary-500 text-white [&_[data-slot=alert-description]]:text-white/80",
         success:
-            "bg-success-600 text-white [&_[data-slot=alert-description]]:text-white/80",
-        info: "bg-info-600 text-white [&_[data-slot=alert-description]]:text-white/80",
+            "bg-success-500 text-white [&_[data-slot=alert-description]]:text-white/80",
+        info: "bg-info-500 text-white [&_[data-slot=alert-description]]:text-white/80",
         warning:
-            "bg-warning-600 text-white [&_[data-slot=alert-description]]:text-white/80",
-        error: "bg-error-600 text-white [&_[data-slot=alert-description]]:text-white/80",
+            "bg-warning-500 text-white [&_[data-slot=alert-description]]:text-white/80",
+        error: "bg-error-500 text-white [&_[data-slot=alert-description]]:text-white/80",
     },
-    soft: {
+    outline: {
         default:
             "border border-primary-500 bg-primary-50 text-primary-500 [&_[data-slot=alert-description]]:text-muted-foreground",
         success:
@@ -29,27 +25,81 @@ const alertVariants = {
     },
 }
 
+const alertPositions = {
+    "top-left": "fixed left-4 top-4 z-50",
+    "top-center": "fixed left-1/2 top-4 z-50 -translate-x-1/2",
+    "top-right": "fixed right-4 top-4 z-50",
+    "bottom-left": "fixed bottom-4 left-4 z-50",
+    "bottom-center": "fixed bottom-4 left-1/2 z-50 -translate-x-1/2",
+    "bottom-right": "fixed bottom-4 right-4 z-50",
+}
+
 export interface AlertProps extends React.HTMLAttributes<HTMLDivElement> {
     severity?: keyof (typeof alertVariants)["filled"]
-    appearance?: keyof typeof alertVariants
+    variant?: keyof typeof alertVariants
+    position?: keyof typeof alertPositions
+    /** seconds until the alert dismisses itself; pauses on hover */
+    duration?: number
+    onDismiss?: () => void
 }
 
 const Alert = React.forwardRef<HTMLDivElement, AlertProps>(
     (
-        { className, severity = "default", appearance = "filled", ...props },
+        {
+            className,
+            severity = "default",
+            variant = "filled",
+            position,
+            duration,
+            onDismiss,
+            children,
+            ...props
+        },
         ref
-    ) => (
-        <div
-            ref={ref}
-            role="alert"
-            className={cn(
-                "relative rounded-xs p-4 [&>svg]:absolute [&>svg]:left-4 [&>svg]:top-4 [&>svg]:size-5 [&>svg~*]:pl-8",
-                alertVariants[appearance][severity],
-                className
-            )}
-            {...props}
-        />
-    )
+    ) => {
+        const [visible, setVisible] = React.useState(true)
+        if (!visible) return null
+        const dismissible = duration != null || onDismiss != null
+        const dismiss = () => {
+            setVisible(false)
+            onDismiss?.()
+        }
+        return (
+            <div
+                ref={ref}
+                role="alert"
+                className={cn(
+                    "group relative overflow-hidden rounded-md p-4 [&>svg]:absolute [&>svg]:left-4 [&>svg]:top-4 [&>svg]:size-5 [&>svg~*]:pl-8",
+                    alertVariants[variant][severity],
+                    position && alertPositions[position],
+                    dismissible && "pr-12",
+                    className
+                )}
+                {...props}
+            >
+                {children}
+                {dismissible && (
+                    <button
+                        type="button"
+                        aria-label="Dismiss"
+                        onClick={dismiss}
+                        className="absolute right-4 top-4"
+                    >
+                        <X className="size-4" />
+                    </button>
+                )}
+                {duration != null && (
+                    <div
+                        className="absolute bottom-0 left-0 h-1 bg-current opacity-30 group-hover:[animation-play-state:paused]"
+                        style={{
+                            animation: `alert-timer ${duration}s linear forwards`,
+                        }}
+                        onAnimationEnd={dismiss}
+                    />
+                )}
+            </div>
+        )
+    }
 )
 Alert.displayName = "Alert"