@moldable-ai/ui 0.2.18 → 0.2.20

package/docs/component-catalog.md

@@ -0,0 +1,59 @@
+# Component catalog
+
+The catalog turns component review into a deterministic matrix rather than a
+set of hand-picked screenshots. Import the catalog utilities from the separate
+subpath so production app bundles do not pull in review infrastructure.
+
+```tsx
+import {
+  ComponentCatalog,
+  createCatalogManifest,
+} from '@moldable-ai/ui/catalog'
+
+const manifest = createCatalogManifest({
+  title: 'App UI',
+  sections: [
+    {
+      id: 'controls',
+      title: 'Controls',
+      stories: [
+        {
+          id: 'primary-action',
+          title: 'Primary action',
+          interactions: ['rest', 'focus-visible', 'disabled', 'loading'],
+          render: ({ interaction }) => (
+            <Button
+              autoFocus={interaction === 'focus-visible'}
+              disabled={interaction === 'disabled'}
+            >
+              Continue
+            </Button>
+          ),
+        },
+      ],
+    },
+  ],
+})
+
+<ComponentCatalog manifest={manifest} />
+```
+
+## Required review matrix
+
+Every public interactive component should cover:
+
+- light and dark themes;
+- regular and compact density;
+- wide and narrow viewports;
+- rest, focus-visible, disabled, invalid, selected, loading, and empty states
+  where those states apply;
+- keyboard behavior in unit tests.
+
+`buildCatalogCases()` generates stable case IDs and supports filtering, which
+lets a visual-regression runner capture one addressable case at a time. Keep
+catalog stories deterministic: fixed content, fixed dates, no network calls,
+and no animation unless motion itself is under review.
+
+The included `coreComponentCatalog` is a smoke foundation, not the complete
+acceptance bar. Add each new public component and its meaningful states as part
+of the same change that adds the component.

package/docs/component-guide-template.md

@@ -0,0 +1,37 @@
+# Component guide template
+
+Use this structure for each public component family.
+
+```markdown
+# Component
+
+One-sentence intent.
+
+## When to use
+
+## When not to use
+
+## Anatomy
+
+## Usage
+
+## Variants and sizes
+
+## API
+
+## States and interaction
+
+## Keyboard and accessibility
+
+## Platform behavior
+
+## Do
+
+## Don't
+
+## Testing
+```
+
+Document the real exported API. Include neighboring-component decisions and
+the states callers must implement. Keep examples compact and use semantic
+theme tokens.

package/docs/design-tokens.md

