Documentation website and migration shell
HIG uses Next.js static export and Fumadocs, matching the sibling SDK sites. SFX and Haptic pin fumadocs-core/fumadocs-ui 16.17.1, fumadocs-mdx 15.4.7 and Next 16.4.0; HIG uses those versions. Font uses 16.15.17/15.4.5/16.3.6 and Chart 16.15.14/15.4.5/16.3.6. React 19.2 satisfies the current Fumadocs peer contract.
docs/ Markdown chapters are the single normative source. The trading glossary is the exception: docs/foundations/glossary.json is authored and docs/foundations/glossary.md is generated. scripts/generate-docs.mjs generates the ignored apps/docs/content/docs collection, meta.json navigation, Markdown downloads, catalog data and llms.txt. Do not edit generated guides. Component reference pages derive from published package declarations and planning/examples.json; they link to the normative family guide. npm run generate:examples emits runnable web/native previews; npm run examples:check compiles all code variants.
apps/docs/source.config.ts defines the MDX collection; lib/source.ts supplies the page tree. app/docs/[[...slug]] renders Fumadocs titles, TOCs, code, navigation and source/edit links. components/provider.tsx and search.tsx provide the dark theme and static Orama search at search.json. Fonts, palette and preview controls import the shipped Bloxwap font and HIG packages. Fumadocs owns the responsive navigation, accessible search dialog and document shell.
Run npm ci, then bun docs:dev or npm run docs:dev. Turbo's terminal UI prepares package declarations, examples and guides before starting Next at http://localhost:3905/, with documents under /docs/. npm run dev:docs is an alias. Use bun docs:dev --ui=stream for plain terminal logs. bun docs:check and bun docs:build also prepare their required package outputs.
npm run build:docs generates the collection, builds Next and copies its static export to apps/docs/dist. Preview with bun docs:preview at http://localhost:4174/hig/. The static build defaults to /hig, while development defaults to the host root; override NEXT_PUBLIC_BASE_PATH without a trailing slash and HIG_DOCS_ORIGIN for another host. Every canonical document lives under /docs/. Explicit static redirect documents retain the previous /guides/*, /components/* and /catalog/ URLs, including their query and fragment. Sitemap, Markdown and LLM exports ship in the same artifact. No deployment is part of the build.
The homepage retains the bounded playground: App/Pro/Docs presets, supported states, locale/direction contracts, independent sound/haptics/motion settings, volume, matching Get Code, and validated share configuration. Native examples are real RN components in the Expo gallery. Device screenshots, VoiceOver/TalkBack and physical feedback observations remain pending. Live examples use sample host-owned actions and never submit orders or call a wallet.
Reusing the shell for issue #34
Each SDK keeps its own content and distinctive demo: Hyperliquid market playground, Chart preview, Font type tester, SFX sound board, Haptic interaction demos. Start with HIG's next.config.mjs, PostCSS/source config, lib/source.ts, root/docs layouts, provider/search and MDX component mapping. Set the product title, repository, base path and port. Copy the shell code as a starting template, then import the versioned HIG token CSS, React CSS and font assets rather than copying palette values or primitive implementations. Keep the SDK's existing content/docs as its normative collection, or generate it from one existing Markdown source as HIG does; never maintain two authored guides.
Place SDK demos behind a client boundary like components/demo.tsx; keep documentation server-rendered and searchable. Compose HIG install/copy/code/callout controls in those demos. Preserve each SDK's static search, llms.txt, sitemap, metadata and legacy URLs. Match the production base path during browser tests. Run build, lint, typecheck, example checks and the docs gates, capture desktop/mobile pages and the distinctive demo, and record exceptions and package versions in the #34 migration matrix. This HIG change provides the shell; it does not claim the five separate SDK migrations are complete.
Validation
npm run check includes the Next build and docs typecheck. CI runs production browser gates against the exported site, including the playground, search/navigation, legacy deep links, code tabs, all component states, runtime errors and axe checks. Screenshots and browser reports are uploaded with the static export as review artifacts. Publication, tagging and deployment remain separate operations.
The separate Documentation workflow builds and typechecks the static site for pull requests and pushes to main. After a successful build on main, it publishes apps/docs/out to GitHub Pages using the /hig base path. Pages uses GitHub Actions as its publishing source. This publishes the candidate documentation; package releases and tags remain separate operations. The workflow can also be run manually from main to redeploy.
The Fumadocs/Next framework changes the whole-export asset baseline: approximately 587 KB gzip of JavaScript and 95 KB CSS across all split routes (previous Vite budgets: 240 KB gzip and 22 KB). The new whole-export ceilings are 650 KB gzip and 110 KB CSS. This measures every chunk, not one page load. Font loading remains Latin Sans/Mono from upstream package files through next/font/local, avoiding the all-script loader’s roughly 13 MB export; the existing 600 KB font ceiling is retained.