docs: tighten Getting Started FAQ pages with correct API usage (SD-2873)

caio-pizzol · caio-pizzol · commit cc6f5a3fc95f · 2026-05-01T11:50:23.000-03:00
- Theming: createTheme returns a className applied via document.documentElement.classList.add, not a constructor option. Adds popover/CSP pitfalls.
- Fonts: modules.toolbar.fonts takes [{ label, key }] objects, not bare strings. Adds dropdown-not-auto-populated pitfall.
- AI: chooser table + three concrete paths with real install command.
- Import/Export: leads with value statement; adds duplicate-download/HTML-base-DOCX pitfalls.
diff --git a/apps/docs/getting-started/ai.mdx b/apps/docs/getting-started/ai.mdx
@@ -1,47 +1,58 @@
 ---
-title: AI
+title: Use SuperDoc with AI
 sidebarTitle: AI
 keywords: "ai, mcp, claude, cursor, llm tools, ai agents, document automation, ai sdk"
 ---
 
-Pick the AI integration that matches what you're building. For the full AI section, see [AI Overview](/ai/overview).
+SuperDoc gives AI models structured access to real Word documents. Use MCP when a coding agent is working on files. Use LLM tools when you're building document editing into your own app. Use the SDK or CLI for backend automation.
 
-## Pick your path
+## Pick the path
 
-<CardGroup cols={2}>
-  <Card title="I want Claude/Cursor to edit DOCX" icon="terminal" href="/ai/mcp/overview">
-    **MCP server.** Drop SuperDoc's MCP server into Claude Desktop, Cursor, or any MCP-compatible host. Claude can then open, read, and edit DOCX files locally.
-  </Card>
-  <Card title="I want AI editing inside my app" icon="bot" href="/ai/agents/llm-tools">
-    **LLM tools.** SuperDoc ships pre-typed tool catalogs for OpenAI, Anthropic, Vercel AI SDK, Mastra, and others. Wire them into your existing agent.
-  </Card>
-  <Card title="I want scripts or CI to edit DOCX" icon="code" href="/document-engine/cli">
-    **CLI or SDKs.** Run DOCX operations from a script, GitHub Action, or backend job. No browser needed.
-  </Card>
-  <Card title="I want LLM-friendly content from DOCX" icon="file-export" href="/getting-started/import-export">
-    **Markdown/JSON export.** Pull document content out as Markdown or JSON to feed into your own LLM context.
-  </Card>
-</CardGroup>
+| You want to | Use |
+|---|---|
+| Let Claude/Cursor edit DOCX files | [MCP server](/ai/mcp/overview) |
+| Build AI editing into your app | [LLM tools](/ai/agents/llm-tools) |
+| Automate DOCX from scripts or CI | [SDK](/document-engine/sdks) or [CLI](/document-engine/cli) |
+| Stream generated content into the editor | Browser editor + [`editor.doc.insert`](/document-api/overview) |
 
-## What ships with SuperDoc
+## Coding agents (MCP)
 
-SuperDoc treats AI as a first-class consumer. Three packages, all driven by the same Document API:
+The fastest path. SuperDoc ships an MCP server that any MCP-aware host can use.
 
-- **`@superdoc-dev/mcp`** — Model Context Protocol server. Lets MCP-aware hosts (Claude Desktop, Cursor) read and edit DOCX files.
-- **`@superdoc-dev/sdk`** — Node and Python SDKs for server-side automation. Same operations as the browser editor.
-- **`@superdoc-dev/cli`** — Command-line tool for scripts, CI, and one-off operations.
+```bash
+claude mcp add superdoc -- npx @superdoc-dev/mcp
+```
 
-All three share the [Document API](/document-api/overview) under the hood — the same `editor.doc.*` operations you use in the browser.
+Then ask Claude to open, read, or edit a DOCX file. The agent calls SuperDoc's typed tools — no HTML wrangling, no re-uploads.
 
-## Why this is different
+## App integration (LLM tools)
 
