@vvedantb/ui 0.36.0 → 0.37.0

package/README.md

@@ -890,7 +890,7 @@ Plain parts, no Motion:
 | `LandingLattice` | `className` (grid columns). Cells share 1px borders. |
 | `LandingFeatureCard` | `icon` (a component, rendered `size={18} stroke={1.5}`), `title`, `description`. |
 | `LandingNavMenu` | `links`, `github` (`href`, `icon`). Overflow menu below `md`. |
-| `LandingFooter` | `brand`, `tagline`, `links`, `actions` (after the links), `github` (`href`, `label`, `icon`). |
+| `LandingFooter` | New path (0.37.0): `app`, `tagline`, `links` (a "Navigation" column) or `columns`, `actions`, plus the `SiteFooter` options. A thin wrapper over `SiteFooter` with every Project V default. Deprecated path (no `app`): `brand`, `tagline`, `links`, `actions` (after the links), `github` (`href`, `label`, `icon`), in the old compact layout. `brand` and `github` are ignored when `app` is set. |
 
 Constants: `landingShellClass`, `landingPanelClass`, `landingItemVariants`, and
 for the footer's `actions` slot `landingFooterLinkClass` (a text link) and
@@ -898,17 +898,36 @@ for the footer's `actions` slot `landingFooterLinkClass` (a text link) and
 
 ### `SiteFooter`
 
-Brand, tagline and social icon buttons; link columns; then copyright and legal
-links under a separator.
+Brand, tagline and social icon buttons; link columns; then copyright, product-of line and legal
+links under a separator. Set `app` for the Project V footer (0.37.0):
+
+```tsx
+<SiteFooter
+  app="vibot"
+  tagline="AI-powered assistant designed to automate tasks, and enhance productivity effortlessly."
+  columns={[{ heading: "Navigation", links: [{ href: "#features", label: "Features" }] }]}
+/>
+```
 
 | Prop | |
 | --- | --- |
-| `brand`, `tagline` | Nodes. |
-| `socials` | `{ href, icon, label? }[]`. `icon` is a component that takes `className`. Links open in a new tab. |
-| `columns` | `{ heading, links }[]`. A link is `{ href, label, external?, image?: { src, alt }, app?: AppName }`. `image` is a 20px round image before the label. `app` (0.29.0) is the 14px `APP_ICONS[app]` glyph before the label, in `currentColor` and `aria-hidden`. If both are set, `app` wins. |
-| `name`, `year` | "Copyright © {year} {name}". `year` defaults to the current year. |
-| `legalLinks` | `{ href, label }[]`, open in a new tab. |
+| `app` | `vibot`, `vmem`, `verve`, `velth` or `vhub`. Brand is `AppWordmark` at `SITE_FOOTER_WORDMARK_SIZE` (16px; no size prop). Copyright name and product-of line use the lowercase id. |
+| `tagline` | Node. |
+| `columns` | Required. `{ heading, links }[]`. A link is `{ href, label, external?, image?: { src, alt }, app?: AppName }`. `image` is a 20px round image before the label. `app` is the 14px `APP_ICONS[app]` glyph before the label, in `currentColor` and `aria-hidden`; it wins over `image`. |
+| `includeAppsColumn` | Default `true`: appends `PROJECT_V_PRODUCT_APPS` (vibot, vmem, verve, velth, vhub) unless `columns` has an "Apps" heading (case-insensitive). `projectVAppsColumn()` returns the column for composition. |
+| `showProductOf` | Default `true`: "{app} is a product of Project V." linking to `https://projectv.uk`. |
+| `socials` | Default `PROJECT_V_SOCIALS` (X, Instagram, GitHub). `[]` hides them. `{ href, icon, label? }[]`; links open in a new tab. |
+| `legalLinks` | Default `PROJECT_V_LEGAL_LINKS` (Privacy Policy, Terms of Service). |
+| `actions` | Node under the socials, for example Sign in. |
+| `year` | Default: the current year. |
 | `variant` | `"muted"` (default, `text-muted`), `"muted-foreground"`, or `"touch"` (`text-muted-foreground`, `max-sm:hit-target` links, safe-area bottom padding). |
+| `brand`, `name` | Optional overrides on the `app` path. |
+
+**Deprecated (no `app`):** `brand`, `socials`, `name` and `legalLinks` are required, and the footer renders as before: the brand sits in the Michroma wrapper, with no product-of line and no Apps column. `actions`, `includeAppsColumn` and `showProductOf` do nothing. Set `app` instead.
+
+### `PageTitle` and `PageHeader`
+
+`PageTitle` is an `h1` with `text-xl font-semibold leading-tight tracking-tight` (`pageTitleClass`): Instrument Sans, 20px, weight 600, never lighter. `PageHeader` is a title row: `title` in a `PageTitle`, an optional `action` slot, and no safe-area padding.
 
 ### `Icon*` app icons
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "license": "MIT",
   "description": "Shared React 19 UI for web apps: one main JavaScript entry (primitives, shell pieces, app helpers including the Convex and Clerk provider, VITE env parsing and ensure-user, artifact viewers over the @vvedantb/server artifacts core, native tokens), third-party brand logos (also @vvedantb/ui/logos), motion-driven animated SVG icons (@vvedantb/ui/icons/animated), a client entry without @vvedantb/server, convex or Clerk for Chrome extensions, design-token CSS, shared Tailwind v4 CSS, a Tailwind preset and packaged Instrument Sans fonts.",
   "type": "module",
