From eb84d8ede8417bb15cbf3aefea4f329218b6a857 Mon Sep 17 00:00:00 2001
From: myelinated-wackerow
 <263208946+myelinated-wackerow@users.noreply.github.com>
Date: Mon, 4 May 2026 13:56:46 -0700
Subject: [PATCH 1/7] feat(skills): add design-system skill

Establishes .claude/skills/design-system/ as the canonical knowledge
base for UI work in this repo. Provides component choices, design
tokens, RTL/i18n rules, server/client guidance, accessibility, and
the "use a variant, not a new component" pattern. Designed for agent
context but useful as developer reference.

Skill structure follows the agentskills.io specification: SKILL.md
entry point plus references/ for progressive disclosure. Total ~3000
lines across 14 files.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>
---
 .claude/skills/design-system/SKILL.md         | 126 ++++
 .../skills/design-system/references/a11y.md   | 104 ++++
 .../references/canonical-imports.md           | 318 ++++++++++
 .../references/card-walkthrough.md            | 123 ++++
 .../references/cleanup-playbook.md            | 304 +++++++++
 .../design-system/references/components.md    | 579 ++++++++++++++++++
 .../design-system/references/gotchas.md       | 179 ++++++
 .../design-system/references/i18n-rtl.md      | 229 +++++++
 .../references/new-component-checklist.md     | 226 +++++++
 .../references/page-hero-walkthrough.md       | 124 ++++
 .../references/server-vs-client.md            | 102 +++
 .../references/spacing-typography.md          | 170 +++++
 .../skills/design-system/references/tokens.md | 241 ++++++++
 .../references/variant-vs-new.md              | 181 ++++++
 14 files changed, 3006 insertions(+)
 create mode 100644 .claude/skills/design-system/SKILL.md
 create mode 100644 .claude/skills/design-system/references/a11y.md
 create mode 100644 .claude/skills/design-system/references/canonical-imports.md
 create mode 100644 .claude/skills/design-system/references/card-walkthrough.md
 create mode 100644 .claude/skills/design-system/references/cleanup-playbook.md
 create mode 100644 .claude/skills/design-system/references/components.md
 create mode 100644 .claude/skills/design-system/references/gotchas.md
 create mode 100644 .claude/skills/design-system/references/i18n-rtl.md
 create mode 100644 .claude/skills/design-system/references/new-component-checklist.md
 create mode 100644 .claude/skills/design-system/references/page-hero-walkthrough.md
 create mode 100644 .claude/skills/design-system/references/server-vs-client.md
 create mode 100644 .claude/skills/design-system/references/spacing-typography.md
 create mode 100644 .claude/skills/design-system/references/tokens.md
 create mode 100644 .claude/skills/design-system/references/variant-vs-new.md

