@vvedantb/ui 0.35.0 → 0.37.0

package/README.md

@@ -7,6 +7,8 @@ Shared React 19 web UI. Source-exported: no build step.
 | `@vvedantb/ui` | The main JavaScript entry. Primitives (Radix-based), AI elements, audio (`playChime`, `useReplyChime`, `playTone`), `toast` and `SonnerToaster`, the composer (`InputArea`, deprecated 0.3 `Composer`), shell (`SidebarHeader`, `SidebarUpgradeCard`, `PillTabs`, `SessionsHoverCard`, and the app shell: `AppShell`, `AppSidebar`, `SidebarRail`, `RailTile`, `SidebarPanel`, `SidebarAccountMenu`, `SignOutDialog` and related helpers), app helpers (confirm skip, update watcher, settings chrome, `useStableAuth`, and from 0.8.0 `createThemeProvider`, `createPageTitleContext`, `PageMotionProvider` and `formatCompactRelativeTime`), marketing pieces from 0.9.0 (`createLandingKit` and the `Landing*` parts, `SiteFooter`, `PricingModal`), animated nav icons from 0.11.0 (`MemoryIcon`, `BoardIcon`, ... and `NavIconBase`; `SettingsIcon` `variant` from 0.12.0), artifact viewers from 0.13.0 (`ArtifactFrame`, `ArtifactList`, `ArtifactViewer`, ...), date pickers from 0.14.0 (`Calendar`, `DatePicker`, `DateTimePicker`, `MonthPicker`), `cn`, and the native tokens `tokens` and `Tokens`. See `app/README.md` in the repository for the app helpers. |
 | `@vvedantb/ui/client` | The root without `@vvedantb/server`, convex or Clerk, for Chrome extensions (0.28.0). Leaves out the artifact viewers, `ConvexClerkProvider`, `useStableAuth`, `createUseStableAuth`, `resetStableAuthSession` and `useEnsureUser`. See [Chrome extensions](#chrome-extensions-0280). |
 | `@vvedantb/ui/brand` | App icons (`Icon*`, `APP_ICONS`), `AppWordmark`, deprecated `AppMark`, raw SVG strings and `FAMILY_APPS`. Also in the root and `/client`. |
+| `@vvedantb/ui/logos` | Third-party brand logos (`GitHubIcon`, `GoogleDriveIcon`, `SlackIcon`, `ClaudeIcon`, `VercelIcon`, ...) and `LogoProps` (0.36.0). Also in the root and `/client`. See [Third-party logos](#third-party-logos-0360). |
+| `@vvedantb/ui/icons/animated` | Motion-driven animated SVG icons (`AnimatedNotificationIcon`, `MorphingMenuIcon`, `AnimatedBellIcon`, ...) (0.36.0). Not in the root or `/client`. Needs the optional `motion` peer. See [Animated SVG icons](#animated-svg-icons-0360). |
 | `@vvedantb/ui/tokens` | `tokens.css`: colour, radius, shadow, ease and font tokens for Tailwind v4. CSS. |
 | `@vvedantb/ui/tokens/tokens.css` | Same file as `@vvedantb/ui/tokens`. CSS. |
 | `@vvedantb/ui/tokens/css/*.css` | `index`, `base`, `dialog`, `modal`, `tabs`, `tabs-pills`, `utilities`, `scrollbar-thin`, `clear-input`, `motion`, `animations`, `nav-icons`, `compat-shadcn-rgb`, `border-beam` (opt-in, for `BorderBeam`), `markdown` (opt-in, for `Markdown`). CSS. `tokens.css` imports `scrollbar-thin`, `clear-input` and `motion`. |
@@ -888,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
@@ -896,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
 
@@ -1155,6 +1176,47 @@ Props (type `IconProps`; all optional):
 
 Other SVG props (`id`, `data-*`, handlers, `ref`) go to the svg. On group hover the svg scales to 1.15 (the first six icons, spring ease) or 1.12 (the rest). `NavIconBase` is the shared svg wrapper, for icons drawn in the same style. The stylesheet has no reduced-motion override.
 
+## Third-party logos (0.36.0)
+
+Full-colour vendor logos, separate from the family marks in `@vvedantb/ui/brand`. Import from `@vvedantb/ui/logos` (also in the root and `/client`):
+
+```tsx
+import { GitHubIcon, GoogleDriveIcon, SlackIcon } from "@vvedantb/ui/logos";
+
+<GoogleDriveIcon />                      // 24px, aria-hidden
+<SlackIcon size={16} title="Slack" />    // role="img", aria-label and <title>
+<GitHubIcon className="text-foreground" /> // monochrome marks follow currentColor
+```
+
+| Logo | Colour |
+| --- | --- |
+| `ChromeIcon`, `ConvexIcon`, `DropboxIcon`, `FigmaIcon`, `GmailIcon`, `GoogleDriveIcon`, `LinearIcon`, `NotionIcon`, `OneDriveIcon`, `SharePointIcon`, `SlackIcon` | Brand colours |
+| `ClaudeIcon`, `CursorIcon`, `GitHubIcon`, `VercelIcon` | `currentColor` |
+
+Props (`LogoProps`): `size` (number or CSS length, default `24`, sets width and height), `title` (accessible name: the svg becomes `role="img"` with `aria-label` and a `<title>`; without `title` or `aria-label` it is `aria-hidden`), and any other SVG prop (`className`, `style`, `data-*`, `ref`). `OneDriveIcon` and `SharePointIcon` use `useId` for their gradient ids, so several on one page do not clash. Paths are the vendors' own: do not recolour the full-colour marks. For the AI provider marks in model pickers, keep using `ProviderIcon`.
+
+## Animated SVG icons (0.36.0)
+
+Motion-driven icons, on their own entry so apps that do not use them do not load them. They are not in the root or `/client`.
+
+```tsx
+import { AnimatedNotificationIcon, MorphingMenuIcon } from "@vvedantb/ui/icons/animated";
+```
+
+They need the optional `motion` peer and animate through `m.*`, so they need the app's `MotionProvider` (or its own `LazyMotion`). Without it they render their resting frame. No stylesheet. All are decorative (`aria-hidden`) except `AnimatedProgress` (`role="progressbar"`) and `AnimatedCounter` (text).
+
+| Component | Props | What it does |
+| --- | --- | --- |
+| `AnimatedNotificationIcon` | `type` (`NotificationIconType`: `success`, `warning`, `error`, `info`), `size` (20), `color`, `className` | On mount the check draws itself, the warning shakes, the error pops in, the info icon rises. Colour: `--color-success`, `--color-warning`, `--color-danger`, `--color-primary` (`info`); `color` overrides. |
+| `AnimatedBellIcon` | `size` (32), `muted` (`true`), `className` | Bell draws itself, then swings every 4.5 s. `muted` adds the slash. |
+| `AnimatedKeyIcon` | `size` (48), `className` | Bolt draws itself, sparkles twinkle, soft pulse. For empty API-key states. |
+| `MorphingMenuIcon` | `isOpen`, `size` (20), `className` | Three bars morph to an X. `data-state="open"` or `"closed"`. Label the button and set its `aria-expanded`. |
+| `MorphingMicIcon` | `isListening`, `size` (32), `strokeWidth` (2), `className` | Cross-fades a microphone and a stop square. |
+| `PulsingRings` | `size`, `ringCount` (3), `color` (`var(--color-danger)`), `active` (`true`), `className` | Staggered expanding rings, absolutely centred in a `relative` parent. `active={false}` renders nothing. |
+| `AnimatedStatusDot` | `phase` (`StatusDotPhase`: `idle`, `listening`, `thinking`, `speaking`, `error`), `size` (10; svg is 3x), `className` | Ripples while listening, glow while listening or speaking. |
+| `AnimatedProgress` | `value` (0 to 100, clamped), `height` (4), `showGradient` (`true`), `label`, `className` | Spring fill in `--color-primary` on `--color-surface-secondary`, with a moving gradient and shimmer. |
+| `AnimatedCounter` | `value`, `duration` (1 s), `formatValue`, `animateOnView` (`true`), `className` | Springs from 0 to `value` once in view. `tabular-nums`. The spring runs without `LazyMotion`. |
+
 ## Artifact viewers (0.13.0)
 
 Web viewers for artifacts: standalone HTML, Markdown, SVG, code or typed JSON (quiz, flashcards) documents with per-user state. The pure core (schemas, state limits and ops, the document wrapper, the guest bridge) lives in `@vvedantb/server` (see its `docs/artifacts.md`); install `@vvedantb/server` 0.6.1 or later next to this package. The components hold no data: rows come in through props and changes leave through callbacks, so any backend works.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.35.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), 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.",
+  "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",
   "publishConfig": {
     "access": "public"
@@ -46,6 +46,14 @@
       "types": "./src/brand/index.ts",
       "default": "./src/brand/index.ts"
     },
+    "./logos": {
+      "types": "./src/logos/index.ts",
+      "default": "./src/logos/index.ts"
+    },
+    "./icons/animated": {
+      "types": "./src/icons/animated/index.ts",
+      "default": "./src/icons/animated/index.ts"
+    },
     "./client": {
       "types": "./src/client.ts",
       "default": "./src/client.ts"
@@ -73,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",
@@ -174,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",
@@ -198,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": {
@@ -219,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,
@@ -399,6 +409,9 @@ export { useHeldResult } from "../app/src/convex/useHeldResult";
 // Family app marks (Icon* components, deprecated AppMark and raw SVG strings for favicons).
 export * from "./brand";
 
+// Third-party brand logos (`GitHubIcon`, `SlackIcon`, `ClaudeIcon`, ...). Also `@vvedantb/ui/logos`.
+export * from "./logos";
+
 // Native tokens (JS values that match tokens.css).
 export { tokens } from "../tokens/src/native";
 export type { Tokens } from "../tokens/src/native";

package/src/icons/animated/animated-bell-icon.tsx

@@ -0,0 +1,68 @@
+import { m } from "motion/react";
+
+export interface AnimatedBellIconProps {
+  /** Width and height in px. Default `32`. */
+  size?: number;
+  className?: string;
+  /** Draw the mute slash. Default `true` (the empty-notifications state). */
+  muted?: boolean;
+}
+
+/**
+ * Bell that draws itself, then swings every few seconds with a moving
+ * clapper. For empty notification states. Uses `currentColor`. Decorative (`aria-hidden`).
+ */
+export function AnimatedBellIcon({ size = 32, className, muted = true }: AnimatedBellIconProps) {
+  return (
+    <m.svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={className}
+      aria-hidden="true"
+      initial={{ rotate: 0 }}
+      animate={{ rotate: [0, 10, -10, 8, -8, 5, -5, 0] }}
+      transition={{ duration: 1.5, ease: "easeInOut", repeat: Infinity, repeatDelay: 3 }}
+      style={{ transformOrigin: "top center" }}
+    >
+      {/* Body */}
+      <m.path
+        d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"
+        initial={{ pathLength: 0 }}
+        animate={{ pathLength: 1 }}
+        transition={{ duration: 0.6, ease: "easeOut" }}
+      />
+      {/* Bottom curve */}
+      <m.path
+        d="M13.73 21a2 2 0 0 1-3.46 0"
+        initial={{ pathLength: 0 }}
+        animate={{ pathLength: 1 }}
+        transition={{ duration: 0.3, delay: 0.4 }}
+      />
+      {/* Mute slash */}
+      {muted ? (
+        <m.path
+          d="M2 2l20 20"
+          data-slot="mute-slash"
+          initial={{ pathLength: 0 }}
+          animate={{ pathLength: 1 }}
+          transition={{ duration: 0.3, delay: 0.6 }}
+        />
+      ) : null}
+      {/* Clapper */}
+      <m.circle
+        cx="12"
+        cy="17"
+        r="0.5"
+        fill="currentColor"
+        animate={{ x: [0, 1, -1, 0.5, -0.5, 0] }}
+        transition={{ duration: 1.5, ease: "easeInOut", repeat: Infinity, repeatDelay: 3 }}
+      />
+    </m.svg>
+  );
+}

package/src/icons/animated/animated-counter.tsx

@@ -0,0 +1,45 @@
+import { m, useInView, useSpring, useTransform } from "motion/react";
+import { useEffect, useRef } from "react";
+import { cn } from "../../utils/cn";
+
+export interface AnimatedCounterProps {
+  /** Target value to count up to. */
+  value: number;
+  /** Rough animation length in seconds (scales the spring stiffness). Default `1`. */
+  duration?: number;
+  className?: string;
+  /** Formats the displayed number. Default: rounded, `toLocaleString()`. */
+  formatValue?: (value: number) => string;
+  /** Wait until the counter scrolls into view. Default `true`. */
+  animateOnView?: boolean;
+}
+
+const defaultFormat = (v: number) => Math.round(v).toLocaleString();
+
+/**
+ * Number that springs up from 0 to `value` (`tabular-nums`). Changes to
+ * `value` spring from the current number. The spring runs without the app's
+ * `LazyMotion`.
+ */
+export function AnimatedCounter({
+  value,
+  duration = 1,
+  className,
+  formatValue = defaultFormat,
+  animateOnView = true,
+}: AnimatedCounterProps) {
+  const ref = useRef<HTMLSpanElement>(null);
+  const isInView = useInView(ref, { once: true, margin: "-50px" });
+  const springValue = useSpring(0, { stiffness: 100 / duration, damping: 30, restDelta: 0.01 });
+  const displayValue = useTransform(springValue, (v) => formatValue(v));
+
+  useEffect(() => {
+    if (!animateOnView || isInView) springValue.set(value);
+  }, [value, springValue, animateOnView, isInView]);
+
+  return (
+    <m.span ref={ref} className={cn("tabular-nums", className)}>
+      {displayValue}
+    </m.span>
+  );
+}

package/src/icons/animated/animated-key-icon.tsx

@@ -0,0 +1,79 @@
+import { m } from "motion/react";
+
+export interface AnimatedKeyIconProps {
+  /** Width and height in px. Default `48`. */
+  size?: number;
+  className?: string;
+}
+
+function Sparkle({ x, y, delay, size = 3 }: { x: number; y: number; delay: number; size?: number }) {
+  return (
+    <g transform={`translate(${x}, ${y})`}>
+      {/* Four-pointed star */}
+      <m.path
+        d={`M0 -${size} L0 ${size} M-${size} 0 L${size} 0`}
+        stroke="currentColor"
+        strokeWidth="1"
+        strokeLinecap="round"
+        initial={{ scale: 0, opacity: 0, rotate: 0 }}
+        animate={{ scale: [0, 1, 0], opacity: [0, 1, 0], rotate: [0, 45, 90] }}
+        transition={{ duration: 1.2, delay, repeat: Infinity, repeatDelay: 2, ease: "easeInOut" }}
+      />
+    </g>
+  );
+}
+
+/**
+ * Lightning-bolt "key" that draws itself, with twinkling sparkles and a soft
+ * pulse. For empty API-key states. Uses `currentColor`. Decorative (`aria-hidden`).
+ */
+export function AnimatedKeyIcon({ size = 48, className }: AnimatedKeyIconProps) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 48 48"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={className}
+      aria-hidden="true"
+    >
+      <Sparkle x={8} y={10} delay={0} size={2.5} />
+      <Sparkle x={40} y={12} delay={0.4} size={2} />
+      <Sparkle x={36} y={38} delay={0.8} size={2.5} />
+      <Sparkle x={10} y={36} delay={1.2} size={2} />
+
+      {/* Bolt with a gentle pulse */}
+      <m.g
+        initial={{ scale: 1 }}
+        animate={{ scale: [1, 1.02, 1] }}
+        transition={{ duration: 2, repeat: Infinity, ease: "easeInOut" }}
+      >
+        <m.path
+          d="M26 6L14 26h8l-4 16 16-22h-9l5-14z"
+          strokeWidth="1.5"
+          fill="none"
+          initial={{ pathLength: 0, opacity: 0 }}
+          animate={{ pathLength: 1, opacity: 1 }}
+          transition={{ duration: 0.8, ease: "easeOut" }}
+        />
+      </m.g>
+
+      {/* Glow pulse behind */}
+      <m.circle
+        cx="24"
+        cy="24"
+        r="16"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="0.5"
+        initial={{ scale: 0.9, opacity: 0 }}
+        animate={{ scale: [0.9, 1.1, 0.9], opacity: [0, 0.15, 0] }}
+        transition={{ duration: 3, repeat: Infinity, ease: "easeInOut" }}
+      />
+    </svg>
+  );
+}

package/src/icons/animated/animated-notification-icon.tsx

@@ -0,0 +1,202 @@
+import { m } from "motion/react";
+
+export type NotificationIconType = "success" | "warning" | "error" | "info";
+
+export interface AnimatedNotificationIconProps {
+  type: NotificationIconType;
+  /** Width and height in px. Default `20`. */
+  size?: number;
+  /** Stroke colour. Default: the type's token (`--color-success`, `--color-warning`, `--color-danger`, `--color-primary` for `info`). */
+  color?: string;
+  /** Class on the wrapping `span`. */
+  className?: string;
+}
+
+const TYPE_COLORS: Record<NotificationIconType, string> = {
+  success: "var(--color-success)",
+  warning: "var(--color-warning)",
+  error: "var(--color-danger)",
+  info: "var(--color-primary)",
+};
+
+interface PartProps {
+  size: number;
+  color: string;
+}
+
+function SuccessIcon({ size, color }: PartProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true">
+      {/* Circle */}
+      <m.circle
+        cx="12"
+        cy="12"
+        r="10"
+        stroke={color}
+        strokeWidth="1.5"
+        fill="none"
+        initial={{ pathLength: 0, opacity: 0 }}
+        animate={{ pathLength: 1, opacity: 1 }}
+        transition={{ duration: 0.4, ease: "easeOut" }}
+      />
+      {/* Checkmark draws itself */}
+      <m.path
+        d="M8 12l2.5 2.5L16 9"
+        stroke={color}
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        fill="none"
+        initial={{ pathLength: 0 }}
+        animate={{ pathLength: 1 }}
+        transition={{ duration: 0.3, delay: 0.3, ease: "easeOut" }}
+      />
+    </svg>
+  );
+}
+
+function WarningIcon({ size, color }: PartProps) {
+  return (
+    <m.svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      aria-hidden="true"
+      initial={{ rotate: 0 }}
+      animate={{ rotate: [0, -5, 5, -3, 3, 0] }}
+      transition={{ duration: 0.5, delay: 0.2 }}
+    >
+      {/* Triangle */}
+      <m.path
+        d="M12 2L2 20h20L12 2z"
+        stroke={color}
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        fill="none"
+        initial={{ pathLength: 0, opacity: 0 }}
+        animate={{ pathLength: 1, opacity: 1 }}
+        transition={{ duration: 0.4, ease: "easeOut" }}
+      />
+      {/* Exclamation line */}
+      <m.path
+        d="M12 9v4"
+        stroke={color}
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        initial={{ pathLength: 0 }}
+        animate={{ pathLength: 1 }}
+        transition={{ duration: 0.2, delay: 0.3 }}
+      />
+      {/* Exclamation dot */}
+      <m.circle
+        cx="12"
+        cy="17"
+        r="1"
+        fill={color}
+        initial={{ scale: 0 }}
+        animate={{ scale: 1 }}
+        transition={{ duration: 0.15, delay: 0.45, type: "spring" }}
+      />
+    </m.svg>
+  );
+}
+
+function ErrorIcon({ size, color }: PartProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true">
+      {/* Circle */}
+      <m.circle
+        cx="12"
+        cy="12"
+        r="10"
+        stroke={color}
+        strokeWidth="1.5"
+        fill="none"
+        initial={{ scale: 0.8, opacity: 0 }}
+        animate={{ scale: 1, opacity: 1 }}
+        transition={{ duration: 0.3, ease: "easeOut" }}
+      />
+      {/* X, first stroke */}
+      <m.path
+        d="M15 9l-6 6"
+        stroke={color}
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        initial={{ pathLength: 0 }}
+        animate={{ pathLength: 1 }}
+        transition={{ duration: 0.2, delay: 0.2 }}
+      />
+      {/* X, second stroke */}
+      <m.path
+        d="M9 9l6 6"
+        stroke={color}
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        initial={{ pathLength: 0 }}
+        animate={{ pathLength: 1 }}
+        transition={{ duration: 0.2, delay: 0.3 }}
+      />
+    </svg>
+  );
+}
+
+function InfoIcon({ size, color }: PartProps) {
+  return (
+    <m.svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      aria-hidden="true"
+      initial={{ y: 2, opacity: 0 }}
+      animate={{ y: 0, opacity: 1 }}
+      transition={{ duration: 0.3, ease: "easeOut" }}
+    >
+      {/* Circle */}
+      <circle cx="12" cy="12" r="10" stroke={color} strokeWidth="1.5" fill="none" />
+      {/* Dot */}
+      <m.circle
+        cx="12"
+        cy="8"
+        r="1"
+        fill={color}
+        initial={{ scale: 0 }}
+        animate={{ scale: 1 }}
+        transition={{ duration: 0.2, delay: 0.2, type: "spring" }}
+      />
+      {/* Line */}
+      <m.path
+        d="M12 12v4"
+        stroke={color}
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        initial={{ pathLength: 0 }}
+        animate={{ pathLength: 1 }}
+        transition={{ duration: 0.2, delay: 0.3 }}
+      />
+    </m.svg>
+  );
+}
+
+const PARTS: Record<NotificationIconType, (props: PartProps) => React.JSX.Element> = {
+  success: SuccessIcon,
+  warning: WarningIcon,
+  error: ErrorIcon,
+  info: InfoIcon,
+};
+
+/**
+ * Notification status icon that animates on mount: the check draws itself,
+ * the warning shakes, the error pops in and the info icon rises. Decorative
+ * (`aria-hidden`); put the message text beside it.
+ */
+export function AnimatedNotificationIcon({ type, size = 20, color, className }: AnimatedNotificationIconProps) {
+  const Part = PARTS[type];
+  return (
+    <span className={className} data-type={type}>
+      <Part size={size} color={color ?? TYPE_COLORS[type]} />
+    </span>
+  );
+}