feat(docs): add Lucide icon validator + tighten icon picks (SD-2873)

caio-pizzol · caio-pizzol · commit 554bf76a9ec5 · 2026-05-01T12:10:29.000-03:00
Add scripts/validate-icons.ts that walks every &lt;Card icon=...&gt;,
&lt;Icon icon=...&gt;, and docs.json icon reference and validates the
name against the locally installed Lucide icon set. Wire into
lefthook pre-commit so invalid icons fail the commit instead of
silently rendering as blank boxes in production.

The validator caught two more icons missed in the previous pass:
- cube -&gt; box
- unlock -&gt; lock-open

Tighten icon picks per code-review feedback:
- React-related cards: code -&gt; atom
- Vue card: code -&gt; blocks
- Vanilla JS card: code -&gt; braces
- Comments card (Custom UI overview): message -&gt; message-square
- Discord references in docs.json (contextual + navbar): discord
  -&gt; messages-square (Lucide ships no brand icons)

Add a follow-up note in apps/docs/AGENTS.md so future agents know
about pnpm run check:icons.
diff --git a/apps/docs/AGENTS.md b/apps/docs/AGENTS.md
@@ -192,6 +192,8 @@ Common name traps when migrating from Font Awesome:
 
 For brand/language icons (React, Vue.js, Microsoft, etc.), Lucide doesn't ship them. Either use a generic Lucide icon that fits the context, or supply an SVG via `icon="/path/to/icon.svg"` or an external URL.
 
+A `pnpm run check:icons` validator runs in pre-commit and walks every `<Card icon="...">`, `<Icon icon="...">`, and `docs.json` icon reference against the locally installed Lucide set. Catches drift before deploy. Add new icons through this validator — if it complains, the name isn't in the Lucide library.
+
 ## Testing
 
 Code examples are tested automatically via pre-commit hooks and CI. Two checks run when `.mdx` files change:
diff --git a/apps/docs/advanced/headless-toolbar-examples.mdx b/apps/docs/advanced/headless-toolbar-examples.mdx
@@ -141,7 +141,7 @@ Replace `<example-name>` with `vue-vuetify`, `svelte-shadcn`, or `vanilla`.
 ## Next steps
 
 <CardGroup cols={2}>
-  <Card title="Bring Your Own UI (React)" icon="code" href="/editor/custom-ui/toolbar-and-commands">
+  <Card title="Bring Your Own UI (React)" icon="atom" href="/editor/custom-ui/toolbar-and-commands">
     The recommended path for React apps. Typed hooks, custom commands, selection-aware buttons.
   </Card>
   <Card title="Headless toolbar API reference" icon="code" href="/advanced/headless-toolbar">
diff --git a/apps/docs/docs.json b/apps/docs/docs.json
@@ -37,7 +37,7 @@
       {
         "title": "Ask on Discord",
         "description": "Join our support channel",
-        "icon": "discord",
+        "icon": "messages-square",
         "href": "https://discord.com/channels/1299087524056010902/1299436491839246409"
       }
     ]
@@ -286,7 +286,7 @@
         "type": "button",
         "href": "https://discord.com/invite/b9UuaZRyaB",
         "label": "Discord",
-        "icon": "discord"
+        "icon": "messages-square"
       }
     ]
   },
diff --git a/apps/docs/document-engine/overview.mdx b/apps/docs/document-engine/overview.mdx
@@ -50,7 +50,7 @@ All three call the same underlying engine. A redline written by your backend, a
   <Card title="Document API" icon="code" href="/document-api/overview">
     The operation contract — every method the editor and SDKs share
   </Card>
-  <Card title="SDKs" icon="cube" href="/document-engine/sdks">
+  <Card title="SDKs" icon="box" href="/document-engine/sdks">
     Node and Python typed methods for backend automation
   </Card>
   <Card title="CLI" icon="terminal" href="/document-engine/cli">
diff --git a/apps/docs/editor/custom-ui/overview.mdx b/apps/docs/editor/custom-ui/overview.mdx
@@ -44,7 +44,7 @@ One hook. One button. Subscribes only to that command's state. Re-renders only w
 ## What's in this section
 
 <CardGroup cols={2}>
-  <Card title="React setup" icon="code" href="/editor/custom-ui/react-setup">
+  <Card title="React setup" icon="atom" href="/editor/custom-ui/react-setup">
     Provider, onReady, hooks. The scaffolding every page below builds on.
   </Card>
   <Card title="Toolbar and commands" icon="bold" href="/editor/custom-ui/toolbar-and-commands">
@@ -53,7 +53,7 @@ One hook. One button. Subscribes only to that command's state. Re-renders only w
   <Card title="Custom commands" icon="code" href="/editor/custom-ui/custom-commands">
     Register your own commands. Override built-ins. Drive AI actions, clause inserts, business logic.
   </Card>