@@ -0,0 +1,172 @@
+# Design tokens
+
+The token system makes an interface feel consistent before it makes it
+distinctive. Use semantic roles from `@moldable-ai/ui/styles`; do not choose
+raw palette values, one-off control dimensions, or custom easing curves in app
+chrome.
+
+Tokens are CSS custom properties so they work in React, plain CSS, canvas
+overlays, and host-provided webviews. Tailwind aliases are provided for the
+roles that are useful in markup.
+
+## Token layers
+
+1. **Theme primitives** such as `--background`, `--foreground`, and
+   `--primary` preserve the shadcn-compatible theme contract.
+2. **Semantic roles** such as `--surface-recessed`, `--text-secondary`, and
+   `--control-pressed` describe intent.
+3. **Component recipes** combine roles into a complete control or layout.
+
+Apps should primarily use layer two through shared components or the Tailwind
+aliases below. Override theme primitives to brand a complete app. Override a
+semantic role only when the meaning of that role changes for the entire
+subtree.
+
+## Typography
+
+The default UI font is the platform sans-serif stack. Monospaced text uses the
+platform monospace stack. Prefer `Text` for normal interface copy; the token
+utilities are useful for display-scale titles and highly composed canvases.
+
+| Role    | CSS token          | Tailwind utility  | Use                                |
+| ------- | ------------------ | ----------------- | ---------------------------------- |
+| Display | `--type-display-*` | `text-ui-display` | One dominant app or document title |
+| Heading | `--type-heading-*` | `text-ui-heading` | Primary view heading               |
+| Title   | `--type-title-*`   | `text-ui-title`   | Major section title                |
+| Body    | `--type-body-*`    | `text-ui-body`    | Dense working content              |
+| Label   | `--type-label-*`   | `text-ui-label`   | Controls and metadata              |
+| Caption | `--type-caption-*` | `text-ui-caption` | Timestamps and compact annotations |
+
+Use display type sparingly. A large title can establish a focused canvas, but
+it should not force every utility screen into a marketing-page hierarchy.
+Prefer `font-sans` and `font-mono` over naming a platform font directly.
+
+## Density
+
+Density is contextual, not a global scale transform. Place `data-density` on
+the smallest pane that needs a different rhythm:
+
+```tsx
+<section data-density="compact">
+  <Toolbar>{/* compact desktop actions */}</Toolbar>
+  <div className="min-h-row">{/* selectable row */}</div>
+</section>
+```
+
+Supported values are:
+
+- `compact`: inspectors, source lists, and toolbars.
+- default (attribute omitted): general app UI.
+- `comfortable`: touch-forward or presentation-oriented surfaces.
+
+The scope sets control heights, row and toolbar heights, gaps, inline padding,
+pane padding, and section spacing. Utilities include `h-control-xs`,
+`h-control-sm`, `h-control-md`, `h-control-lg`, `min-h-row`, `min-h-toolbar`,
+`gap-control-gap`, `px-control-inline`, `p-pane`, and `gap-section`.
+
+Component size or density props remain authoritative when supplied. Do not use
+density to shrink labels below readable sizes or to make a pointer-only target
+difficult to acquire.
+
+## Text and surfaces
+
+Use the narrowest semantic role that describes the region:
+
+| Role                 | Tailwind alias        | Purpose                           |
+| -------------------- | --------------------- | --------------------------------- |
+| `--text-primary`     | `text-text-primary`   | Primary content                   |
+| `--text-secondary`   | `text-text-secondary` | Supporting content                |
+| `--text-tertiary`    | `text-text-tertiary`  | De-emphasized metadata            |
+| `--text-disabled`    | `text-text-disabled`  | Unavailable content               |
+| `--surface-canvas`   | `bg-surface-canvas`   | Primary work surface              |
+| `--surface-raised`   | `bg-surface-raised`   | Bounded content above the canvas  |
+| `--surface-recessed` | `bg-surface-recessed` | Wells and subordinate regions     |
+| `--surface-sidebar`  | `bg-surface-sidebar`  | Source navigation                 |
+| `--surface-toolbar`  | `bg-surface-toolbar`  | Translucent window or pane chrome |
+| `--surface-overlay`  | `bg-surface-overlay`  | Menus, popovers, and toasts       |
+| `--surface-selected` | `bg-surface-selected` | Selected collection items         |
+
+Use `border-separator` for ordinary pane boundaries and
+`border-separator-strong` when the boundary must remain clear over imagery or
+a busy canvas. Avoid stacking raised surfaces inside cards merely to create
+visual hierarchy; whitespace and a separator are usually quieter.
+
+## Control states
+
+Control state roles are shared across buttons, rows, grid items, segmented
+controls, and fields:
+
+- `--control-hover`
+- `--control-pressed`
+- `--control-selected`
+- `--control-selected-foreground`
+- `--control-disabled`
+- `--control-focus`
+- `--control-invalid`
+
+A complete recipe covers rest, hover, pressed, focus-visible, selected,
+disabled, and invalid states. Disabled wins over pointer states. Focus remains
+visible when combined with selected or invalid. Selection is durable state;
+hover is not a substitute for it.
+
+Do not use state-layer colors as arbitrary fills. Prefer the shared component
+when one exists.
+
+## Shape and materials
+
+Use `rounded-control`, `rounded-container`, and `rounded-overlay` to keep
+related objects visually consistent. `rounded-window` is host-informed and
+normally only useful in previews; the native host owns the actual window
+shape.
+
+Material tokens keep depth and translucency restrained:
+
+- `--material-blur-toolbar` and `--material-blur-overlay`
+- `--material-saturation`
+- `shadow-panel`, `shadow-overlay`, and `shadow-window`
+
+Translucency must have an opaque fallback. The token system removes blur and
+uses opaque toolbar and overlay surfaces when the operating system requests
+reduced transparency or an ancestor has `data-transparency="reduced"`.
+
+## Motion
+
+Use motion to explain entry, exit, reordering, or a state transition:
+
+| Purpose                         | Duration                    | Easing                   |
+| ------------------------------- | --------------------------- | ------------------------ |
+| Immediate feedback              | `--motion-duration-instant` | `--motion-ease-standard` |
+| Hover and press                 | `--motion-duration-fast`    | `--motion-ease-standard` |
+| Popover or selection transition | `--motion-duration-normal`  | `--motion-ease-enter`    |
+| Large surface transition        | `--motion-duration-slow`    | `--motion-ease-enter`    |
+
+`ease-standard`, `ease-enter`, `ease-exit`, and `ease-spring` are available as
+Tailwind utilities. Use the duration variables directly or with an arbitrary
+value such as `duration-[var(--motion-duration-fast)]`.
+
+Reduced-motion preferences collapse token durations to 1ms and remove
+decorative package animations. Components must still render their final state
+without depending on an animation callback.
+
+## Contrast and themes
+
+Light and dark themes share semantic names. Never branch app behavior on a
+specific color value. Increased-contrast preferences strengthen separators,
+state layers, and tertiary text. Forced-color mode maps semantic roles to
+system colors and removes material shadows.
+
+Test at minimum:
+
+- Light and dark.
+- Default and increased contrast.
+- Reduced motion and reduced transparency.
+- Compact and comfortable density.
+- Focus-visible, selected, disabled, and invalid states in combination.
+
+## Adding a token
+
+Add a token only when the decision repeats across component families. Name it
+for its role, provide light and dark behavior when necessary, define
+accessibility fallbacks, expose a Tailwind alias only if it improves normal
+composition, and document the intended use. A component-specific visual tweak
+belongs in that component recipe instead.