-Most editors expose AI via "ask the AI to write something." SuperDoc exposes the document itself: AI can list comments, decide tracked changes, replace text by selection, insert tables, format runs — all as discrete typed operations. No HTML wrangling, no re-uploading the file after each change.
+For agent editing inside your own app, SuperDoc ships pre-typed tool catalogs for OpenAI, Anthropic, Vercel AI SDK, Mastra, and others. Wire them into your existing model loop.
 
-For the agent best-practices guide and the full tool catalog, see [AI > Agents](/ai/agents/llm-tools).
+```javascript
+import { tools } from '@superdoc-dev/sdk';
+// pass tools to your model, dispatch tool calls against the SuperDoc SDK
+```
+
+## Browser editor + AI output
+
+If you're already running the SuperDoc editor in the browser and want AI-generated content to land in the document:
+
+```javascript
+const html = await callYourLLM(prompt);
+editor.doc.insert({ target: cursor, html });
+```
+
+The same Document API the editor uses internally — typed inputs, structured outputs, no string parsing.
+
+## Common pitfalls
+
+- **MCP server in the wrong host context.** The MCP server runs on the same machine as the agent. Configure it in Claude Desktop / Cursor / your MCP host, not in the SuperDoc browser app.
+- **Tool dispatch with stale schemas.** SDK tool catalogs are versioned with the SDK. Pin both packages together to keep types and runtime in sync.
 
 ## Where to next
 
 - [AI Overview](/ai/overview) — the full AI section
-- [AI > MCP](/ai/mcp/overview) — Model Context Protocol setup
-- [AI > Agents > LLM tools](/ai/agents/llm-tools) — typed tool catalogs for OpenAI, Anthropic, etc.
+- [AI > MCP > Overview](/ai/mcp/overview) — MCP setup for Claude Desktop, Cursor, and other hosts
+- [AI > Agents > LLM tools](/ai/agents/llm-tools) — typed tool catalogs and integration patterns
 - [Document API](/document-api/overview) — the operations all AI integrations share
diff --git a/apps/docs/getting-started/fonts.mdx b/apps/docs/getting-started/fonts.mdx
@@ -4,70 +4,60 @@ sidebarTitle: Font Support
 keywords: "fonts, font loading, calibri, cambria, aptos, font fallback, custom fonts, font dropdown, office fonts"
 ---
 
-How fonts work in SuperDoc, and what to do when a document looks different from how it looks in Word.
+SuperDoc keeps the font name from the Word document. Rendering that font is the browser's job. If the browser can't find Calibri, Cambria, Aptos, or your brand font, it falls back to another font and the layout shifts.
 
-## How SuperDoc handles fonts
+## Load fonts in your app
 