-  <Card title="Comments" icon="message" href="/editor/custom-ui/comments">
+  <Card title="Comments" icon="message-square" href="/editor/custom-ui/comments">
     Custom comments sidebar with the typed selection-capture flow.
   </Card>
   <Card title="Track changes" icon="circle-check" href="/editor/custom-ui/track-changes">
diff --git a/apps/docs/getting-started/frameworks/laravel.mdx b/apps/docs/getting-started/frameworks/laravel.mdx
@@ -122,7 +122,7 @@ This runs `php artisan serve` (port 8000) and Vite's dev server together. Open [
 ## Next steps
 
 <CardGroup cols={2}>
-<Card title="Vanilla JS Integration" icon="code" href="/getting-started/frameworks/vanilla-js">
+<Card title="Vanilla JS Integration" icon="braces" href="/getting-started/frameworks/vanilla-js">
   Plain JavaScript setup and patterns
 </Card>
 <Card title="Configuration" icon="cog" href="/editor/superdoc/configuration">
diff --git a/apps/docs/getting-started/frameworks/nextjs.mdx b/apps/docs/getting-started/frameworks/nextjs.mdx
@@ -80,7 +80,7 @@ export default function RootLayout({ children }) {
 ## Next Steps
 
 <CardGroup cols={2}>
-<Card title="React Integration" icon="code" href="/getting-started/frameworks/react">
+<Card title="React Integration" icon="atom" href="/getting-started/frameworks/react">
   Full React wrapper documentation
 </Card>
 <Card title="Configuration" icon="cog" href="/editor/superdoc/configuration">
diff --git a/apps/docs/getting-started/frameworks/nuxt.mdx b/apps/docs/getting-started/frameworks/nuxt.mdx
@@ -150,7 +150,7 @@ const handleFile = (e: Event) => {
 ## Next steps
 
 <CardGroup cols={2}>
-<Card title="Vue Integration" icon="code" href="/getting-started/frameworks/vue">
+<Card title="Vue Integration" icon="blocks" href="/getting-started/frameworks/vue">
   Full Vue setup and patterns
 </Card>
 <Card title="Configuration" icon="cog" href="/editor/superdoc/configuration">
diff --git a/apps/docs/getting-started/frameworks/react.mdx b/apps/docs/getting-started/frameworks/react.mdx
@@ -91,7 +91,7 @@ function FileEditor() {
 ## Next steps
 
 <CardGroup cols={2}>
-<Card title="React API Reference" icon="code" href="/editor/react/overview">
+<Card title="React API Reference" icon="atom" href="/editor/react/overview">
   Props, ref API, TypeScript types, and patterns
 </Card>
 <Card title="Bring Your Own UI" icon="layout-dashboard" href="/editor/custom-ui/overview">
diff --git a/apps/docs/guides/collaboration/self-hosted-overview.mdx b/apps/docs/guides/collaboration/self-hosted-overview.mdx
@@ -18,7 +18,7 @@ Run your own collaboration infrastructure for full control over data, persistenc
   <Card title="On-Premise" icon="building">
     Deploy behind your firewall
   </Card>
-  <Card title="No Vendor Lock-in" icon="unlock">
+  <Card title="No Vendor Lock-in" icon="lock-open">
     Standard Yjs protocol, portable data
   </Card>
 </CardGroup>
diff --git a/apps/docs/package.json b/apps/docs/package.json
@@ -9,6 +9,7 @@
     "gen:all": "pnpm run gen:api && pnpm run gen:docs",
     "check:links": "mintlify broken-links",
     "check:imports": "bun scripts/validate-code-imports.ts",
+    "check:icons": "bun scripts/validate-icons.ts",
     "test:examples": "bun test __tests__/doctest.test.ts"
   },
   "devDependencies": {
diff --git a/apps/docs/scripts/validate-icons.ts b/apps/docs/scripts/validate-icons.ts
@@ -0,0 +1,113 @@
+#!/usr/bin/env bun
+/**
+ * Validate that every icon name used in mdx + docs.json resolves against
+ * the configured icon library (Lucide). Mintlify silently renders unknown
+ * icon names as blank boxes, so this catches drift early.
+ *
+ * Run: bun scripts/validate-icons.ts
+ */
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(fileURLToPath(import.meta.url), '../..');
+const DOCS_JSON = join(ROOT, 'docs.json');
+
+const docsConfig = JSON.parse(readFileSync(DOCS_JSON, 'utf8'));
+const library = docsConfig.icons?.library ?? 'lucide';
+
+if (library !== 'lucide') {
+  console.log(`Library is "${library}"; this validator currently only supports lucide.`);
+  process.exit(0);
+}
+
+// Find the installed Lucide icon set (any version).
+function findLucideDir(): string {
+  const repoRoot = resolve(ROOT, '../..');
+  const pnpmDir = join(repoRoot, 'node_modules/.pnpm');
+  const entries = readdirSync(pnpmDir);
+  const match = entries.find((e) => /^lucide@[\d.]+$/.test(e));
+  if (!match) throw new Error('Could not find lucide package under node_modules/.pnpm');
+  return join(pnpmDir, match, 'node_modules/lucide/dist/esm/icons');
+}
+
+const validIcons = new Set<string>();
+for (const file of readdirSync(findLucideDir())) {
+  if (file.endsWith('.js') && !file.endsWith('.js.map')) {
+    validIcons.add(file.slice(0, -3));
+  }
+}
+
+// Walk all mdx files
+function walk(dir: string, files: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    if (entry === 'node_modules' || entry.startsWith('.')) continue;
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) walk(full, files);
+    else if (entry.endsWith('.mdx')) files.push(full);
+  }
+  return files;
+}
+
+const ICON_RE = /\bicon=(?:"([^"]+)"|\{`([^`]+)`\})/g;
+const issues: { file: string; line: number; icon: string }[] = [];
+
+function scanContent(file: string, content: string) {
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    // Skip code blocks / Vue v-btn
+    if (line.includes('v-btn')) continue;
+    let m: RegExpExecArray | null;
+    ICON_RE.lastIndex = 0;
+    while ((m = ICON_RE.exec(line))) {
+      const name = m[1] ?? m[2];
+      if (!name) continue;
+      // Skip URL/file paths (start with / or http)
+      if (name.startsWith('/') || name.startsWith('http')) continue;
+      // Skip MDI which is a Vue example, not Mintlify
+      if (name.startsWith('mdi-')) continue;
+      if (!validIcons.has(name)) {
+        issues.push({ file: file.slice(ROOT.length + 1), line: i + 1, icon: name });
+      }
+    }
+  }
+}
+
+// Scan mdx
+for (const file of walk(ROOT)) {
+  scanContent(file, readFileSync(file, 'utf8'));
+}
+
+// Scan docs.json
+function scanJsonForIcons(node: unknown, path: string[] = []) {
+  if (typeof node !== 'object' || node === null) return;
+  if (Array.isArray(node)) {
+    node.forEach((item, i) => scanJsonForIcons(item, [...path, String(i)]));
+    return;
+  }
+  for (const [key, value] of Object.entries(node)) {
+    if (key === 'icon' && typeof value === 'string') {
+      if (value.startsWith('/') || value.startsWith('http')) continue;
+      if (!validIcons.has(value)) {
+        issues.push({ file: 'docs.json', line: 0, icon: value });
+      }
+    } else {
+      scanJsonForIcons(value, [...path, key]);
+    }
+  }
+}
+scanJsonForIcons(docsConfig);
+
+if (issues.length === 0) {
+  console.log(`\u001b[32mAll icons valid (${validIcons.size} Lucide icons available).\u001b[0m`);
+  process.exit(0);
+}
+
+console.log(`\u001b[31mFound ${issues.length} invalid icon(s):\u001b[0m`);
+for (const { file, line, icon } of issues) {
+  const loc = line ? `${file}:${line}` : file;
+  console.log(`  ${loc}  icon="${icon}"`);
+}
+console.log(`\nLibrary is set to "${library}". See https://lucide.dev/icons/ for valid names.`);
+process.exit(1);
diff --git a/lefthook.yml b/lefthook.yml
@@ -20,6 +20,10 @@ pre-commit:
       root: "apps/docs/"
       glob: "apps/docs/**/*.mdx"
       run: pnpm run check:imports
+    docs-check-icons:
+      root: "apps/docs/"
+      glob: "apps/docs/**/*.{mdx,json}"
+      run: pnpm run check:icons
     docs-test-examples:
       root: "apps/docs/"
       glob: "apps/docs/**/*.mdx"

Original file line number	Diff line number	Diff line change
`@@ -37,7 +37,7 @@`
`37`	`37`	`{`
`38`	`38`	`"title": "Ask on Discord",`
`39`	`39`	`"description": "Join our support channel",`
`40`		`- "icon": "discord",`
	`40`	`+ "icon": "messages-square",`
`41`	`41`	`"href": "https://discord.com/channels/1299087524056010902/1299436491839246409"`
`42`	`42`	`}`
`43`	`43`	`]`
`@@ -286,7 +286,7 @@`
`286`	`286`	`"type": "button",`
`287`	`287`	`"href": "https://discord.com/invite/b9UuaZRyaB",`
`288`	`288`	`"label": "Discord",`
`289`		`- "icon": "discord"`
	`289`	`+ "icon": "messages-square"`
`290`	`290`	`}`
`291`	`291`	`]`
`292`	`292`	`},`