@@ -81,17 +81,6 @@
     "./src/marketing/landing.css",
     "./fonts/instrument-sans.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 tsconfig.consumer.json && tsc -p tsconfig.consumer-speech.json && tsc -p tokens/tsconfig.json",
-    "test": "node tokens/scripts/check-component-tokens.mjs && vitest run && node --test tokens/test/*.test.mjs app/tests-node/*.test.mjs",
-    "verify": "node tokens/scripts/check-component-tokens.mjs && node tokens/verify/run.mjs",
-    "analyze": "node tokens/verify/analyze.mjs",
-    "brand:assets": "node scripts/build-brand-assets.mjs",
-    "brand:sheet": "node scripts/build-brand-sheet.mjs",
-    "prepack": "node tokens/scripts/check-exports.mjs"
-  },
   "dependencies": {
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/modifiers": "^9.0.0",
@@ -182,7 +171,6 @@
     "@tanstack/react-hotkeys": "^0.13.0",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
-    "@vvedantb/server": "workspace:*",
     "ai": "^5.0.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -206,7 +194,8 @@
     "vaul": "^1.1.0",
     "vitest": "^3.2.0",
     "zod": "^4.0.0",
-    "zod3": "npm:zod@^3.25.76"
+    "zod3": "npm:zod@^3.25.76",
+    "@vvedantb/server": "0.14.0"
   },
   "peerDependenciesMeta": {
     "@clerk/clerk-react": {
@@ -227,5 +216,15 @@
     "@vvedantb/server": {
       "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 tsconfig.consumer.json && tsc -p tsconfig.consumer-speech.json && tsc -p tokens/tsconfig.json",
+    "test": "node tokens/scripts/check-component-tokens.mjs && vitest run && node --test tokens/test/*.test.mjs app/tests-node/*.test.mjs",
+    "verify": "node tokens/scripts/check-component-tokens.mjs && node tokens/verify/run.mjs",
+    "analyze": "node tokens/verify/analyze.mjs",
+    "brand:assets": "node scripts/build-brand-assets.mjs",
+    "brand:sheet": "node scripts/build-brand-sheet.mjs"
   }
-}
+}

package/src/brand/index.ts

@@ -28,3 +28,4 @@ export { FAMILY_APPS, familyApp } from "./familyApps";
 export type { FamilyApp, FamilyAppName } from "./familyApps";
 export { V_PRO_APP_BENEFITS } from "./vProAppBenefits";
 export type { PricingPlanAppBenefit } from "./vProAppBenefits";
+export { PROJECT_V_PRODUCT_APPS, PROJECT_V_PRODUCT_APP_IDS, projectVAppsColumn } from "./productApps";

package/src/brand/productApps.ts

@@ -0,0 +1,20 @@
+import type { ProductAppName } from "./AppWordmark";
+
+/** The five product apps in footer order (not `FAMILY_APPS` order). */
+export const PROJECT_V_PRODUCT_APP_IDS: readonly ProductAppName[] = ["vibot", "vmem", "verve", "velth", "vhub"];
+
+/** Apps column: each app links to `https://{app}.projectv.uk` in a new tab, with its glyph and lowercase id as the label. */
+export function projectVAppsColumn() {
+  return {
+    heading: "Apps",
+    links: PROJECT_V_PRODUCT_APP_IDS.map((app) => ({
+      href: `https://${app}.projectv.uk`,
+      label: app,
+      external: true as const,
+      app,
+    })),
+  };
+}
+
+/** `projectVAppsColumn()`, built once. */
+export const PROJECT_V_PRODUCT_APPS = projectVAppsColumn();

package/src/client.ts

@@ -54,6 +54,7 @@ export * from "./ui/avatar";
 export * from "./ui/badge";
 export * from "./ui/border-beam";
 export * from "./ui/breadcrumb";
+export * from "./ui/page-title";
 export * from "./ui/button";
 export * from "./ui/button-group";
 export * from "./ui/card";