package/docs/foundations.md

@@ -0,0 +1,56 @@
+# Foundations
+
+## Character
+
+Moldable apps are local working instruments, not websites or SaaS dashboards.
+The interface should be calm, compact, direct, and organized around the user's
+objects. Decoration must clarify hierarchy or state.
+
+## Hierarchy
+
+Use `Text` roles instead of rebuilding typography from arbitrary utilities.
+Most desktop chrome should use `regular`, `strong`, `small`, or
+`small-strong`. Reserve `heading1` for a view's primary title and `heading2`
+for a major section.
+
+Use one obvious accent action in a region. Secondary actions should be quiet.
+Status color communicates status only; it is not decoration.
+
+## Density
+
+- Compact controls are the default in toolbars and inspectors.
+- Preserve usable pointer targets even when the visible control is small.
+- Prefer separators, background shifts, and whitespace over nested cards.
+- Working panes own scrolling. The window shell should not accidentally scroll.
+- Set `data-density="compact"`, `"default"`, or `"comfortable"` at a
+  composition boundary. Components should consume density tokens rather than
+  inventing per-screen heights.
+
+## Surfaces
+
+- `background`: primary work surface.
+- `muted`: subordinate region, well, or quiet selection context.
+- `sidebar`: navigation/list source surface.
+- `popover`: temporary floating surface.
+- `card`: bounded content group, not a universal page wrapper.
+
+Use semantic tokens only. Do not introduce raw gray, zinc, white, or black
+classes in app UI.
+
+Use material tokens for translucency and elevation. Materials distinguish
+canvas, toolbar, sidebar, raised, recessed, and overlay roles; they are not
+decorative glass effects.
+
+## Motion
+
+Motion explains state or continuity. Keep it brief and honor
+`prefers-reduced-motion`. Pulse only for live activity; a static notification
+does not pulse.
+
+Use the shared duration and easing tokens. Do not make routine controls feel
+springy, and do not animate layout merely to make a screen feel active.
+
+## Focus
+
+Keyboard focus must remain visible against every surface. Do not remove a
+focus ring unless the replacement is at least as clear.

package/docs/native-integration.md

@@ -0,0 +1,33 @@
+# Native integration
+
+Renderer components should feel compatible with macOS without pretending to be
+native controls. Use a host-native control only when Moldable exposes a shared,
+transport-neutral capability for it.
+
+## Selection policy
+
+1. Prefer a real Moldable host contract when the operation is inherently
+   platform-owned, such as sharing, file selection, or a system permission.
+2. Use the shared renderer component when its semantics are app-owned.
+3. Provide an accessible renderer fallback only when the product contract
+   defines what happens on desktop, iOS, and remote clients.
+
+Do not create UI-only no-op stubs for native menus, share sheets, or date
+pickers. First define ownership, cancellation, errors, replay/reconnect
+behavior, and platform fallbacks.
+
+`DateField` is the portable renderer baseline. A future system date picker,
+share sheet, or native menu must only be selected after the host advertises the
+service through a versioned context. Requests must remain bound to the
+originating app window and user activation.
+
+Standalone windows should remain host-owned surfaces around an app frame. Do
+not load arbitrary app URLs directly into a privileged native webview merely to
+gain window chrome.
+
+## Platform details
+
+Use toolbars, panes, compact controls, keyboard commands, restrained material,
+and clear selection state to achieve platform affinity. Do not copy private
+framework code, undocumented IPC, proprietary fonts, or host-specific symbol
+plumbing.

