WIP — This PR is a draft and still under active development.

Summary

New Docusaurus-powered documentation site for the Gusto Embedded React SDK, designed to publish to ReadMe and give partners a best-in-class developer experience.

What's here

• Quickstart section — "Your First 5 Minutes" guide that gets developers from npm install to a working component on screen, including proxy setup
• Concepts section — 8 concept pages covering Flows & Blocks, Provider configuration, Events, Authentication & Proxy, Composition, Theming & Customization, Error Handling, and i18n
• Complete Component Inventory — Individual documentation pages for every flow and block across all 5 domains (Company, Employee, Contractor, Payroll, Information Requests). 75+ component pages with props tables, events tables, and code examples
• Consolidated Guides — Deep integration guides for Routing, Observability, Component Adapter, Proxy Setup, Request Interceptors, Theme Variables, and more
• Updated navigation — New sidebar structure, landing page, footer, and README reflecting the new information architecture

Why Docusaurus

• ReadMe publishing — Docusaurus markdown is compatible with ReadMe's import format, giving us a path to publish directly to the Gusto developer portal
• Local-first authoring — Authors preview changes instantly with hot reload before publishing
• Built-in features — Local search, dark/light mode, OpenAPI API reference (auto-generated from spec), syntax-highlighted code blocks, breadcrumb navigation, and responsive layout
• Docusaurus MCP server potential — With the docs site running locally, we can wire up an MCP server that lets AI tools (Cursor, Claude, etc.) query our documentation directly. This means AI assistants can look up accurate SDK component props, events, and usage patterns from the live docs instead of relying on training data
• Version control — Documentation lives alongside the code it describes, making it easy to keep in sync as components evolve

Fact-checked against source

5 verification passes were run against the TypeScript source code:

1. Props validated against actual TypeScript interfaces for every component
2. Events cross-referenced against componentEvents constants (all 244 events)
3. Code examples verified for correct imports, component names, and prop shapes
4. Flow steps verified against state machines (onboardingStateMachine.ts, etc.)
5. All internal cross-references and links validated

Stats

• 96 new markdown files across docs/quickstart/, docs/concepts/, docs/components/, and docs/guides/
• 5 files modified — sidebars.ts, docusaurus.config.ts, index.tsx, README.md, what-is-the-gep-react-sdk.md
• 6,015 lines added, 133 lines modified

Information Architecture

docs/
├── what-is-the-gep-react-sdk.md     # SDK overview
├── quickstart/                       # 3 files: install → first flow → next steps
├── concepts/                         # 8 files: flows/blocks, provider, events, auth, composition, theming, errors, i18n
├── components/                       # 75+ files organized by domain
│   ├── company/                      # 1 flow, 15 blocks
│   ├── employee/                     # 3 flows, 15 blocks
│   ├── contractor/                   # 2 flows, 11 blocks
│   ├── payroll/                      # 5 flows, 14 blocks
│   └── information-requests/        # 1 flow, 2 blocks
├── guides/                           # 8 consolidated guides
├── hooks/                            # Experimental hooks (unchanged)
└── reference/                        # Auto-generated endpoint reference (unchanged)

Still to do

• Remove legacy doc directories (docs/workflows-overview/, docs/integration-guide/, docs/getting-started/, etc.)
• Docusaurus deployment config (hosting, CI/CD)
• Screenshot/image assets for component previews
• Polish pass on the Quickstart CodeSandbox link
• ReadMe publishing pipeline

How to preview locally

cd website
npm install
npx docusaurus start --port 3333
# Open http://localhost:3333

Screenshots