@@ -285,6 +286,8 @@ export {
 } from "./marketing/landing";
 export type {
   LandingFeature,
+  LandingFooterAppProps,
+  LandingFooterLegacyProps,
   LandingFooterProps,
   LandingLatticeProps,
   LandingLink,
@@ -311,8 +314,15 @@ export {
   landingShellClass,
 } from "./marketing/marketing-classes";
 export type { PricingModalTone, SiteFooterVariant } from "./marketing/marketing-classes";
-export { SiteFooter } from "./marketing/SiteFooter";
-export type { SiteFooterLink, SiteFooterProps, SiteFooterSocial } from "./marketing/SiteFooter";
+export { PROJECT_V_LEGAL_LINKS, PROJECT_V_SOCIALS, SITE_FOOTER_WORDMARK_SIZE, SiteFooter } from "./marketing/SiteFooter";
+export type {
+  SiteFooterAppProps,
+  SiteFooterColumn,
+  SiteFooterLegacyProps,
+  SiteFooterLink,
+  SiteFooterProps,
+  SiteFooterSocial,
+} from "./marketing/SiteFooter";
 export { PricingModal, V_PRO_APP_BENEFITS } from "./marketing/PricingModal";
 export type {
   PricingModalLegacyProps,

package/src/index.ts

@@ -50,6 +50,7 @@ export * from "./ui/avatar";
 export * from "./ui/badge";
 export * from "./ui/border-beam";
 export * from "./ui/breadcrumb";
+export * from "./ui/page-title";
 export * from "./ui/button";
 export * from "./ui/button-group";
 export * from "./ui/card";
@@ -285,6 +286,8 @@ export {
 } from "./marketing/landing";
 export type {
   LandingFeature,
+  LandingFooterAppProps,
+  LandingFooterLegacyProps,
   LandingFooterProps,
   LandingLatticeProps,
   LandingLink,
@@ -311,8 +314,15 @@ export {
   landingShellClass,
 } from "./marketing/marketing-classes";
 export type { PricingModalTone, SiteFooterVariant } from "./marketing/marketing-classes";
-export { SiteFooter } from "./marketing/SiteFooter";
-export type { SiteFooterLink, SiteFooterProps, SiteFooterSocial } from "./marketing/SiteFooter";
+export { PROJECT_V_LEGAL_LINKS, PROJECT_V_SOCIALS, SITE_FOOTER_WORDMARK_SIZE, SiteFooter } from "./marketing/SiteFooter";
+export type {
+  SiteFooterAppProps,
+  SiteFooterColumn,
+  SiteFooterLegacyProps,
+  SiteFooterLink,
+  SiteFooterProps,
+  SiteFooterSocial,
+} from "./marketing/SiteFooter";
 export { PricingModal, V_PRO_APP_BENEFITS } from "./marketing/PricingModal";
 export type {
   PricingModalLegacyProps,

package/src/marketing/SiteFooter.tsx

@@ -1,5 +1,6 @@
 import type { ComponentType, ReactNode } from "react";
-import { APP_ICONS, type AppName } from "../brand";
+import { IconBrandGithub, IconBrandInstagram, IconBrandX } from "@tabler/icons-react";
+import { APP_ICONS, AppWordmark, projectVAppsColumn, type AppName, type ProductAppName } from "../brand";
 import { Button } from "../ui/button";
 import { Separator } from "../ui/separator";
 import { siteFooterClasses, type SiteFooterVariant } from "./marketing-classes";
@@ -23,47 +24,100 @@ export type SiteFooterSocial = {
   label?: string;
 };
 
-export type SiteFooterProps = {
-  /** Wordmark text above the tagline. */
-  brand: ReactNode;
+/** Text size in px of the built-in `AppWordmark` brand. Fixed: `SiteFooter` has no size prop. */
+export const SITE_FOOTER_WORDMARK_SIZE = 16;
+
+/** Default `socials` on the `app` path: X, Instagram and GitHub. */
+export const PROJECT_V_SOCIALS: readonly SiteFooterSocial[] = [
+  { href: "https://x.com/projectvdotuk", icon: IconBrandX, label: "Project V on X" },
+  { href: "https://www.instagram.com/projectvdotuk/", icon: IconBrandInstagram, label: "Project V on Instagram" },
+  { href: "https://github.com/projectvdotuk", icon: IconBrandGithub, label: "Project V on GitHub" },
+];
+
+/** Default `legalLinks` on the `app` path. */
+export const PROJECT_V_LEGAL_LINKS: readonly { href: string; label: string }[] = [
+  { href: "https://projectv.uk/privacy", label: "Privacy Policy" },
+  { href: "https://projectv.uk/terms", label: "Terms of Service" },
+];
+
+export type SiteFooterColumn = { heading: string; links: readonly SiteFooterLink[] };
+
+type SiteFooterCommonProps = {
   tagline: ReactNode;
-  /** Icon buttons under the tagline. Always open in a new tab. */
-  socials: readonly SiteFooterSocial[];
   /** Link columns to the right of the brand block. */
-  columns: readonly { heading: string; links: readonly SiteFooterLink[] }[];
-  /** Name in "Copyright © {year} {name}". */
-  name: string;
+  columns: readonly SiteFooterColumn[];
   /** Default: the current year. */
   year?: number;
-  /** Bottom-right links, for example Privacy Policy and Terms of Service. Always open in a new tab. */
-  legalLinks: readonly { href: string; label: string }[];
   /**
    * `"muted"` (default) and `"muted-foreground"` pick the secondary text
    * colour class. `"touch"` uses `text-muted-foreground`, `max-sm:hit-target`
    * links and a safe-area bottom padding.
    */
   variant?: SiteFooterVariant;
+  /** Under the socials, for example a Sign-in button. Not rendered on the legacy path. */
+  actions?: ReactNode;
 };
 
+/** Opinionated footer: set `app` and the Project V brand, socials, legal links, Apps column and product-of line follow. */
+export type SiteFooterAppProps = SiteFooterCommonProps & {
+  /** Product app id. Sets the wordmark (size 16), the copyright name and the product-of line. */
+  app: ProductAppName;
+  /** Replaces the `AppWordmark`. */
+  brand?: ReactNode;
+  /** Default `PROJECT_V_SOCIALS`. `[]` hides them. */
+  socials?: readonly SiteFooterSocial[];
+  /** Default `PROJECT_V_LEGAL_LINKS`. */
+  legalLinks?: readonly { href: string; label: string }[];
+  /** Overrides the copyright name (default: `app`). */
+  name?: string;
+  /** Appends the standard Apps column unless `columns` has an "Apps" heading (default `true`). */
+  includeAppsColumn?: boolean;
+  /** Shows "{app} is a product of Project V." (default `true`). */
+  showProductOf?: boolean;
+};
+
+/** Legacy footer: you pass every part. Prefer `SiteFooterAppProps`. */
+export type SiteFooterLegacyProps = SiteFooterCommonProps & {
+  app?: undefined;
+  /**
+   * @deprecated Set `app` instead: the footer renders `AppWordmark`. Without `app` the brand sits in the Michroma wrapper.
+   */
+  brand: ReactNode;
+  /** @deprecated Set `app` for the Project V defaults (`PROJECT_V_SOCIALS`). Icon buttons under the tagline; always open in a new tab. */
+  socials: readonly SiteFooterSocial[];
+  /** @deprecated Set `app`: the copyright name is then the app id. Name in "Copyright © {year} {name}". */
+  name: string;
+  /** @deprecated Set `app` for `PROJECT_V_LEGAL_LINKS`. Bottom-right links; always open in a new tab. */
+  legalLinks: readonly { href: string; label: string }[];
+  includeAppsColumn?: undefined;
+  showProductOf?: undefined;
+};
+
+export type SiteFooterProps = SiteFooterAppProps | SiteFooterLegacyProps;
+
 /** Marketing site footer: brand, socials, link columns, then copyright and legal links under a separator. */
-export function SiteFooter({
-  brand,
-  tagline,
-  socials,
-  columns,
-  name,
-  year = new Date().getFullYear(),
-  legalLinks,
-  variant = "muted",
-}: SiteFooterProps) {
+export function SiteFooter(props: SiteFooterProps) {
+  const { tagline, year = new Date().getFullYear(), variant = "muted", actions } = props;
   const c = siteFooterClasses[variant];
+  const modern = props.app !== undefined;
+  const brandNode = modern ? (
+    <div className="mb-3 md:mb-4">{props.brand ?? <AppWordmark app={props.app} size={SITE_FOOTER_WORDMARK_SIZE} />}</div>
+  ) : (
+    <div className="text-lg font-michroma font-normal tracking-wider mb-3 md:mb-4">{props.brand}</div>
+  );
+  const socials = modern ? (props.socials ?? PROJECT_V_SOCIALS) : props.socials;
+  const legalLinks = modern ? (props.legalLinks ?? PROJECT_V_LEGAL_LINKS) : props.legalLinks;
+  const name = modern ? (props.name ?? props.app) : props.name;
+  const hasApps = props.columns.some((column) => column.heading.toLowerCase() === "apps");
+  const columns: readonly SiteFooterColumn[] = modern && (props.includeAppsColumn ?? true) && !hasApps ? [...props.columns, projectVAppsColumn()] : props.columns;
+  const showProductOf = modern && (props.showProductOf ?? true);
   return (
     <footer className={c.footer}>
       <div className="relative z-10">
         <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
           <div className="flex flex-col lg:flex-row lg:items-start lg:justify-between gap-8 lg:gap-12">
             <div className="flex-1 lg:flex-none">
-              <div className="text-lg font-michroma font-normal tracking-wider mb-3 md:mb-4">{brand}</div>
+              {brandNode}
               <p className={c.tagline}>{tagline}</p>
               <div className="flex gap-3 md:gap-4">
                 {socials.map(({ href, icon: Icon, label }) => (
@@ -74,6 +128,7 @@ export function SiteFooter({
                   </a>
                 ))}
               </div>
+              {modern && actions ? <div className="mt-3 md:mt-4">{actions}</div> : null}
             </div>
 
             <div className="flex flex-col sm:flex-row gap-8 md:gap-12 lg:gap-16 xl:gap-20">
@@ -120,6 +175,15 @@ export function SiteFooter({
                 {` ${name}`}
               </p>
               <p className={c.rights}>All rights reserved.</p>
+              {showProductOf ? (
+                <p className={c.rights}>
+                  {props.app} is a product of{" "}
+                  <a href="https://projectv.uk" target="_blank" rel="noopener noreferrer" className="underline underline-offset-2">
+                    Project V
+                  </a>
+                  .
+                </p>
+              ) : null}
             </div>
 
             <div className="flex flex-col gap-1 text-center sm:text-right">

package/src/marketing/landing.tsx

@@ -11,6 +11,7 @@ import {
   DropdownMenuTrigger,
 } from "../ui/dropdown-menu";
 import { cn } from "../utils/cn";
+import { SiteFooter, type SiteFooterAppProps } from "./SiteFooter";
 import { landingClasses, landingFooterLinkClass, landingShellClass } from "./marketing-classes";
 
 export type LandingLink = { href: string; label: string };
@@ -140,19 +141,46 @@ export function LandingNavMenu({ links, github }: LandingNavMenuProps) {
   );
 }
 
-export type LandingFooterProps = {
-  /** Wordmark above the tagline. */
-  brand: ReactNode;
+type LandingFooterCommonProps = {
   tagline: ReactNode;
+  /** Section links. On the `app` path they become a "Navigation" column unless `columns` is set. */
   links: readonly LandingLink[];
-  /** After the links, before GitHub. Style with `landingFooterLinkClass` or `landingFooterButtonClass`. */
+  /** App actions, for example Sign in. Style with `landingFooterLinkClass` or `landingFooterButtonClass`. */
   actions?: ReactNode;
-  /** `label` is the link's `aria-label`. */
+};
+
+/** Project V footer: a thin wrapper over `SiteFooter` with every default (wordmark, socials, legal links, Apps column, product-of line). */
+export type LandingFooterAppProps = LandingFooterCommonProps &
+  Pick<SiteFooterAppProps, "app" | "year" | "variant" | "socials" | "legalLinks" | "includeAppsColumn" | "showProductOf"> & {
+    /** Replaces the Navigation column built from `links`. */
+    columns?: SiteFooterAppProps["columns"];
+    /** @deprecated Ignored on the `app` path: the footer renders `AppWordmark`. */
+    brand?: ReactNode;
+    /** @deprecated Ignored on the `app` path: `PROJECT_V_SOCIALS` includes GitHub. */
+    github?: LandingFooterLegacyProps["github"];
+  };
+
+/** Old compact footer. Deprecated: set `app` instead. */
+export type LandingFooterLegacyProps = LandingFooterCommonProps & {
+  app?: undefined;
+  /** @deprecated Set `app`. Wordmark above the tagline. */
+  brand: ReactNode;
+  /** @deprecated Set `app`: `PROJECT_V_SOCIALS` includes GitHub. `label` is the link's `aria-label`. */
   github: { href: string; label: string; icon: ReactNode };
 };
 
-/** Footer row: brand and tagline, then section links, app actions and a GitHub icon link. */
-export function LandingFooter({ brand, tagline, links, actions, github }: LandingFooterProps) {
+export type LandingFooterProps = LandingFooterAppProps | LandingFooterLegacyProps;
+
+/**
+ * With `app`: `SiteFooter` with `links` as a Navigation column. Without `app` (deprecated): the old compact row of
+ * brand and tagline, section links, app actions and a GitHub icon link.
+ */
+export function LandingFooter(props: LandingFooterProps) {
+  if (props.app !== undefined) {
+    const { links, columns, brand: _brand, github: _github, ...rest } = props;
+    return <SiteFooter {...rest} columns={columns ?? [{ heading: "Navigation", links }]} />;
+  }
+  const { brand, tagline, links, actions, github } = props;
   return (
     <footer className="border-t border-separator">
       <div

package/src/ui/page-title.tsx

@@ -0,0 +1,29 @@
+import * as React from "react";
+import { cn } from "../utils/cn";
+
+/** The page title class contract: Instrument Sans (the sans token), 20px, weight 600, never lighter. Same string as `Breadcrumb`. */
+export const pageTitleClass = "text-xl font-semibold leading-tight tracking-tight";
+
+/** Page title: `h1`, `text-xl font-semibold leading-tight tracking-tight`. */
+const PageTitle = React.forwardRef<HTMLHeadingElement, React.HTMLAttributes<HTMLHeadingElement>>(
+  ({ className, ...props }, ref) => <h1 ref={ref} className={cn(pageTitleClass, className)} {...props} />,
+);
+PageTitle.displayName = "PageTitle";
+
+export type PageHeaderProps = Omit<React.HTMLAttributes<HTMLElement>, "title"> & {
+  /** Title text or node, rendered in `PageTitle`. */
+  title: React.ReactNode;
+  /** Right-aligned slot, for example a button. */
+  action?: React.ReactNode;
+};
+
+/** Title row: `PageTitle` with an optional `action` slot. No safe-area padding (web). */
+const PageHeader = React.forwardRef<HTMLElement, PageHeaderProps>(({ title, action, className, ...props }, ref) => (
+  <header ref={ref} className={cn("flex min-w-0 items-center justify-between gap-3 px-4 py-4 sm:px-6", className)} {...props}>
+    <PageTitle className="min-w-0 truncate">{title}</PageTitle>
+    {action ? <div className="flex shrink-0 items-center gap-2">{action}</div> : null}
+  </header>
+));
+PageHeader.displayName = "PageHeader";
+
+export { PageHeader, PageTitle };

package/app/README.md

@@ -1,269 +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` used by the app helpers: `@clerk/clerk-react` (`useStableAuth`, `ConvexClerkProvider`), `convex` (`ConvexClerkProvider`, `useEnsureUser`), `@tanstack/react-hotkeys` and `zod` (your `z` for `parseClientEnv`). The root imports Clerk and `convex/react` statically, so they must be installed even if you do not use these helpers; see the package README.
-
-`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 calls `showUpdateAvailableToast` once. `fingerprintFromHtml` and `fetchDeployFingerprint` are exported too. The fingerprint looks for Vite `/assets/*.js` URLs in the index HTML.
-
-`showUpdateAvailableToast({ toast, closeConvex?, toastId?, reload? })` (from 0.31.1) shows the toast on its own, for an app with its own update signal:
-
-```ts
-import { showUpdateAvailableToast, toast } from "@vvedantb/ui";
-
-showUpdateAvailableToast({ toast, closeConvex: () => void convex.close() });
-```
-
-It shows a sticky "Update available" toast, "Refresh to load the latest version.", with a Refresh action. Refresh calls `closeConvex` (errors ignored), then reloads. The same `toastId` replaces an open toast instead of adding a second one. Mount `SonnerToaster`: from 0.31.1 its default `content` class grows the text column, so Refresh sits at the right edge without app classes.
-
-## 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`.
-
-## Theme
-
-```tsx
-import { createThemeProvider } from "@vvedantb/ui";
-
-// One kit per app, at module level.
-export const { ThemeProvider, useTheme } = createThemeProvider();
-
-<ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
-  <App />
-</ThemeProvider>;
-
-const { theme, resolvedTheme, setTheme, isDark, toggleTheme, mounted } = useTheme();
-```
-
-`createThemeProvider` is a port of next-themes 0.4.6. An app that uses next-themes can switch without a change in behaviour: the same localStorage writes, `<html>` classes and attributes, `style.colorScheme`, `prefers-color-scheme` listener, cross-tab `storage` sync and transition blocking. Parity tests run both side by side.
-
-- Props, as in next-themes: `storageKey` (`"theme"`), `defaultTheme` (`"system"` with `enableSystem`, else `"light"`), `enableSystem` (`true`), `enableColorScheme` (`true`), `attribute` (`"data-theme"`; `"class"`, any `data-*`, or an array), `themes` (`["light", "dark"]`), `value` (theme name to written value), `forcedTheme`, `disableTransitionOnChange` (`false`) and `nonce`.
-- State: `theme`, `setTheme` (a value or a function of the current theme), `resolvedTheme`, `systemTheme`, `forcedTheme` and `themes`, as in next-themes. Added: `mounted` (after the provider's first effect), `isDark` (`mounted && resolvedTheme === "dark"`) and `toggleTheme` (from `resolvedTheme`).
-- `setTheme` is a new function each time `theme` changes and stable otherwise, as in next-themes, so effects that list it re-run at the same times.
-- next-themes reads the DOM options (`attribute`, `themes`, `value`, `enableSystem`, `enableColorScheme`, `defaultTheme`, `disableTransitionOnChange`, `nonce`) once, on the first render, and so does this port. If `enableSystem` starts `false` and later turns `true`, a stored `"system"` is written as the class `system`. `forcedTheme` follows props.
-- A nested `ThemeProvider` from the same kit renders only its children.
-- `createThemeProvider({ missingProviderMessage })`: `useTheme()` outside the provider throws that message. Without it, `useTheme()` returns an empty state with no-op setters, as next-themes does.
-- No inline script is rendered. next-themes renders one for server rendering; React does not run it in a client-rendered app. Keep a pre-paint script in `index.html` if the app has one.
-
-For an app with its own theme state (for example a theme synced from the server), two helpers:
-
-- `getSystemTheme()`: `"dark"` or `"light"` from `prefers-color-scheme`; `"light"` without `window`.
-- `applyThemeClass(theme)`: removes `light` and `dark` from `<html>`, then adds `theme`. No-op without `document`.
-
-## Page title
-
-```tsx
-import { createPageTitleContext } from "@vvedantb/ui";
-
-export const { PageTitleProvider, usePageTitle, usePageTitleSync } = createPageTitleContext({
-  missingProviderMessage: "usePageTitle must be used within a PageTitleProvider",
-});
-
-// The shell reads it:
-const { pageTitle } = usePageTitle();
-// A page publishes it while mounted:
-usePageTitleSync(title);
-```
-
-- `usePageTitle()` returns `{ pageTitle, setPageTitle, mobileActionsSlot, setMobileActionsSlot }`. `mobileActionsSlot` is an element a mobile top bar registers (pass `setMobileActionsSlot` as its `ref`) so pages can portal actions into it.
-- `usePageTitleSync(title)` sets the title while the caller is mounted and clears it on unmount. Titles that are not strings publish `""`.
-- `missingProviderMessage`: `usePageTitle()` outside the provider throws it. Without it, `usePageTitle()` returns an empty title and no-op setters.
-- `documentTitle` (off by default; without it `document.title` is never touched): `{ suffix?, separator? = " · ", fallback? }`. While a page title is set, `document.title` is `` `${pageTitle}${separator}${suffix}` `` (just the page title without a suffix). While it is empty, `fallback`, else the title at mount. The mount-time title comes back on unmount.
-
-## Page motion
-
-```tsx
-import { MotionConfig } from "motion/react";
-import { PageMotionProvider, useDisablePageMotion } from "@vvedantb/ui";
-
-<PageMotionProvider disabled={flags?.disablePageMotion === true} motionConfig={MotionConfig}>
-  <App />
-</PageMotionProvider>;
-```
-
-- Sets `html[data-page-motion]` to `"off"` or `"on"` in a layout effect. The attribute stays after unmount. From 0.15.0 `tokens.css` (through `tokens/css/motion.css`) ships the `"off"` rules: `.ui-page-enter`, `.ui-enter`, `.ui-enter-up` and `.ui-stagger` fade only, `animate-in` / `animate-out`, `.t-modal` and `.t-tabs-pill` stop transitioning, and view transitions stop.
-- Renders `motionConfig` with `reducedMotion` `"always"` when disabled, else `"never"`.
-- `useDisablePageMotion()`: the `disabled` value, `false` outside the provider.
-- This module does not import `motion`. Pass `MotionConfig`, or an app component that wraps it, defined at module level, for example with `LazyMotion`:
-
-```tsx
-function LazyMotionConfig({ reducedMotion, children }: PageMotionConfigProps) {
-  return (
-    <LazyMotion features={domAnimation}>
-      <MotionConfig reducedMotion={reducedMotion}>{children}</MotionConfig>
-    </LazyMotion>
-  );
-}
-```
-
-## Compact relative time
-
-```ts
-import { formatCompactRelativeTime } from "@vvedantb/ui";
-
-formatCompactRelativeTime(createdAt, { justNow: "now" }); // "now", "5m", "3h", "2d", "4mo", "1y"
-formatCompactRelativeTime(updatedAt, { calendar: true }); // "42s", ..., calendar months and years
-```
-
-Pure TypeScript, no dependencies. Options:
-
-- `now`: clock in ms, default `Date.now()`.
-- `justNow`: returned for anything under a minute old, future times included. Without it the result is whole seconds (`"42s"`), and a future time gives `"0s"` or a negative count.
-- `calendar`: `false` (default) counts elapsed time: a day is 24 hours, a month 30 days, a year 12 such months. `true` counts as `dayjs().diff(date, unit)` does: days by the local calendar across DST changes, and calendar months and years.
-
-Strings are parsed with `new Date(string)`. dayjs parses a date-only string such as `"2026-03-01"` as local midnight, `new Date` as UTC midnight; numbers, `Date` objects and ISO strings with a time give the same result either way. An invalid date gives `"NaNy"` (`"0mo"` with `calendar`).
-
-## Convex provider, VITE env and ensure-user (0.10.0)
-
-React and VITE env helpers for Convex apps. The non-React Convex helpers (`mapLoadedQuery`, `forEachLoadedQuery`, `updateAllCachedQueries`, `patchLoadedQuery`, `OptimisticStore`, `tempId`, `createMemoryOptimisticStore`) live in `@vvedantb/server`, so backend packages, tests and React Native can use them without loading this package.
-
-### `ConvexClerkProvider`
-
-```tsx
-import { ConvexClerkProvider, useStableAuth } from "@vvedantb/ui";
-import { ConvexReactClient } from "convex/react";
-
-const convex = new ConvexReactClient(env.VITE_CONVEX_URL);
-
-<ClerkProvider publishableKey={env.VITE_CLERK_PUBLISHABLE_KEY}>
-  <ConvexClerkProvider client={convex} useAuth={useStableAuth}>
-    <App />
-  </ConvexClerkProvider>
-</ClerkProvider>;
-```
-
-| Props | Renders |
-| --- | --- |
-| `client` is `null` or `undefined` | `children` alone (no provider). |
-| `clerk={false}` | `<ConvexProvider client={client}>`. |
-| otherwise | `<ConvexProviderWithClerk client={client} useAuth={useAuth}>`; `useAuth` defaults to `@clerk/clerk-react`'s. |
-
-`clerk` defaults to `true`. Render it inside `ClerkProvider` unless `clerk` is `false`. Types: `ConvexClerkProviderProps`, `ConvexClerkUseAuth`.
-
-### `parseClientEnv`
-
-```ts
-import { z } from "zod";
-import { parseClientEnv } from "@vvedantb/ui";
-
-export const clientEnv = parseClientEnv(import.meta.env, { z, viteEnv: "fallback" });
-// { VITE_CONVEX_URL: string; VITE_CLERK_PUBLISHABLE_KEY: string; VITE_ENV: "development" | "staging" | "production" }
-
-export const extensionEnv = parseClientEnv(import.meta.env, {
-  z,
-  viteEnv: false,
-  extend: { VITE_CLERK_SYNC_HOST: z.string().url() },
-});
-```
-
-The schema is `z.object({ VITE_CONVEX_URL: z.string().min(1), VITE_CLERK_PUBLISHABLE_KEY: z.string().min(1), VITE_ENV: z.enum(["development", "staging", "production"]), ...extend })`, built with your `z` (zod 3.25+ or 4; the package never imports zod at runtime). Only the schema's keys are read from `rawEnv`. Failure throws the `ZodError` from `.parse`.
-
-| `viteEnv` | `VITE_ENV` |
-| --- | --- |
-| `"strict"` (default) | Must be one of `VITE_ENV_NAMES`. |
-| `"fallback"` | Any other value, or none, becomes `"development"` before parsing. |
-| `false` | Not in the schema or the result. |
-
-Types: `ClientEnv`, `ClientEnvWithoutViteEnv`, `ClientEnvOptions`, `ClientEnvSource`, `ViteEnvMode`, `ViteEnvName`.
-
-### `useEnsureUser`
-
-```tsx
-function EnsureUser() {
-  useEnsureUser(api.users.ensureUserExists);
-  return null;
-}
-```
-
-Calls `mutation({})` every time `useConvexAuth().isAuthenticated` becomes `true` (once on mount if already signed in), and logs a rejection with `console.error`. Needs a Convex auth provider above it (`ConvexClerkProvider` with Clerk on). Pair it with `ensureUser` from `@vvedantb/server`. Type: `EnsureUserMutation`.
-
-Tests: `app/tests/convex/` ports each app's copy and runs it beside the helper (env with zod 4 and zod 3.25; provider variants; ensure-user calls over auth sequences). `app/tests-node/convex-esm.test.mjs` loads the helpers in plain Node.

package/tokens/README.md

@@ -1,122 +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, the radius utilities `rounded-surface` (`clamp(0.75rem, var(--radius), 1rem)`), `rounded-menu-item` (`min(var(--radius), 0.5rem)`) and `rounded-control` (`min(var(--radius), 0.625rem)`) (0.7.1; `rounded-surface` was in `utilities.css` before), `*` border and `body` defaults. From 0.16.3 `--field-radius` (`rounded-field`) is `min(var(--radius), 0.625rem)`, the same cap as `rounded-control` (was `1.25rem`). 0.7.2 adds `--sidebar-accent` / `sidebar-accent` (sidebar nav row fill: light `var(--surface-tertiary)`, dark `oklch(22.64% 0 0)`). 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. From 0.15.0 it imports `clear-input.css`, `scrollbar-thin.css` and `motion.css`, sets the `--modal-*` and `--tabs-*` motion variables on `:root`, and defines `.glass-panel-strong` (`var(--overlay)`) and `.sidebar-section-label`. |
-| `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-tabs` container (0.15.0), `.t-tab` with its press scale, 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`, `reveal-on-hover`, `motion-press`, `motion-base`, `motion-emphasized` and `scrollbar-none`. The motion utilities read `--motion-fast`, `--motion-base`, `--motion-ease-out` and `--motion-ease-emphasized`, with defaults in the utility. `rounded-surface` moved to `tokens.css` in 0.7.1. |
-| `@vvedantb/ui/tokens/css/scrollbar-thin.css` | `src/css/scrollbar-thin.css` | `.scrollbar-thin` (`@layer utilities`, always emitted). Imported by `tokens.css` from 0.15.0. |
-| `@vvedantb/ui/tokens/css/clear-input.css` | `src/css/clear-input.css` | `ClearInput` layers (`.t-clear*`) and the `--clear-*` / `--glow-*` timings. Imported by `tokens.css`. From 0.15.1 the layers clip in `.t-clear-clip`, so `.t-clear` keeps the focus ring, and the placeholder layer only shows during `.is-clearing`. |
-| `@vvedantb/ui/tokens/css/motion.css` | `src/css/motion.css` | `.ui-page-enter`, `.ui-enter`, `.ui-enter-up`, `.ui-stagger`, their keyframes and reduced-motion rules, and the `html[data-page-motion="off"]` overrides for `PageMotionProvider`. Imported by `tokens.css`. |
-| `@vvedantb/ui/tokens/css/type-scale.css` | `src/css/type-scale.css` | The `text-*` scale (`3xs` 10px to `7xl` 72px, with `2xs` 11px and `2sm` 13px) as `@theme` variables. Each tier has its own line height and letter-spacing: positive below 14px (`+0.01em` at 10-11px), `0` at `sm`, negative above (`-0.03em` at `7xl`). Imported by `tokens.css`. |
-| `@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` (both `min(var(--radius), 0.625rem)` from 0.16.3), the same three radius utilities as `tokens.css` and `.glass-panel-strong` (solid `--popover` from 0.15.0). Import it **or** `tokens.css`, never both. |
-| `@vvedantb/ui/tokens/css/index.css` | `src/css/index.css` | base + dialog + modal + tabs + tabs-pills + utilities + animations + nav-icons, for new CSS-first apps (`tokens.css` brings scrollbar-thin). |
-| `@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... */
-/* no --modal-* / --tabs-* needed: tokens.css sets them */
-```
-
-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` | tokens.css (0.15.0), or app `:root` with the compat file |
-| `tabs.css` | `--tabs-dur`, `--tabs-ease` (tokens.css, or app `:root` with the compat file); `--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); optional `--motion-*` | Tailwind |
-| `scrollbar-thin.css` | `--scrollbar` | tokens.css or the app theme |
-| `clear-input.css`, `motion.css` | none (own `:root` defaults) | |
-| `type-scale.css` | none (own `@theme` values) | |
-| `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`, `clear-input.css`, `motion.css`, `utilities.css`, `dialog.css`, `modal.css` and `tabs.css` need no `tokens.css` (`modal.css` and `tabs.css` then need the `--modal-*` / `--tabs-*` values on the app `:root`). `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` |
-
-From 0.15.0 the files that moved out of the apps take `:root` variables too. Every rule is in a Tailwind layer, so an app rule for the same selector (unlayered, or later in the same layer) also wins.
-
-| File | Property | Default |
-| --- | --- | --- |
-| `tokens.css` | `--modal-open-dur`, `--modal-close-dur` | `180ms`, `120ms` |
-| `tokens.css` | `--modal-scale`, `--modal-scale-close` | `0.96`, `0.96` |
-| `tokens.css` | `--modal-ease`, `--tabs-ease` | `cubic-bezier(0.22, 1, 0.36, 1)` |
-| `tokens.css` | `--tabs-dur` | `200ms` |
-| `tokens.css` | `--sidebar-section-label-mix`, `--sidebar-section-label-hover-mix` | `55%`, `80%` (share of `--muted`) |
-| `scrollbar-thin.css` | `--scrollbar-thin-rest`, `--scrollbar-thin-hover` | `40%`, `80%` (share of `--scrollbar`) |
-| `clear-input.css` | `--clear-dur`, `--clear-out-dur`, `--clear-in-dur` | `1000ms`, `400ms`, `400ms` |
-| `clear-input.css` | `--clear-out-fly`, `--clear-in-fly` | `12px`, `12px` |
-| `clear-input.css` | `--clear-out-ease`, `--clear-in-ease` | `cubic-bezier(0.22, 1, 0.36, 1)` |
-| `clear-input.css` | `--glow-delay`, `--glow-peak-at`, `--glow-opacity`, `--glow-spread` | `50ms`, `0.15`, `0.85`, `1.5` |
-| `motion.css` | `--ui-enter-ease` | `cubic-bezier(0.22, 1, 0.36, 1)` |
-| `motion.css` | `--ui-page-enter-dur`, `--ui-enter-dur`, `--ui-enter-up-dur` | `160ms`, `200ms`, `220ms` |
-| `motion.css` | `--ui-stagger-step` | `40ms` (children 1 to 8) |
-
-## 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.