feat(docs): consume HIG packages instead of copied CSS and primitives (hig#34)

[joeblau]

Part of bloxwap/hig#34 (Font row). This is a follow-up to the #10 pilot. Base: 82ad793.

#10 pinned hand-copied HIG CSS from 1a776b9. This PR switches apps/docs to the HIG packages, which come from bloxwap/hig@7c67a07 (npm ci && npm run build && npm run release:dry-run -- --channel candidate → 0.1.0-candidate.sha7c67a07c). Nothing was published, tagged or released.

What changed

• How HIG is consumed: vendor/bloxwap-hig/ contains only the three packed tarballs it needs: hig-tokens, hig-contracts and hig-react. They are installed as file: dependencies of apps/docs, and root overrides pin the transitive HIG versions to the same files. provenance.json records the commit and the SHA-256 of each tarball. scripts/check-hig-vendor.ts runs at the start of build. It checks those hashes and the installed versions. It also fails if HIG palette/spacing tokens or the base .hig-button rule are redefined in the docs sources.
• Files removed: styles/hig-tokens.css, styles/hig-controls.css, styles/HIG-LICENSE, styles/hig-source.json and scripts/check-hig-source.ts. global.css now imports @bloxwap/hig-tokens/css and @bloxwap/hig-react/css.
• Controls: buttons use Button from @bloxwap/hig-react/button. Copy controls use IconButton (ghost intent, 48px target). Link-buttons (download, "Try it", guide links, 404) carry the HIG data-intent. The local secondary/ghost fills and the "step up on a card" overrides are gone. .btn now only adds icon layout and the compact size, set through --hig-control.
• States: the language list uses HIG Spinner + Surface while loading and HIG EmptyState for "no data" and "no matches". The glyph grid uses Spinner while loading. In-development notes use HIG Callout (warning). The local .sr-only and :focus-visible are replaced by HIG's.
• Tokens in TS: themeColor and the social-card colours read tokens.colors.*.srgb from @bloxwap/hig-tokens. The card text colour moves from #f5f7fa to the HIG text colour #fafafa.
• Duplicates removed: Tailwind --text-* / --radius-2xl variables that were redeclared, and a second copy of the segmented-control styles for the install tabs. The undefined --bloxwap-pink syntax colour is fixed: code keywords are now coloured as intended.
• Unchanged: the Fumadocs shell, sidebar, mobile drawer and static Orama search; base path /font; static export; metadata, OG cards and sitemap; deep links; API/install examples; and the type tester, glyph browser and variable-axis controls (Range, Switch, Segmented, FamilyPicker).
• CI: docs.yml now also runs when vendor/bloxwap-hig/** changes.

Before → after (from summary.json, produced by measure.mjs and capture.mjs)

Metric	Before	After	Δ
Generated CSS (_next chunk, raw)	139,967	139,695	−272
Generated CSS (gzip -9)	24,470	24,573	+103
Presentation source files (global.css + styles/*)	6 files / 830 lines / 68,202 B	2 files / 718 lines / 60,698 B	−4 files / −112 lines / −7,504 B
Static export, total	107,522,123	107,518,967	−3,156
Export JS	1,333,825	1,337,903	+4,078
Decoded CSS per page (home/docs, desktop and mobile)	193,351	193,079	−272
Decoded JS on home, desktop	1,191,217	1,195,295	+4,078
Font bytes per page	unchanged	unchanged	0
Runtime dependencies (apps/docs)	8	11	+3
Lockfile packages	724	727	+3

Notes on the numbers:

• The +3 dependencies are the HIG tarballs themselves. They pull nothing from the registry, because the optional Radix/chart peers are not installed.
• CSS shrinks by less than the deleted rules because the 7c67a07 token package adds an oklch @supports block (--hig-source-*), about 2 KB, that the old copied snapshot lacked.
• The +4 KB of JS is the HIG button, status, surface, provider and contracts modules.
• No dependency was removed: lucide-react and @number-flow/react are still used by the demos.

Screenshots (Chromium, production export at /font; desktop 1280×900, mobile 390×844)

	Before	After
Home, desktop
Home, 390px
Installation, desktop
Type tester demo, desktop
Glyph browser demo, 390px

All 26 PNGs, including the Sans family page, the character set page and the 390px tester, are in evidence/hig-34/.

Verification (local, macOS, bun 1.4.3 as in CI; verification.txt)

• bun install --frozen-lockfile: no changes.
• bun run lint: passes (exit 0).
• bun run typecheck (fumadocs-mdx && next typegen && tsc --noEmit): passes.
• NEXT_PUBLIC_BASE_PATH=/font bun run docs:build: vendor guard OK. Static export OK: 27 HTML files, 24 social cards, 52 @font-face rules, base path /font.
• bun test apps/docs/lib/glyph-text.test.ts: 4 pass.
• Browser (Playwright, headless): 48/48 passed on Chromium and WebKit against the static export served under /font. That is the existing 19 specs plus the new test/hig-packages.spec.ts. The new spec covers package CSS loaded, theme colour, keyboard copy through the HIG IconButton with a polite status, HIG intents, the EmptyState, ⌘/Ctrl+K search into the static index and navigating a result under /font, and no horizontal scroll at 390px on home, installation and character-set.
• The existing suite still covers search, install-tab arrow keys and copy, variable axes, glyph search/copy, mobile drawer navigation, 320/640/1280 reflow and 200% text.
• Firefox runs in CI only. Local Playwright Firefox fails to launch on this Mac ("Could not find profile folder"), and this happens before any page loads.
• packages/npm package tests need the Python font build; they run in the "Font delivery quality" CI job and are unaffected by this change.

Exceptions / remaining

• The tarballs are vendored candidates. Switch to registry versions once @bloxwap/hig-* are published.
• Host adapters that stay local:
  • Fumadocs routing/search. The SDK-docs kit allows keeping it.
  • The type-tester controls. HIG Slider/Switch only take string labels and render label: value. Using them would change the accessible names and drop the NumberFlow readouts and the <code> axis tags.
  • The transient copy toast. HIG Toast stays until dismissed.
• Rollback: revert this PR, which restores the previous lockfile and imports.
• The HIG planning/adoption.json Font row still needs updating by HIG owners. The local row is in evidence/adoption.json.
• Physical-device and AT checks are not claimed. All evidence here is automated or browser-based.

Review fix (44b8a00)

• test/scripts.spec.ts asserted .bw-callout-wip had count 0, but this PR removed that class, so the check always passed. It now asserts .bw-callout and getByRole('note').filter({ hasText: 'is being drawn' }) both have count 0 on the Arabic, Armenian, Georgian and Hebrew pages.
• The HIG Callout (severity warning, announce={false}, wip-badge action) moved into components/docs/in-development.tsx. InDevelopment still reads font data and renders it. No family renders that path today, so in-development.test.tsx renders the real vendored @bloxwap/hig-react Callout and checks: one static note with no status/alert live region, data-severity="warning", the title, the badge, and planned coverage present or omitted. The new test:unit script runs it, and the Font delivery quality docs job now calls test:unit.
• Browser check that the new selectors catch a regression (local Chromium, production export at /font, ad hoc, not committed): on sans-arabic, the counts were 0/0 before anything was injected. After injecting the server-rendered Callout markup, .bw-callout = 1 and the note filter = 1, while the old .bw-callout-wip selector still found 0.
• Local results (bun 1.4.0-canary): bun run lint passed, bun run typecheck passed, bun run docs:build passed with base path /font (27 HTML files), bun run test:unit gave 7 pass / 0 fail, and playwright test --project=chromium --project=webkit gave 48 passed. Firefox would not launch on this Mac (browserType.launch failed), so Firefox results come from CI only. bun install --frozen-lockfile reports lockfile drift with both local bun builds (1.4.0-canary and 1.2.20), and it does the same on the unmodified branch head. CI's setup-bun installs cleanly.

🤖 Generated with Claude Code

[joeblau]

CI on 2e14ce1 is green.

• Font delivery quality: assets passed (package build/tests, Next fixture). docs passed lint, typecheck and docs:build, and Production browser checks 72/72 passed on Chromium, Firefox and WebKit with no retries.
• Documentation: build passed. deploy was skipped because this is a PR.

Not merged; this is left for independent verification.

🤖 Generated with Claude Code