package/docs/standalone-app-windows.md

@@ -0,0 +1,128 @@
+# Standalone app windows
+
+Moldable apps should work as focused windows as well as embedded views. The
+same app surface must survive either presentation without imitating operating
+system chrome or assuming that a global desktop shell is present.
+
+## Ownership boundary
+
+| Layer             | Owns                                                                                                                              |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Native host       | Window creation, close/minimize/zoom controls, dragging, resize regions, focus state, system menus, share sheets, and safe insets |
+| Shared UI package | Semantic window tokens, app-level layout recipes, accessible controls, density, and embedded fallbacks                            |
+| App               | Title, document context, primary canvas, toolbars, navigation, selection, and app-specific state                                  |
+| Orchestrator      | Cross-app commands, conversation, launching, and switching; it is not permanent app chrome                                        |
+
+Do not draw traffic-light controls or recreate a title bar in React. When a
+platform cannot provide a native capability, expose it through a host contract
+or use a clearly web-native fallback.
+
+## Window inset contract
+
+The stylesheet defines a renderer boundary with zero-value browser-safe
+defaults:
+
+- `--window-safe-area-top`
+- `--window-safe-area-inline-start`
+- `--window-safe-area-inline-end`
+- `--window-safe-area-bottom`
+- `--window-titlebar-height`
+- `--window-drag-region-height`
+- `--window-control-inset-inline-start`
+- `--window-control-inset-inline-end`
+- `--window-content-inset-top`
+- `--window-content-inset-inline-start`
+- `--window-content-inset-inline-end`
+- `--window-content-inset-bottom`
+- `--window-corner-radius`
+
+The host may set the primitive safe-area, titlebar, and control inset values on
+the document root. Composite content insets then resolve automatically. The
+transport used to deliver those values belongs to the host integration layer,
+not individual apps.
+
+Window appearance roles are `--window-chrome-background`,
+`--window-chrome-foreground`, `--window-chrome-muted-foreground`,
+`--window-border`, and `--material-shadow-window`. The host may update the
+foreground roles when a window becomes inactive. Apps must not infer focus
+from pointer events.
+
+## A portable root
+
+Keep the root bounded and make one descendant own each scroll region:
+
+```tsx
+<main
+  className="bg-surface-canvas text-text-primary flex h-dvh min-h-0 min-w-0 flex-col overflow-hidden"
+  style={{
+    paddingTop: 'var(--window-content-inset-top)',
+    paddingInlineStart: 'var(--window-content-inset-inline-start)',
+    paddingInlineEnd: 'var(--window-content-inset-inline-end)',
+    paddingBottom: 'var(--window-content-inset-bottom)',
+  }}
+>
+  <Toolbar>{/* app title and primary actions */}</Toolbar>
+  <PanelContent>{/* the primary canvas or collection */}</PanelContent>
+</main>
+```
+
+This conservative layout places app chrome below any overlay titlebar. A
+future shared window-shell recipe may integrate a toolbar into a host-declared
+drag region, but only the platform adapter should mark draggable and
+non-draggable areas.
+
+In embedded presentation all window insets resolve to zero. If chat overlays
+the app, the owning bottom scroll region uses `--chat-safe-padding`. A
+standalone window must not reserve that space unless the orchestrator is
+actually overlaid in that window.
+
+## Window-shaped information architecture
+
+A standalone app should identify itself without relying on a global sidebar:
+
+- Put the current app or document identity in its own top region.
+- Keep the primary object visually dominant.
+- Place frequent tools near the edge of the canvas they affect.
+- Use a sidebar or inspector only when the task needs one.
+- Keep primary actions reachable at narrow widths.
+- Make empty and onboarding states feel like the app, not a generic dialog.
+
+Large, single-purpose canvases can use display typography and generous space.
+Dense utilities should retain compact controls and stronger information
+hierarchy. Native feeling comes from predictable focus, keyboard behavior,
+selection, materials, and restraint—not from decorative window chrome.
+
+## Multi-window state
+
+Treat each window as an independent client of shared product APIs:
+
+- Give each window its own React root, focus, selection, and transient UI
+  state.
+- Keep durable workspace data behind the same authoritative API used by
+  embedded and remote clients.
+- Make document and route identity explicit so a window can reconnect or
+  restore without a process-global singleton.
+- Define ordering, replay, and conflict behavior for live shared state.
+- Keep binary assets addressable; do not place large payloads in window or
+  conversation events.
+
+Closing one window must not imply closing an app service or discarding another
+window's state. System menu, share, file, and date behavior should remain
+behind platform-neutral capability contracts with native adapters.
+
+## Verification matrix
+
+Every app shell or shared window recipe should cover:
+
+- Embedded and standalone presentation.
+- Active and inactive native windows.
+- Light and dark appearance.
+- Narrow, default, and wide sizes.
+- Keyboard-only use and visible focus.
+- Increased contrast, reduced motion, and reduced transparency.
+- Empty, loading, error, ready, and offline or disconnected states.
+- Reopen or reconnect with durable state intact.
+
+Visual regression fixtures should capture the same canonical states at stable
+viewport sizes. Interaction tests should verify focus movement, selection,
+resize behavior, and that window controls remain host-owned.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moldable-ai/ui",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "description": "Shared UI components for Moldable applications",
   "author": "Desiderata LLC",
   "license": "SEE LICENSE IN LICENSE",