diff --git a/.claude/skills/design-system/SKILL.md b/.claude/skills/design-system/SKILL.md
new file mode 100644
index 00000000000..2e523b7de19
--- /dev/null
+++ b/.claude/skills/design-system/SKILL.md
@@ -0,0 +1,126 @@
+---
+name: design-system
+description: Use when building, refactoring, or styling any UI in the ethereum.org Next.js site (`src/components/`, `app/`, `src/styles/`, `public/content/`, or any `.tsx`/`.mdx`/`.css` change that affects the rendered UI). Provides canonical component choices, design tokens, RTL/i18n rules, server/client guidance, and the "use a variant, not a new component" pattern for the project's Tailwind v4 + Radix + shadcn-style design system.
+---
+
+# ethereum.org Design System
+
+Tailwind v4 (CSS-first config, no `tailwind.config.ts`) + React 18 / Next.js App Router + Radix UI primitives + shadcn-style component layer. Tokens live in CSS. Read this file fully on activation; pull from `references/` only when the listed trigger applies.
+
+## The Core Habit: Reuse Over Reinvent
+
+The single highest-leverage habit for keeping this codebase consistent: **when you need new UI, look for a primitive or variant first, only invent if nothing fits.** Most "new component" instincts are actually "new variant" instincts in disguise.
+
+Before you write any UI code, ask:
+- Is there a primitive that already does this? (`Card`, `Button`, `Alert`, `Tag`, `Hero/*`)
+- Is the difference small enough to express as a *variant* on an existing primitive?
+- Can I compose existing primitives instead of inlining a long Tailwind class chain?
+
+If you find yourself writing `flex items-center gap-X rounded-Y border bg-... p-Z` for a card-like thing, you're reinventing `<Card>`. If you write `<p className="text-4xl font-bold">N</p>` for a stat, you're reinventing `<BigNumber>`. If you write `<div className="text-5xl font-bold">Title</div>`, you're reinventing `<h1>` (which is already styled by `base.css`). **Compose, don't inline.**
+
+When the existing primitive doesn't quite fit, the answer is usually "add a variant," not "create a new file." See `references/variant-vs-new.md`.
+
+## Top Rules
+
+1. **No raw `<a>` or `<button>`.** Use `<Button>`/`<ButtonLink>` from `@/components/ui/buttons/Button` and `InlineLink`/`BaseLink`/`LinkWithArrow` from `@/components/ui/Link`. These primitives handle event tracking, external-link safety, locale routing, and focus rings.
+2. **No raw color values.** Use semantic tokens (`text-body`, `bg-background`, `border-border`, `text-primary`). Hex literals and `rgb()` calls bypass dark mode.
+3. **Prefer adding a variant** to an existing primitive over creating a new component. Card, Button, Alert, Tag are the most common targets.
+4. **Server Components by default.** Only `"use client"` when you need state, effects, browser APIs, or inline event handlers.
+5. **All text is translatable.** `getTranslations` (server) or `useTranslations` (client) from `next-intl`. Never hard-code user-facing English.
+6. **Logical CSS for direction.** Use `ms-`/`me-`/`ps-`/`pe-`/`inset-s-`/`inset-e-`/`border-s`/`border-e`/`text-start`/`text-end`. The site supports Arabic and Urdu (RTL). Hard-coded `left-`/`right-`/`ml-`/`mr-`/`pl-`/`pr-` breaks RTL.
+7. **Locale-aware formatters.** `numberFormat()` from `@/lib/utils/numbers`, `dateTimeFormat()` from `@/lib/utils/date`. Never `toLocaleString` / `Intl.NumberFormat` directly.
+8. **`useRtlFlip()` for directional icons** (right-pointing arrows/chevrons). Or use `ChevronNext`/`ChevronPrev` from `@/components/Chevron`.
+9. **Markdown content goes through `MdComponents`.** The legacy `@/components/Card` (default export) is reserved for markdown shortcodes -- never import it from app code; use `@/components/ui/card`.
+10. **Storybook stories ship with new UI components.** No automated unit tests; Storybook + Chromatic + types are the verification layer.
+
+## Highest-Value Gotchas (read these now)
+
+These are landmines where the code looks reasonable but the pattern is wrong. The full set is in `references/gotchas.md`; these are the ones that come up most often.
+
+### Imports that look right but aren't
+
+- **Cards**: `import { Card } from "@/components/ui/card"` is canonical. **Not** `import Card from "@/components/Card"` (default export of that file is reserved for markdown shortcodes).
+- **Tooltips**: `import Tooltip from "@/components/Tooltip"` (mobile-aware, Matomo-tracked, scroll-close). **Not** `import { Tooltip } from "@/components/ui/tooltip"` (that's the bare Radix primitive used internally).
+- **Modals**: `import Modal from "@/components/ui/dialog-modal"` (default export, the high-level convenience) for typical modal needs. `@/components/ui/dialog` is the vanilla shadcn-style primitive for fine-grained Radix control. Same names exported from both files; **do not mix sources within a feature**.
+- **Heroes**: import from `@/components/Hero` (`ContentHero`, `SimpleHero`, `HubHero`, `MdxHero`, `HomeHero`). **Not** `@/components/PageHero` (deprecation track).
+
+### Stale shadcn token names that don't resolve
+
+`bg-popover`, `text-popover-foreground`, `bg-accent`, `text-accent-foreground`, `bg-muted`, `text-muted-foreground`, `focus:ring-ring`, `ring-offset-background` appear in `ui/select.tsx`, `ui/dialog.tsx`, `ui/dropdown-menu.tsx`, `ui/tabs.tsx` but are **NOT defined** in this project's tokens. They render incorrectly. If you touch these files, replace with project semantic tokens (`bg-background-highlight`, `text-body`, `bg-accent-a`, `text-body-medium`, etc.). Don't introduce new uses.
+
+### `useColorModeValue` is a Chakra leftover
+
+Used in 5 places. Don't introduce new uses. Use Tailwind `dark:` variant + semantic tokens.
+
+### Subtle component behaviors
+
+- `<Button isSecondary>` only takes effect on `outline` and `ghost` variants. Silent no-op on `solid`/`link`.
+- `<CardBanner fit="contain">` with a single `<Image>` child auto-clones it as a blurred backdrop. Pass two children and you lose this magic.
+- `LinkBox` requires a `LinkOverlay` somewhere inside; without it, the whole-card-clickable pattern doesn't work.
+- `commonControlClasses` in `ui/checkbox.tsx` is shared by `Switch` and `RadioGroup`. Editing it changes all three.
+
+### No `Heading` primitive -- use semantic tags
+
+`base.css` styles `<h1>`-`<h6>` with the right sizes and `font-bold`. Just write `<h1>Title</h1>`. Override the size class on the heading element when really needed (`<h2 className="text-4xl">`). Reinventing with `<div className="text-5xl font-bold">` loses semantics and screen-reader navigation.
+
+### One stray `toLocaleString` in `ui/chart.tsx:241`
+
+Don't add more. Use `numberFormat()`.
+
+## Quick "Where Do I Import From?" Cheatsheet
+
+| I need... | Import |
+|---|---|
+| Card | `import { Card, CardBanner, CardContent, CardTitle, CardParagraph } from "@/components/ui/card"` |
+| Modal/Dialog (typical) | `import Modal from "@/components/ui/dialog-modal"` (default export) |
+| Side sheet | `import { Sheet, ... } from "@/components/ui/sheet"` |
+| Tooltip | `import Tooltip from "@/components/Tooltip"` (NOT `@/components/ui/tooltip`) |
+| Button | `import { Button, ButtonLink } from "@/components/ui/buttons/Button"` |
+| Anchor (in prose) | `import InlineLink from "@/components/ui/Link"` (default) |
+| Anchor (CTA with arrow) | `import { LinkWithArrow } from "@/components/ui/Link"` |
+| Page hero | `import { ContentHero, SimpleHero, HubHero, MdxHero } from "@/components/Hero"` |
+| Inline alert | `import { Alert, AlertContent, AlertDescription } from "@/components/ui/alert"` |
+| Top-of-page banner | `import BannerNotification from "@/components/Banners/BannerNotification"` |
+| Big numeric display | `import BigNumber from "@/components/BigNumber"` |
+| Layout | `import { Stack, HStack, VStack, Flex, Center } from "@/components/ui/flex"` |
+| Number formatting | `import { numberFormat } from "@/lib/utils/numbers"` |
+| Date formatting | `import { dateTimeFormat } from "@/lib/utils/date"` |
+| RTL flip helper | `import { useRtlFlip } from "@/hooks/useRtlFlip"` |
+
+For full decision trees with all the look-alike landmines, see `references/canonical-imports.md`.
+
+## When to Load Each Reference
+
+Pull these in only when the trigger applies. Don't read them all upfront.
+
+- **`references/canonical-imports.md`** -- Load when you're about to import a component and aren't sure which file is canonical (Card, Modal, Tooltip, Hero, Tabs all have multiple plausible imports).
+- **`references/components.md`** -- Load when you need the full inventory: what each component is for, its variants, its canonical usage example.
+- **`references/tokens.md`** -- Load when you need to add a new token, define a gradient, choose a z-index, or are unsure which semantic token applies. Also: when working in `src/styles/`.
+- **`references/spacing-typography.md`** -- Load when laying out a page or section, deciding heading sizes, choosing spacing rhythms, or working with text density.
+- **`references/gotchas.md`** -- Load when you hit unexpected behavior in a primitive (auto-blur backdrop, slot-prop coupling, hidden client boundary, etc.) or want the long-tail confusion patterns beyond what's inline above.
+- **`references/variant-vs-new.md`** -- Load when you're tempted to create a new component file. Read this first to confirm whether a variant is the right answer.
+- **`references/cleanup-playbook.md`** -- Load when refactoring existing code that has anti-patterns (one-off styling, raw `<a>`/`<button>`, hex colors, hard-coded English, etc.). The "old pattern -> new pattern" map.
+- **`references/i18n-rtl.md`** -- Load when adding user-facing text, formatting numbers/dates, working with directional spacing, or writing translation keys.
+- **`references/server-vs-client.md`** -- Load when deciding whether to mark a component `"use client"`, structuring a page that mixes static and interactive parts, or refactoring across the SSR boundary.
+- **`references/a11y.md`** -- Load when adding interactive elements (modals, dropdowns, custom click targets), building forms, or working with images and headings.
+- **`references/card-walkthrough.md`** -- Load when starting any card-shaped UI work; an end-to-end worked example.
+- **`references/page-hero-walkthrough.md`** -- Load when starting a new page that needs a hero; an end-to-end worked example.
+- **`references/new-component-checklist.md`** -- Load before opening a PR for a new component. The pre-merge checklist.
+
+## Other Project Skills That May Apply
+
+- **`data-layer`** -- For data fetching/sources. UI work that needs data should compose with this.
+
+## Pre-Merge Smoke Test
+
+Before opening a PR for any UI work:
+
+- [ ] No raw `<a>` or `<button>`
+- [ ] No hard-coded colors (`#hex`, `rgb()`, `hsla()`); semantic tokens only
+- [ ] No `left-`/`right-`/`ml-`/`mr-`/`pl-`/`pr-` (use logical equivalents)
+- [ ] All user-facing strings translatable
+- [ ] `numberFormat()`/`dateTimeFormat()` for formatting (not native APIs)
+- [ ] Server Components wherever possible
+- [ ] New UI primitives have a `.stories.tsx`
+- [ ] Headings use `<h1>`-`<h6>` (not `<div className="text-5xl font-bold">`)
+- [ ] If introducing a new component, justify why it isn't a variant of an existing one
diff --git a/.claude/skills/design-system/references/a11y.md b/.claude/skills/design-system/references/a11y.md
new file mode 100644
index 00000000000..95bf8ce878d
--- /dev/null
+++ b/.claude/skills/design-system/references/a11y.md
@@ -0,0 +1,104 @@
+# Accessibility (Project-Specific)
+
+The agent already knows generic a11y rules (don't skip heading levels, label form inputs, etc.). This reference focuses on what's specific to this codebase.
+
+## Use Project Primitives -- They Handle a11y For You
+
+Most a11y in this codebase comes from "use the right primitive." The primitives wrap Radix UI which provides focus management, keyboard handling, ARIA semantics, and focus trap automatically:
+
+- **Modals**: `Modal` (`ui/dialog-modal`), `Dialog` (`ui/dialog`), `Sheet` (`ui/sheet`) -- focus trap and Escape-to-close are handled
+- **Dropdowns/Menus**: `DropdownMenu`, `Select`, `Popover`, `Tabs` -- arrow-key nav handled
+- **Accordion / Collapsible** -- `aria-expanded` handled
+- **Buttons**: `Button` -- focus-visible ring is built in
+- **Anchors**: `InlineLink` / `BaseLink` -- external-link `rel` attrs and screen-reader "(opens in new tab)" hint handled
+
+If you find yourself rolling custom focus management or ARIA wiring, stop and check whether a primitive already does it.
+
+## What's Easy to Get Wrong in This Codebase
+
+### `<div onClick>` is a `Button`
+
+Even if it's a small icon-only target, use `<Button variant="ghost" size="sm" aria-label="...">`. Don't reach for `<div role="button" tabIndex={0}>` -- the answer is almost always `Button`.
+
+Examples in current code that need fixing: `SideNavMobile.tsx:88-94`, `BoxGrid.tsx:55-69`.
+
+### Icon-only `Button` needs `aria-label`
+
+```tsx
+<Button variant="ghost" size="sm" aria-label="Close"><X /></Button>
+<ButtonLink href="/x" aria-label="Open in new tab"><ExternalLinkIcon /></ButtonLink>
+```
+
+Without it, screen readers announce nothing meaningful for the button.
+
+### `<aside>` is for tangentially-related content
+
+`<aside>` is being used for site-wide ribbons in `Banners/BannerNotification.tsx:15` and `TranslationBanner.tsx:57`. For announcement banners, `role="status"` (non-urgent) or `role="alert"` (urgent) is more appropriate.
+
+### Image `alt` text
+
+Most images on this site are decorative -- `alt=""` is correct and common. Hero images and topical illustrations rarely contain content; they're visual flourishes that aid scanning, not information sources. Especially given i18n constraints (text in images would need to be re-translated), images here almost never carry text or load-bearing content.
+
+**Default to `alt=""`** for hero/illustration/decorative images. Only describe the image when it actually conveys content the user couldn't otherwise get -- typically:
+
+- Diagrams in developer docs (e.g., the whitepaper, protocol explanations)
+- Charts with data the surrounding text doesn't restate
+- Images that are themselves the link target's primary content
+
+Historically this codebase has *over-used* descriptive alt tags on decorative images. Don't reinforce that pattern.
+
+### Custom collapse toggles need `aria-expanded` / `aria-controls`
+
+If you're rolling your own collapse (which you usually shouldn't -- use `Collapsible` or `Accordion`), don't forget `aria-expanded={isOpen}` and `aria-controls={panelId}`. Example currently missing it: `Codeblock.tsx:138`.
+
+### `Breadcrumb` current-page item
+
+`ui/breadcrumb.tsx:73-78` renders the current page as `<span role="link" aria-disabled="true">`. The `role="link"` is misleading -- the current page isn't a link. `aria-current="page"` is correct, but the `role="link"` should arguably be dropped. Aware-only; don't fix in passing.
+
+### `PersistentPanel` has custom focus management
+
+`@radix-ui/react-focus-scope` directly, not Radix Dialog. If you're working with `PersistentPanel`, be aware its focus story is custom -- don't add competing focus logic on top.
+
+## Form Validation
+
+When wiring an `Input` for error state, combine the visual `hasError` prop with ARIA:
+
+```tsx
+<Input
+  id="email"
+  type="email"
+  aria-invalid={hasError}
+  aria-describedby={hasError ? "email-error" : undefined}
+  hasError={hasError}
+/>
+{hasError && <p id="email-error" className="text-error">Invalid email</p>}
+```
+
+`hasError` styles the visual error state; the ARIA wiring handles screen readers.
+
+## Live Regions
+
+For dynamic content that should be announced:
+
+```tsx
+<div role="status" aria-live="polite">{message}</div>      // Non-urgent: "Saving..."
+<div role="alert" aria-live="assertive">{urgentMessage}</div>  // Urgent: "Error"
+```
+
+## One `<h1>` Per Page
+
+`MdxHero` and `HubHero` both render `<h1>`. Most React-page heroes do. Most markdown layouts also auto-render the page `title` from frontmatter as the `<h1>`.
+
+**Exception**: the `Static` layout does NOT auto-render `title` as `<h1>`. Pages using the `Static` layout must include `# Title` in the markdown body to provide the page heading. That's the only place `# Title` should appear in markdown -- on every other layout, a markdown `# Title` would create a duplicate `<h1>`.
+
+In `HubHero`, the eyebrow text is rendered as `<h1>` when `title` is set -- intentional (the eyebrow IS the page title for SEO).
+
+## Manual Verification
+
+No automated a11y tests in this codebase. Verify in Storybook or the dev server:
+
+- Tab through your UI -- can you reach everything?
+- Does focus return correctly after closing a modal/sheet?
+- Does VoiceOver / NVDA / TalkBack announce things sensibly?
+- Does the page work at 200% zoom?
+- Sufficient contrast in both light AND dark mode?
diff --git a/.claude/skills/design-system/references/canonical-imports.md b/.claude/skills/design-system/references/canonical-imports.md
new file mode 100644
index 00000000000..2a6b12b7819
--- /dev/null
+++ b/.claude/skills/design-system/references/canonical-imports.md
@@ -0,0 +1,318 @@
+# Canonical Imports
+
+When two or more imports look like they could solve the same problem, this document tells you which one is correct. Read it cold before reaching for any UI primitive.
+
+## Cards
+
+Three "Card" things exist. Most of the time you want the first.
+
+### Use `@/components/ui/card`
+
+```tsx
+import {
+  Card,
+  CardBanner,
+  CardContent,
+  CardFooter,
+  CardHeader,
+  CardParagraph,
+  CardTitle,
+} from "@/components/ui/card"
+```
+
+The canonical card primitive. Composable parts. If `href` is provided, the card auto-wraps in `BaseLink` and propagates a `group/link` class so descendant text can react to card-level hover.
+
+`CardBanner` props worth knowing:
+- `background`: `"accent-a" | "accent-b" | "accent-c" | "primary" | "body" | "none"` (default `body`)
+- `size`: `"full" | "thumbnail"` (default `full`)
+- `fit`: `"cover" | "contain"` (default `cover`)
+
+When `fit="contain"` and you pass a single `<Image>` child, the banner auto-clones it as a blurred backdrop behind a sharp foreground. Pass two children and you lose this magic.
+
+### Do NOT import `@/components/Card`
+
+```tsx
+// DON'T:
+import Card from "@/components/Card"
+```
+
+This is the legacy card, registered in `MdComponents` for the markdown `<Card>` shortcode. It is reserved for markdown rendering. Importing it from app code is a smell.
+
+### Domain-specific cards exist (`AppCard`, `Layer2ProductCard`, `EthPriceCard`, etc.)
+
+These are feature components. Don't reuse them outside their domain.
+
+## Modal / Dialog
+
+Three import paths. Pick by use case.
+
+### Default: `Modal` from `@/components/ui/dialog-modal`
+
+```tsx
+import Modal from "@/components/ui/dialog-modal"
+```
+
+The high-level convenience: title + content + optional action button, with `size: "md" | "lg" | "xl"` and `variant: "simulator" | "unstyled"`. This is what you want 90% of the time.
+
+```tsx
+<Modal
+  title="Are you sure?"
+  actionButton={{ label: "Confirm", onClick: handleConfirm }}
+  isOpen={isOpen}
+  setIsOpen={setIsOpen}
+>
+  Body content here.
+</Modal>
+```
+
+### When you need fine-grained Radix control: `@/components/ui/dialog`
+
+```tsx
+import { Dialog, DialogContent, DialogTrigger, ... } from "@/components/ui/dialog"
+```
+
+The vanilla shadcn-style primitive. Use only when you need direct Radix Dialog control (rare; e.g., inside `Command`).
+
+### Landmine: re-exports from `dialog-modal`
+
+`@/components/ui/dialog-modal` also exports named `Dialog`, `DialogContent`, etc. -- but those are the **`tv`-styled** versions, not the same as the ones from `@/components/ui/dialog`. Different file, different styles. **Pick one source and stick with it within a feature.**
+
+## Tooltip
+
+Two imports. Almost always the first one is correct.
+
+### Use `@/components/Tooltip`
+
+```tsx
+import Tooltip from "@/components/Tooltip"
+```
+
+Mobile-aware (falls back from hover-only Radix Tooltip to click-driven Popover on touch devices), Matomo-tracked, scroll-close behavior. This is the one you want.
+
+### Avoid `@/components/ui/tooltip`
+
+```tsx
+// Avoid unless you have a specific reason:
+import { Tooltip, TooltipContent } from "@/components/ui/tooltip"
+```
+
+The bare Radix primitive. Only used inside `@/components/Tooltip` itself.
+
+## Buttons
+
+Single source of truth. Don't roll your own.
+
+```tsx
+import { Button, ButtonLink } from "@/components/ui/buttons/Button"
+```
+
+- `Button` -- `<button>`-like
+- `ButtonLink` -- `<a>`-like, handles internal/external/file detection via `BaseLink`
+
+Variants: `solid | outline | ghost | link` (default `solid`). Sizes: `lg | md | sm` (default `md`).
+
+`isSecondary` flips text/border to body color -- but only applies to `outline` and `ghost`. Setting `isSecondary` on a `solid` or `link` button does nothing (silent no-op).
+
+### Two-line buttons
+
+```tsx
+import { ButtonTwoLines, ButtonLinkTwoLines } from "@/components/ui/buttons/ButtonTwoLines"
+```
+
+Stacked main/helper text with an icon. Restricted to `solid` / `outline` variants and `md` / `sm` sizes.
+
+### SVG-stylized link cards
+
+```tsx
+import { SvgButtonLink } from "@/components/ui/buttons/SvgButtonLink"
+```
+
+Box-shadow halo card with icon + label + description. Variants: `row | col`.
+
+## Anchors / Links
+
+```tsx
+// Default export -- in-prose links with visited styling:
+import InlineLink from "@/components/ui/Link"
+
+// Named exports for specific uses:
+import {
+  BaseLink,        // No visited styling. Use inside LinkOverlay or as ButtonLink's asChild slot.
+  LinkWithArrow,   // Explicit CTA arrow. Reserved for unique cases where the arrow is part of the design intent.
+  ExternalLinkIcon // Just the icon component (rare).
+} from "@/components/ui/Link"
+```
+
+`InlineLink` / `BaseLink` auto-detect external URLs (opens new tab + screen-reader hint), `mailto:`, files (`.pdf` etc.), hashes, and locale-aware routing. **External-link styling is handled by the primitive itself -- you don't need `LinkWithArrow` to indicate externality.** Reach for `LinkWithArrow` only when the arrow is a deliberate CTA cue on an internal link.
+
+### Do NOT use raw `<a>` tags
+
+A raw `<a>` bypasses external-link safety, RTL flipping, locale routing, and Matomo tracking. Effectively never the right choice in this codebase.
+
+### Whole-card-clickable: `LinkBox` + `LinkOverlay`
+
+```tsx
+import { LinkBox, LinkOverlay } from "@/components/ui/link-box"
+```
+
+For when an entire card should be clickable but contains other interactive elements (you can't nest `<a>` inside `<a>`).
+
+```tsx
+<LinkBox>
+  <h3>
+    <LinkOverlay asChild>
+      <BaseLink href="/x">Title</BaseLink>
+    </LinkOverlay>
+  </h3>
+  <p>Other content; the LinkOverlay's :before pseudo covers the whole LinkBox.</p>
+</LinkBox>
+```
+
+If you use `LinkBox` without `LinkOverlay` somewhere inside, the whole-card-click pattern won't work.
+
+## Heroes
+
+```tsx
+import {
+  ContentHero,
+  HomeHero,
+  HubHero,
+  MdxHero,
+  SimpleHero,
+} from "@/components/Hero"
+```
+
+| Hero | Use case |
+|---|---|
+| `ContentHero` | Most internal pages: 2-column with image, breadcrumb, buttons. The workhorse. |
+| `HubHero` | Full-bleed hero image with overlay text card. |
+| `HomeHero` | Homepage only. Async server component. |
+| `SimpleHero` | Text-only with breadcrumb + buttons. No image. |
+| `MdxHero` | Minimal: breadcrumb + h1. For long-form articles. |
+
+### Do NOT use `@/components/PageHero`
+
+```tsx
+// DON'T:
+import PageHero from "@/components/PageHero"
+```
+
+`PageHero` predates the `Hero/` directory. It's used by a few legacy pages (`staking`, `run-a-node`) but is on the deprecation track. New pages must pick from `@/components/Hero`.
+
+## Banners / Callouts / Alerts
+
+These three shapes overlap visually. Pick by *placement* and *purpose*:
+
+### Inline message in content area: `Alert`
+
+```tsx
+import { Alert, AlertContent, AlertDescription } from "@/components/ui/alert"
+```
+
+Variants: `info | error | success | warning | update`. Optional `size: "full"` for borderless full-width.
+
+### Top-of-page site-wide stripe: `BannerNotification`
+
+```tsx
+import BannerNotification from "@/components/Banners/BannerNotification"
+```
+
+Full-width `bg-primary-action` stripe. Use for site-wide announcements.
+
+### Dismissable banner: `DismissableBanner`
+
+```tsx
+import DismissableBanner from "@/components/Banners/DismissableBanner"
+```
+
+Wraps `BannerNotification` with localStorage state for "don't show again."
+
+### In-content callout with image + heading: `CalloutBannerSSR`
+
+```tsx
+import CalloutBannerSSR from "@/components/CalloutBannerSSR"
+```
+
+Use this, NOT `CalloutBanner.tsx`. The SSR variant uses `cva` with `large | medium | small` sizes and is server-renderable.
+
+### Big ornamental section divider: `CalloutSSR` / `Callout`
+
+```tsx
+import CalloutSSR from "@/components/CalloutSSR"
+```
+
+For the marketing-style large ornamental callouts with image overlap.
+
+## Tabs / Tab Navigation
+
+Two different shapes. Pick by what changes when the user clicks.
+
+### When clicking a tab swaps panels: `Tabs`
+
+```tsx
+import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/ui/tabs"
+```
+
+Radix-driven tabs that swap content panels.
+
+### When clicking navigates within a long page: `TabNav`
+
+```tsx
+import TabNav from "@/components/ui/TabNav"
+```
+
+URL-fragment-driven section navigation. Uses `useActiveHash` to highlight the current section based on scroll position. Different shape -- accepts a `sections` array.
+
+## Layout primitives
+
+```tsx
+import {
+  Center,
+  Flex,
+  HStack,
+  Stack,
+  VStack,
+} from "@/components/ui/flex"
+```
+
+`Stack` (default `flex-col gap-2`) supports a `separator` prop that clones a separator element between children. Use these instead of writing `flex flex-col gap-2` everywhere.
+
+## Avatars
+
+```tsx
+import { Avatar, AvatarImage, AvatarFallback, AvatarGroup } from "@/components/ui/avatar"
+```
+
+Don't inline a `<div className="rounded-full">` for a user avatar -- use `AvatarFallback`.
+
+## Tags
+
+```tsx
+import { Tag, TagButton } from "@/components/ui/tag"
+```
+
+Big variant matrix: `status` × `variant` × `size`. See `references/components.md` for the full set.
+
+## Tables
+
+```tsx
+import { Table, TableHeader, TableBody, TableRow, TableCell, TableHead } from "@/components/ui/table"
+```
+
+Variants: `simple | minimal | minimal-striped | simple-striped | product | highlight-first-column`.
+
+For markdown-rendered tables, `mdxTableComponents` shims the same primitive.
+
+Domain-specific tables (`DataTable`, `Layer2NetworksTable`, `FindWalletProductTable`, `StablecoinsTable`, `ProductTable`) wrap `ui/table` for specific data shapes. Use them only if the data shape matches.
+
+## i18n & Formatting Utilities
+
+For locale-aware number/date formatting, RTL helpers, and directional-icon imports, see `references/i18n-rtl.md`. Quick pointers:
+
+- `numberFormat` / `dateTimeFormat` from `@/lib/utils/numbers` and `@/lib/utils/date`
+- `useRtlFlip` from `@/hooks/useRtlFlip`
+- `ChevronNext` / `ChevronPrev` from `@/components/Chevron` (RTL-aware)
+
+## Markdown Content
+
+For MDX/Markdown files in `public/content/`, the shortcodes are wired up in `@/components/MdComponents`. Don't invent new shortcodes -- if the markdown needs a new component, add it to `MdComponents` so the shortcode is consistent with the rest of the content.
diff --git a/.claude/skills/design-system/references/card-walkthrough.md b/.claude/skills/design-system/references/card-walkthrough.md
new file mode 100644
index 00000000000..754f51b2798
--- /dev/null
+++ b/.claude/skills/design-system/references/card-walkthrough.md
@@ -0,0 +1,123 @@
+# Walkthrough: "I Need a Card"
+
+A worked example of using the design system correctly when adding card-shaped UI.
+
+## Step 1: Identify what you actually need
+
+Before reaching for a primitive, name the shape:
+
+- **A linkable summary card** with title, description, optional image -> `Card`
+- **A whole-card-clickable wrapper for non-card content** (multiple interactive elements inside) -> `LinkBox` + `LinkOverlay`
+- **A skeleton loading placeholder** -> `SkeletonCard`
+- **An app/product listing** -> existing domain-specific component (e.g., `AppCard`, `Layer2ProductCard`) -- only if data shape matches
+- **Markdown shortcode** -- `MdComponents` already wires this up; just use `<Card>` in markdown
+
+## Step 2: Compose `Card`
+
+For a typical linkable card with a banner image:
+
+```tsx
+import { Card, CardBanner, CardContent, CardTitle, CardParagraph } from "@/components/ui/card"
+import Image from "next/image"
+
+<Card href="/articles/proof-of-stake">
+  <CardBanner background="accent-a">
+    <Image src={posIllustration} alt="Stylized validators staking ETH" />
+  </CardBanner>
+  <CardContent>
+    <CardTitle>Proof of Stake</CardTitle>
+    <CardParagraph>How Ethereum secures the network.</CardParagraph>
+  </CardContent>
+</Card>
+```
+
+### What's happening
+
+- `Card` with `href` automatically wraps in `BaseLink`, gets a `group/link` class for hover propagation, and handles internal/external/file detection.
+- `CardBanner` `background="accent-a"` uses the `--accent-a` semantic token (light/dark aware).
+- `CardContent`, `CardTitle`, `CardParagraph` provide the typographic rhythm without inline class chains.
+
+## Step 3: When the shape doesn't quite match
+
+If your card needs a layout `Card` doesn't directly support, the answer is *almost always* "add a variant to `Card`," not "create a new component file."
+
+### Example: horizontal layout
+
+You need a card with the image to the left of the content.
+
+**Wrong**: Make `HorizontalCard.tsx` with `flex items-center gap-8`.
+
+**Right**: Add `layout="horizontal"` variant to `Card`.
+
+```tsx
+// In ui/card.tsx, add to the variants:
+const cardVariants = tv({
+  base: "rounded-2xl text-body",
+  variants: {
+    layout: {
+      vertical: "flex flex-col",
+      horizontal: "flex flex-row items-center gap-8",
+    },
+  },
+  defaultVariants: { layout: "vertical" },
+})
+
+// Then use:
+<Card href="..." layout="horizontal">
+  <CardBanner size="thumbnail">...</CardBanner>
+  <CardContent>...</CardContent>
+</Card>
+```
+
+See `references/variant-vs-new.md` for the full pattern.
+
+## Step 4: When you genuinely need a domain-specific card
+
+If you're building UI that:
+- Has its own data fetching shape
+- Composes Card + Tag + Avatar + specific layout for a recurring product/wallet/network listing
+- Has its own loading/error states
+
+...then a wrapper component makes sense. Look at `Layer2ProductCard` or `AppCard` for the pattern: they compose `Card` underneath and add domain-specific structure on top. Don't reinvent the card shell.
+
+## What NOT to Do
+
+```tsx
+// DON'T: Inline the card shell
+<div className="flex flex-col gap-3 rounded-3xl border border-[rgba(159,43,212,0.11)] bg-card-gradient-secondary p-6 hover:bg-card-gradient-secondary-hover hover:shadow-lg">
+  <h3 className="text-2xl font-bold">Title</h3>
+  <p className="text-body-medium">Description</p>
+</div>
+```
+
+This recreates `Card` poorly:
+- Hex border instead of token (`border-primary/10` would work)
+- Manual padding/spacing
+- Manually-styled headings instead of `CardTitle`
+- No href handling
+- No hover-group propagation
+- Not consistent with other cards on the site
+
+```tsx
+// DO: Use Card with the right variant
+<Card href="..." decoration="purple-gradient">  {/* once the variant exists */}
+  <CardContent>
+    <CardTitle>Title</CardTitle>
+    <CardParagraph>Description</CardParagraph>
+  </CardContent>
+</Card>
+```
+
+## Pre-Merge Checklist for a Card
+
+- [ ] Imports `Card` from `@/components/ui/card` (NOT `@/components/Card`)
+- [ ] If linkable, uses `Card href="..."` instead of wrapping in a separate `<a>`
+- [ ] No raw color hex values (use `border-primary/10`, `bg-accent-a`, etc.)
+- [ ] Heading is `CardTitle` (NOT a manually-styled `<div>` or `<h3>`)
+- [ ] Description is `CardParagraph` (NOT `<p className="text-body-medium">`)
+- [ ] Image inside `CardBanner` (NOT a sibling of `Card`)
+- [ ] If image needs containment, uses `<CardBanner fit="contain">` to get the auto-blur backdrop
+- [ ] Story exists (`*.stories.tsx`) for any new variant added
+- [ ] Tested in light AND dark mode (Storybook + Chromatic)
+- [ ] Tested with verbose-language (German/Spanish) text to verify no overflow
+- [ ] Tested with RTL locale (Arabic) -- nothing breaks
diff --git a/.claude/skills/design-system/references/cleanup-playbook.md b/.claude/skills/design-system/references/cleanup-playbook.md
new file mode 100644
index 00000000000..8a40782eb67
--- /dev/null
+++ b/.claude/skills/design-system/references/cleanup-playbook.md
@@ -0,0 +1,304 @@
+# Cleanup Playbook
+
+When you encounter an anti-pattern in existing code, this is the canonical replacement. Use this as the script for cleanup-track work.
+
+## Raw `<a>` -> `InlineLink` / `BaseLink`
+
+```tsx
+// Before:
+<a href="/about">About</a>
+
+// After (in-prose):
+import InlineLink from "@/components/ui/Link"
+<InlineLink href="/about">About</InlineLink>
+
+// After (CTA with arrow):
+import { LinkWithArrow } from "@/components/ui/Link"
+<LinkWithArrow href="/about">About</LinkWithArrow>
+
+// After (whole-card-clickable):
+import { LinkOverlay } from "@/components/ui/link-box"
+import { BaseLink } from "@/components/ui/Link"
+<LinkOverlay asChild><BaseLink href="/about">...</BaseLink></LinkOverlay>
+```
+
+## Raw `<button>` -> `Button`
+
+```tsx
+// Before:
+<button onClick={onClick} className="flex text-inherit"><Icon /></button>
+
+// After (icon-only):
+import { Button } from "@/components/ui/buttons/Button"
+<Button variant="ghost" size="sm" onClick={onClick} aria-label="Description"><Icon /></Button>
+
+// After (text):
+<Button variant="solid" onClick={onClick}>Click me</Button>
+```
+
+## `<div onClick>` -> `Button`
+
+```tsx
+// Before:
+<div className="cursor-pointer" onClick={onClick}>...</div>
+
+// After:
+<Button variant="ghost" onClick={onClick}>...</Button>
+```
+
+## Hard-coded color hex -> semantic token
+
+```tsx
+// Before:
+className="bg-[#FF0000]"
+className="border-[rgba(159,43,212,0.11)]"
+className="from-[#5c1eb4] to-[#7b3fd8]"
+
+// After:
+className="bg-error"
+className="border-primary/10"
+// For gradients, check utilities.css for an existing one (e.g., bg-gradient-main, bg-card-gradient-secondary).
+// If no token fits, add it to semantic-tokens.css before using a hex value in a component.
+```
+
+## Stale shadcn token names -> project semantic tokens
+
+These appear in `ui/select.tsx`, `ui/dialog.tsx`, `ui/dropdown-menu.tsx`, `ui/tabs.tsx` and DON'T resolve in this project's tokens.
+
+| Stale | Replace with |
+|---|---|
+| `bg-popover` | `bg-background-highlight` (or appropriate semantic background) |
+| `text-popover-foreground` | `text-body` |
+| `bg-accent` | `bg-accent-a` (or `accent-b`/`accent-c` as appropriate) |
+| `text-accent-foreground` | `text-body-inverse` (verify per-context) |
+| `text-muted-foreground` | `text-body-medium` |
+| `bg-muted` | `bg-background-medium` |
+| `focus:ring-ring` | Use the project's `focus-visible:` outline pattern |
+| `ring-offset-background` | `bg-background` |
+
+These are best-guess mappings; verify with a Storybook visual check before merging.
+
+## `useColorModeValue` -> Tailwind `dark:`
+
+```tsx
+// Before (Chakra leftover):
+import useColorModeValue from "@/hooks/useColorModeValue"
+const bgColor = useColorModeValue("white", "gray.900")
+return <div style={{ background: bgColor }} />
+
+// After:
+return <div className="bg-background" />  // Token swaps automatically
+// Or, if no semantic token fits:
+return <div className="bg-white dark:bg-gray-900" />
+```
+
+## `<div className="text-5xl font-bold">` -> semantic heading
+
+```tsx
+// Before:
+<div className="text-5xl font-bold">Page Title</div>
+
+// After:
+<h1>Page Title</h1>  // base.css already styles this
+```
+
+If you need a specific size that doesn't match `base.css` defaults, override on the heading:
+
+```tsx
+<h2 className="text-4xl">Custom-sized Heading</h2>
+```
+
+## `<p className="text-Xxl font-bold">number</p>` -> `BigNumber`
+
+```tsx
+// Before:
+<p className="text-4xl font-bold">$3000</p>
+<p className="text-2xl font-bold">1st place</p>
+
+// After:
+import BigNumber from "@/components/BigNumber"
+<BigNumber>$3000</BigNumber>
+```
+
+## Inlined avatar circle -> `AvatarFallback`
+
+```tsx
+// Before:
+<div className="grid size-8 place-items-center rounded-full text-body-inverse">
+  {name.charAt(0)}
+</div>
+
+// After:
+import { Avatar, AvatarFallback } from "@/components/ui/avatar"
+<Avatar><AvatarFallback>{name.charAt(0)}</AvatarFallback></Avatar>
+```
+
+## Custom card shell -> `Card` composition
+
+```tsx
+// Before:
+<div className="flex flex-col gap-3 rounded-3xl border border-[rgba(159,43,212,0.11)] bg-card-gradient-secondary p-6 hover:bg-card-gradient-secondary-hover hover:shadow-lg">
+  <h3>Title</h3>
+  <p>Description</p>
+</div>
+
+// After:
+import { Card, CardContent, CardTitle, CardParagraph } from "@/components/ui/card"
+<Card decoration="purple-gradient">  {/* once the variant is added */}
+  <CardContent>
+    <CardTitle>Title</CardTitle>
+    <CardParagraph>Description</CardParagraph>
+  </CardContent>
+</Card>
+```
+
+If the matching variant doesn't exist yet, add it to `Card` before this cleanup.
+
+## `value.toLocaleString()` -> `numberFormat()`
+
+```tsx
+// Before:
+{value.toLocaleString()}
+new Intl.NumberFormat(locale).format(value)
+
+// After:
+import { numberFormat } from "@/lib/utils/numbers"
+{numberFormat(locale, options).format(value)}
+```
+
+## Native date methods -> `dateTimeFormat()`
+
+```tsx
+// Before:
+date.toLocaleDateString()
+date.toLocaleTimeString()
+new Intl.DateTimeFormat(locale).format(date)
+
+// After:
+import { dateTimeFormat } from "@/lib/utils/date"
+dateTimeFormat(locale, options).format(date)
+```
+
+## Hard-coded `left-`/`right-` -> logical equivalents
+
+```tsx
+// Before:
+className="left-2 mr-4 pl-8 border-l text-left"
+
+// After:
+className="inset-s-2 me-4 ps-8 border-s text-start"
+```
+
+(Only physical positioning is OK for genuinely non-directional cases like centering or vertical positioning.)
+
+## Right-pointing icon -> RTL-aware
+
+```tsx
+// Before:
+import { ChevronRight } from "lucide-react"
+<ChevronRight className="size-4" />
+
+// After (option A: project's RTL-aware wrapper):
+import { ChevronNext } from "@/components/Chevron"
+<ChevronNext className="size-4" />
+
+// After (option B: useRtlFlip + base icon):
+"use client"
+import { ChevronRight } from "lucide-react"
+import { useRtlFlip } from "@/hooks/useRtlFlip"
+import { cn } from "@/lib/utils/cn"
+const { twFlipForRtl } = useRtlFlip()
+<ChevronRight className={cn("size-4", twFlipForRtl)} />
+```
+
+## Hard-coded English string -> translation
+
+```tsx
+// Before:
+<h1>Welcome to Ethereum</h1>
+
+// After (Server Component):
+import { getTranslations } from "next-intl/server"
+const t = await getTranslations("page-namespace")
+<h1>{t("welcome-heading")}</h1>
+
+// After (Client Component):
+"use client"
+import { useTranslations } from "next-intl"
+const t = useTranslations("page-namespace")
+<h1>{t("welcome-heading")}</h1>
+```
+
+Add the new key to `src/intl/en/[namespace].json`.
+
+> **Data fetching patterns** (Server Component data, caching, sources) are out of scope for this design-system skill. See the `data-layer` skill for canonical fetching guidance.
+
+## `Callout` (client) -> `CalloutSSR` (server)
+
+```tsx
+// Before:
+import Callout from "@/components/Callout"
+<Callout title={t("title")} ... />
+
+// After (when the parent can be server):
+import CalloutSSR from "@/components/CalloutSSR"
+const t = await getTranslations()
+<CalloutSSR title={t("title")} ... />
+```
+
+Same applies to `CalloutBanner` -> `CalloutBannerSSR`.
+
+## `PageHero` -> `ContentHero` (or appropriate Hero variant)
+
+```tsx
+// Before:
+import PageHero from "@/components/PageHero"
+<PageHero header={...} title={...} description={...} />
+
+// After:
+import { ContentHero } from "@/components/Hero"
+<ContentHero {...} />
+```
+
+The shapes are different; you may need to restructure the page slightly. `PageHero` is on the deprecation track.
+
+## Arbitrary z-index -> named z scale
+
+```tsx
+// Before:
+className="z-[10000]"
+className="z-[1500]"
+
+// After:
+className="z-tooltip"  // 1800
+className="z-popover"  // 1500
+```
+
+See `tokens.md` for the full named z-index scale.
+
+## Inlined gradient with hex stops -> token gradient
+
+```tsx
+// Before:
+className="bg-linear-to-br from-[#7f7fd5]/20 via-[#86a8e7]/20 to-[#91eae4]/20"
+
+// After (if a token gradient matches):
+className="bg-gradient-main"
+
+// If no existing gradient matches:
+// 1. Add a new @utility to utilities.css
+// 2. Use it
+```
+
+## Inline `<div className="flex flex-col gap-2">` -> `Stack`
+
+```tsx
+// Before:
+<div className="flex flex-col gap-2">{children}</div>
+
+// After:
+import { Stack } from "@/components/ui/flex"
+<Stack className="gap-2">{children}</Stack>
+```
+
+(Stack already defaults to `flex-col gap-2`, so often you can drop the className entirely.)
diff --git a/.claude/skills/design-system/references/components.md b/.claude/skills/design-system/references/components.md
new file mode 100644
index 00000000000..76981b6aab4
--- /dev/null
+++ b/.claude/skills/design-system/references/components.md
@@ -0,0 +1,579 @@
+# Component Catalog
+
+Reference for the components in `src/components/ui/` and notable feature components. For the "which import wins" decision tree, see `canonical-imports.md`. For confusion landmines, see `gotchas.md`.
+
+> **STATUS**: This document is the skeleton. Sections marked TODO need their canonical-usage examples filled in during the next pass.
+
+## Conventions
+
+Each entry has:
+- **Import path**
+- **What it's for** (one-line use case)
+- **Canonical usage** (shortest valid invocation)
+- **Notable props/variants**
+- **Gotchas worth knowing**
+
+## Buttons & Links
+
+### `Button` / `ButtonLink`
+
+```tsx
+import { Button, ButtonLink } from "@/components/ui/buttons/Button"
+```
+
+The canonical clickable. `Button` for `<button>`-class actions; `ButtonLink` for `<a>`-class navigation (handles internal/external/file detection via `BaseLink`).
+
+```tsx
+<Button>Click me</Button>
+<ButtonLink href="/about">About</ButtonLink>
+```
+
+**Variants**: `solid | outline | ghost | link` (default `solid`)
+**Sizes**: `lg | md | sm` (default `md`)
+**Other props**: `isSecondary` (flips text/border to body color; *only applies to `outline`/`ghost`*), `asChild` (Radix Slot), `toId` (smooth-scroll to element), `customEventOptions` (Matomo override).
+
+`"use client"` because of click tracking and `scrollIntoView`.
+
+### `ButtonTwoLines` / `ButtonLinkTwoLines`
+
+```tsx
+import { ButtonTwoLines, ButtonLinkTwoLines } from "@/components/ui/buttons/ButtonTwoLines"
+```
+
+Stacked two-line button with icon.
+
+```tsx
+<ButtonTwoLines icon={ChevronRight} mainText="Title" helperText="Subtitle" />
+```
+
+**Variants**: `solid | outline` only
+**Sizes**: `md | sm` only
+
+### `SvgButtonLink`
+
+```tsx
+import { SvgButtonLink } from "@/components/ui/buttons/SvgButtonLink"
+```
+
+Iconic link card with stylized box-shadow halo. Used heavily on docs hubs.
+
+```tsx
+<SvgButtonLink href="/x" Svg={MySvg} label="Title">desc</SvgButtonLink>
+```
+
+**Variants**: `row | col` (default `row`)
+Built with `tv`.
+
+### `BaseLink` / `InlineLink` / `LinkWithArrow`
+
+```tsx
+import InlineLink, { BaseLink, LinkWithArrow } from "@/components/ui/Link"
+```
+
+ALL anchor tags. Auto-detects external (new tab + sr-only "(opens in new tab)"), mailto, files (`.pdf`), hashes, and locale-aware routing.
+
+| Export | When to use |
+|---|---|
+| `InlineLink` (default) | In-prose links (has `visited:` styling) |
+| `BaseLink` | Inside `LinkOverlay`, as `ButtonLink` `asChild` slot, or when `visited:` styling is unwanted |
+| `LinkWithArrow` | CTA arrow links, RTL-flip-aware |
+
+`"use client"` because of `usePathname` and tracking.
+
+## Cards & Containers
+
+### `Card` (+ parts)
+
+```tsx
+import {
+  Card,
+  CardBanner,
+  CardContent,
+  CardFooter,
+  CardHeader,
+  CardParagraph,
+  CardTitle,
+} from "@/components/ui/card"
+```
+
+The canonical card primitive. `rounded-2xl text-body`. With `href`, wraps in `BaseLink` and propagates a `group/link` class so descendant text can react to card-level hover.
+
+```tsx
+<Card href="/x">
+  <CardBanner background="accent-a">
+    <Image src="..." alt="..." />
+  </CardBanner>
+  <CardContent>
+    <CardTitle>Title</CardTitle>
+    <CardParagraph>Description</CardParagraph>
+  </CardContent>
+</Card>
+```
+
+**`CardBanner` props**:
+- `background`: `accent-a | accent-b | accent-c | primary | body | none` (default `body`)
+- `size`: `full | thumbnail` (default `full`)
+- `fit`: `cover | contain` (default `cover`)
+- **Magic**: `fit="contain"` with a single `<Image>` child auto-clones it as a blurred backdrop.
+
+**`CardTitle` variants**: `semibold | bold | black` (default `bold`).
+
+### `Section`
+
+```tsx
+import { Section } from "@/components/ui/section"
+```
+
+Top-level `<section>` wrapper with scroll-margin pre-set for sticky-nav offset.
+
+```tsx
+<Section id="my-section" className="space-y-8">
+  {/* content */}
+</Section>
+```
+
+**Variants**: `responsiveFlex` (col -> row at md), `scrollMargin: "tabNav"` (extra scroll-mt for TabNav layouts).
+
+**Common usage**: high-level `Section` with an `id` (for hash navigation) and a `space-y-n` class for vertical rhythm. Don't try to convert page sections into flex containers unless the layout calls for it -- vertical stacking with `space-y-*` is the dominant pattern across the site.
+
+**Sub-components** (`SectionBanner`, `SectionContent`, `SectionHeader`, `SectionTag`): exist in the file but are only meaningfully used on the homepage. Other pages tend to compose `Section` with raw heading + content. Don't reach for the sub-components for new work without confirming the homepage pattern is what you want.
+
+> File header has a `// TODO: Add to design system` comment -- vestigial from prior DS attempts; the component is stable, ignore the TODO.
+
+### `Flex` / `Center` / `Stack` / `HStack` / `VStack`
+
+```tsx
+import { Center, Flex, HStack, Stack, VStack } from "@/components/ui/flex"
+```
+
+Layout primitives.
+
+| Component | Default classes |
+|---|---|
+| `Flex` | `flex` |
+| `Center` | `flex items-center justify-center` |
+| `Stack` | `flex flex-col gap-2` |
+| `HStack` | `flex flex-row items-center gap-2` |
+| `VStack` | `flex flex-col items-center gap-2` |
+
+`Stack` supports a `separator` prop that clones a separator element between children:
+
+```tsx
+<Stack separator={<Divider />}>{items}</Stack>
+```
+
+### `LinkBox` / `LinkOverlay`
+
+```tsx
+import { LinkBox, LinkOverlay } from "@/components/ui/link-box"
+```
+
+Whole-card-clickable without nesting `<a>` in `<a>`.
+
+```tsx
+<LinkBox>
+  <h3>
+    <LinkOverlay asChild>
+      <BaseLink href="/x">Title</BaseLink>
+    </LinkOverlay>
+  </h3>
+  <p>Other content; the LinkOverlay's :before pseudo covers the whole LinkBox.</p>
+</LinkBox>
+```
+
+`LinkBox` without a `LinkOverlay` somewhere inside doesn't work.
+
+### `EdgeScrollContainer` / `EdgeScrollItem`
+
+```tsx
+import { EdgeScrollContainer, EdgeScrollItem } from "@/components/ui/edge-scroll-container"
+```
+
+Preferred horizontal scroll primitive (over `Carousel` and `Swiper`). See "Horizontal scroll / carousel" section below for the full picture.
+
+## Overlay Primitives
+
+### `Modal` (default) / `Dialog` (named) -- `ui/dialog-modal`
+
+```tsx
+import Modal from "@/components/ui/dialog-modal"
+```
+
+Higher-level convenience for typical modal needs. `tv` slots with `size` and `variant`.
+
+```tsx
+<Modal
+  title="Are you sure?"
+  actionButton={{ label: "Confirm", onClick: handleConfirm }}
+  isOpen={isOpen}
+  setIsOpen={setIsOpen}
+>
+  Body content here.
+</Modal>
+```
+
+**`size`**: `md | lg | xl`
+**`variant`**: `simulator | unstyled`
+
+### `Dialog` -- `ui/dialog`
+
+```tsx
+import { Dialog, DialogContent, DialogTrigger, ... } from "@/components/ui/dialog"
+```
+
+Vanilla shadcn-style. Use only when you need fine-grained Radix control (rare).
+
+### `Sheet` vs `PersistentPanel` (slide-in panels)
+
+Both render a slide-in panel from a side. They're not interchangeable -- pick by mount semantics:
+
+| Component | Mount behavior | Underlying primitive | Compositional parts |
+|---|---|---|---|
+| `Sheet` | Mounts/unmounts each open | Radix Dialog (battle-tested) | `SheetHeader`, `SheetFooter`, `SheetTitle`, `SheetDescription` |
+| `PersistentPanel` | Lazy-mounts on first open, then **stays mounted** | Custom (`FocusScope` directly) | None |
+
+Use `Sheet` for ordinary side-panel UI -- the conventional choice with the better-trodden Radix Dialog underneath:
+
+```tsx
+import { Sheet, SheetTrigger, SheetContent, SheetHeader, SheetTitle } from "@/components/ui/sheet"
+```
+
+**`side`**: `top | bottom | left | right` (default `right`). `SheetClose` wraps `Button variant="ghost" isSecondary`. `hideOverlay` prop on `SheetContent`.
+
+Use `PersistentPanel` when content is expensive to render or when state should survive close (filter forms, big paginated lists, stateful editors):
+
+```tsx
+import { PersistentPanel } from "@/components/ui/persistent-panel"
+```
+
+`"use client"`. Lazy mount + stay mounted means the second open is instant. No header/footer/title sub-components.
+
+> **Future**: There's an open question about consolidating these two using Radix Dialog's `forceMount` prop for the persistent case. Tracked in the cleanup tracking issue. For now, use them as documented above.
+
+### `Drawer` (deprecation track)
+
+```tsx
+// DON'T use for new work:
+import { Drawer, ... } from "@/components/ui/drawer"
+```
+
+Bottom drawer using `vaul`. **Zero consumers in the codebase.** Marked for removal. Use `Sheet` (with `side="bottom"`) for any new bottom-panel needs.
+
+### `Popover`
+
+```tsx
+import { Popover, PopoverTrigger, PopoverContent } from "@/components/ui/popover"
+```
+
+Radix Popover with Arrow. Default `align="center" sideOffset=4`. Uses `z-popover`.
+
+### `Tooltip` (bare) -- DON'T import this directly
+
+```tsx
+// DON'T:
+import { Tooltip, TooltipContent } from "@/components/ui/tooltip"
+```
+
+Bare hover-only Radix tooltip. Used only inside `@/components/Tooltip`. Use `@/components/Tooltip` instead.
+
+### `DropdownMenu`
+
+```tsx
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, ... } from "@/components/ui/dropdown-menu"
+```
+
+Many subparts. Note: this file currently uses several stale shadcn class names that don't resolve in this project's tokens (see `gotchas.md`).
+
+### `Select`
+
+```tsx
+import { Select, SelectTrigger, SelectContent, ... } from "@/components/ui/select"
+```
+
+Radix Select. Same stale-shadcn-token issue as `DropdownMenu`.
+
+### `Command`
+
+```tsx
+import { Command, ... } from "@/components/ui/command"
+```
+
+Imports from `cmdk`.
+
+## Form Inputs
+
+### `Input`
+
+```tsx
+import { Input } from "@/components/ui/input"
+```
+
+**Props**: `size: md | sm`, `hasError: boolean`. (Default omits `size` from `InputHTMLAttributes` to free the prop.)
+
+### `Textarea`
+
+```tsx
+import { Textarea } from "@/components/ui/textarea"
+```
+
+Same shape as `Input`.
+
+### `Checkbox` / `Switch` / `RadioGroup`
+
+```tsx
+import Checkbox from "@/components/ui/checkbox"
+import Switch from "@/components/ui/switch"
+import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
+```
+
+All three share styling via `commonControlClasses` exported from `checkbox.tsx`. Editing that constant affects all three.
+
+## Display
+
+### `Tag`
+
+```tsx
+import { Tag, TagButton, TagsInlineText } from "@/components/ui/tag"
+```
+
+Big variant matrix.
+
+```tsx
+<Tag status="success">Live</Tag>
+```
+
+**`status`**: `normal | tag | success | error | warning | update | accent-a | accent-b | accent-c | primary | tag-green | tag-yellow | tag-red`
+**`variant`**: `subtle | high-contrast | solid | outline`
+**`size`**: `small | medium`
+
+### `Alert`
+
+```tsx
+import { Alert, AlertContent, AlertDescription, AlertTitle, AlertEmoji, AlertIcon, AlertCloseButton } from "@/components/ui/alert"
+```
+
+Inline messages.
+
+```tsx
+<Alert variant="warning">
+  <AlertContent>
+    <AlertDescription>Heads up.</AlertDescription>
+  </AlertContent>
+</Alert>
+```
+
+**`variant`**: `info | error | success | warning | update`
+**`size`**: `full` (borderless full-width)
+
+### `Avatar`
+
+```tsx
+import { Avatar, AvatarBase, AvatarImage, AvatarFallback, AvatarGroup } from "@/components/ui/avatar"
+```
+
+Uses `tv` slots with React context. `"use client"` because of `useState(hasError)`.
+
+### `Tabs`
+
+```tsx
+import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/ui/tabs"
+```
+
+Pure Radix wrapper. Same stale-shadcn-token issue as `DropdownMenu`/`Select`.
+
+### `TabNav`
+
+```tsx
+import TabNav from "@/components/ui/TabNav"
+```
+
+Custom horizontal nav for long-page section navigation. URL-fragment-driven, uses `useActiveHash`. Different shape from `Tabs` -- accepts a `sections` array.
+
+### `Accordion`
+
+```tsx
+import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from "@/components/ui/accordion"
+```
+
+Custom chevron rotation, RTL `dir(rtl)` variant included.
+
+### `Breadcrumb`
+
+```tsx
+import { Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage } from "@/components/ui/breadcrumb"
+```
+
+> Gotcha: The current-page item is rendered as `<span role="link" aria-disabled="true">` -- the `role="link"` is misleading; should arguably be a plain styled `<span>`. Aware-only; don't fix in passing.
+
+### `Progress`
+
+```tsx
+import { Progress } from "@/components/ui/progress"
+```
+
+**`color`**: `disabled | primary`
+
+### `ScrollArea` / `ScrollBar`
+
+```tsx
+import { ScrollArea, ScrollBar } from "@/components/ui/scroll-area"
+```
+
+### `Skeleton`
+
+```tsx
+import { Skeleton, SkeletonLines, SkeletonCard, SkeletonCardContent, SkeletonCardGrid } from "@/components/ui/skeleton"
+```
+
+`SkeletonCard` composes `Card` for consistency.
+
+### `Spinner`
+
+```tsx
+import Spinner from "@/components/ui/spinner"
+```
+
+Wraps `Loader2` from Lucide.
+
+### `Divider` (deprecation track)
+
+```tsx
+import Divider from "@/components/ui/divider"
+```
+
+Project-specific look: `my-16 h-1 w-[10%] bg-primary-high-contrast` purple bar. **Largely deprecated in current usage.** For visual section separation, prefer a border (`border-t border-border` on a subsequent element) over rendering a `<Divider />`. Don't introduce new `Divider` usage; existing uses can be left until a deliberate cleanup.
+
+### `Table`
+
+```tsx
+import { Table, TableHeader, TableBody, TableRow, TableCell, TableHead } from "@/components/ui/table"
+```
+
+`tv` with slots, React context.
+
+**Variants**: `simple | minimal | minimal-striped | simple-striped | product | highlight-first-column`
+
+The `product` variant currently has stale shadcn tokens (`hover:bg-muted/50`, `text-muted-foreground`).
+
+### Horizontal scroll / carousel
+
+Three components exist in this space; only one is recommended for new work:
+
+| Component | Status |
+|---|---|
+| `EdgeScrollContainer` (`@/components/ui/edge-scroll-container`) | **Preferred** for new horizontal scroll lists |
+| `Carousel` (`@/components/ui/carousel`) | Not recommended for new work; has unresolved RTL issues |
+| `Swiper` (`@/components/ui/swiper`) | Not recommended for new work; planned for removal |
+
+`EdgeScrollContainer` is a CSS-driven horizontal scroll with snap and edge mask:
+
+```tsx
+import { EdgeScrollContainer, EdgeScrollItem } from "@/components/ui/edge-scroll-container"
+```
+
+CSS-var driven (`--edge-spacing`, `--edge-mask-size`, `--edge-overflow-y-pad`). Mask fade only at `2xl+`. The component is being polished further; don't add new `Carousel` or `Swiper` usage in the meantime.
+
+### `List` / `OrderedList` / `UnorderedList` / `ListItem`
+
+```tsx
+import { List, OrderedList, UnorderedList, ListItem } from "@/components/ui/list"
+```
+
+> `base.css` still has legacy global `ul`/`ol` styles flagged for removal. List migration is in progress.
+
+### `TerminalTypewriter`
+
+```tsx
+import TerminalTypewriter from "@/components/ui/terminal-typewriter"
+```
+
+`"use client"`. Animated terminal-style typing.
+
+### `TruncatedText`
+
+```tsx
+import TruncatedText from "@/components/ui/TruncatedText"
+```
+
+`"use client"`. Show-more/show-less expansion. Uses `LINE_CLAMP_CLASS_MAPPING` constant -- pass an integer line count via prop.
+
+### `Chart`
+
+```tsx
+import { Chart, ... } from "@/components/ui/chart"
+```
+
+Recharts wrapper.
+
+> Has the lone remaining `value.toLocaleString()` in `src/` (line 241). Replace with `numberFormat()` when touching this file.
+
+### `Collapsible`
+
+```tsx
+import { Collapsible, CollapsibleTrigger, CollapsibleContent } from "@/components/ui/collapsible"
+```
+
+Radix Collapsible.
+
+### `ErrorBoundary`
+
+```tsx
+import ErrorBoundary from "@/components/ui/error-boundary"
+```
+
+Class component (`getDerivedStateFromError`), integrates with `@sentry/nextjs`. `"use client"`.
+
+## No `Heading` Primitive Exists
+
+There's a `Heading.stories.tsx` file but it just renders raw `<h1>` through `<h6>`. The headings are styled by `base.css` element defaults. Use semantic tags directly:
+
+```tsx
+<h1>Title</h1>           // text-4xl lg:text-5xl, font-bold (from base.css)
+<h2>Subtitle</h2>        // text-3xl lg:text-4xl, font-bold
+```
+
+For markdown-rendered content, sizing comes from `MdComponents`.
+
+If you need specific in-page typography that isn't a heading (e.g., a big numeric stat), use `BigNumber` from `@/components/BigNumber` -- it exists.
+
+## Notable Feature Components
+
+### `BigNumber` -- USE FOR LARGE NUMERIC DISPLAYS
+
+```tsx
+import BigNumber from "@/components/BigNumber"
+```
+
+For prominent numeric displays (e.g., "$3000" prize amounts, statistics). Don't inline `<p className="text-4xl font-bold">N</p>`.
+
+### Heroes -- `@/components/Hero`
+
+```tsx
+import { ContentHero, HomeHero, HubHero, MdxHero, SimpleHero } from "@/components/Hero"
+```
+
+See `canonical-imports.md` for selection.
+
+### Banners -- `@/components/Banners`
+
+`BannerNotification`, `DismissableBanner`, `EnvWarningBanner` (exemplary -- thin wrap of `Alert variant="warning"`), `TranslationBanner`, `UpgradeBannerNotification`.
+
+### `MdComponents`
+
+```tsx
+// Used internally by next-mdx-remote, not imported in app code:
+import { MdComponents } from "@/components/MdComponents"
+```
+
+The shortcode registry for markdown content. To add a markdown shortcode, add the component to `MdComponents`.
+
+## Components NOT to Use
+
+### Legacy / deprecated
+
+- `@/components/PageHero` -- use `@/components/Hero/*` instead
+- `@/hooks/useColorModeValue` -- Chakra leftover; use Tailwind `dark:` variant
+
+### Reserved
+
+- `@/components/Card` (default export) -- reserved for markdown shortcode; use `@/components/ui/card`
diff --git a/.claude/skills/design-system/references/gotchas.md b/.claude/skills/design-system/references/gotchas.md
new file mode 100644
index 00000000000..62d003070b9
--- /dev/null
+++ b/.claude/skills/design-system/references/gotchas.md
@@ -0,0 +1,179 @@
+# Gotchas
+
+The highest-value content in this skill. Each entry is a place where the code looks reasonable but the pattern is wrong, or where two paths exist and only one is right.
+
+## Imports That Look Right But Aren't
+
+### `@/components/Card` vs `@/components/ui/card`
+
+Default export of `@/components/Card` exists for the markdown `<Card>` shortcode (registered in `MdComponents`). Importing it from app code is wrong, even though it autocompletes.
+
+**Use `@/components/ui/card`** for any new card UI.
+
+### `@/components/ui/tooltip` vs `@/components/Tooltip`
+
+The bare Radix tooltip (`@/components/ui/tooltip`) is hover-only and has no mobile fallback. The mobile-aware wrapper is `@/components/Tooltip` (no `ui/` prefix).
+
+**Use `@/components/Tooltip`** unless you specifically need the bare Radix primitive (rare; mostly used inside `@/components/Tooltip` itself).
+
+### `Dialog` from two different files
+
+`@/components/ui/dialog` exports `Dialog`, `DialogContent`, etc. (vanilla shadcn-style).
+
+`@/components/ui/dialog-modal` ALSO exports `Dialog`, `DialogContent`, etc. -- but those are **`tv`-styled, different from `dialog.tsx`**. Same names, different visuals.
+
+**Within a feature, don't mix.** Pick one file as your dialog source. The default export from `dialog-modal` is `Modal` (the high-level convenience); use that when you can.
+
+### `PageHero` is on the deprecation track
+
+`@/components/PageHero` predates the `Hero/` directory. New pages must import from `@/components/Hero` (`ContentHero`, `SimpleHero`, `HubHero`, `MdxHero`, `HomeHero`).
+
+## Component Behaviors You'd Miss
+
+### `Button isSecondary` does nothing on `solid` and `link` variants
+
+In `Button.tsx` lines 67-69, there's an early-out: `["solid", "link"].includes(variant || "solid")`. So `<Button isSecondary>...</Button>` (defaulting to `solid`) silently does nothing. `isSecondary` only takes effect on `outline` and `ghost` variants.
+
+### `CardBanner fit="contain"` auto-clones a single child as a blurred backdrop
+
+If you pass `<CardBanner fit="contain"><Image .../></CardBanner>` with **one** child, you get a blurred-bg + sharp-fg automatically (Card.tsx lines 95-119). Pass two children and you lose this magic.
+
+### `LinkBox` requires `LinkOverlay` somewhere inside
+
+The whole-card-clickable pattern uses a `before:absolute` pseudo-element on `LinkOverlay`. Use `LinkBox` without `LinkOverlay` and the click-the-whole-card behavior breaks.
+
+### `commonControlClasses` in `ui/checkbox.tsx` is shared by Switch and RadioGroup
+
+`Checkbox.tsx` exports a `commonControlClasses` constant that is also imported by `Switch` and `RadioGroup`. Editing it changes all three. If you're adjusting checkbox styling, you're adjusting switches and radios too -- audit all three before merging.
+
+### `Stack`'s `separator` prop clones a separator between children
+
+`<Stack separator={<hr className="border-t border-border" />}>` puts the separator element between every pair of children automatically. Useful pattern; many devs miss it and end up rendering separators manually.
+
+## Styling Anti-Patterns
+
+### `<div onClick>` for a clickable thing
+
+No keyboard support, no `role`, no focus management. Use `<Button>` (or `<Button variant="ghost">` for icon-only) instead. If you really do need a non-button clickable, add `role="button"`, `tabIndex={0}`, and keyboard handlers -- but the answer is almost always "use Button."
+
+### `<button>` with manual styling instead of `Button`
+
+Same problem -- bypasses focus rings, hover states, and a11y baseline. Use `Button` from `@/components/ui/buttons/Button`, even for icon-only buttons (use `variant="ghost"` and `aria-label`).
+
+### Reinventing a heading with a `<div>`
+
+`<div className="text-5xl font-bold">Hello</div>` is wrong. Headings are styled by `base.css` defaults on `<h1>` through `<h6>`. Use the semantic tag and override sizes via `className` only when really needed.
+
+### Inlining instead of composing
+
+If you're writing `flex items-center gap-X rounded-Y border bg-... p-Z` to make a card, you're reinventing `<Card>`. If you're writing `text-Xxl font-bold` to make a numeric stat, you're reinventing `<BigNumber>` (which exists at `@/components/BigNumber`).
+
+**Any time you reach for `className`, ask: "Is there a primitive that already does this?"** Some className use is fine (small overrides, layout adjustments), but every reach should raise the question. If you're chaining 4+ utilities to recreate something a primitive does, stop and use the primitive.
+
+### Using `cva` for new components
+
+The team prefers `tailwind-variants` (`tv`) for new and refactored work. Existing `cva` components are not being migrated -- don't refactor them unless asked. But for *new* components, use `tv`.
+
+## Hidden Side Effects
+
+### Server / Client component composition is fine in both directions
+
+A Server Component can render a Client Component (the boundary is established at the Client Component itself). A Client Component can also render Server Components passed in via `children` -- React Server Components support this composition.
+
+Example: `ui/Link.tsx` is `"use client"`. `ui/card.tsx` is a Server Component that imports `BaseLink`. Using `<Card href="...">` from a Server-Component page is fine -- the client boundary lives at `BaseLink`, not at `Card` and not at the page.
+
+Just be aware which side of the boundary you're on when adding hooks/effects.
+
+### `Button` is `"use client"` because of click tracking and `scrollIntoView` (`toId` prop)
+
+Static buttons get unnecessarily forced into client. Splitting would be invasive; for now, just know this is true.
+
+### `Callout.tsx` is `"use client"` only because of `useTranslation`
+
+There's a `CalloutSSR.tsx` for the server-translated split. Prefer `CalloutSSR` whenever the parent can do the translation work via `getTranslations` (server). Same applies to `CalloutBanner` vs `CalloutBannerSSR`.
+
+### Event tracking is automatic on `Button` and `Link`
+
+`@/components/ui/Link.tsx` and `@/components/ui/buttons/Button.tsx` auto-fire Matomo events when `customEventOptions` is omitted (with sensible defaults). Manually wiring `trackCustomEvent` in a new component is usually unnecessary if you're using these primitives.
+
+## Tokens That Aren't Real
+
+These class names appear in `ui/select.tsx`, `ui/dialog.tsx`, `ui/dropdown-menu.tsx`, `ui/tabs.tsx` but are **NOT defined** in this project's tokens. They're stale shadcn defaults that don't resolve:
+
+- `bg-popover`, `text-popover-foreground`
+- `bg-accent`, `text-accent-foreground`
+- `bg-muted`, `text-muted-foreground`
+- `focus:ring-ring`, `ring-offset-background`
+
+If you're touching one of these files, replace these with semantic tokens (see `tokens.md` and `cleanup-playbook.md`). Don't introduce new usage of these names.
+
+## Internationalization Landmines
+
+### Hard-coded `left-`/`right-`/`ml-`/`mr-`/`pl-`/`pr-` breaks RTL
+
+Use logical equivalents: `inset-s-`, `inset-e-`, `ms-`, `me-`, `ps-`, `pe-`. The site supports Arabic and Urdu. The `ui/select.tsx` and `ui/dropdown-menu.tsx` files currently have a number of these violations; don't add more.
+
+### `toLocaleString` / `Intl.NumberFormat` without locale wrappers
+
+Use `numberFormat()` from `@/lib/utils/numbers` and `dateTimeFormat()` from `@/lib/utils/date`. They handle Urdu/Arabic numbering systems and calendar correctly.
+
+There's currently exactly one violation: `ui/chart.tsx:241`. Don't add more.
+
+### Directional icons: use `ChevronNext` / `ChevronPrev`
+
+Right-pointing arrows and chevrons that imply "forward" need to mirror in RTL. **`@/components/Chevron`'s `ChevronNext` and `ChevronPrev` are the way -- don't reinvent.**
+
+```tsx
+import { ChevronNext } from "@/components/Chevron"
+return <ChevronNext className="size-4" />
+```
+
+Use `useRtlFlip` only when you need to flip a non-chevron directional icon (a curved arrow, etc.) where no project wrapper exists.
+
+### Code blocks force LTR globally
+
+`base.css` includes `pre:has(code) { direction: ltr; text-align: left; }`. This is intentional -- code is always read LTR. Don't fight it.
+
+### Urdu uses `list-style-type: urdu` for ordered lists
+
+Configured in `base.css` lines 97-107. Persian fallback. Triggered by `:lang(ur)`, not `dir`. Don't override.
+
+## Heading Hierarchy
+
+### One `<h1>` per page
+
+`MdxHero` and `HubHero` both render `<h1>`. Most React-page heroes do. Most markdown layouts auto-render the page `title` from frontmatter as the `<h1>`.
+
+**Exception: the `Static` layout**. It does NOT auto-render `title` as `<h1>`. Pages on the `Static` layout MUST include `# Title` in the markdown body to provide the page heading. That's the only place a markdown `# Title` is correct -- on every other layout, a markdown `# Title` creates a duplicate `<h1>`.
+
+### Eyebrow text in `HubHero` is rendered as `<h1>`
+
+`HubHero` uses `<h1>` for its uppercase eyebrow when `title` is set. This is content-correct (the eyebrow IS the page title for SEO).
+
+## Things Not Used Anymore
+
+### `Drawer` (`ui/drawer.tsx`)
+
+Zero consumers in `src/`/`app/`. On the deprecation track. Use `Sheet` (with `side="bottom"` if needed). Don't introduce new `Drawer` usage.
+
+### `useColorModeValue` (`@/hooks/useColorModeValue`)
+
+Chakra leftover, used in 5 places. Don't introduce new uses. Replace with Tailwind `dark:` variants when touching code that has it.
+
+## Random Footguns
+
+### `Tooltip` has `z-[10000]`
+
+`@/components/Tooltip/index.tsx:115` uses `z-[10000]` instead of `z-tooltip` (1800). Should use the named token. Flagged for cleanup; don't replicate.
+
+### `MdComponents` heading sizes are arbitrary
+
+`MdComponents/index.tsx:47,59,74,89` overrides h1/h2 with `text-[2.5rem]`, `text-[2rem]`. These are markdown-specific sizing rules. Don't replicate the arbitrary values in non-markdown code.
+
+### `SimpleHero` and `MdComponents` both use `text-[2.5rem]`
+
+This duplicate "page title size" suggests we need a `--text-page-title` token (or a `Heading` primitive). Until that exists, the arbitrary value is the convention.
+
+### `BigNumber` exists -- USE IT
+
+`@/components/BigNumber` is a real component for prominent numeric displays. If you find yourself writing `<p className="text-4xl font-bold">$3000</p>`, you should be using `BigNumber` instead.
diff --git a/.claude/skills/design-system/references/i18n-rtl.md b/.claude/skills/design-system/references/i18n-rtl.md
new file mode 100644
index 00000000000..caec1682bed
--- /dev/null
+++ b/.claude/skills/design-system/references/i18n-rtl.md
@@ -0,0 +1,229 @@
+# Internationalization & RTL
+
+The site supports 25 languages, including **Arabic** and **Urdu** (RTL). Translations live in `src/intl/[locale]/` (JSON UI strings) and `public/content/translations/[locale]/` (markdown content). UI strings are managed through Crowdin.
+
+## Translation
+
+### Server Components (preferred)
+
+```tsx
+import { getLocale, getTranslations } from "next-intl/server"
+
+export default async function Page() {
+  const t = await getTranslations("page-namespace")
+  const locale = await getLocale()
+  return <h1>{t("page-title")}</h1>
+}
+```
+
+### Client Components
+
+```tsx
+"use client"
+import { useTranslations } from "next-intl"
+
+export function Widget() {
+  const t = useTranslations("widget-namespace")
+  return <p>{t("widget-description")}</button>
+}
+```
+
+### Never hard-code English
+
+If a string is rendered to a user, it must come from a translation key. The exception is dev-only debug UI (e.g., `AB/TestDebugPanel`) and developer-facing internal copy.
+
+If you find yourself wanting to hard-code, add the key to `src/intl/en/[namespace].json` and use `t()`.
+
+## RTL: Logical CSS Properties
+
+Always use logical equivalents instead of physical directions:
+
+| Don't use | Use instead |
+|---|---|
+| `left-X` | `inset-s-X` |
+| `right-X` | `inset-e-X` |
+| `ml-X` | `ms-X` |
+| `mr-X` | `me-X` |
+| `pl-X` | `ps-X` |
+| `pr-X` | `pe-X` |
+| `border-l` | `border-s` |
+| `border-r` | `border-e` |
+| `text-left` | `text-start` |
+| `text-right` | `text-end` |
+
+Same for arbitrary values: `inset-s-[2rem]`, `me-[1.25rem]`, etc. (Note: prefer the standard spacing scale over arbitrary values regardless of direction -- see `references/spacing-typography.md`.)
+
+### When physical positioning is fine
+
+Only when the position genuinely doesn't depend on reading direction:
+- Centered overlays: `left-1/2 -translate-x-1/2` (centered, not directional)
+- Top/bottom positioning: `top-X`, `bottom-X` (vertical, not directional)
+- Decorative elements that should look the same in LTR and RTL
+
+If you're unsure, default to logical.
+
+## Directional Icons
+
+Right-pointing arrows and chevrons that imply "forward" need to mirror in RTL.
+
+### Pattern: `useRtlFlip`
+
+```tsx
+"use client"
+import { useRtlFlip } from "@/hooks/useRtlFlip"
+import { cn } from "@/lib/utils/cn"
+import { ChevronRight } from "lucide-react"
+
+export function NextLink() {
+  const { twFlipForRtl } = useRtlFlip()
+  return <ChevronRight className={cn("size-4", twFlipForRtl)} />
+}
+```
+
+`twFlipForRtl` returns `"-scale-x-100"` in RTL locales, `""` otherwise.
+
+### Pattern: pre-flipped icons
+
+For the most common directional icons, the project provides RTL-aware wrappers:
+
+```tsx
+import { ChevronNext, ChevronPrev } from "@/components/Chevron"
+```
+
+These automatically flip in RTL. Prefer them over the raw Lucide chevrons.
+
+### Icons that should NOT flip
+
+Some icons are non-directional even when they look it:
+- A "send" airplane icon -- universal, don't flip
+- A "play" triangle -- always points to "next" but conventionally not flipped
+- Spinners, loaders -- circular motion, don't flip
+- Anything with built-in mirror symmetry
+
+## Locale-Aware Formatting
+
+### Numbers
+
+```tsx
+import { numberFormat } from "@/lib/utils/numbers"
+
+const formatted = numberFormat(locale, { maximumFractionDigits: 2 }).format(1234.5678)
+// In Urdu: "۱٬۲۳۴٫۵۷"  (uses arabext numerals)
+// In Arabic and other locales: "1,234.57"  (latn numerals)
+```
+
+`numberFormat` wraps `Intl.NumberFormat` with the right numbering system rules: Urdu (`ur`) uses `arabext`; everything else uses `latn`. (Arabic does NOT use `arab` numerals in this project.)
+
+**Never use** `Intl.NumberFormat` or `value.toLocaleString()` directly -- they don't enforce the project's numbering-system rules.
+
+### Dates
+
+```tsx
+import { dateTimeFormat } from "@/lib/utils/date"
+
+const formatted = dateTimeFormat(locale, { dateStyle: "medium" }).format(new Date())
+// Handles calendar (Hijri for Arabic), numbering system, locale-correct ordering
+```
+
+**Never use** `Intl.DateTimeFormat`, `.toLocaleDateString()`, or `.toLocaleTimeString()` directly.
+
+## Language-Specific Behaviors
+
+### Code blocks force LTR globally
+
+`base.css` includes:
+
+```css
+pre:has(code) {
+  direction: ltr;
+  text-align: left;
+}
+```
+
+Code is always read LTR, even inside an RTL document. Don't fight this -- it's intentional. If you need to override the direction of a non-code element inside an RTL context, use `dir="ltr"` explicitly.
+
+### Urdu uses native numerals for ordered lists
+
+`base.css` lines 97-107:
+
+```css
+:lang(ur) ol {
+  list-style-type: urdu;
+  /* Persian fallback */
+}
+```
+
+Triggered by `:lang(ur)`, not `dir`. Don't override this in components.
+
+### Verbose languages can overflow
+
+German, Spanish, French, and others can produce significantly longer strings than English. Avoid:
+- Fixed widths on text containers
+- `whitespace-nowrap` on UI labels (unless it's part of the design intent and you've tested across locales)
+- Heading sizes without responsive breakpoints
+
+Test with the language picker; the dev server supports locale switching.
+
+## BiDi (Bidirectional) Text Handling
+
+When inserting LTR-only chunks (numbers, units, math expressions, code identifiers, URLs) into a paragraph that may render in an RTL locale, the chunk can flip or scramble unless explicitly marked.
+
+For markdown content, the `intl-pipeline` handles BiDi wrapping automatically. **For React components rendering mixed-direction text, you need to wrap the LTR-only chunks yourself.**
+
+### Pattern
+
+```tsx
+// Number with unit: "5.6 GB" should always read left-to-right, even in RTL paragraph
+<p>{t("storage-line", { size: <span dir="ltr">5.6 GB</span> })}</p>
+
+// Math expression: "2 + 2 = 4"
+<span dir="ltr">2 + 2 = 4</span>
+
+// Code identifier in prose: "the function calculateGas() returns..."
+<span dir="ltr">calculateGas()</span>
+```
+
+### When to wrap
+
+- Numbers with units (`5.6 GB`, `100 ETH`, `42°F`)
+- Math expressions
+- Code/identifier references in prose
+- URLs displayed inline
+- Any LTR-only token that might end up adjacent to RTL-locale text
+
+### When NOT to wrap
+
+- Pure-text content -- it'll inherit the document direction correctly
+- Numbers used purely for display (e.g., a stat in a `BigNumber`) where the surrounding context is also a number; the formatter handles direction
+- Inside `<pre>` / `<code>` blocks -- already force-LTR by `base.css`
+
+## Translatable Strings: Where They Go
+
+### UI strings (buttons, labels, alerts, placeholders)
+
+`src/intl/[locale]/[namespace].json` -- managed via Crowdin.
+
+When adding a new key:
+1. Add to `src/intl/en/[namespace].json` (English source of truth)
+2. The translation pipeline picks it up
+3. Reference via `t("namespace.key")` (where namespace is the file basename)
+
+### Markdown content
+
+`public/content/translations/[locale]/[path]` -- one tree per language.
+
+**Don't manually edit non-English markdown files.** The intl-pipeline propagates English changes; manual edits get overwritten.
+
+### Heading IDs
+
+H1-H4 headings in markdown require a custom `{#lower-kebab-id}`. Enforced by markdownlint pre-commit hook. Run `pnpm lint:md:fix` to auto-add.
+
+## Common Mistakes
+
+- Using `left-`/`right-`/`ml-`/`mr-`/`pl-`/`pr-` for layout (use logical equivalents)
+- Hard-coding English in JSX
+- `value.toLocaleString()` -- use `numberFormat()`
+- `new Date().toLocaleDateString()` -- use `dateTimeFormat()`
+- Right-pointing chevrons without `useRtlFlip` (or use `ChevronNext` from `@/components/Chevron`)
+- Manually editing translated markdown files -- let the pipeline propagate
+- Adding `whitespace-nowrap` without considering verbose-language overflow
diff --git a/.claude/skills/design-system/references/new-component-checklist.md b/.claude/skills/design-system/references/new-component-checklist.md
new file mode 100644
index 00000000000..47ab08d0071
--- /dev/null
+++ b/.claude/skills/design-system/references/new-component-checklist.md
@@ -0,0 +1,226 @@
+# New Component Checklist
+
+Use before opening a PR that introduces a new UI component.
+
+## Step 0: Should this even be a new component?
+
+Before writing a new file, run through `references/variant-vs-new.md`. The answer is usually "add a variant to an existing primitive." A new component file should encapsulate *fundamentally different behavior*, not just different styling.
+
+If you've justified the new file, continue.
+
+## Where Does It Live?
+
+| Use scope | Location |
+|---|---|
+| UI primitive, reusable anywhere on the site | `src/components/ui/` |
+| shadcn-regenerable primitive | `src/components/ui/` (mixed with custom; that's OK) |
+| Reused across many pages | `src/components/ComponentName/index.tsx` |
+| Reused across a sub-tree (e.g. `/community/**`), or required as a separate file due to client-side needs | `_components/` directory inside that page folder (e.g. `app/[locale]/community/_components/`) |
+| Used only ONCE | Inline in the page file -- don't extract |
+| Markdown shortcode | Add to `src/components/MdComponents/` |
+
+**Default to inlining single-use JSX in the page file.** A separate component file is justified by *reuse* or by a *technical need* (client-component split, hook isolation), not by length.
+
+## File Structure
+
+```
+src/components/ui/MyComponent.tsx          # Single-file component
+src/components/ui/MyComponent.stories.tsx  # Storybook story (REQUIRED for ui/)
+```
+
+For complex components with sub-parts, use a directory:
+
+```
+src/components/MyComponent/
+  index.tsx
+  MyComponent.stories.tsx
+  SubComponent.tsx
+  useMyComponent.ts  (if there's a custom hook)
+```
+
+## Implementation Conventions
+
+### TypeScript
+
+```tsx
+// Props extending HTML attributes (for UI primitives that wrap a single element):
+type MyComponentProps = React.ComponentPropsWithoutRef<"div"> & {
+  customProp: string
+} & VariantProps<typeof myComponentVariants>
+
+// Or use ComponentPropsWithRef if forwarding refs:
+type MyComponentProps = React.ComponentPropsWithRef<"div"> & { ... }
+
+// Standalone interface for feature components that don't wrap a single HTML element:
+interface MyFeatureProps {
+  data: SomeDataType
+  className?: string
+}
+```
+
+**Rules**:
+- All visible components MUST accept `className?: string`. Non-negotiable for composability.
+- Don't use `React.FC<Props>` -- function declarations are preferred.
+- Don't `Omit` from HTML attributes unless you genuinely need to.
+
+### Variant Pattern: `tailwind-variants` (`tv`)
+
+```tsx
+import { tv, type VariantProps } from "tailwind-variants"
+
+const myComponentVariants = tv({
+  base: "rounded-lg border p-4",
+  variants: {
+    variant: {
+      default: "bg-background text-body",
+      outline: "border-2 border-primary bg-transparent",
+    },
+    size: {
+      sm: "p-2 text-sm",
+      md: "p-4 text-md",
+      lg: "p-6 text-lg",
+    },
+  },
+  defaultVariants: { variant: "default", size: "md" },
+})
+```
+
+Don't use `cva` for new components. (Existing `cva` components are not being migrated.)
+
+### `cn` for className merging
+
+```tsx
+import { cn } from "@/lib/utils/cn"
+
+return <div className={cn(myComponentVariants({ variant, size }), className)} {...props} />
+```
+
+### `forwardRef` (when applicable)
+
+Use `forwardRef` when:
+- The component wraps a single interactive HTML element (button, input, anchor)
+- It wraps a Radix primitive that accepts refs
+- It needs to participate in focus management
+
+```tsx
+const MyComponent = React.forwardRef<HTMLDivElement, MyComponentProps>(
+  ({ className, variant, size, ...props }, ref) => {
+    return (
+      <div
+        ref={ref}
+        className={cn(myComponentVariants({ variant, size }), className)}
+        {...props}
+      />
+    )
+  }
+)
+MyComponent.displayName = "MyComponent"
+```
+
+Don't use `forwardRef` on:
+- Feature/business components (they aren't composed into other UI)
+- Pure layout components (Flex, Stack) unless they need DOM measurement
+
+## Server vs Client
+
+Default to Server Component. Only mark `"use client"` if you genuinely need:
+- `useState` / `useReducer` / `useEffect`
+- Browser APIs (`window`, `document`, `localStorage`)
+- Inline event handlers (`onClick`, `onChange`, etc.)
+- Context consumers for client-only context
+
+See `references/server-vs-client.md` for boundary patterns.
+
+## Internationalization
+
+- All user-facing text comes from `t()` -- never hard-code English.
+- Number formatting via `numberFormat()` from `@/lib/utils/numbers`.
+- Date formatting via `dateTimeFormat()` from `@/lib/utils/date`.
+- Spacing/positioning uses logical CSS (`start-`, `end-`, `ms-`, `me-`, `ps-`, `pe-`).
+- Directional icons use `useRtlFlip` (or the project's `ChevronNext` / `ChevronPrev`).
+
+See `references/i18n-rtl.md`.
+
+## Accessibility
+
+- Semantic HTML first (`<button>`, `<a>`, `<nav>`, etc., or the project's primitives).
+- Icon-only interactive elements need `aria-label`.
+- Images: `alt=""` only for purely decorative; otherwise describe.
+- Heading hierarchy: one `<h1>` per page; don't skip levels.
+- Use Radix primitives where they exist -- they handle focus, ARIA, keyboard for free.
+
+See `references/a11y.md`.
+
+## Storybook Story (REQUIRED for `ui/`)
+
+```tsx
+// src/components/ui/MyComponent.stories.tsx
+import type { Meta, StoryObj } from "@storybook/nextjs"
+import { MyComponent } from "."
+
+const meta = {
+  title: "UI / MyComponent",
+  component: MyComponent,
+} satisfies Meta<typeof MyComponent>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {}
+
+export const Variants: StoryObj = {
+  render: () => (
+    <div className="flex gap-4">
+      <MyComponent variant="default" />
+      <MyComponent variant="outline" />
+    </div>
+  ),
+}
+```
+
+Title hierarchy:
+- `UI / Primitives / [Name]` -- shadcn-regenerable
+- `UI / [Name]` -- custom project primitives
+- `Components / [Name]` -- feature components
+- `Layouts / [Name]` -- layout components
+
+## Pre-Merge Checklist
+
+### Implementation
+- [ ] Component justifies its existence (not just a variant of an existing one)
+- [ ] Lives in the correct directory
+- [ ] Accepts `className?: string`
+- [ ] Uses `tv()` for variants (not `cva`)
+- [ ] Uses `cn()` for className merging
+- [ ] `forwardRef` if appropriate (and not if not)
+- [ ] No raw color hex / `rgb()` -- semantic tokens only
+- [ ] No `left-`/`right-`/`ml-`/`mr-`/`pl-`/`pr-` -- logical equivalents
+- [ ] No raw `<a>` or `<button>` inside -- uses project primitives
+- [ ] No `useColorModeValue` -- Tailwind `dark:` instead
+- [ ] No hard-coded English strings
+- [ ] No `toLocaleString()` / `Intl.*` directly -- locale wrappers
+
+### Server / Client
+- [ ] Server Component unless `"use client"` is genuinely required
+- [ ] If client, the boundary is as deep as possible (not at the top of a page)
+
+### Story
+- [ ] `MyComponent.stories.tsx` exists
+- [ ] Story shows all variants
+- [ ] Title follows the hierarchy convention
+
+### Verification
+- [ ] Renders in light AND dark mode (check Storybook)
+- [ ] Renders in RTL (Arabic) -- spacing, icons, alignment all sensible
+- [ ] Renders in verbose-language (German/Spanish) without overflow
+- [ ] Tab-reachable -- keyboard navigation works
+- [ ] Focus-visible ring shows on keyboard focus (and not mouse)
+- [ ] Screen-reader announces sensibly (test with VoiceOver / NVDA / TalkBack)
+
+### Cleanup
+- [ ] No commented-out code
+- [ ] No `console.log` debug statements
+- [ ] No TODO comments without an owner / issue link
+- [ ] Type errors clean (`npx tsc --noEmit`)
+- [ ] Lint clean (`pnpm lint`)
+- [ ] Format clean (`pnpm format`)
diff --git a/.claude/skills/design-system/references/page-hero-walkthrough.md b/.claude/skills/design-system/references/page-hero-walkthrough.md
new file mode 100644
index 00000000000..13c2c41c0f9
--- /dev/null
+++ b/.claude/skills/design-system/references/page-hero-walkthrough.md
@@ -0,0 +1,124 @@
+# Walkthrough: "I Need a Page Hero"
+
+A worked example of adding a page hero correctly.
+
+## Step 1: Pick the right Hero variant
+
+`@/components/Hero` exports 5 hero shapes. Pick by what your page needs:
+
+| Hero | When to use |
+|---|---|
+| `ContentHero` | Most internal pages: 2-column with image, breadcrumb, buttons. The workhorse. |
+| `HubHero` | Hub/landing pages: full-bleed background image with overlay text card. |
+| `HomeHero` | Homepage only. Async server component with optimized image loading. |
+| `SimpleHero` | Text-only with breadcrumb + buttons. No image. |
+| `MdxHero` | Long-form articles: minimal breadcrumb + h1, optimized for reading. |
+
+If none of these fit, **stop and ask**. Don't reach for `PageHero` (deprecated). Don't invent a new hero.
+
+## Step 2: Compose
+
+### `ContentHero` (most common)
+
+```tsx
+import { getTranslations } from "next-intl/server"
+import { ContentHero } from "@/components/Hero"
+import heroImage from "@/public/images/topics/proof-of-stake.png"
+
+export default async function Page() {
+  const t = await getTranslations("page-pos")
+  return (
+    <main>
+      <ContentHero
+        breadcrumbs={[
+          { href: "/", label: "Home" },
+          { href: "/topics", label: "Topics" },
+        ]}
+        heroImg={heroImage}
+        header={t("hero-header")}
+        title={t("hero-title")}
+        description={t("hero-description")}
+        buttons={[
+          { content: t("primary-cta"), href: "/about" },
+          { content: t("secondary-cta"), href: "/learn", variant: "outline" },
+        ]}
+      />
+      {/* page content */}
+    </main>
+  )
+}
+```
+
+### `SimpleHero` (text-only)
+
+```tsx
+import { SimpleHero } from "@/components/Hero"
+
+<SimpleHero
+  breadcrumbs={[...]}
+  header={t("eyebrow")}
+  title={t("title")}
+  description={t("description")}
+/>
+```
+
+### `MdxHero` (article-style)
+
+```tsx
+import { MdxHero } from "@/components/Hero"
+
+<MdxHero
+  breadcrumbs={[...]}
+  title={t("title")}
+/>
+```
+
+## Step 3: Translation, not English
+
+All user-facing copy in the hero comes from `t()`. Don't hard-code English. Add new keys to `src/intl/en/[page-namespace].json`.
+
+The page above is a Server Component (default), so it uses `getTranslations` from `next-intl/server`. Don't add `"use client"` to use `useTranslations` -- the hero primitives handle their own client boundaries where needed.
+
+## Step 4: Image
+
+- Use a static import (`import heroImage from "@/public/..."`) so Next.js can optimize at build time
+- Pass the imported `StaticImageData` directly: `heroImg={heroImage}` (not as an object)
+- The hero component handles `next/image` internals -- you don't need to render `<Image>` yourself
+- Hero images are decorative -- the component renders them with `alt=""`. Don't pass alt text; hero illustrations on this site don't carry content that needs description
+
+## What NOT to Do
+
+```tsx
+// DON'T: Use deprecated PageHero
+import PageHero from "@/components/PageHero"
+<PageHero ... />
+```
+
+```tsx
+// DON'T: Inline a hero from scratch
+<section className="relative">
+  <h1 className="mt-8 mb-4 text-md uppercase font-normal">{eyebrow}</h1>
+  <h2 className="mt-8 mb-0 text-[2.5rem] !leading-xs font-bold lg:mt-12 lg:text-5xl">{title}</h2>
+  <p className="mt-4 mb-8 text-xl !leading-xs lg:text-2xl">{description}</p>
+  <div className="flex gap-4">{buttons}</div>
+</section>
+```
+
+Reasons it's wrong:
+- Arbitrary `text-[2.5rem]` and `!important` overrides are fragile
+- No breadcrumb
+- No hero image handling
+- Won't be visually consistent with other hero pages
+- Loses the heading hierarchy (`<h2>` should be `<h1>`)
+
+## Pre-Merge Checklist for a New Page Hero
+
+- [ ] Imports from `@/components/Hero` (NOT `@/components/PageHero`)
+- [ ] Picks the right Hero variant for the page type
+- [ ] All copy comes from `t()` -- no hard-coded English
+- [ ] Hero image is passed as a static import (`heroImg={heroImage}`)
+- [ ] Breadcrumbs are populated (most pages should have them)
+- [ ] Tested in light + dark mode
+- [ ] Tested in RTL locale (Arabic) -- text alignment, button order, image placement all sensible
+- [ ] Tested in verbose-language (German) -- title doesn't overflow
+- [ ] Page is a Server Component (no `"use client"` unless required)
diff --git a/.claude/skills/design-system/references/server-vs-client.md b/.claude/skills/design-system/references/server-vs-client.md
new file mode 100644
index 00000000000..35663a820f2
--- /dev/null
+++ b/.claude/skills/design-system/references/server-vs-client.md
@@ -0,0 +1,102 @@
+# Server vs Client Components (Project-Specific)
+
+Default to Server Components. The agent already knows the React Server Components rules; this reference focuses on this codebase's patterns and the boundaries that already exist.
+
+## Boundaries Established by Existing Primitives
+
+These primitives are already `"use client"`. Importing them into a Server Component still works -- the client boundary lives at the primitive, not at your component. So this is fine in a Server Component:
+
+```tsx
+import { Card, CardContent, CardTitle } from "@/components/ui/card"
+import Modal from "@/components/ui/dialog-modal"
+
+export default async function Page() {
+  const t = await getTranslations()
+  return (
+    <Card href="/about">
+      <CardContent>
+        <CardTitle>{t("title")}</CardTitle>
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+`Card` itself isn't `"use client"` -- but it imports `BaseLink`, which is. The boundary establishes there. Your page stays server.
+
+Primitives that handle their own client boundary:
+
+- `Button` / `ButtonLink` (click tracking + scrollIntoView)
+- `InlineLink` / `BaseLink` (`usePathname` + tracking)
+- `Avatar` (image-error state)
+- `Tooltip` (mobile detection, scroll-close)
+- `Modal` / `Dialog` / `Sheet` / `Drawer` / `Popover` / `DropdownMenu` / `Select` (open state)
+- `Tabs`, `Accordion`, `TabNav` (active-state)
+- `Carousel`, `Swiper`, `TerminalTypewriter`, `TruncatedText` (animation/state)
+- `LinkBox` / `LinkOverlay`, `PersistentPanel` (interaction state)
+
+## Translation Boundary
+
+`useTranslations` (client) and `getTranslations` (server) serve the same purpose for content. **Don't mark a file `"use client"` just to use `useTranslations`.** Restructure: keep the parent server, let it call `getTranslations`, pass the translated strings down as props.
+
+The `t()` functions returned by these are *similar but not strictly equivalent* -- variable interpolation, ICU pluralization, and rich-text/htmr patterns can behave differently between server and client paths. If a change touches both, test both. Don't assume swapping `useTranslations` for `getTranslations` (or vice versa) is a no-op.
+
+### Existing SSR variants for translation-only client splits
+
+Several components have `*SSR` variants explicitly to keep parent pages server-side:
+
+| Client | SSR equivalent (preferred) |
+|---|---|
+| `Callout.tsx` | `CalloutSSR.tsx` |
+| `CalloutBanner.tsx` | `CalloutBannerSSR.tsx` (canonical; older variant deprecated) |
+
+Use the SSR version whenever the parent can do the translation work via `getTranslations`.
+
+## Patterns Worth Knowing
+
+### Extract the small interactive island
+
+If a page is mostly static with one interactive piece, keep the page server and extract the island as a separate client component. Don't mark the whole page `"use client"`.
+
+```tsx
+// app/[locale]/page.tsx -- Server Component
+import { ClientWidget } from "./client-widget"
+
+export default async function Page() {
+  const t = await getTranslations()
+  return (
+    <main>
+      <h1>{t("title")}</h1>
+      <p>{t("description")}</p>
+      <ClientWidget />  {/* Only this becomes client */}
+    </main>
+  )
+}
+```
+
+```tsx
+// app/[locale]/client-widget.tsx
+"use client"
+import { useState } from "react"
+export function ClientWidget() { /* ... */ }
+```
+
+### Server Components can be `async`
+
+Use this for data fetching at render time. Don't fetch in `useEffect` from a Server Component candidate.
+
+```tsx
+export default async function Page() {
+  const data = await getSomeData()
+  return <SomethingThatUsesData data={data} />
+}
+```
+
+## Common Mistakes in This Codebase
+
+- **`Callout` instead of `CalloutSSR`** when parent could be server
+- **`CalloutBanner` instead of `CalloutBannerSSR`** (the latter is canonical post-cva)
+- **`useEffect` data fetching** in a component that could be a Server Component
+- **`"use client"` at the top of a page** when only a small subtree is interactive
+- **`useTranslations` in a leaf component** instead of restructuring so the parent uses `getTranslations`
+- **`useColorModeValue`** (Chakra leftover) -- use Tailwind `dark:` variant instead
diff --git a/.claude/skills/design-system/references/spacing-typography.md b/.claude/skills/design-system/references/spacing-typography.md
new file mode 100644
index 00000000000..3dc785e7433
--- /dev/null
+++ b/.claude/skills/design-system/references/spacing-typography.md
@@ -0,0 +1,170 @@
+# Spacing & Typography
+
+The most common source of "one-off styling" in this codebase is ad-hoc spacing and heading sizing decisions. This reference centralizes the canonical patterns so you don't reinvent them per-page.
+
+## Heading Sizes
+
+Headings (`<h1>`-`<h6>`) are styled by `src/styles/base.css` element defaults. **Just write the semantic tag.** Don't reinvent with `<div className="text-Xxl font-bold">`.
+
+| Tag | Default sizing | When to use |
+|---|---|---|
+| `<h1>` | `text-4xl lg:text-5xl font-bold` | Page title -- ONE per page |
+| `<h2>` | `text-3xl lg:text-4xl font-bold` | Top-level section title |
+| `<h3>` | `text-2xl lg:text-3xl font-bold` | Subsection title |
+| `<h4>` | `text-xl lg:text-2xl font-bold` | Sub-subsection title |
+| `<h5>` | `text-lg font-bold` | Small heading |
+| `<h6>` | `text-base font-bold` | Smallest heading; also used in `Alert`/`Callout` titles |
+
+### Overrides
+
+If you need a heading at a different size (because the design calls for it), override on the element:
+
+```tsx
+<h2 className="text-4xl lg:text-5xl">A larger h2</h2>
+```
+
+Don't override structurally (e.g., using `<h1>` for an `<h3>`-sized element just to get the size). Heading hierarchy matters for screen readers.
+
+### Skip-level prevention
+
+Don't go from `<h2>` to `<h4>`. Screen reader users navigate by heading level, and gaps confuse the structure. If you need a smaller-looking heading, use the right level and override the size class.
+
+### Hero "title" vs "header"
+
+Several `Hero/*` components use:
+- `header` -- a small uppercase eyebrow (often rendered as `<h1>` for SEO; this is intentional in `HubHero`)
+- `title` -- the visible large title
+- `description` -- the lead paragraph
+
+Don't conflate these. Pass the right field to the Hero variant. See `references/page-hero-walkthrough.md`.
+
+### The "page title" gap
+
+There's a recurring `text-[2.5rem]` arbitrary value used in `MdComponents` and `SimpleHero` for in-article page titles. This is a known gap pending a `--text-page-title` token decision. Until that lands, the arbitrary value is the convention; don't reinvent your own page-title size.
+
+## Spacing Scale
+
+Tailwind v4 generates the full spacing scale automatically, including fractional values. You can use `mt-3.5` (14px), `mt-7.5` (30px), `inset-s-3.75` (15px), etc. without anything extra in `theme.css`. **Avoid nit-picky granularity** -- `mt-8` is good, `mt-9` is rarely worth it. Stick to common increments unless the design genuinely calls for a fractional value.
+
+Common increments: `0`, `0.5` (2px), `1` (4px), `2` (8px), `3` (12px), `4` (16px), `6` (24px), `8` (32px), `12` (48px), `16` (64px), `20`, `24`, `32`, `48`, `64` ...
+
+If you do need a fractional value, prefer scale syntax over arbitrary syntax. See "Arbitrary Values" in `references/tokens.md` for the priority order.
+
+### Common patterns
+
+| Use case | Class |
+|---|---|
+| Tight inline spacing (icon-text gap) | `gap-2` (8px) |
+| Default item spacing in a list | `gap-4` (16px) |
+| Between major content elements | `gap-6` or `gap-8` |
+| Between content blocks within a section | `gap-12` (48px) or `gap-16` (64px) |
+| Between sections on a page | `gap-16` to `gap-24` (64-96px) |
+| Section padding (vertical) | `py-16` to `py-24` |
+| Container horizontal padding | Handled by `Section`/page layout, not per-component |
+
+These are heuristics, not rules. Match what surrounding components use rather than picking arbitrarily.
+
+### Stack over `space-y-*`
+
+Prefer the project's `Stack` primitive over `space-y-X` classes:
+
+```tsx
+// Less consistent:
+<div className="flex flex-col space-y-4">{children}</div>
+
+// More consistent:
+import { Stack } from "@/components/ui/flex"
+<Stack className="gap-4">{children}</Stack>
+```
+
+`Stack` defaults to `flex flex-col gap-2`. It also has a `separator` prop:
+
+```tsx
+<Stack separator={<Divider />}>{items}</Stack>
+```
+
+`HStack` (`flex-row items-center`) and `VStack` (`flex-col items-center`) are also available.
+
+### `Section` for page-level padding
+
+`@/components/ui/section` handles the `<section>` wrapper with appropriate scroll-margin (so sticky-nav doesn't clip the heading when navigating to anchors). Use it for top-level page sections instead of writing your own `<section className="...">` chain.
+
+## Logical Spacing for RTL
+
+Always use logical equivalents for direction-dependent spacing:
+
+| Don't use | Use instead |
+|---|---|
+| `ml-X` | `ms-X` |
+| `mr-X` | `me-X` |
+| `pl-X` | `ps-X` |
+| `pr-X` | `pe-X` |
+| `border-l` | `border-s` |
+| `border-r` | `border-e` |
+| `text-left` | `text-start` |
+| `text-right` | `text-end` |
+| `left-X` | `inset-s-X` |
+| `right-X` | `inset-e-X` |
+
+Same for arbitrary values: `inset-s-[12px]`, `me-[2rem]`.
+
+Vertical (`top-`, `bottom-`, `mt-`, `mb-`, `pt-`, `pb-`) is fine -- it's not direction-dependent.
+
+## Breakpoints (Non-Default)
+
+The project resets Tailwind defaults. From `src/styles/theme.css`:
+
+| Token | Value | Common use |
+|---|---|---|
+| `sm` | 480px | Mobile landscape / large phone |
+| `md` | 768px | Tablet |
+| `lg` | 992px (NOT Tailwind's 1024px) | Desktop |
+| `xl` | 1280px | Wide desktop |
+| `2xl` | 1536px | Ultra-wide |
+
+Mobile-first: write base styles for mobile, layer responsive prefixes (`sm:`, `md:`, `lg:`) for larger screens.
+
+Most components need at most 2-3 breakpoint tiers. If you find yourself writing 4+ responsive variants, the component is doing too much -- decompose.
+
+## Typography Scale
+
+Tailwind text size utilities. Pair with leading utilities (`leading-base`, `leading-tight`, etc.).
+
+| Class | Size | Common use |
+|---|---|---|
+| `text-2xs` | 10px | Fine print, tags |
+| `text-xs` | 12px | Tags, captions, helper text |
+| `text-sm` | 14px | Secondary body, button labels (sm) |
+| `text-base` | 16px | Body text default |
+| `text-md` | 18px | Slightly emphasized body |
+| `text-lg` | 20px | Lead paragraphs, h5 |
+| `text-xl` | 24px | h4 (mobile) |
+| `text-2xl` | 28px | h3 (mobile), h4 (desktop) |
+| `text-3xl` | 32px | h2 (mobile), h3 (desktop) |
+| `text-4xl` | 40px | h1 (mobile), h2 (desktop) |
+| `text-5xl` | 48px | h1 (desktop) |
+| `text-6xl` / `text-7xl` | 56-72px | Special: `HomeHero` only |
+
+Use semantic tokens (`text-body`, `text-body-medium`, `text-body-light`, `text-primary`, etc.) for color. See `references/tokens.md`.
+
+### Don't mix arbitrary text sizes
+
+`text-[2.5rem]`, `text-[1.125rem]`, etc. should be a last resort. They bypass the responsive scale and get inconsistent across the site. If a design calls for a size that isn't in the scale, raise it as a design question rather than baking the arbitrary value into a component.
+
+## Arbitrary Values
+
+Quick rule: prefer scale syntax over arbitrary syntax even for fractional values. See `references/tokens.md` for the full discussion. For grid templates specifically, check the existing custom `grid-cols-*` utilities (`grid-cols-bento`, `grid-cols-fill-N`, `grid-cols-fit-4`) before reaching for arbitrary track sizes -- documented in `tokens.md` under "Custom Utilities -- Grid templates."
+
+## Common One-Off Styling Anti-Patterns
+
+These are the recurring patterns that cause "every page looks slightly different":
+
+1. **Inline `<div className="flex flex-col gap-4">` chains** -- use `Stack`
+2. **Custom card shells with hand-picked padding/border/radius** -- use `Card`
+3. **`<p className="text-Xxl font-bold">` for prominent numbers** -- use `BigNumber`
+4. **`<div className="text-5xl font-bold">` for headings** -- use `<h1>`-`<h6>`
+5. **Page-level `<section className="my-32 py-16 px-4">`** -- use `Section`
+6. **Page-level horizontal padding hand-rolled** -- check the page layout, not the section
+7. **Arbitrary `text-[2.5rem]` for in-article titles** -- known gap; don't add new instances
+
+The pattern: when you reach for arbitrary values or inline class chains, pause and check whether a primitive already does this. The answer is almost always yes.
diff --git a/.claude/skills/design-system/references/tokens.md b/.claude/skills/design-system/references/tokens.md
new file mode 100644
index 00000000000..6d8bdf24166
--- /dev/null
+++ b/.claude/skills/design-system/references/tokens.md
@@ -0,0 +1,241 @@
+# Design Tokens (Tailwind v4, CSS-first)
+
+The project does NOT have a `tailwind.config.ts`. Tokens are defined in CSS using Tailwind v4's `@theme` directive. Anyone reaching for `tailwind.config.ts` is working from outdated info.
+
+## File Layout
+
+`src/styles/global.css` is the single CSS entrypoint. It imports the Tailwind base + project token files in this fixed order:
+
+```
+colors.css            # Foundational palette (raw HSL triplets in CSS vars)
+semantic-tokens.css   # Semantic abstraction layer (light + dark mode mappings)
+theme.css             # @theme inline -- registers tokens into Tailwind utilities
+base.css              # Element defaults (h1-h6 sizing, body, links, code blocks)
+utilities.css         # @utility directives for things @theme can't express
+docsearch.css         # Vendor CSS for the Algolia DocSearch plugin
+```
+
+Order matters: foundational palette -> semantic abstraction -> Tailwind registration -> element defaults -> custom utilities. Don't reorganize without understanding the cascade.
+
+## The Three-Layer Token Architecture
+
+### Layer 1: Foundational Palette (`colors.css`)
+
+Raw color values. HSL triplets stored as CSS custom properties:
+
+```css
+--gray-50: 0 0% 98%;
+--gray-100: 0 0% 96%;  /* TODO: Confirm */
+--purple-600: 264 70% 50%;
+--blue-500: ...;
+```
+
+These are *foundational* -- they don't change with light/dark mode. Reach for them only when a semantic token doesn't exist (rare, and a last resort).
+
+Available palettes: gray (50-950), purple (50-900), blue, pink, teal, yellow, red, green, orange (100/800/900 only), amber-500, cyan-500.
+
+### Layer 2: Semantic Abstraction (`semantic-tokens.css`)
+
+This is where you get colors for Claude-driven work. Light mode in `:root`, dark mode in `.dark`:
+
+```css
+:root {
+  --body: var(--gray-900);
+  --background: var(--gray-50);
+  ...
+}
+.dark {
+  --body: var(--gray-50);
+  --background: var(--gray-900);
+  ...
+}
+```
+
+#### Semantic token catalog
+
+**Text:**
+- `--body` (default text)
+- `--body-medium` (secondary text)
+- `--body-light` (tertiary text)
+- `--body-inverse` (text on dark surfaces)
+
+**Backgrounds:**
+- `--background` (page bg)
+- `--background-highlight`
+- `--background-low`
+- `--background-medium`
+- `--background-high`
+
+**Borders:**
+- `--border`
+- `--border-high-contrast`
+- `--border-low-contrast`
+- `--border-hover`
+
+**Primary:**
+- `--primary`
+- `--primary-high-contrast`
+- `--primary-low-contrast`
+- `--primary-hover`
+- `--primary-visited`
+- `--primary-action`
+- `--primary-action-hover`
+
+**Accents** (used for variation, e.g., `CardBanner background="accent-a"`):
+- `--accent-a` / `--accent-a-hover`
+- `--accent-b` / `--accent-b-hover`
+- `--accent-c` / `--accent-c-hover`
+
+**Status:**
+- `--success` / `--success-light` / `--success-dark` / `--success-border`
+- `--error` / `--error-light` / `--error-dark` / `--error-border`
+- `--warning` / `--warning-light` / `--warning-dark` / `--warning-border`
+
+**Domain-specific:**
+- `--staking-gold` / `--staking-green` / `--staking-blue` / `--staking-red` (with `-fill` variants)
+
+**Gradients & shadows** also live here (`--radial-a`, `--card-gradient`, `--gradient-main`, complex shadows).
+
+### Layer 3: Tailwind Registration (`theme.css`)
+
+The `@theme inline` block registers tokens as Tailwind utilities:
+
+```css
+@theme inline {
+  --color-body: hsla(var(--body));
+  --color-background: hsla(var(--background));
+  ...
+}
+```
+
+`inline` is critical: it tells Tailwind NOT to resolve the variable at build time. The `hsla(var(--body))` call resolves at runtime, which is what makes light/dark mode work via the `.dark` class on a parent.
+
+This file also registers:
+- **Custom breakpoints** (NOT Tailwind defaults):
+  - `sm: 480px`
+  - `md: 768px`
+  - `lg: 992px`  ← non-Tailwind-default
+  - `xl: 1280px`
+  - `2xl: 1536px`
+- **Custom radii**: `--radius-4xl: 2rem`
+- **Animations**: `--animate-spin-30`, `--animate-pulse-light`, `--animate-fade-in`, `--animate-blink`, etc.
+
+> **Spacing**: Tailwind v4 generates fractional spacing classes automatically (e.g., `mt-3.5`, `mt-7.5`, `inset-s-3.75`). The custom `--spacing-7_5`, `--spacing-10_5`, etc. defined in this file may be vestigial from v3 and worth verifying as a cleanup item. Don't rely on the underscore notation -- use the v4 native fractional syntax (`mt-7.5`, not `mt-7_5`).
+
+## Custom Utilities (`utilities.css`)
+
+Things `@theme` can't express are defined as `@utility` directives:
+
+### Named z-index scale
+
+Use these instead of arbitrary `z-[N]` values:
+
+| Utility | Value |
+|---|---|
+| `z-hide` | -1 |
+| `z-base` | 0 |
+| `z-docked` | 10 |
+| `z-dropdown` | 1000 |
+| `z-sticky` | 1100 |
+| `z-banner` | 1200 |
+| `z-overlay` | 1300 |
+| `z-modal` | 1400 |
+| `z-popover` | 1500 |
+| `z-skipLink` | 1600 |
+| `z-toast` | 1700 |
+| `z-tooltip` | 1800 |
+
+### Gradient backgrounds
+
+`bg-gradient-main`, `bg-card-gradient-secondary`, `bg-radial-a`, `bg-ten-year-gradient`. Use these instead of inlining a multi-stop `bg-linear-to-br from-[#...] via-[#...] to-[#...]`.
+
+### Grid templates
+
+`grid-cols-bento`, `grid-cols-fill-3`, `grid-cols-fill-4`, `grid-cols-fill-8`, `grid-cols-fill-10`, `grid-cols-fit-4`. Plus staking-specific grid templates.
+
+### Misc
+
+`underline-offset-3`, `animate-pause`.
+
+## Arbitrary Values: Priority Order
+
+Tailwind v4 lets you bypass the scale with arbitrary syntax (`p-[12px]`, `mt-[1.5rem]`, `inset-s-[8px]`). **Avoid this.** The standard scale and its fractional values cover most needs.
+
+Priority order for spacing/sizing values (best to worst):
+
+1. **Standard scale** -- `mt-3`, `mt-8`, `inset-s-4`. Use whenever possible.
+2. **Fractional scale (v4 native)** -- `mt-3.5`, `inset-s-3.75`. If you genuinely need a fractional value.
+3. **Arbitrary syntax with token-derived values** -- `inset-s-[15px]` is poor when `inset-s-3.75` would do the same thing. Same for `inset-s-[0.875rem]` vs `inset-s-3.5`.
+4. **Arbitrary syntax with novel values** -- last resort, only when nothing else fits.
+
+A `[Xpx]` or `[Xrem]` arbitrary in a className is a red flag. It's almost always a token waiting to be used. Same for arbitrary border, radius, and other values.
+
+The exceptions are genuinely arbitrary cases:
+- `w-[calc(100%-2rem)]` -- calc expressions
+- `aspect-[3/2]` -- aspect ratios that don't have a token
+- `grid-cols-[200px_1fr]` -- but check the custom `grid-cols-*` utilities above first; `grid-cols-bento`, `grid-cols-fill-N`, `grid-cols-fit-4` already exist for common cases
+
+## Dark Mode
+
+Dark mode is class-based. The `@custom-variant dark (&:where(.dark, .dark *))` directive in `global.css` defines the variant. The `.dark` class lives on a parent (typically `<html>` or `<body>`).
+
+To use dark-mode-specific overrides on a property that doesn't have a semantic token:
+
+```tsx
+<div className="bg-white dark:bg-gray-900" />  // OK if no semantic token fits
+<div className="bg-background" />              // Better -- token swaps automatically
+```
+
+The `useColorModeValue` hook (Chakra leftover) is **deprecated**. Don't introduce new uses; replace with `dark:` variants when touching code that has it.
+
+## Element Defaults (`base.css`)
+
+`<body>` automatically gets `bg-background font-body leading-base text-body`. You don't need to repeat these on top-level page wrappers.
+
+Headings (`<h1>` through `<h6>`) get sizing and `font-bold` from `base.css`:
+- `<h1>`: `text-4xl lg:text-5xl`
+- `<h2>`: `text-3xl lg:text-4xl`
+- `<h3>`: `text-2xl lg:text-3xl`
+- `<h4>`: `text-xl lg:text-2xl`
+- `<h5>`: `text-lg`
+- `<h6>`: `text-base`
+
+This means `<h1>Hello</h1>` already looks correct. Writing `<div className="text-5xl font-bold">Hello</div>` is reinventing -- and it loses semantics.
+
+`<a>` tags get `text-primary` + underline + `focus-visible` outline.
+
+`<pre>`, `<code>`, `<kbd>`, `<samp>` get `font-monospace text-base`. Code blocks (`pre:has(code)`) are also force-LTR globally so RTL languages don't flip code.
+
+## Stale shadcn Token Names (DO NOT USE)
+
+These appear in `ui/select.tsx`, `ui/dialog.tsx`, `ui/dropdown-menu.tsx`, `ui/tabs.tsx` but are **NOT defined** in this project's tokens. They're vestigial shadcn defaults from the migration:
+
+- `bg-popover` → use `bg-background-highlight` or appropriate semantic
+- `text-popover-foreground` → `text-body`
+- `bg-accent` / `text-accent-foreground` → use semantic accent tokens
+- `text-muted-foreground` → `text-body-medium`
+- `bg-muted` → `bg-background-medium` or appropriate
+- `focus:ring-ring` → use the project's focus-visible pattern
+- `ring-offset-background` → use `bg-background`
+
+If you're touching one of these primitives, replace the stale tokens. See `cleanup-playbook.md`.
+
+## Where to Add a New Token
+
+Decide based on what you're adding:
+
+- **A new semantic color** → `semantic-tokens.css` (must include both light and dark values), then register in `theme.css`'s `@theme inline` block.
+- **A new gradient** → `utilities.css` as `@utility`. Reference foundational/semantic vars.
+- **A new custom spacing/radius/breakpoint** → `theme.css` (under `@theme inline`).
+- **A foundational color** → `colors.css` (only if a new hue family is being added; rare).
+
+Don't add raw hex values to component className. If a color doesn't exist as a token, add it to the token system first.
+
+## Common Mistakes
+
+- Hard-coding `#hex` or `rgb(...)` in component classes -- use semantic tokens
+- Reaching for `text-gray-900` / `bg-white` -- use `text-body` / `bg-background` so dark mode works
+- Using `z-[10000]` or other arbitrary z-index values -- use the named `z-*` scale
+- Inlining a multi-stop `bg-linear-to-br from-[#...]` -- check `utilities.css` for an existing gradient first
+- Assuming `lg` is `1024px` -- it's `992px` in this project
+- Using `theme()` function in CSS -- deprecated in Tailwind v4; use `var()` references
diff --git a/.claude/skills/design-system/references/variant-vs-new.md b/.claude/skills/design-system/references/variant-vs-new.md
new file mode 100644
index 00000000000..7629067b7e0
--- /dev/null
+++ b/.claude/skills/design-system/references/variant-vs-new.md
@@ -0,0 +1,181 @@
+# Variants vs New Components
+
+When something *close enough* exists, prefer reuse over reinvention. This is the single highest-leverage habit for keeping the codebase DRY and consistent.
+
+## The Three-Tier Hierarchy
+
+When you need new UI, walk this list top-to-bottom and stop at the first match:
+
+1. **Use an existing variant** of the right component. If `Card` already has `decoration="purple-gradient"` and that's what you need, just use it.
+2. **Add a new variant** to the right component. If the right component exists but no existing variant covers the case "closely enough," add a new variant rather than creating a new file. See "When the right component has no variants yet" below if the component isn't already variant-driven.
+3. **New component file** -- only if no existing component is the right shape (different *behavior*, not just different *styling*).
+
+The bar gets higher as you go down. Most "new component" instincts are actually "new variant" instincts in disguise.
+
+## The Decision
+
+Before creating a new component file, ask:
+
+1. **Is there an existing primitive that's close to what I need?** (Card, Button, Alert, Tag, Hero variants)
+2. **Does an existing variant of that primitive cover my case?**
+3. **If not, what's actually different?** (Different colors? Different padding? Different layout? Different content shape?)
+4. **Could that difference be expressed as a variant prop?**
+
+If you can stop at any of those steps, you don't need a new file.
+
+## When a Variant Is the Answer
+
+If your "new component" is mostly:
+
+- A wrapper around an existing primitive with different colors/spacing/layout
+- The same primitive with different content composition
+- A specialization for one specific use case that mostly just changes class names
+
+...it's a variant.
+
+### Example: A new "ghost" card style
+
+**Wrong**: Create `GhostCard.tsx` with the offset-shadow look.
+
+**Right**: Add a `decoration="ghost-shadow"` variant to `Card`. The card primitive already supports composition; the variant just adds the shadow element.
+
+### Example: A horizontal layout for cards
+
+**Wrong**: Create `HorizontalCard.tsx` with `flex items-center gap-8`.
+
+**Right**: Add a `layout="horizontal"` variant to `Card`. Same composition, different flex direction.
+
+### Example: A specialized button
+
+**Wrong**: Create `<DownloadButton>` that wraps `Button` with a download icon.
+
+**Right**: Just use `<Button><Download /> Download</Button>`. If the icon-button pattern is repeated 10+ times, *then* consider a tiny wrapper -- but call it `IconButton` or use `ButtonTwoLines` if it fits.
+
+## When a New Component IS the Answer
+
+A new component is justified when:
+
+- It encapsulates a **different shape of behavior** (e.g., `LinkBox` -- different click semantics, not just styling)
+- It composes **multiple primitives in a domain-specific way** (e.g., `Layer2ProductCard` -- Card + Tag + Avatar + specific data shape)
+- It manages **its own state or effects** that don't belong in a generic primitive
+- It has **a different a11y story** (e.g., `Tooltip` wrapping both `ui/tooltip` for hover AND `ui/popover` for click)
+
+The bar is high. Most "new component" instincts are actually "new variant" instincts in disguise.
+
+## Adding a Variant with `tailwind-variants` (`tv`)
+
+The team prefers `tv` for new and refactored components. (Existing `cva` components are not being migrated -- don't refactor them unless asked, but use `tv` for new work.)
+
+### Pattern
+
+```tsx
+import { tv, type VariantProps } from "tailwind-variants"
+
+const cardVariants = tv({
+  base: "rounded-2xl text-body",
+  variants: {
+    decoration: {
+      none: "",
+      "ghost-shadow": "relative before:absolute before:inset-0 before:translate-x-2 before:translate-y-2 before:bg-background-medium before:rounded-2xl before:-z-10",
+      "purple-gradient": "border border-primary/10 bg-card-gradient-secondary hover:bg-card-gradient-secondary-hover",
+    },
+    layout: {
+      vertical: "flex flex-col",
+      horizontal: "flex flex-row items-center gap-8",
+    },
+  },
+  defaultVariants: {
+    decoration: "none",
+    layout: "vertical",
+  },
+})
+
+type CardProps = React.ComponentPropsWithoutRef<"div"> & VariantProps<typeof cardVariants>
+
+export function Card({ decoration, layout, className, ...props }: CardProps) {
+  return <div className={cn(cardVariants({ decoration, layout }), className)} {...props} />
+}
+```
+
+## When the Right Component Has No Variants Yet
+
+Sometimes the right component is structurally correct, but its styling is hard-coded -- no `tv()` variants exist yet. You need a new visual variation. The wrong move is to create a wrapper component or fork the file. The right move is a backward-compatible refactor:
+
+1. **Refactor the existing component to use `tv()`**, with the current/existing styles becoming the **default variant**. No consumer behavior changes -- everyone using the component without specifying a variant still gets exactly what they had.
+2. **Add the new variant** for the new case. Use it where you need it.
+3. Existing consumers continue to work unchanged. Future consumers can pick from the available variants or contribute new ones.
+
+This pattern preserves backward compatibility while opening the component for extension. Don't introduce variants that *change* default behavior -- the goal is "now-extensible, same baseline."
+
+### Example refactor
+
+```tsx
+// Before -- no variants, single hard-coded style:
+export function MyComponent({ className, ...props }: Props) {
+  return <div className={cn("bg-background p-4 rounded-lg", className)} {...props} />
+}
+
+// After -- introduce tv() with current style as default:
+const myComponentVariants = tv({
+  base: "rounded-lg",
+  variants: {
+    tone: {
+      default: "bg-background p-4",      // existing style preserved as default
+      highlight: "bg-accent-a p-6",      // new variant added
+    },
+  },
+  defaultVariants: { tone: "default" },
+})
+
+type Props = React.ComponentPropsWithoutRef<"div"> & VariantProps<typeof myComponentVariants>
+
+export function MyComponent({ tone, className, ...props }: Props) {
+  return <div className={cn(myComponentVariants({ tone }), className)} {...props} />
+}
+```
+
+All existing `<MyComponent>` usages keep their look. New `<MyComponent tone="highlight">` usages get the new style.
+
+### `tv` features worth knowing
+
+- **`base`** — the always-applied classes
+- **`variants`** — discrete options (one selected at a time)
+- **`compoundVariants`** — apply specific classes only when multiple variants combine ("when `size=sm` AND `variant=outline`, also add ...")
+- **`defaultVariants`** — what's applied when the consumer doesn't specify
+- **`slots`** — for components with multiple parts (used in `Modal`, `Avatar`, `Table`)
+- **`VariantProps<typeof variants>`** — derive the type for prop typing
+
+See `tailwind-variants` docs for slot patterns; the project's `Modal` (`ui/dialog-modal.tsx`) and `Table` (`ui/table.tsx`) are good examples.
+
+## Checklist Before Creating a New Component File
+
+Run through these. If you can't say "yes" to all of them, you should be adding a variant or composing existing primitives instead:
+
+- [ ] **Is the behavior fundamentally different from existing primitives?** (Not just styling.)
+- [ ] **Does it have a name that's not already a variant of an existing thing?** (`Card` with `decoration="ghost"` is not "GhostCard.")
+- [ ] **Will it be reused in multiple places?** (One-off doesn't justify a new file -- inline the JSX.)
+- [ ] **Is its API stable enough to commit to?** (Or is it actually a variant of something in flux?)
+- [ ] **Does it pull its weight?** (More than 50 lines of custom logic, or a complex composition pattern that simplifies callers significantly.)
+- [ ] **Does the team know about it?** (For a new shared primitive, propose it before building.)
+
+## When You Find Inlining
+
+If you're auditing existing code and find a long inline Tailwind chain that reproduces what a primitive already does, the right move is:
+
+1. Replace the inline chain with the primitive (compose, don't inline)
+2. If the primitive doesn't quite fit, *add a variant to the primitive* and use it
+3. **Don't** create a new component file just to wrap the primitive with extra classes
+
+## Examples of Things That Should Be Variants
+
+These are all current candidates for absorption (each is a one-off that could be a variant on an existing primitive):
+
+| Existing one-off | Should be |
+|---|---|
+| `GhostCard.tsx` | `Card` `decoration="ghost-shadow"` |
+| `SubpageCard.tsx` | `Card` `decoration="purple-gradient"` |
+| `HorizontalCard.tsx` | `Card` `layout="horizontal"` |
+| `FloatingCard.tsx` | `Card` `tone="primary-gradient"` |
+| `FeedbackCard.tsx` | `Card` `tone="feedback-gradient"` |
+
+See `cleanup-playbook.md` for the full list of cleanup-track items.

From 43a2d4a460a0c8a0cf2fd24704b2eccb01f883bb Mon Sep 17 00:00:00 2001
From: myelinated-wackerow
 <263208946+myelinated-wackerow@users.noreply.github.com>
Date: Mon, 4 May 2026 14:04:24 -0700
Subject: [PATCH 2/7] docs: point at design-system skill

Update AGENTS.md styling-conventions section to reflect tv-over-cva
preference and add a pointer to the new design-system skill.

Stub docs/ds-implementation.md to redirect at the skill + Storybook;
the previous content (Figma reference, DS V1 epic) is superseded by
the skill but the file is preserved so existing links resolve.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>
---
 AGENTS.md                 |  6 ++-
 docs/ds-implementation.md | 81 ++++++++-------------------------------
 2 files changed, 20 insertions(+), 67 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index f7d2ab37601..c00fc9ca96f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -76,11 +76,13 @@ This is the official Ethereum.org website - a Next.js application that serves as
 ### Styling Conventions
 
 - **Primary approach**: Tailwind CSS utility classes
-- **Component variants**: Use `class-variance-authority` (cva)
+- **Component variants**: Use `tailwind-variants` (`tv`) for new and refactored work. Existing `class-variance-authority` (`cva`) components are not being migrated.
 - **Dynamic classes**: Use `cn()` utility (clsx + tailwind-merge)
-- **Custom properties**: CSS variables in `:root` for theme values
+- **Custom properties**: CSS variables in `src/styles/` for theme values
 - **Responsive design**: Mobile-first approach
 
+For UI work, see the **`design-system` skill** at `.claude/skills/design-system/`. It's the canonical knowledge base for component choices, design tokens, RTL/i18n, server/client boundaries, and the "use a variant, not a new component" pattern.
+
 ## Development Workflows
 
 ### Available Scripts
diff --git a/docs/ds-implementation.md b/docs/ds-implementation.md
index 2b570bcced7..8bbd0eb17ab 100644
--- a/docs/ds-implementation.md
+++ b/docs/ds-implementation.md
@@ -1,65 +1,16 @@
-# DS implementation guide
-
-This document serves as a reference for implementing the new Design System (DS) components and styles defined in the public [Figma file](https://www.figma.com/file/NrNxGjBL0Yl1PrNrOT8G2B/ethereum.org-Design-System).
-
-This work is part of the [Design System implementation epic](https://github.com/ethereum/ethereum-org-website/issues/9546).
-Currently, we are implementing **v1** — you can track remaining tasks [here](https://github.com/ethereum/ethereum-org-website/issues/9548).
-
----
-
-## Basics
-
-* Use **shadcn/ui** components and patterns for all base UI elements.
-  [shadcn/ui documentation](https://ui.shadcn.com/docs/components)
-* Follow **Radix UI** principles for accessibility and composability.
-* Reference base components located in `src/components/ui`.
-* Use **Tailwind CSS utility classes** and DS tokens (spacing, colors, breakpoints) as defined in the Figma file.
-* Read the [Best Practices doc](https://github.com/ethereum/ethereum-org-website/blob/dev/docs/best-practices.md) for examples and additional details.
-
----
-
-**IMPORTANT**
-Follow the new component directory structure:
-
-```markdown
-src/
-└── components/
-····└── ComponentA/
-··········├── index.tsx
-··········├── ComponentA.stories.tsx
-··········└── // Any other files as applicable (utils, child components, useHook, etc.)
-```
-
----
-
-## Component implementation from the DS
-
-If you are implementing:
-
-### 🧩 Base components
-
-*(components that already exist in the [shadcn/ui components list](https://ui.shadcn.com/docs/components), e.g., Button, Input, Alert)*
-
-* Do **not** create a new component file under `/ComponentA/index.tsx` unless additional or custom logic is required.
-* Extend or style base components in `src/components/ui`.
-* Use Tailwind and `class-variance-authority` (`cva`) for managing variants and states.
-* Create a `.stories.tsx` file under `src/components/BaseStories` for Storybook documentation.
-
-### 🧱 Custom components
-
-*(components not covered by shadcn/ui, e.g., PageHero)*
-
-* Use base `ui` components whenever possible.
-* Keep the structure consistent with the DS and Figma specifications.
-* Avoid re-implementing primitives that already exist in `shadcn/ui` or Radix UI.
-
----
-
-## Stories
-
-Each created or adapted component must include a corresponding Storybook story.
-
-* Follow the [Storybook integration guide](https://github.com/ethereum/ethereum-org-website/blob/dev/docs/applying-storybook.md)
-* Follow the [proposed Storybook structure](https://www.figma.com/file/Ne3iAassyfAcJ0AlgqioAP/DS-to-storybook-structure)
-
-
+# Design System Implementation
+
+> **This document has been superseded.** See the **`design-system` skill** at [`.claude/skills/design-system/`](../.claude/skills/design-system/) for canonical guidance on:
+>
+> - Component choices and canonical imports
+> - Design tokens (Tailwind v4, CSS-first config)
+> - Component variants and the "use a variant, not a new component" pattern
+> - Server vs Client component boundaries
+> - RTL and internationalization rules
+> - Accessibility patterns
+> - Spacing and typography conventions
+> - Cleanup playbook for migrating from older patterns
+>
+> For visual reference of canonical components, see [Storybook](https://master--63c66e6dffac86afa9e2f25e.chromatic.com/) (running in Chromatic).
+>
+> The skill is the source of truth for any UI work in this repo. This document is preserved as a redirect for stale links.

From 87e874cf4b02832d8e044a8b8bcf3c444cb748ba Mon Sep 17 00:00:00 2001
From: myelinated-wackerow
 <263208946+myelinated-wackerow@users.noreply.github.com>
Date: Mon, 4 May 2026 14:43:25 -0700
Subject: [PATCH 3/7] docs: soften cva-migration phrasing

"Not being migrated" was too declarative -- the actual stance is no
bulk migration, but opportunistic cva-to-tv swaps are fine when you're
already touching the component for another reason. Updated AGENTS.md
and the three skill references that carried the same wording.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>
---
 .claude/skills/design-system/references/gotchas.md              | 2 +-
 .../skills/design-system/references/new-component-checklist.md  | 2 +-
 .claude/skills/design-system/references/variant-vs-new.md       | 2 +-
 AGENTS.md                                                       | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.claude/skills/design-system/references/gotchas.md b/.claude/skills/design-system/references/gotchas.md
index 62d003070b9..eccc66a28a0 100644
--- a/.claude/skills/design-system/references/gotchas.md
+++ b/.claude/skills/design-system/references/gotchas.md
@@ -72,7 +72,7 @@ If you're writing `flex items-center gap-X rounded-Y border bg-... p-Z` to make
 
 ### Using `cva` for new components
 
-The team prefers `tailwind-variants` (`tv`) for new and refactored work. Existing `cva` components are not being migrated -- don't refactor them unless asked. But for *new* components, use `tv`.
+The team prefers `tailwind-variants` (`tv`) for new and refactored work. No bulk migration of existing `cva` components -- swap to `tv` opportunistically when you're touching one for another reason. For *new* components, always use `tv`.
 
 ## Hidden Side Effects
 
diff --git a/.claude/skills/design-system/references/new-component-checklist.md b/.claude/skills/design-system/references/new-component-checklist.md
index 47ab08d0071..2e5d6d55eb5 100644
--- a/.claude/skills/design-system/references/new-component-checklist.md
+++ b/.claude/skills/design-system/references/new-component-checklist.md
@@ -85,7 +85,7 @@ const myComponentVariants = tv({
 })
 ```
 
-Don't use `cva` for new components. (Existing `cva` components are not being migrated.)
+Don't use `cva` for new components. (No bulk migration of existing `cva` components -- swap opportunistically when touching them for other reasons.)
 
 ### `cn` for className merging
 
diff --git a/.claude/skills/design-system/references/variant-vs-new.md b/.claude/skills/design-system/references/variant-vs-new.md
index 7629067b7e0..9945558123e 100644
--- a/.claude/skills/design-system/references/variant-vs-new.md
+++ b/.claude/skills/design-system/references/variant-vs-new.md
@@ -64,7 +64,7 @@ The bar is high. Most "new component" instincts are actually "new variant" insti
 
 ## Adding a Variant with `tailwind-variants` (`tv`)
 
-The team prefers `tv` for new and refactored components. (Existing `cva` components are not being migrated -- don't refactor them unless asked, but use `tv` for new work.)
+The team prefers `tv` for new and refactored components. No bulk migration of existing `cva` components -- swap to `tv` opportunistically when you're already touching one for another reason. For *new* components, always use `tv`.
 
 ### Pattern
 
diff --git a/AGENTS.md b/AGENTS.md
index c00fc9ca96f..a6d833e8f33 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -76,7 +76,7 @@ This is the official Ethereum.org website - a Next.js application that serves as
 ### Styling Conventions
 
 - **Primary approach**: Tailwind CSS utility classes
-- **Component variants**: Use `tailwind-variants` (`tv`) for new and refactored work. Existing `class-variance-authority` (`cva`) components are not being migrated.
+- **Component variants**: Use `tailwind-variants` (`tv`) for new and refactored work. Existing `class-variance-authority` (`cva`) components don't need bulk migration -- swap to `tv` opportunistically when you're already touching the component for another reason.
 - **Dynamic classes**: Use `cn()` utility (clsx + tailwind-merge)
 - **Custom properties**: CSS variables in `src/styles/` for theme values
 - **Responsive design**: Mobile-first approach

From bbb0e78f3623e61501d1d995b6c7b11afd7b3fbb Mon Sep 17 00:00:00 2001
From: myelinated-wackerow
 <263208946+myelinated-wackerow@users.noreply.github.com>
Date: Mon, 4 May 2026 18:33:09 -0700
Subject: [PATCH 4/7] docs(skills): correct ui/ story file location

ui/ primitive stories live in src/components/ui/__stories__/, not
co-located alongside the source. Update file-structure example,
import path in the story template, and clarify that only feature
components co-locate stories.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>
---
 .../references/new-component-checklist.md          | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/.claude/skills/design-system/references/new-component-checklist.md b/.claude/skills/design-system/references/new-component-checklist.md
index 2e5d6d55eb5..cb49826176d 100644
--- a/.claude/skills/design-system/references/new-component-checklist.md
+++ b/.claude/skills/design-system/references/new-component-checklist.md
@@ -23,12 +23,16 @@ If you've justified the new file, continue.
 
 ## File Structure
 
+For `ui/` primitives: source co-located in `src/components/ui/`, stories under `src/components/ui/__stories__/` (NOT co-located alongside the source). Story files use PascalCase names regardless of source casing.
+
 ```
-src/components/ui/MyComponent.tsx          # Single-file component
-src/components/ui/MyComponent.stories.tsx  # Storybook story (REQUIRED for ui/)
+src/components/ui/
+  my-component.tsx                      # Source
+  __stories__/
+    MyComponent.stories.tsx             # Story (REQUIRED for ui/ primitives)
 ```
 
-For complex components with sub-parts, use a directory:
+For feature components with sub-parts, use a directory and co-locate the story:
 
 ```
 src/components/MyComponent/
@@ -154,9 +158,9 @@ See `references/a11y.md`.
 ## Storybook Story (REQUIRED for `ui/`)
 
 ```tsx
-// src/components/ui/MyComponent.stories.tsx
+// src/components/ui/__stories__/MyComponent.stories.tsx
 import type { Meta, StoryObj } from "@storybook/nextjs"
-import { MyComponent } from "."
+import { MyComponent } from "../my-component"
 
 const meta = {
   title: "UI / MyComponent",

From 46b2e391ce781a3b0a242666c46d2718245ea766 Mon Sep 17 00:00:00 2001
From: myelinated-wackerow
 <263208946+myelinated-wackerow@users.noreply.github.com>
Date: Tue, 5 May 2026 15:29:43 -0700
Subject: [PATCH 5/7] docs(skills): mark Swiper deprecation track explicitly

Consistent with Drawer and Divider headings. Carousel kept ambiguous
pending team discussion.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>
---
 .../design-system/references/components.md      | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/.claude/skills/design-system/references/components.md b/.claude/skills/design-system/references/components.md
index 76981b6aab4..baf002abe17 100644
--- a/.claude/skills/design-system/references/components.md
+++ b/.claude/skills/design-system/references/components.md
@@ -457,13 +457,13 @@ The `product` variant currently has stale shadcn tokens (`hover:bg-muted/50`, `t
 
 ### Horizontal scroll / carousel
 
-Three components exist in this space; only one is recommended for new work:
+Three components exist in this space:
 
 | Component | Status |
 |---|---|
 | `EdgeScrollContainer` (`@/components/ui/edge-scroll-container`) | **Preferred** for new horizontal scroll lists |
-| `Carousel` (`@/components/ui/carousel`) | Not recommended for new work; has unresolved RTL issues |
-| `Swiper` (`@/components/ui/swiper`) | Not recommended for new work; planned for removal |
+| `Carousel` (`@/components/ui/carousel`) | Not recommended for new work; has unresolved RTL issues. Status pending team discussion |
+| `Swiper` (deprecation track) | Don't use for new work; on the path to removal |
 
 `EdgeScrollContainer` is a CSS-driven horizontal scroll with snap and edge mask:
 
@@ -471,7 +471,16 @@ Three components exist in this space; only one is recommended for new work:
 import { EdgeScrollContainer, EdgeScrollItem } from "@/components/ui/edge-scroll-container"
 ```
 
-CSS-var driven (`--edge-spacing`, `--edge-mask-size`, `--edge-overflow-y-pad`). Mask fade only at `2xl+`. The component is being polished further; don't add new `Carousel` or `Swiper` usage in the meantime.
+CSS-var driven (`--edge-spacing`, `--edge-mask-size`, `--edge-overflow-y-pad`). Mask fade only at `2xl+`.
+
+### `Swiper` (deprecation track)
+
+```tsx
+// DON'T use for new work:
+import { Swiper, ... } from "@/components/ui/swiper"
+```
+
+`"use client"`, wraps swiper.js. On the deprecation track. Migrate existing consumers to `EdgeScrollContainer`.
 
 ### `List` / `OrderedList` / `UnorderedList` / `ListItem`
 

From 9981ff6bfeb3bd43de49c0c9e3e99b190a1dc996 Mon Sep 17 00:00:00 2001
From: myelinated-wackerow
 <263208946+myelinated-wackerow@users.noreply.github.com>
Date: Tue, 5 May 2026 17:47:58 -0700
Subject: [PATCH 6/7] docs(skills): drop unused components, add Faq, update
 Callout consolidation

Audit surfaced components that are unused or being deleted; remove
their entries across the skill so the registry stays accurate:

- Remove ButtonTwoLines/ButtonLinkTwoLines (unused, being deleted)
- Remove SvgButtonLink (unused, being deleted)
- Remove Drawer (unused, being deleted)
- Remove Layer2ProductCard references (unused, being deleted)
- Remove RadioGroup from Checkbox/Switch group (being deleted)
- Add Faq (built but never used; should be referenced in registry)

Update Callout / CalloutBanner / BannerNotification / DismissableBanner
sections to point at a planned unified server-renderable Callout
component (tracked in a dedicated issue) instead of treating them as
separate canonical paths.

Drop the specific Callout-to-CalloutSSR migration entry from the
cleanup playbook since the migration target is changing -- the
playbook should hold general patterns, not in-flight refactor
specifics.

Sweep stale references across SKILL.md, a11y.md, canonical-imports.md,
card-walkthrough.md, gotchas.md, server-vs-client.md, variant-vs-new.md.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>
---
 .claude/skills/design-system/SKILL.md         |  2 +-
 .../skills/design-system/references/a11y.md   |  2 +-
 .../references/canonical-imports.md           | 56 +++----------------
 .../references/card-walkthrough.md            |  4 +-
 .../references/cleanup-playbook.md            | 15 -----
 .../design-system/references/components.md    | 54 ++++--------------
 .../design-system/references/gotchas.md       | 12 ++--
 .../references/server-vs-client.md            | 17 ++----
 .../references/variant-vs-new.md              |  4 +-
 9 files changed, 34 insertions(+), 132 deletions(-)

diff --git a/.claude/skills/design-system/SKILL.md b/.claude/skills/design-system/SKILL.md
index 2e523b7de19..857db5c84f0 100644
--- a/.claude/skills/design-system/SKILL.md
+++ b/.claude/skills/design-system/SKILL.md
@@ -57,7 +57,7 @@ Used in 5 places. Don't introduce new uses. Use Tailwind `dark:` variant + seman
 - `<Button isSecondary>` only takes effect on `outline` and `ghost` variants. Silent no-op on `solid`/`link`.
 - `<CardBanner fit="contain">` with a single `<Image>` child auto-clones it as a blurred backdrop. Pass two children and you lose this magic.
 - `LinkBox` requires a `LinkOverlay` somewhere inside; without it, the whole-card-clickable pattern doesn't work.
-- `commonControlClasses` in `ui/checkbox.tsx` is shared by `Switch` and `RadioGroup`. Editing it changes all three.
+- `commonControlClasses` in `ui/checkbox.tsx` is shared by `Switch`. Editing it changes both.
 
 ### No `Heading` primitive -- use semantic tags
 
diff --git a/.claude/skills/design-system/references/a11y.md b/.claude/skills/design-system/references/a11y.md
index 95bf8ce878d..30e396be163 100644
--- a/.claude/skills/design-system/references/a11y.md
+++ b/.claude/skills/design-system/references/a11y.md
@@ -20,7 +20,7 @@ If you find yourself rolling custom focus management or ARIA wiring, stop and ch
 
 Even if it's a small icon-only target, use `<Button variant="ghost" size="sm" aria-label="...">`. Don't reach for `<div role="button" tabIndex={0}>` -- the answer is almost always `Button`.
 
-Examples in current code that need fixing: `SideNavMobile.tsx:88-94`, `BoxGrid.tsx:55-69`.
+Examples in current code that need fixing: `SideNavMobile.tsx:88-94`.
 
 ### Icon-only `Button` needs `aria-label`
 
diff --git a/.claude/skills/design-system/references/canonical-imports.md b/.claude/skills/design-system/references/canonical-imports.md
index 2a6b12b7819..e18e920224a 100644
--- a/.claude/skills/design-system/references/canonical-imports.md
+++ b/.claude/skills/design-system/references/canonical-imports.md
@@ -38,7 +38,7 @@ import Card from "@/components/Card"
 
 This is the legacy card, registered in `MdComponents` for the markdown `<Card>` shortcode. It is reserved for markdown rendering. Importing it from app code is a smell.
 
-### Domain-specific cards exist (`AppCard`, `Layer2ProductCard`, `EthPriceCard`, etc.)
+### Domain-specific cards exist (`AppCard`, `EthPriceCard`, etc.)
 
 These are feature components. Don't reuse them outside their domain.
 
@@ -113,22 +113,6 @@ Variants: `solid | outline | ghost | link` (default `solid`). Sizes: `lg | md |
 
 `isSecondary` flips text/border to body color -- but only applies to `outline` and `ghost`. Setting `isSecondary` on a `solid` or `link` button does nothing (silent no-op).
 
-### Two-line buttons
-
-```tsx
-import { ButtonTwoLines, ButtonLinkTwoLines } from "@/components/ui/buttons/ButtonTwoLines"
-```
-
-Stacked main/helper text with an icon. Restricted to `solid` / `outline` variants and `md` / `sm` sizes.
-
-### SVG-stylized link cards
-
-```tsx
-import { SvgButtonLink } from "@/components/ui/buttons/SvgButtonLink"
-```
-
-Box-shadow halo card with icon + label + description. Variants: `row | col`.
-
 ## Anchors / Links
 
 ```tsx
@@ -201,8 +185,6 @@ import PageHero from "@/components/PageHero"
 
 ## Banners / Callouts / Alerts
 
-These three shapes overlap visually. Pick by *placement* and *purpose*:
-
 ### Inline message in content area: `Alert`
 
 ```tsx
@@ -211,37 +193,15 @@ import { Alert, AlertContent, AlertDescription } from "@/components/ui/alert"
 
 Variants: `info | error | success | warning | update`. Optional `size: "full"` for borderless full-width.
 
-### Top-of-page site-wide stripe: `BannerNotification`
-
-```tsx
-import BannerNotification from "@/components/Banners/BannerNotification"
-```
-
-Full-width `bg-primary-action` stripe. Use for site-wide announcements.
-
-### Dismissable banner: `DismissableBanner`
-
-```tsx
-import DismissableBanner from "@/components/Banners/DismissableBanner"
-```
-
-Wraps `BannerNotification` with localStorage state for "don't show again."
-
-### In-content callout with image + heading: `CalloutBannerSSR`
+### In-content / top-of-page callout: `Callout`
 
-```tsx
-import CalloutBannerSSR from "@/components/CalloutBannerSSR"
-```
-
-Use this, NOT `CalloutBanner.tsx`. The SSR variant uses `cva` with `large | medium | small` sizes and is server-renderable.
-
-### Big ornamental section divider: `CalloutSSR` / `Callout`
-
-```tsx
-import CalloutSSR from "@/components/CalloutSSR"
-```
+> **Migration in progress.** A unified server-renderable `Callout` component is being built that absorbs the current `Callout`/`CalloutSSR`/`CalloutBanner`/`CalloutBannerSSR`/`BannerNotification`/`DismissableBanner` set into a single primitive with variants. Tracked in a dedicated issue.
 
-For the marketing-style large ornamental callouts with image overlap.
+Until the unified `Callout` lands:
+- For **in-content** callouts with image + heading: use `CalloutBannerSSR` (NOT `CalloutBanner.tsx`). Server-renderable; uses `cva` with `large | medium | small` sizes.
+- For **big ornamental section dividers** with image overlap: use `CalloutSSR` (NOT `Callout.tsx`). Server-renderable.
+- For **top-of-page site-wide stripes**: use `BannerNotification` (`@/components/Banners/BannerNotification`). Will be absorbed as a `notification` variant on the unified `Callout`.
+- Avoid `Callout.tsx` and `CalloutBanner.tsx` (client-only thunks; superseded by their SSR siblings and ultimately by the unified component).
 
 ## Tabs / Tab Navigation
 
diff --git a/.claude/skills/design-system/references/card-walkthrough.md b/.claude/skills/design-system/references/card-walkthrough.md
index 754f51b2798..f7fdac37ce5 100644
--- a/.claude/skills/design-system/references/card-walkthrough.md
+++ b/.claude/skills/design-system/references/card-walkthrough.md
@@ -9,7 +9,7 @@ Before reaching for a primitive, name the shape:
 - **A linkable summary card** with title, description, optional image -> `Card`
 - **A whole-card-clickable wrapper for non-card content** (multiple interactive elements inside) -> `LinkBox` + `LinkOverlay`
 - **A skeleton loading placeholder** -> `SkeletonCard`
-- **An app/product listing** -> existing domain-specific component (e.g., `AppCard`, `Layer2ProductCard`) -- only if data shape matches
+- **An app/product listing** -> existing domain-specific component (e.g., `AppCard`) -- only if data shape matches
 - **Markdown shortcode** -- `MdComponents` already wires this up; just use `<Card>` in markdown
 
 ## Step 2: Compose `Card`
@@ -78,7 +78,7 @@ If you're building UI that:
 - Composes Card + Tag + Avatar + specific layout for a recurring product/wallet/network listing
 - Has its own loading/error states
 
-...then a wrapper component makes sense. Look at `Layer2ProductCard` or `AppCard` for the pattern: they compose `Card` underneath and add domain-specific structure on top. Don't reinvent the card shell.
+...then a wrapper component makes sense. Look at `AppCard` for the pattern: it composes `Card` underneath and adds domain-specific structure on top. Don't reinvent the card shell.
 
 ## What NOT to Do
 
diff --git a/.claude/skills/design-system/references/cleanup-playbook.md b/.claude/skills/design-system/references/cleanup-playbook.md
index 8a40782eb67..47897d69695 100644
--- a/.claude/skills/design-system/references/cleanup-playbook.md
+++ b/.claude/skills/design-system/references/cleanup-playbook.md
@@ -233,21 +233,6 @@ Add the new key to `src/intl/en/[namespace].json`.
 
 > **Data fetching patterns** (Server Component data, caching, sources) are out of scope for this design-system skill. See the `data-layer` skill for canonical fetching guidance.
 
-## `Callout` (client) -> `CalloutSSR` (server)
-
-```tsx
-// Before:
-import Callout from "@/components/Callout"
-<Callout title={t("title")} ... />
-
-// After (when the parent can be server):
-import CalloutSSR from "@/components/CalloutSSR"
-const t = await getTranslations()
-<CalloutSSR title={t("title")} ... />
-```
-
-Same applies to `CalloutBanner` -> `CalloutBannerSSR`.
-
 ## `PageHero` -> `ContentHero` (or appropriate Hero variant)
 
 ```tsx
diff --git a/.claude/skills/design-system/references/components.md b/.claude/skills/design-system/references/components.md
index baf002abe17..46f6cd29ede 100644
--- a/.claude/skills/design-system/references/components.md
+++ b/.claude/skills/design-system/references/components.md
@@ -34,36 +34,6 @@ The canonical clickable. `Button` for `<button>`-class actions; `ButtonLink` for
 
 `"use client"` because of click tracking and `scrollIntoView`.
 
-### `ButtonTwoLines` / `ButtonLinkTwoLines`
-
-```tsx
-import { ButtonTwoLines, ButtonLinkTwoLines } from "@/components/ui/buttons/ButtonTwoLines"
-```
-
-Stacked two-line button with icon.
-
-```tsx
-<ButtonTwoLines icon={ChevronRight} mainText="Title" helperText="Subtitle" />
-```
-
-**Variants**: `solid | outline` only
-**Sizes**: `md | sm` only
-
-### `SvgButtonLink`
-
-```tsx
-import { SvgButtonLink } from "@/components/ui/buttons/SvgButtonLink"
-```
-
-Iconic link card with stylized box-shadow halo. Used heavily on docs hubs.
-
-```tsx
-<SvgButtonLink href="/x" Svg={MySvg} label="Title">desc</SvgButtonLink>
-```
-
-**Variants**: `row | col` (default `row`)
-Built with `tv`.
-
 ### `BaseLink` / `InlineLink` / `LinkWithArrow`
 
 ```tsx
@@ -250,15 +220,6 @@ import { PersistentPanel } from "@/components/ui/persistent-panel"
 
 > **Future**: There's an open question about consolidating these two using Radix Dialog's `forceMount` prop for the persistent case. Tracked in the cleanup tracking issue. For now, use them as documented above.
 
-### `Drawer` (deprecation track)
-
-```tsx
-// DON'T use for new work:
-import { Drawer, ... } from "@/components/ui/drawer"
-```
-
-Bottom drawer using `vaul`. **Zero consumers in the codebase.** Marked for removal. Use `Sheet` (with `side="bottom"`) for any new bottom-panel needs.
-
 ### `Popover`
 
 ```tsx
@@ -318,15 +279,14 @@ import { Textarea } from "@/components/ui/textarea"
 
 Same shape as `Input`.
 
-### `Checkbox` / `Switch` / `RadioGroup`
+### `Checkbox` / `Switch`
 
 ```tsx
 import Checkbox from "@/components/ui/checkbox"
 import Switch from "@/components/ui/switch"
-import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
 ```
 
-All three share styling via `commonControlClasses` exported from `checkbox.tsx`. Editing that constant affects all three.
+Both share styling via `commonControlClasses` exported from `checkbox.tsx`. Editing that constant affects both.
 
 ## Display
 
@@ -565,7 +525,15 @@ See `canonical-imports.md` for selection.
 
 ### Banners -- `@/components/Banners`
 
-`BannerNotification`, `DismissableBanner`, `EnvWarningBanner` (exemplary -- thin wrap of `Alert variant="warning"`), `TranslationBanner`, `UpgradeBannerNotification`.
+`BannerNotification` (will be absorbed into the unified `Callout` -- see `canonical-imports.md`), `EnvWarningBanner` (exemplary -- thin wrap of `Alert variant="warning"`), `TranslationBanner`.
+
+### `Faq`
+
+```tsx
+import { Faq, FaqContent, FaqItem, FaqTrigger } from "@/components/Faq"
+```
+
+Compositional FAQ primitive. Stories exist; ready for use in pages that need an expandable Q&A list.
 
 ### `MdComponents`
 
diff --git a/.claude/skills/design-system/references/gotchas.md b/.claude/skills/design-system/references/gotchas.md
index eccc66a28a0..36cbd499324 100644
--- a/.claude/skills/design-system/references/gotchas.md
+++ b/.claude/skills/design-system/references/gotchas.md
@@ -42,9 +42,9 @@ If you pass `<CardBanner fit="contain"><Image .../></CardBanner>` with **one** c
 
 The whole-card-clickable pattern uses a `before:absolute` pseudo-element on `LinkOverlay`. Use `LinkBox` without `LinkOverlay` and the click-the-whole-card behavior breaks.
 
-### `commonControlClasses` in `ui/checkbox.tsx` is shared by Switch and RadioGroup
+### `commonControlClasses` in `ui/checkbox.tsx` is shared by Switch
 
-`Checkbox.tsx` exports a `commonControlClasses` constant that is also imported by `Switch` and `RadioGroup`. Editing it changes all three. If you're adjusting checkbox styling, you're adjusting switches and radios too -- audit all three before merging.
+`Checkbox.tsx` exports a `commonControlClasses` constant that is also imported by `Switch`. Editing it changes both. If you're adjusting checkbox styling, you're adjusting switches too -- audit both before merging.
 
 ### `Stack`'s `separator` prop clones a separator between children
 
@@ -88,9 +88,9 @@ Just be aware which side of the boundary you're on when adding hooks/effects.
 
 Static buttons get unnecessarily forced into client. Splitting would be invasive; for now, just know this is true.
 
-### `Callout.tsx` is `"use client"` only because of `useTranslation`
+### `Callout` and `CalloutBanner` are pending consolidation
 
-There's a `CalloutSSR.tsx` for the server-translated split. Prefer `CalloutSSR` whenever the parent can do the translation work via `getTranslations` (server). Same applies to `CalloutBanner` vs `CalloutBannerSSR`.
+`Callout.tsx`/`CalloutSSR.tsx` and `CalloutBanner.tsx`/`CalloutBannerSSR.tsx` exist as client/server pairs today. A unified server-renderable `Callout` component is being built to absorb both pairs (plus `BannerNotification` and `DismissableBanner`) into a single primitive with variants. While the migration is in flight, prefer the `*SSR` variants when the parent can do translation work via `getTranslations`. Tracked in a dedicated issue.
 
 ### Event tracking is automatic on `Button` and `Link`
 
@@ -152,10 +152,6 @@ Configured in `base.css` lines 97-107. Persian fallback. Triggered by `:lang(ur)
 
 ## Things Not Used Anymore
 
-### `Drawer` (`ui/drawer.tsx`)
-
-Zero consumers in `src/`/`app/`. On the deprecation track. Use `Sheet` (with `side="bottom"` if needed). Don't introduce new `Drawer` usage.
-
 ### `useColorModeValue` (`@/hooks/useColorModeValue`)
 
 Chakra leftover, used in 5 places. Don't introduce new uses. Replace with Tailwind `dark:` variants when touching code that has it.
diff --git a/.claude/skills/design-system/references/server-vs-client.md b/.claude/skills/design-system/references/server-vs-client.md
index 35663a820f2..815c9db10aa 100644
--- a/.claude/skills/design-system/references/server-vs-client.md
+++ b/.claude/skills/design-system/references/server-vs-client.md
@@ -30,7 +30,7 @@ Primitives that handle their own client boundary:
 - `InlineLink` / `BaseLink` (`usePathname` + tracking)
 - `Avatar` (image-error state)
 - `Tooltip` (mobile detection, scroll-close)
-- `Modal` / `Dialog` / `Sheet` / `Drawer` / `Popover` / `DropdownMenu` / `Select` (open state)
+- `Modal` / `Dialog` / `Sheet` / `Popover` / `DropdownMenu` / `Select` (open state)
 - `Tabs`, `Accordion`, `TabNav` (active-state)
 - `Carousel`, `Swiper`, `TerminalTypewriter`, `TruncatedText` (animation/state)
 - `LinkBox` / `LinkOverlay`, `PersistentPanel` (interaction state)
@@ -41,16 +41,9 @@ Primitives that handle their own client boundary:
 
 The `t()` functions returned by these are *similar but not strictly equivalent* -- variable interpolation, ICU pluralization, and rich-text/htmr patterns can behave differently between server and client paths. If a change touches both, test both. Don't assume swapping `useTranslations` for `getTranslations` (or vice versa) is a no-op.
 
-### Existing SSR variants for translation-only client splits
+### Callout / CalloutBanner consolidation
 
-Several components have `*SSR` variants explicitly to keep parent pages server-side:
-
-| Client | SSR equivalent (preferred) |
-|---|---|
-| `Callout.tsx` | `CalloutSSR.tsx` |
-| `CalloutBanner.tsx` | `CalloutBannerSSR.tsx` (canonical; older variant deprecated) |
-
-Use the SSR version whenever the parent can do the translation work via `getTranslations`.
+`Callout.tsx`/`CalloutSSR.tsx` and `CalloutBanner.tsx`/`CalloutBannerSSR.tsx` exist as client/server pairs today. A unified server-renderable `Callout` is being built to absorb both pairs into a single primitive. While the migration is in flight, prefer the `*SSR` variants when the parent can call `getTranslations`. Tracked in a dedicated issue.
 
 ## Patterns Worth Knowing
 
@@ -94,8 +87,8 @@ export default async function Page() {
 
 ## Common Mistakes in This Codebase
 
-- **`Callout` instead of `CalloutSSR`** when parent could be server
-- **`CalloutBanner` instead of `CalloutBannerSSR`** (the latter is canonical post-cva)
+- **`Callout` instead of `CalloutSSR`** when parent could be server (pending the unified `Callout`)
+- **`CalloutBanner` instead of `CalloutBannerSSR`** (same -- the latter is the canonical until consolidation)
 - **`useEffect` data fetching** in a component that could be a Server Component
 - **`"use client"` at the top of a page** when only a small subtree is interactive
 - **`useTranslations` in a leaf component** instead of restructuring so the parent uses `getTranslations`
diff --git a/.claude/skills/design-system/references/variant-vs-new.md b/.claude/skills/design-system/references/variant-vs-new.md
index 9945558123e..dfdd4cc91fe 100644
--- a/.claude/skills/design-system/references/variant-vs-new.md
+++ b/.claude/skills/design-system/references/variant-vs-new.md
@@ -49,14 +49,14 @@ If your "new component" is mostly:
 
 **Wrong**: Create `<DownloadButton>` that wraps `Button` with a download icon.
 
-**Right**: Just use `<Button><Download /> Download</Button>`. If the icon-button pattern is repeated 10+ times, *then* consider a tiny wrapper -- but call it `IconButton` or use `ButtonTwoLines` if it fits.
+**Right**: Just use `<Button><Download /> Download</Button>`. If the icon-button pattern is repeated 10+ times, *then* consider a tiny wrapper -- but call it `IconButton`.
 
 ## When a New Component IS the Answer
 
 A new component is justified when:
 
 - It encapsulates a **different shape of behavior** (e.g., `LinkBox` -- different click semantics, not just styling)
-- It composes **multiple primitives in a domain-specific way** (e.g., `Layer2ProductCard` -- Card + Tag + Avatar + specific data shape)
+- It composes **multiple primitives in a domain-specific way** (e.g., `AppCard` -- Card + Tag + Avatar + specific data shape)
 - It manages **its own state or effects** that don't belong in a generic primitive
 - It has **a different a11y story** (e.g., `Tooltip` wrapping both `ui/tooltip` for hover AND `ui/popover` for click)
 

From deca48a131bd5bfc521df73757aa4731f7256f7b Mon Sep 17 00:00:00 2001
From: myelinated-wackerow
 <263208946+myelinated-wackerow@users.noreply.github.com>
Date: Tue, 12 May 2026 10:35:48 -0700
Subject: [PATCH 7/7] testing(design-system): initial skill evals

Add eval workspaces to .gitignore

Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>
---
 .claude/skills/design-system/evals/evals.json | 76 +++++++++++++++++++
 .gitignore                                    |  3 +
 2 files changed, 79 insertions(+)
 create mode 100644 .claude/skills/design-system/evals/evals.json

diff --git a/.claude/skills/design-system/evals/evals.json b/.claude/skills/design-system/evals/evals.json
new file mode 100644
index 00000000000..ac80fc414f2
--- /dev/null
+++ b/.claude/skills/design-system/evals/evals.json
@@ -0,0 +1,76 @@
+{
+  "skill_name": "design-system",
+  "notes": "Output evals for the design-system skill. Each prompt exercises a distinct high-leverage rule (variant-over-new, canonical imports, i18n/RTL, hero family + server/client, modal disambiguation + raw-element ban).",
+  "evals": [
+    {
+      "id": 1,
+      "name": "variant-over-new-stat-block",
+      "prompt": "hey can you add a little stat block to the bottom of app/[locale]/staking/page.tsx? something like \"$45.2B\" on top in big bold text and \"ETH staked\" underneath. I want it centered. probably just spin up a new component for it, call it StakingStat or something",
+      "expected_output": "Skill should resist the 'new component' framing and steer toward the existing BigNumber primitive (and/or Card composition). Should also flag that user-facing strings need translation and that the number should go through numberFormat() if it isn't a static literal.",
+      "files": [],
+      "assertions": [
+        {"text": "Output uses BigNumber primitive (imports from @/components/BigNumber)"},
+        {"text": "Output does NOT create a new top-level component named StakingStat (or similar) in outputs"},
+        {"text": "All visible English strings ('ETH staked', any label) routed through a next-intl translation function (getTranslations or t())"},
+        {"text": "Output does NOT inline a div with `text-5xl font-bold` (or similar manual size+weight) for the stat number"},
+        {"text": "notes.md explicitly names BigNumber (and/or Card) as the chosen primitive and explains the pushback on the user's 'new component' framing"}
+      ]
+    },
+    {
+      "id": 2,
+      "name": "tooltip-canonical-import",
+      "prompt": "the \"Bridge\" button in src/components/Nav/Mobile/index.tsx needs a little info tooltip on hover explaining what bridging is. can you wire that up? grab whatever tooltip the project uses",
+      "expected_output": "Skill should pick the high-level Tooltip default export from @/components/Tooltip (mobile-aware, Matomo-tracked, scroll-close) and explicitly NOT import { Tooltip } from @/components/ui/tooltip (which is the bare Radix primitive). Translatable copy expected.",
+      "files": [],
+      "assertions": [
+        {"text": "Output imports Tooltip from `@/components/Tooltip` (the mobile-aware default export)"},
+        {"text": "Output does NOT import from `@/components/ui/tooltip` (which is the bare Radix primitive)"},
+        {"text": "Tooltip content text is routed through a next-intl translation function (not a hard-coded English literal)"},
+        {"text": "notes.md justifies the Tooltip import choice and references the mobile-aware/Matomo-tracked rationale"}
+      ]
+    },
+    {
+      "id": 3,
+      "name": "i18n-rtl-and-number-format",
+      "prompt": "on the contributors page (app/[locale]/contributing/page.tsx) i want to show \"There are 3,847 open issues right now\" with the number in bold. put it in a div with ml-4 mt-6 so it sits indented under the section heading. the count comes from a `count` variable thats already in scope",
+      "expected_output": "Skill should: (a) replace ml-4 with logical ms-4 (RTL safety), (b) replace the hard-coded English string with a getTranslations call and translation key, (c) format the count with numberFormat() rather than toLocaleString or a raw interpolation, (d) NOT recommend Intl.NumberFormat directly.",
+      "files": [],
+      "assertions": [
+        {"text": "Output uses `ms-4` (logical inline-start) instead of `ml-4`"},
+        {"text": "Output does NOT contain `ml-4`, `pl-`, `pr-`, `mr-`, `left-`, or `right-` Tailwind classes"},
+        {"text": "Output imports and uses `numberFormat()` from `@/lib/utils/numbers`"},
+        {"text": "Output does NOT call `count.toLocaleString()` or `new Intl.NumberFormat(...)` directly"},
+        {"text": "User-facing English ('There are', 'open issues right now', 'open issues') is routed through `getTranslations` / `t()` / `t.rich()` rather than appearing as a bare JSX literal"}
+      ]
+    },
+    {
+      "id": 4,
+      "name": "hero-family-and-server-component",
+      "prompt": "we're adding a new landing page at app/[locale]/community/online/page.tsx. it needs a hero up top with a title, a one-paragraph blurb, an illustration on the right (use public/images/community.png), and two CTA buttons. should i build the hero from scratch or is there a pattern? just give me the file",
+      "expected_output": "Skill should recommend a hero from the @/components/Hero family (likely ContentHero or SimpleHero depending on shape) and explicitly avoid @/components/PageHero (deprecation track). Should keep the page as a Server Component (no 'use client'), use ButtonLink for CTAs (not raw <a>), and use getTranslations for copy.",
+      "files": [],
+      "assertions": [
+        {"text": "Output imports a hero from the `@/components/Hero` family (ContentHero, SimpleHero, HubHero, or MdxHero)"},
+        {"text": "Output does NOT import from `@/components/PageHero` (deprecation track)"},
+        {"text": "Output does NOT include `'use client'` at the top of page.tsx (Server Component default)"},
+        {"text": "CTA buttons use `ButtonLink` (or are passed via the hero's `buttons` prop), not raw `<a>` or `<button>` elements"},
+        {"text": "Page-level copy (title, blurb, CTA labels) is routed through `getTranslations` from `next-intl/server`"}
+      ]
+    },
+    {
+      "id": 5,
+      "name": "modal-import-and-no-raw-button",
+      "prompt": "add a \"Delete account\" button to src/components/Profile/Settings.tsx that pops a confirm dialog (\"are you sure? this cant be undone\"). on confirm it calls deleteAccount(). use a plain html button for the trigger and a basic radix dialog, im not sure what this repo prefers",
+      "expected_output": "Skill should refuse the raw <button> in favor of <Button> from @/components/ui/buttons/Button, and pick the high-level Modal default export from @/components/ui/dialog-modal rather than wiring up @/components/ui/dialog from scratch. Should mark the file 'use client' (interactivity) and use translations for the prompts.",
+      "files": [],
+      "assertions": [
+        {"text": "Output imports the default-export `Modal` from `@/components/ui/dialog-modal`"},
+        {"text": "Output does NOT import named primitives directly from `@/components/ui/dialog` or `@radix-ui/react-dialog`"},
+        {"text": "Trigger uses `<Button>` from `@/components/ui/buttons/Button` (NOT a raw `<button>` element)"},
+        {"text": "File begins with `'use client'` (needed for useState + handlers)"},
+        {"text": "All user-facing copy ('Delete account' label, 'are you sure?' warning, confirm/cancel) routed through `useTranslations` (no hard-coded English literals in JSX)"},
+        {"text": "notes.md explicitly notes the pushback on the user's 'plain html button' and 'basic radix dialog' framing"}
+      ]
+    }
+  ]
+}
diff --git a/.gitignore b/.gitignore
index 93385efd35e..8f23988109e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -70,3 +70,6 @@ storybook-static
 
 # Git worktrees for Claude commands
 .worktrees
+
+# Hide skill eval workspaces
+.claude/skills/*-workspace