@vvedantb/ui 0.5.1 → 0.5.2

package/README.md

@@ -208,11 +208,13 @@ import { ConfirmDialog, SlideOverPanel, ToolbarSearchInput } from "@vvedantb/ui"
 <ToolbarSearchInput value={query} onChange={setQuery} />
 
 <ConfirmDialog size="sm" open={open} onOpenChange={setOpen} title="Delete item?" variant="destructive" onConfirm={remove} />
+
+<ConfirmDialog size="md" open={open} onOpenChange={setOpen} title="Delete item?" description="This cannot be undone." confirmLabel="Delete" variant="destructive" onConfirm={remove} />
 ```
 
 - `SlideOverPanel`: a right-side panel, absolutely positioned inside its nearest positioned parent. It is not a portal or dialog. It slides in with a spring and is hidden below `md`. Only the close button closes it (no Escape, no outside click). `width` is `"w-96"` (default) or `"w-80"`. `closeLabel` defaults to `"Close panel"`. `className` merges last.
 - `ToolbarSearchInput`: a compact `h-8` search field for toolbars, with a search icon and a clear button. The clear button stays mounted and is hidden while the value is blank. Clearing calls `onChange("")` and does not move focus. Defaults: `placeholder="Search..."`, `label="Search"` (the `aria-label`), `clearLabel="Clear search"`. The ref goes to the `<input>`.
-- `ConfirmDialog` `size`: `"default"` keeps the alert dialog. `"sm"` renders a compact, dismissible dialog (outside click, Escape and the close button close it) with small Cancel and confirm buttons. Cancel calls `onCancel` and then `onOpenChange(false)`. Confirm calls `onConfirm` only, so the caller closes it.
+- `ConfirmDialog` `size`: `"default"` keeps the alert dialog. `"sm"` renders a compact, dismissible dialog (outside click, Escape and the close button close it) with small Cancel and confirm buttons. Cancel calls `onCancel` and then `onOpenChange(false)`. Confirm calls `onConfirm` only, so the caller closes it. `"md"` (0.5.2) is dismissible like `"sm"`, with the title in a header (`pb-4`), the description in its own section (`py-6`) and a footer (`pt-4`) with default-size buttons. It has the same Cancel and confirm behaviour as `"sm"`.
 
 ## Buttons, menus and fields (0.4.4)
 
@@ -248,7 +250,7 @@ import {
 - `SelectField`: a labelled single select built from `Select`. Children are `SelectItem`s. An empty `value` shows the placeholder. `id` goes to the trigger and the label points at it. `className` merges onto the trigger.
 - Motion: `springTransition`, `springFastTransition` and `fadeUpSpring` presets. `FadePresence` takes optional `variants` (`hidden`, `show`, `exit`); omitted, it keeps its opacity fade. `PanelTransition` wraps children in React `ViewTransition` with `default="none"` and `enter`/`exit` classes (`vt-panel-in`, `vt-panel-out` by default). It needs a React build that exports `ViewTransition`, and the app supplies the `::view-transition-*` CSS.
 
-## App shell (0.5.0, 0.5.1)
+## App shell (0.5.0 to 0.5.2)
 
 A sidebar and main page layout, extracted from existing app markup. It is router-free: pass your own links (with `asChild`), state and media query result. Tooltips need a `TooltipProvider` above the shell.
 
@@ -289,15 +291,42 @@ import {
 
 - Widths: `AppShell` sets `--app-shell-rail-width` (default `4rem`), `--app-shell-sidebar-width` (rail plus panel, default `20rem`) and `--app-shell-mobile-header-height` (default `calc(3.5rem + env(safe-area-inset-top, 0px))`) as inline style. Change them with `railWidth`, `sidebarWidth` and `mobileHeaderHeight`. The other pieces read these variables. Outside `AppShell`, set the variables yourself or pass a width class with `className`.
 - `AppShell`: `sidebar`, `children`, `panelHidden` (main offsets by the rail width instead of the sidebar width), `skipLinkLabel` (`"Skip to main content"`), `mainId` (`"main-content"`), `className`, `mainClassName`, `contentClassName`.
-- `AppSidebar`: `rail`, `panel` (not rendered while `panelHidden`), `collapsed`, `panelHidden`, `isDesktop`, `mobileOpen`, `onMobileOpenChange`, `id` (default from `useId`), `asideProps` (`data-*` attributes for the `<aside>`), `className`, `mobileTitle`, `mobileMenuIcon` (`(open) => node`, default a menu icon), `mobileMenuLabel` (`"Open navigation menu"`), `closeLabel` (`"Close navigation"`). Swipe left or Escape closes the drawer. The drawer is `inert` while closed on mobile, and closes when `isDesktop` becomes `true`. Close it on route change in the app.
+- `AppSidebar`: `rail`, `panel` (not rendered while `panelHidden`), `collapsed`, `panelHidden`, `isDesktop`, `mobileOpen`, `onMobileOpenChange`, `id` (default from `useId`), `asideProps` (`data-*` attributes for the `<aside>`), `className`, `mobileTitle`, `mobileHeaderActions` (0.5.2; trailing actions such as icon buttons, in place of the end spacer), `mobileMenuIcon` (`(open) => node`, default a menu icon), `mobileMenuLabel` (`"Open navigation menu"`), `closeLabel` (`"Close navigation"`). Swipe left or Escape closes the drawer. The drawer is `inert` while closed on mobile, and closes when `isDesktop` becomes `true`. Close it on route change in the app.
 - `SidebarRail`: `top`, `children` (scroll body), `footer`, `showDivider`, `bodyAsChild` (the single child, for example a tabs list, becomes the body), `className`, `topClassName`, `bodyClassName`, `footerClassName`. Other HTML attributes (`id`, `data-*`, `aria-*`) go to the root `<div>`. The top and footer wrappers render only when their slot is set.
 - `RailTile`: `label` (`aria-label` and tooltip), `active`, `tooltip`, `showTooltip` (default `true`), `badge` (inside the tile, after the children; style it with `railBadgeClass`), `asChild`, `className`. Without `asChild` it is a ghost `Button`; other props go to it. With `asChild` the child (for example a router link) gets the tile classes and `aria-current="page"` when active.
 - `RailDivider`, `SidebarIconTooltip` (`label`, `enabled`, `side` `"right"`, `sideOffset` 8).
 - `SidebarPanel`: `title`, `headerTrailing`, `onClose` (adds the close button; pass it on the mobile drawer only), `closeLabel`, `closeButtonClassName`, `collapsed` (`md:hidden`), `className`, `children`.
-- `SidebarAccountMenu`: `name`, `email` (two-line label when set), `stackedLabel` (two-line layout even without `email`, default `false`), `imageUrl` (initials without it), `align` (`"center"`), `side` (`"right"`), `sideOffset` (8), `collisionPadding`, `contentClassName`, `children` (menu items). `SidebarAccountMenuPlaceholder` is the tile-sized loading box.
+- `SidebarAccountMenu`: `name`, `email` (two-line label when set), `stackedLabel` (two-line layout even without `email`, default `false`), `imageUrl` (initials without it), `align` (`"center"`), `side` (`"right"`), `sideOffset` (8), `collisionPadding`, `contentClassName`, `children` (menu items). 0.5.2 adds `badge` (unread dot beside the trigger, in a `relative` wrapper around the menu, so the trigger's dimming and press scale skip it: `true` shows it, `false` fades it out, omitted renders no wrapper and no dot), `triggerProps` (spread onto the trigger `Button` after the defaults; `className` merges last) and `contentProps` (spread onto `DropdownMenuContent`, for example `fitViewport` or `aria-label`; no `className`, use `contentClassName`). `SidebarAccountMenuPlaceholder` is the tile-sized loading box.
 - `SignOutDialog`: `open`, `onOpenChange` (not called with `false` while `pending`), `pending`, `onConfirm`, `description`, `contentClassName`, `title` (`"Sign out"`), `question` (`"Sign out of your account?"`).
 - Class helpers: `railTileClass`, `railTileStateClass(active)`, `railBadgeClass`, `sidebarNavRowClass(isIconOnly)`, `sidebarNavLinkTextClass(isActive)`, `sidebarSectionLabelClass`.
 
+### Header actions and account badge (0.5.2)
+
+All opt-in. Without these props the header keeps its end spacer and the account trigger has no dot.
+
+```tsx
+<AppSidebar
+  /* … */
+  mobileHeaderActions={
+    <>
+      <Button size="icon" variant="ghost" aria-label="Search"><IconSearch size={20} /></Button>
+      <Button size="icon" variant="ghost" aria-label="New item"><IconPlus size={20} /></Button>
+    </>
+  }
+/>
+
+<SidebarAccountMenu
+  name={name}
+  badge={hasUnread}
+  triggerProps={{ "aria-label": hasUnread ? `Account menu for ${name}, unread updates` : `Account menu for ${name}` }}
+  contentProps={{ fitViewport: true, "aria-label": "Account" }}
+>
+  <DropdownMenuItem>Settings</DropdownMenuItem>
+</SidebarAccountMenu>
+```
+
+The dot is `aria-hidden`, so say it in the trigger label when it matters, as above.
+
 ### Resizable panel (0.5.1)
 
 Pass `resizable` to `AppShell`. Widths are panel px, rail excluded. Without it nothing changes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "license": "MIT",
   "description": "Shared React 19 UI for web apps: one JavaScript entry (primitives, shell pieces, app helpers, native tokens), design-token CSS, shared Tailwind v4 CSS and a Tailwind preset.",
   "type": "module",
@@ -52,15 +52,6 @@
   "sideEffects": [
     "./src/ui/sonner.css"
   ],
-  "scripts": {
-    "check:tokens": "node tokens/scripts/check-component-tokens.mjs",
-    "build": "node tokens/scripts/check-exports.mjs && node tokens/scripts/check-component-tokens.mjs && tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json && tsc -p tokens/tsconfig.json",
-    "test": "node tokens/scripts/check-component-tokens.mjs && vitest run && node --test tokens/test/*.test.mjs",
-    "verify": "node tokens/scripts/check-component-tokens.mjs && node tokens/verify/run.mjs",
-    "analyze": "node tokens/verify/analyze.mjs",
-    "prepack": "node tokens/scripts/check-exports.mjs"
-  },
   "peerDependencies": {
     "@clerk/clerk-react": ">=5",
     "@radix-ui/react-accordion": "^1.2.12",
@@ -171,5 +162,13 @@
     "zod": {
       "optional": true
     }
+  },
+  "scripts": {
+    "check:tokens": "node tokens/scripts/check-component-tokens.mjs",
+    "build": "node tokens/scripts/check-exports.mjs && node tokens/scripts/check-component-tokens.mjs && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tokens/tsconfig.json",
+    "test": "node tokens/scripts/check-component-tokens.mjs && vitest run && node --test tokens/test/*.test.mjs",
+    "verify": "node tokens/scripts/check-component-tokens.mjs && node tokens/verify/run.mjs",
+    "analyze": "node tokens/verify/analyze.mjs"
   }
-}
+}

package/shell/src/AppSidebar.tsx

@@ -29,6 +29,8 @@ export type AppSidebarProps = {
   className?: string;
   /** Centred in the mobile header when truthy. */
   mobileTitle?: ReactNode;
+  /** Trailing actions in the mobile header, for example icon buttons. Replaces the end spacer. */
+  mobileHeaderActions?: ReactNode;
   /** Menu button icon. Default a 20px menu icon. */
   mobileMenuIcon?: (open: boolean) => ReactNode;
   /** Default `"Open navigation menu"`. */
@@ -57,6 +59,7 @@ export function AppSidebar({
   asideProps,
   className,
   mobileTitle,
+  mobileHeaderActions,
   mobileMenuIcon = defaultMobileMenuIcon,
   mobileMenuLabel = "Open navigation menu",
   closeLabel = "Close navigation",
@@ -114,7 +117,13 @@ export function AppSidebar({
             {mobileTitle}
           </h1>
         ) : null}
-        <div className="ml-auto h-11 w-11 shrink-0" aria-hidden="true" />
+        {mobileHeaderActions ? (
+          <div data-app-sidebar-mobile-actions="" className="ml-auto flex shrink-0 items-center gap-2">
+            {mobileHeaderActions}
+          </div>
+        ) : (
+          <div className="ml-auto h-11 w-11 shrink-0" aria-hidden="true" />
+        )}
       </header>
 
       <AnimatePresence initial={false}>

package/shell/src/SidebarAccountMenu.tsx

@@ -30,6 +30,19 @@ export type SidebarAccountMenuProps = {
   collisionPadding?: ContentProps["collisionPadding"];
   /** Merged onto the menu content after `w-56`. */
   contentClassName?: string;
+  /**
+   * Unread dot over the trigger's top-right corner, a sibling of the trigger in
+   * a `relative` wrapper. `true` shows it, `false` keeps it mounted at zero
+   * opacity so it fades out. Omitted: no wrapper and no dot.
+   */
+  badge?: boolean;
+  /** Spread onto the trigger `Button` after the defaults (overrides `title`, `aria-label`, …). `className` merges last. */
+  triggerProps?: Omit<ComponentPropsWithoutRef<typeof Button>, "children" | "asChild">;
+  /** Spread onto `DropdownMenuContent`, for example `fitViewport` or `aria-label`. Use `contentClassName` for classes. */
+  contentProps?: Omit<
+    ContentProps,
+    "children" | "className" | "align" | "side" | "sideOffset" | "collisionPadding"
+  >;
   /** Menu items after the label and separator. */
   children?: ReactNode;
 };
@@ -73,9 +86,12 @@ export function SidebarAccountMenu({
   sideOffset = 8,
   collisionPadding,
   contentClassName,
+  badge,
+  triggerProps,
+  contentProps,
   children,
 }: SidebarAccountMenuProps) {
-  return (
+  const menu = (
     <DropdownMenu>
       <DropdownMenuTrigger asChild>
         <Button
@@ -83,12 +99,19 @@ export function SidebarAccountMenu({
           variant="ghost"
           title={name}
           aria-label={`Account menu for ${name}`}
-          className={cn(railTileClass, "h-11 w-11 p-0", railTileStateClass(false))}
+          {...triggerProps}
+          className={cn(
+            railTileClass,
+            "h-11 w-11 p-0",
+            railTileStateClass(false),
+            triggerProps?.className,
+          )}
         >
           <AccountAvatar src={imageUrl} name={name} className="h-7 w-7" />
         </Button>
       </DropdownMenuTrigger>
       <DropdownMenuContent
+        {...contentProps}
         align={align}
         side={side}
         sideOffset={sideOffset}
@@ -111,6 +134,21 @@ export function SidebarAccountMenu({
       </DropdownMenuContent>
     </DropdownMenu>
   );
+  if (badge === undefined) return menu;
+  // Sibling of the trigger, so its opacity and press scale do not reach the dot.
+  return (
+    <div className="relative">
+      {menu}
+      <span
+        aria-hidden="true"
+        data-account-badge=""
+        className={cn(
+          "pointer-events-none absolute right-0 top-0 h-2.5 w-2.5 rounded-full border-2 border-background bg-danger transition-opacity duration-150 ease-out",
+          badge ? "opacity-100" : "opacity-0",
+        )}
+      />
+    </div>
+  );
 }
 
 export type SidebarAccountMenuPlaceholderProps = { className?: string };

package/src/ui/confirm-dialog.tsx

@@ -10,7 +10,14 @@ import {
   AlertDialogTitle,
 } from "./alert-dialog";
 import { Button } from "./button";
-import { Dialog, DialogContent, DialogDescription, DialogTitle } from "./dialog";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "./dialog";
 
 export type ConfirmDialogProps = React.ComponentProps<typeof AlertDialog> & {
   title: React.ReactNode;
@@ -25,8 +32,10 @@ export type ConfirmDialogProps = React.ComponentProps<typeof AlertDialog> & {
    * `"default"`: blocking alert dialog that closes on either button.
    * `"sm"`: compact dismissible dialog (outside click, Escape and the close
    * button close it). Confirm does not close it; the caller controls `open`.
+   * `"md"`: dismissible dialog like `"sm"`, with a header, description and
+   * footer in separate sections and default-size buttons.
    */
-  size?: "default" | "sm";
+  size?: "default" | "sm" | "md";
 };
 
 function ConfirmDialog({
@@ -78,6 +87,36 @@ function ConfirmDialog({
     );
   }
 
+  if (size === "md") {
+    return (
+      <Dialog {...props}>
+        {children}
+        <DialogContent className="sm:max-w-96">
+          <DialogHeader className="pb-4">
+            <DialogTitle>{title}</DialogTitle>
+          </DialogHeader>
+          {description != null ? (
+            <DialogDescription className="py-6 text-muted-foreground">{description}</DialogDescription>
+          ) : null}
+          <DialogFooter className="pt-4">
+            <Button
+              variant="ghost"
+              onClick={() => {
+                onCancel?.();
+                props.onOpenChange?.(false);
+              }}
+            >
+              {cancelLabel}
+            </Button>
+            <Button variant={variant} disabled={confirmDisabled} onClick={onConfirm}>
+              {confirmLabel}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    );
+  }
+
   return (
     <AlertDialog {...props}>
       {children}

package/app/README.md

@@ -1,100 +0,0 @@
-# App helpers (`@vvedantb/ui`)
-
-Shared web React helpers that were duplicated across apps. Source-exported as the `./app` subpath of `@vvedantb/ui`.
-
-## Install
-
-```sh
-npm install @vvedantb/ui
-```
-
-## Peers
-
-Required: `react` and `react-dom` (>=19). Optional peers of `@vvedantb/ui`, needed only for the app helpers: `@clerk/clerk-react` (`useStableAuth`), `@tanstack/react-hotkeys` and `zod`.
-
-`sonner` is not a dependency. The update watcher takes the toast API as an option. The app source uses a local class join, which the root does not export (the root `cn` is the clsx and tailwind-merge one). Tailwind must scan `node_modules/@vvedantb/ui/app/src/**/*.{ts,tsx}` so the class names are generated, and the app needs the `@vvedantb/ui/tokens` names (`bg-surface-card`, `divide-separator`, `text-muted-foreground` and so on).
-
-```css
-@source "../node_modules/@vvedantb/ui/app/src/**/*.{ts,tsx}";
-```
-
-## Confirm skip (Alt-click)
-
-```tsx
-import { ConfirmSkipHint, skipConfirmTitle, useRequestConfirm } from "@vvedantb/ui";
-
-const { request } = useRequestConfirm();
-
-<DropdownMenuItem
-  title={skipConfirmTitle("Delete")}
-  onSelect={(event) => request(() => setOpen(true), () => remove(), event)}
->
-  Delete <ConfirmSkipHint />
-</DropdownMenuItem>
-```
-
-- `useRequestConfirm` does not subscribe to Alt. It reads `getAltHeld()` when the request happens, so the menu owner does not re-render when Alt goes down. It returns `{ request }` only.
-- `ConfirmSkipHint` stays mounted and gains a `hidden` class when Alt is not held, so an open Radix menu keeps a stable child tree.
-- The Alt store resets when the last subscriber leaves, clears on blur and tab hide, and cancels a bare Alt keydown only inside `[role='menu']` or `[data-radix-menu-content]`.
-- Also exported: `useAltHeld`, `getAltHeld`, `createAltHeldStore`, `bindToWindow`, `shouldSkipConfirm`, `requestConfirm`.
-
-## Update available watcher
-
-```ts
-import { toast } from "sonner";
-import { startUpdateAvailableWatcher } from "@vvedantb/ui";
-
-useEffect(
-  () =>
-    startUpdateAvailableWatcher({
-      origin: window.location.origin,
-      toast,
-      closeConvex: () => void convex.close(),
-      enabled: !import.meta.env.DEV,
-    }),
-  [],
-);
-```
-
-Options: `origin`, `toast`, `closeConvex?`, `pollMs?` (default 60000), `toastId?` (default `app-update-available`), `enabled?` (default true), `reload?` (default `window.location.reload`). On a changed asset fingerprint it shows a sticky "Update available" toast. Refresh calls `closeConvex` (errors ignored), then reloads. `fingerprintFromHtml` and `fetchDeployFingerprint` are exported too. The fingerprint looks for Vite `/assets/*.js` URLs in the index HTML.
-
-## Settings chrome
-
-```tsx
-import { SettingsPage, SettingsSection, SettingsToggleRow } from "@vvedantb/ui";
-
-<SettingsPage
-  title="Notifications"
-  layout={({ title, headerRight, toolbar, tabs, fillHeight, children }) => (
-    <PageContainer title={title} rightSection={headerRight} toolbar={toolbar} tabs={tabs} noScroll={fillHeight}>
-      {children}
-    </PageContainer>
-  )}
->
-  <SettingsSection title="Email" bodyVariant="list">
-    <SettingsToggleRow title="Weekly digest" action={<Switch />} />
-  </SettingsSection>
-</SettingsPage>
-```
-
-Exports: `SettingsSection`, `SettingsField`, `SettingsStack`, `SettingsToggleRow`, `SettingsEmptyState` (icon is `ComponentType<{ size?: number; className?: string }>`), `SettingsPage`. `SettingsField` `layout`: `"stacked"` (default) puts the label above the control. `"horizontal"` renders one row with the label and description on the left and the control on the right. Without `layout`, `SettingsPage` renders a plain `div` with a heading and the optional slots.
-
-## useStableAuth
-
-```ts
-import { useStableAuth } from "@vvedantb/ui"; // 2000 ms debounce, wraps Clerk useAuth
-import { createUseStableAuth } from "@vvedantb/ui";
-
-const useAuth = createUseStableAuth(useClerkAuth, { debounceMs: 3000 });
-```
-
-After a signed-in session, a drop to signed-out reports `isLoaded: false` for the debounce window so Convex does not cascade. State is module-level. `resetStableAuthSession()` clears it and is for tests only.
-
-## Develop
-
-```sh
-pnpm --filter @vvedantb/ui typecheck
-pnpm --filter @vvedantb/ui test
-```
-
-Source is in `app/src` and tests in `app/tests`. Publish steps are in the root `README.md`.

package/tokens/README.md

@@ -1,98 +0,0 @@
-# `@vvedantb/ui/tokens`
-
-Design tokens and shared Tailwind v4 CSS for the vvedantb web apps. The CSS and Tailwind preset are subpaths of `@vvedantb/ui`; the native JS tokens are named exports of the root (`tokens`, `Tokens`). Source-exported: no build step. Paths in the `File` column are relative to `packages/ui/tokens/`.
-
-## Exports
-
-| Export | File | What it is |
-| --- | --- | --- |
-| `@vvedantb/ui/tokens`, `@vvedantb/ui/tokens/tokens.css` | `src/tokens.css` | Colour, radius, shadow, ease and font tokens (`@theme`), light/dark variables, `dark` variant, `*` border and `body` defaults. In 0.2.1 it also defines shadcn-style aliases (`primary`, `muted-foreground`, `secondary`, `destructive`, `card`, `popover`, `input`, `ring`) that point at the same tokens. |
-| `tokens` and `Tokens` from `@vvedantb/ui` | `src/native.ts` | JS colours, radii and spacing for React Native. `@vvedantb/native-ui` keeps its own copy in `src/tokens.ts`; a test keeps the two equal. |
-| `@vvedantb/ui/tokens/css/base.css` | `src/css/base.css` | `html` touch/accent, `::selection`, control transitions, pointer cursor, range accent (`@layer base`). |
-| `@vvedantb/ui/tokens/css/dialog.css` | `src/css/dialog.css` | Unlayered `max-width: none` for `@vvedantb/ui` compact (bottom-sheet) dialogs. |
-| `@vvedantb/ui/tokens/css/modal.css` | `src/css/modal.css` | `.t-modal`, `.is-open`, `.is-closing` and `t-modal-presence-wait` (`@layer components`). |
-| `@vvedantb/ui/tokens/css/tabs.css` | `src/css/tabs.css` | `.t-tab`, active colour, `.t-tabs-pill`, small-screen `.t-tabs` scrolling. |
-| `@vvedantb/ui/tokens/css/tabs-pills.css` | `src/css/tabs-pills.css` | `--tabs-*` colour variables, `.t-tabs--segmented`, `.t-tabs--pills` and pill hover / active fills. |
-| `@vvedantb/ui/tokens/css/utilities.css` | `src/css/utilities.css` | `@utility hit-target`, `@utility reveal-on-hover` and `@utility rounded-surface` (`clamp(0.75rem, var(--radius), 1rem)`). |
-| `@vvedantb/ui/tokens/css/scrollbar-thin.css` | `src/css/scrollbar-thin.css` | `.scrollbar-thin` (`@layer utilities`, always emitted). |
-| `@vvedantb/ui/tokens/css/animations.css` | `src/css/animations.css` | `animate-aurora`, `animate-fade-in-up`, `animate-indeterminate` as `@theme` (CSS-first apps). |
-| `@vvedantb/ui/tokens/css/compat-shadcn-rgb.css`, `@vvedantb/ui/tokens/compat/shadcn-rgb.css` | `src/css/compat-shadcn-rgb.css` | Replaces `tokens.css` for apps with shadcn-style `R G B` channel variables. Defines only the UI-only `--color-*` names as `rgb(var(--x) / alpha)` references, `--radius-field`, `--scrollbar`, `--field-radius` and a `glass-panel-strong` fallback. Import it **or** `tokens.css`, never both. |
-| `@vvedantb/ui/tokens/css/index.css` | `src/css/index.css` | base + dialog + utilities + scrollbar-thin + animations, for new CSS-first apps. |
-| `@vvedantb/ui/tokens/tailwind-preset` | `src/tailwind-preset.mjs` (+ `.d.mts`) | Tailwind preset for apps that load a JS config with `@config`. |
-
-Every file was extracted because the same rule (same at-rule context, selector and body) sits in 3 or more of the five apps. The measured duplication is in `verify/ANALYSIS.md`, and the proof that each app compiles to the same CSS after migrating is in `verify/RESULTS.md`. Blocks that only 2 apps share, or that drift in a way that would change an app's CSS, stay in the apps; `verify/ANALYSIS.md` lists them.
-
-## Use
-
-CSS-first app (no `tailwind.config`):
-
-```css
-@import "tailwindcss";
-@import "@vvedantb/ui/tokens";
-@import "@vvedantb/ui/tokens/css/animations.css";
-@import "@vvedantb/ui/tokens/css/base.css";
-/* ...app @layer base rules... */
-@import "@vvedantb/ui/tokens/css/modal.css";
-@import "@vvedantb/ui/tokens/css/tabs.css";
-/* ...app @layer components rules... */
-```
-
-App with a JS config (`@config "../tailwind.config.ts"`):
-
-```ts
-import { tokensPreset } from "@vvedantb/ui/tokens/tailwind-preset";
-
-export default {
-  presets: [tokensPreset()],
-  // or tokensPreset({ color: (name) => `color-mix(in oklch, var(--${name}) calc(<alpha-value> * 100%), transparent)` })
-  content: ["./src/**/*.{ts,tsx}"],
-  theme: { extend: { /* app-only colours, fonts, animations */ } },
-  plugins: [tailwindcssAnimate],
-};
-```
-
-The preset holds `darkMode: "class"`, the shared colour map (`border`, `surface.*`, `danger.*`, `field.*`, shadcn aliases `primary`/`secondary`/`destructive`/`card`/`popover`/`input` ...), `borderRadius` lg/md/sm/field, `boxShadow` soft/panel/insetSoft, `ease-smooth`, `screens` xs to 2xl in px, and the aurora / fade-in-up / indeterminate / accordion keyframes. It does not hold plugins, `content`, fonts, `accent`/`muted`/`ring`/`sidebar` (they differ per app) or accordion timings.
-
-Do not import `css/animations.css` in an app that uses the preset: the preset already defines the same keyframes and animations.
-
-### Where to put the imports
-
-Tailwind inlines an `@import` where it sits, even in the middle of a file (it must be at top level, not inside an `@layer` block). Put each import where the app's own copy of the rules was. Within one layer, later rules win at equal specificity, so moving shared rules above or below app rules can flip the result for elements matched by both. `examples/migration.md` gives the exact position for each app, and `pnpm --filter @vvedantb/ui verify` checks it.
-
-### Variables each file needs
-
-| File | Needs | Provided by |
-| --- | --- | --- |
-| `base.css` | `--accent`, `--foreground` | tokens.css or the app theme |
-| `dialog.css` | none | |
-| `modal.css` | `--modal-open-dur`, `--modal-close-dur`, `--modal-scale`, `--modal-scale-close`, `--modal-ease` | app `:root` |
-| `tabs.css` | `--tabs-dur`, `--tabs-ease` (app `:root`); `--tabs-text-muted`, `--tabs-text-active`, `--tabs-pill-bg` | colours: tabs-pills.css or the app theme |
-| `tabs-pills.css` | `--muted`, `--segment`, `--segment-foreground`, `--default` | tokens.css or the app theme |
-| `utilities.css` | `--breakpoint-sm` (Tailwind default or app theme) | Tailwind |
-| `scrollbar-thin.css` | `--scrollbar` | tokens.css or the app theme |
-| `animations.css` | none | |
-| `tailwind-preset` | the CSS variables named in its colour map, `--radius`, `--field-radius` | tokens.css or the app theme |
-
-### Using an existing shadcn RGB theme
-
-See the package `README.md`. With the compat file, `base.css`, `scrollbar-thin.css`, `utilities.css`, `dialog.css`, `modal.css` and `tabs.css` need no `tokens.css`. `base.css` reads `--accent` and `--foreground` and `tabs-pills.css` reads `--muted`, `--segment` and `--default`. Those are not channel-compatible, so skip `tabs-pills.css` and `index.css` (which includes `base.css`) unless the app defines those variables as full colours.
-
-### Parameters
-
-Where apps share a rule but drifted in one value, the value is a custom property whose fallback is the most common value. Set it on `:root` to keep a different value.
-
-| File | Property | Default | Set by |
-| --- | --- | --- | --- |
-| `base.css` | `--tokens-control-transition-property` | `background-color, border-color, color, box-shadow, transform, opacity` | app-c: `background-color, color, transform, opacity` |
-| `base.css` | `--tokens-control-transition-duration` | `240ms` | app-c: `100ms` |
-
-## Develop
-
-```sh
-pnpm --filter @vvedantb/ui build     # export targets exist + tsc (primitives, shell, app)
-pnpm --filter @vvedantb/ui test      # vitest (app helpers) + offline node --test: exports, CSS structure, Tailwind compile, preset
-pnpm --filter @vvedantb/ui analyze   # rule-level duplication across the app clones -> verify/ANALYSIS.tables.md
-pnpm --filter @vvedantb/ui verify    # before/after compile of every app -> verify/RESULTS.md, examples/migration.md
-```
-
-`analyze` and `verify` need the app clones (`APPS_DIR`, default `/workspace/cvx`; name or symlink the clones `app-a` to `app-e` inside it) and network access the first time: they install Tailwind 4.3.3, the plugins, postcss and jiti into a scratch directory (`VERIFY_DIR`, default `/workspace/pk-tokens-verify`, outside the repo). The migration for each app is data in `verify/migrations/<app>.json`. Each removed block must equal the shared file's block with the same context and selector, or the run fails.