@@ -26,10 +26,17 @@
       "import": "./dist/index.js",
       "require": "./dist/index.js"
     },
+    "./catalog": {
+      "types": "./dist/catalog/index.d.ts",
+      "import": "./dist/catalog/index.js",
+      "require": "./dist/catalog/index.js"
+    },
     "./styles": "./src/styles/index.css"
   },
   "files": [
     "dist",
+    "docs",
+    "src/components/ui/*.md",
     "src/styles",
     "LICENSE"
   ],
@@ -73,6 +80,7 @@
     "@radix-ui/react-toggle": "^1.1.10",
     "@radix-ui/react-toggle-group": "^1.1.11",
     "@radix-ui/react-tooltip": "^1.2.8",
+    "@shadcn/react": "^0.2.1",
     "@tailwindcss/typography": "^0.5.16",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -82,7 +90,6 @@
     "framer-motion": "^12.15.0",
     "input-otp": "^1.4.2",
     "lucide-react": "^0.473.0",
-    "next-themes": "^0.4.6",
     "react-day-picker": "^9.13.0",
     "react-hook-form": "^7.71.1",
     "react-markdown": "^10.1.0",
@@ -96,7 +103,6 @@
     "tailwindcss": "^4.1.10",
     "tw-animate-css": "^1.3.4",
     "vaul": "^1.1.2",