-SuperDoc preserves the font names that come from your DOCX. It does **not** load font files for you. Whether `Calibri Light` actually renders as Calibri Light depends on whether that font is available to the browser running your app.
-
-Three things you control:
-
-1. **Loading font files** — your app's responsibility (CSS `@font-face`, `<link>` tags, font CDNs).
-2. **Toolbar dropdown options** — which fonts users can pick from in the built-in toolbar.
-3. **Font fallbacks** — what happens when the requested font isn't available.
-
-## The "why does it look different from Word?" question
-
-Most of the time, the document references Microsoft fonts (Calibri, Cambria, Aptos, Times New Roman) that aren't on the user's system or aren't loaded by your host page. The browser falls back to a default font and the layout shifts.
-
-Two common fixes:
-
-- **License the actual fonts** and load them via `@font-face`. This gives pixel-accurate rendering.
-- **Load free substitutes** with similar metrics. [Carlito](https://fonts.google.com/specimen/Carlito) for Calibri, [Caladea](https://fonts.google.com/specimen/Caladea) for Cambria are common Google Fonts swaps.
+Fonts are your host page's responsibility. `@font-face`, a hosted stylesheet, or a font CDN — anything the browser can resolve.
 
 ```css
-/* Example: load Carlito as a Calibri substitute */
 @font-face {
   font-family: 'Calibri';
-  src: url('https://fonts.gstatic.com/s/carlito/...') format('woff2');
+  src: url('/fonts/Carlito-Regular.woff2') format('woff2');
   font-display: swap;
 }
 ```
 
-## Configuring the toolbar font dropdown
+For Office fonts that aren't free (Calibri, Cambria, Aptos), either license them or alias compatible substitutes — [Carlito](https://fonts.google.com/specimen/Carlito) for Calibri, [Caladea](https://fonts.google.com/specimen/Caladea) for Cambria.
+
+## Register fonts in the toolbar
 
-The built-in toolbar has a font picker. By default it shows a curated list. To customize the available fonts:
+The toolbar's font dropdown shows whatever you register in `modules.toolbar.fonts`. Each entry is a `{ label, key }` pair where `key` is the CSS `font-family` value:
 
 ```javascript
 new SuperDoc({
   selector: '#editor',
   document: 'contract.docx',
   modules: {
     toolbar: {
-      fonts: ['Inter', 'Calibri', 'Times New Roman', 'Custom Brand Font'],
+      fonts: [
+        { label: 'Calibri', key: 'Calibri, sans-serif' },
+        { label: 'Inter', key: 'Inter, sans-serif' },
+        { label: 'Times New Roman', key: '"Times New Roman", serif' },
+      ],
     },
   },
 });
 ```
 
-<Note>
-  Adding a font to the toolbar dropdown does **not** load the font file. You still need to make the font available to the browser via CSS. The dropdown only controls which fonts the user can select.
-</Note>
+Registering a font makes it **selectable** in the dropdown. It does **not** load the font file. You still need the `@font-face` (or equivalent) on your host page.
 
-For the full toolbar font configuration options, see [Built-in UI > Toolbar](/editor/built-in-ui/toolbar#font-configuration).
+## Programmatic font changes
 
-## Setting fonts programmatically
-
-To set fonts from code (e.g. an AI agent applying a brand font), use the Document API:
+For AI agents or scripts setting a brand font:
 
 ```javascript
 editor.doc.format.fontFamily({ target, value: 'Inter' });
 ```
 
-For the full font formatting API surface, see [Document API > Available operations](/document-api/available-operations).
+## Common pitfalls
+
+- **Font name preserved, browser falls back.** The font name from the DOCX is intact, but the actual file isn't loaded. Add `@font-face`.
+- **Dropdown doesn't show a font.** Imported documents don't auto-populate the toolbar list. If a `.docx` uses Cambria but Cambria isn't in `fonts`, the user can't pick it from the dropdown — even though the current selection indicator may show "Cambria" if that's what the run uses.
+- **Office font licensing.** Calibri, Cambria, and Aptos are licensed Microsoft fonts. Self-hosting requires a license. Free substitutes are common in non-pixel-perfect contexts.
 
 ## Where to next
 
-- [Built-in UI > Toolbar](/editor/built-in-ui/toolbar) — toolbar font configuration
+- [Built-in UI > Toolbar](/editor/built-in-ui/toolbar#font-configuration) — full toolbar font configuration options
 - [Document API > Available operations](/document-api/available-operations) — programmatic font formatting
 - [Editor > Theming](/editor/theming/overview) — set the default font for SuperDoc's UI chrome
diff --git a/apps/docs/getting-started/import-export.mdx b/apps/docs/getting-started/import-export.mdx
@@ -4,7 +4,9 @@ sidebarTitle: Import/Export
 keywords: "import, export, docx export, html import, markdown import, document formats"
 ---
 
-Five-minute orientation for getting documents in and out of SuperDoc. For the full reference, see [Editor > SuperDoc > Import/Export](/editor/superdoc/import-export).
+SuperDoc treats DOCX as the real document, not an export target. Load a Word file, edit it in the browser, and export a Word file again — tracked changes, comments, complex tables, all preserved. HTML and Markdown are useful for AI-generated content, but DOCX is the full-fidelity path.
+
+For the full reference, see [Editor > SuperDoc > Import/Export](/editor/superdoc/import-export).
 
 ## Loading a document
 
@@ -65,6 +67,12 @@ DOCX preserves tracked changes, comments, complex tables, and section breaks. HT
 
 Store the **DOCX blob** if you want full fidelity (recommended). Store JSON if you want programmatic search/diff and don't need round-tripping with Word users. Don't store HTML or Markdown unless you accept losing fidelity.
 
+## Common pitfalls
+
+- **Duplicate downloads.** `superdoc.export()` triggers a browser download by default. If you want to upload to a backend, pass `{ triggerDownload: false }` — otherwise you get the file twice.
+- **HTML import without a base DOCX.** The `html` and `markdown` options need a `document` (a base `.docx`) for styles. Without one, headings and lists fall back to defaults.
+- **HTML round-trips lose styling.** Importing HTML, exporting DOCX, and then importing the resulting HTML back will not produce the original Word styling. For round-tripping, use DOCX or JSON.
+
 ## Where to next
 
 - [Editor > SuperDoc > Import/Export](/editor/superdoc/import-export) — full API reference (every option, every export flag)
diff --git a/apps/docs/getting-started/theming.mdx b/apps/docs/getting-started/theming.mdx
@@ -1,49 +1,56 @@
 ---
-title: Theming
+title: Theme SuperDoc
 sidebarTitle: Theming
 keywords: "theming, css variables, custom theme, dark mode, design tokens, branding, createTheme"
 ---
 
-Five-minute setup for matching SuperDoc to your brand. For the full token catalog and `createTheme()` reference, see [Editor > Theming](/editor/theming/overview).
+SuperDoc's UI is styled with CSS variables. `createTheme()` generates a class name that sets those variables; you apply the class to `<html>` and every SuperDoc surface picks it up — toolbar, comments, dropdowns, context menu, popovers.
 
-## Set your brand colors
+## The fast path
 
 ```javascript
 import { SuperDoc, createTheme } from 'superdoc';
 
 const theme = createTheme({
   colors: {
-    action: '#6366f1', // buttons, links, active states
-    bg: '#ffffff', // panels, dropdowns
-    text: '#1e293b',
-    border: '#e2e8f0',
+    action: '#1355FF', // buttons, links, active states
+    bg: '#ffffff',
+    text: '#1f2937',
+    border: '#d1d5db',
   },
   font: 'Inter, sans-serif',
-  radius: '8px',
+  radius: '6px',
 });
 
-new SuperDoc({
-  selector: '#editor',
-  document: 'contract.docx',
-  theme,
-});
+document.documentElement.classList.add(theme);
+
+new SuperDoc({ selector: '#editor', document: 'contract.docx' });
 ```
 
-The toolbar, comments sidebar, dropdowns, and every other built-in surface pick up the theme automatically.
+`theme` is a className string. Apply it to `<html>` (not the editor container) so popovers, dropdowns, and the comments sidebar — which can render outside the editor element — pick up the same tokens.
+
+## What themes affect
 
-## Common patterns
+Toolbar buttons, comments sidebar, dropdowns, context menu, search bar, dialog surfaces. Any chrome SuperDoc renders. The document content itself (paragraphs, headings, tables) renders with its own styles from the DOCX.
 
-**Dark mode**: pass a different theme when your app's color scheme changes.
+## When to drop to CSS variables
+
+`createTheme()` covers the common case. For component-level overrides, use the `vars` option or set raw `--sd-*` variables in your stylesheet:
 
 ```javascript
-const dark = createTheme({
-  colors: { action: '#818cf8', bg: '#0f172a', text: '#f1f5f9', border: '#334155' },
+const theme = createTheme({
+  colors: { action: '#1355FF', bg: '#ffffff', text: '#1f2937', border: '#d1d5db' },
+  vars: {
+    '--sd-ui-toolbar-bg': '#f8fafc',
+    '--sd-comments-resolved-bg': '#ecfdf5',
+  },
 });
 ```
 
-**Per-instance override**: each `SuperDoc` instance can have its own theme.
+## Common pitfalls
 
-**CSS variable escape hatch**: every theme value is a CSS custom property (`--sd-color-action`, `--sd-color-bg`, etc.). You can override individual variables in your stylesheet without rewriting the whole theme.
+- **Theme class on the wrong element.** Add it to `document.documentElement` (the `<html>` tag), not the editor's container. Popovers render at the body level and won't pick up the theme otherwise.
+- **CSP environments.** `createTheme()` injects a `<style>` tag. If you serve with a strict CSP, use `buildTheme()` instead — it returns `{ className, css }` so you can inject the CSS yourself with the right nonce.
 
 ## Where to next
 
