feat(docs): consume HIG packages instead of copied CSS and fonts (bloxwap/hig#58)

[joeblau]

Refs bloxwap/hig#58. The docs site now gets HIG from packages instead of copied CSS, palette and fonts. This follows hig's docs/governance/new-repository.md and the five SDK docs pilots (sfx#50 and others).

What changed

• Install path: the HIG 0.1.0 candidate tarballs (hig-tokens, hig-react, hig-contracts) are built from bloxwap/hig@19c7561 with release:dry-run --channel candidate. They are vendored in vendor/bloxwap-hig/ and installed through file: dependencies. The README and provenance.json record the hashes. Nothing was published, tagged or released.
• Tokens and controls: @bloxwap/hig-tokens/css and @bloxwap/hig-react/css replace vendor/hig/tokens.css and styles/hig.generated.css.
  • Fumadocs variables now map straight onto --hig-* roles; the --bloxwap-*/--card/--space-* alias layer is gone.
  • The local .btn family and focus ring are removed.
  • A few JS-only HIG numbers (radius, motion, type, compact density) stay in global.css. docs:check checks them against the installed tokens.
• HIG components:
  • Tabs + InstallCommand for the install picker
  • IconButton for code copy
  • Alert for the search error and EmptyState for search with no results
  • Callout for MDX <Callout>
  • hig-button intents for the hero and 404 links
• Fonts: apps/docs/fonts is deleted. OG cards use @bloxwap/hig-tokens colors and its Bold/Black TTFs. The rendered cards are byte-identical.
• Guards: hig-drift.json plus a CI step that runs drift.mjs from the same pinned HIG commit. New npm run docs:smoke (Playwright) runs in the Documentation workflow.
• Unchanged: CLI content, Fumadocs shell, static search index, /agent-cli base path, metadata, social cards and deep links.

Before / after (full report, measurements.json)

	Before (main 19ebad0)	After
Docs source CSS	3 files, 25,447 B	1 file, 21,885 B
Committed fonts / copied HIG files	892,964 B / 9 files	0 / 0
Emitted CSS	142,143 B (22,554 gz)	150,822 B (24,357 gz)
Emitted JS	1,262,320 B (404,715 gz)	1,268,249 B (406,679 gz)
Emitted fonts	12,965,628 B	same
Docs direct deps / lockfile entries	15 / 703	21 / 764

Where the dependency increase comes from:

• +3 HIG packages.
• +1 playwright (dev).
• +2 Radix optional peers. These are only needed because @bloxwap/hig-react/recipes statically imports overlay.js, which needs react-dropdown-menu and react-tooltip. Without them the build fails with "Module not found". The overlay code is tree-shaken out, so the JS is the same as composing the recipe by hand. This is an upstream HIG packaging issue.

Validation (local Linux x64, Node 24.22.0)

• npm run build ✔, npm run lint ✔, npm run typecheck ✔, npm test ✔
• npm run docs:check ✔ (content, HIG provenance/installed versions/host token values, typegen, tsc)
• NEXT_PUBLIC_BASE_PATH=/agent-cli npm run docs:build ✔: 16 HTML pages, 597 local links/assets, 13 social cards, base path /agent-cli
• node <hig@19c7561>/scripts/drift.mjs --root . --config hig-drift.json: Scoped anti-drift: passed (36 files, 0 dated exceptions). On main it reports 6 violations (vendor/hig import ×2, 2 TTFs, copied palette and token definitions).
• npm run docs:smoke (Chromium, /agent-cli static preview) passes 10/10 here and 10/10 on main. It covers:
  • base-path assets
  • install tabs with Arrow/Home/End
  • install and code copy, checked against the clipboard
  • Tab focus ring
  • Ctrl+K search: results, the no-results state and Escape
  • docs and table pages
  • the 404 page staying in the base path
  • 390 px: no horizontal scroll, and sidebar navigation to a deep link

Screenshots

• Home: before / after
• Mobile home: before / after
• Mobile nav: after
• Search with no results: before / after
• Tables: before / after
• 404: after

Visible changes:

• HIG Tabs: the selected tab is filled green.
• The install recipe has a "Copy install command" button.
• The copy icon button has a nested fill.
• HIG table cell padding is 12 px.

Not covered

• No large-text or RTL checks.
• Firefox and WebKit were not run.
• No devices; this is a static web docs change.
• The planning/adoption.json row lives in bloxwap/hig. It gets updated in a follow-up hig PR once this merges.

Rollback: revert this PR.

🤖 Generated with Claude Code