-    "virtua": "^0.48.5",
     "zod": "^4.3.5"
   },
   "devDependencies": {

package/src/components/ui/alert.md

@@ -0,0 +1,55 @@
+# Alert
+
+## Purpose
+
+`Alert` presents an important inline message that belongs to the current surface. Use it for recoverable errors, permission or connection problems, and information the user should notice before continuing.
+
+Use `AlertDialog` when the user must confirm an action. Use `Empty` for the normal absence of data. Use a toast for brief feedback that does not need to remain in the layout.
+
+## Usage patterns
+
+```tsx
+import { CircleAlert } from 'lucide-react'
+import { Alert, AlertDescription, AlertTitle } from '@moldable-ai/ui'
+
+;<Alert variant="destructive">
+  <CircleAlert />
+  <AlertTitle>Could not save</AlertTitle>
+  <AlertDescription>
+    The file changed on disk. Reload it, then try again.
+  </AlertDescription>
+</Alert>
+```
+
+An alert can include a compact retry or setup action in its description, but the message should still stand on its own. Place the action close to the cause rather than at the top of the whole app.
+
+## API summary
+
+- `Alert`: a `div` with `role="alert"`.
+- `variant`: `default` or `destructive`; defaults to `default`.
+- `AlertTitle`: the short, emphasized heading.
+- `AlertDescription`: muted supporting content; supports nested paragraphs and controls.
+- All parts accept the native props for their rendered element and a `className`.
+- A direct icon child on `Alert` receives the component’s grid placement and sizing.
+
+## Do
+
+- State what failed or what is blocked in a short title.
+- Include the specific message and a retry action when recovery is possible.
+- Keep technical details available through logs or a disclosure, not in the primary message.
+- Use an icon only when it improves recognition.
+- Keep the alert close to the field, pane, or operation it describes.
+
+## Don't
+
+- Do not use an alert as decorative introductory copy.
+- Do not show stack traces, raw exceptions, or secret values.
+- Do not use `destructive` for neutral notices.
+- Do not rely on the icon or color alone for meaning.
+- Do not use `Alert` as a confirmation surface.
+
+## Moldable considerations
+
+Alerts inside a scrollable pane must participate in that pane’s chat-safe bottom spacing. Long-lived errors should not be covered by a fixed dock or desktop chat overlay.
+
+Copy should be calm and literal: “Could not load messages” is better than “Something went wrong!”. For authentication and permission states, name the blocked capability and offer exactly one primary next action. If the alert includes buttons, follow the standard button accessibility and density rules.

package/src/components/ui/app-frame.md

@@ -0,0 +1,33 @@
+# App frame
+
+The top-level shell for an app that can run in its own window or inside a host
+surface.
+
+```tsx
+<AppFrame>
+  <AppFrameTitlebar>
+    <AppFrameToolbar>
+      <strong>Calendar</strong>
+      <div className="ml-auto">{/* compact actions */}</div>
+    </AppFrameToolbar>
+  </AppFrameTitlebar>
+  <AppFrameContent>{/* the app-owned canvas */}</AppFrameContent>
+  <AppFrameStatusbar>Saved locally</AppFrameStatusbar>
+</AppFrame>
+```
+
+## Rules
+
+- Let the host render real window controls. Never draw imitation traffic lights.
+- Make the app's primary canvas the visual focus; titlebars and status bars are
+  supporting structure.
+- The app frame does not make the outer window draggable. A decorated native
+  titlebar or host-owned drag region must provide that behavior.
+- The host owns the `--window-*` inset variables. The component only consumes
+  them.
+- `AppFrameContent` applies the shared chat-safe padding by default. The value is
+  zero in a standalone window and is updated by the embedded host lifecycle.
+- Use `mode="embedded"` or `mode="window"` only for deterministic previews and
+  tests. Runtime apps should normally use `mode="auto"`; a future host context
+  may set `data-moldable-display-mode` before render when a window still uses an
+  app iframe.

package/src/components/ui/badge.md

@@ -0,0 +1,57 @@
+# Badge
+
+## Purpose
+
+`Badge` is a compact, non-primary label for status, category, count, or metadata. It helps a user scan rows and objects without becoming another action surface.
+
+Use a button or toggle when the element changes state. Use plain muted text when the metadata does not need a bounded shape.
+
+## Usage patterns
+
+```tsx
+import { Badge } from '@moldable-ai/ui'
+
+<Badge variant="secondary">Draft</Badge>
+<Badge variant="outline">3 selected</Badge>
+<Badge variant="destructive">Failed</Badge>
+```
+
+Badges work best at the edge of list rows, in compact inspector metadata, or beside a title. Keep the content short enough to scan without wrapping.
+
+When a badge is interactive, give the child its correct semantics:
+
+```tsx
+<Badge asChild variant="outline">
+  <a href="/jobs/running">Running</a>
+</Badge>
+```
+
+## API summary
+
+- `variant`: `default`, `secondary`, `destructive`, `outline`, `ghost`, or `link`. Defaults to `default`.
+- `asChild`: renders a Radix `Slot` and applies badge styling to its child.
+- Accepts native `span` props.
+- `badgeVariants` is exported for composing the same variants elsewhere.
+- Icons placed directly inside are normalized to a compact size.
+
+## Do
+
+- Use one or two words, a short number, or a concise state.
+- Prefer `secondary` or `outline` for ordinary metadata.
+- Use `destructive` only for a failure, blocked state, or serious warning.
+- Pair a colored state with clear text or an icon so meaning is not color-only.
+- Use `tabular-nums` through `className` for counts that update in place.
+
+## Don't
+
+- Do not turn every property into a badge.
+- Do not use badges as a substitute for primary buttons, tabs, or filters.
+- Do not place long explanations or sentences inside.
+- Do not invent raw category colors; use semantic variants unless a small, meaningful object color is required.
+- Do not show “AI” as a decorative badge when no actionable distinction exists.
+
+## Moldable considerations
+
+Moldable surfaces are intentionally dense, so badges should preserve horizontal scan order. In rows, keep the badge `shrink-0` and make the main text column `min-w-0`. Prefer a small status marker plus text over multiple adjacent badges.
+
+For background activity, use a precise state such as “Syncing” or “Queued”; remove the badge when the state no longer helps. A badge is not a notification and should not replace a useful Today item, alert, or progress indicator.