Build Free Design System Docs with Astro Starlight

Docs hub Starlight MDX pages + sidebar + search

• Part 01 Included Component pages Props, states, usage, do/don't
• Part 02 Included Figma embeds Live frames via iframe share links
• Part 03 Included Storybook links Interactive demos in a separate app
• Part 04 Included Token reference Auto-generated from JSON source
• Part 05 Included Claude automation Re-generate docs from real code

I have built design system docs in Mintlify, Supernova, Notion, Confluence, and a custom Next.js site. The verdict, after all of that, is annoyingly boring: most teams need much less than they think they do. They need a fast site, a sidebar, search, dark mode, and a way to get content out the door without fighting the platform.

Astro Starlight gives you all of that for free. It’s open source, MDX-based, and the hosting is whatever Vercel free tier gives you. The trade-off is you do the styling and the polish work yourself instead of paying someone else to have done it. If you have a designer on the team, that trade-off is usually a win.

This guide covers the full setup, the styling system, embedding Figma frames live in your docs, the Storybook question, and how to use Claude Code to auto-generate docs from your real components.

---

Why Starlight (and when not to)

The honest comparison:

	Starlight	Mintlify	Supernova	Docusaurus
Cost	Free (self-hosted)	$120+/mo per team	Enterprise pricing	Free (self-hosted)
Setup time	10 minutes	5 minutes	1 hour+	30 minutes
Markdown / MDX	Yes (MDX)	Yes (MDX)	Limited	Yes (MDX)
Built-in search	Yes (Pagefind)	Yes	Yes	Plugin
Dark mode	Yes	Yes	Yes	Yes
Custom styling	Full control	Limited theming	Limited theming	Full control
Figma integration	Manual (iframe / image)	Manual	Native sync	Manual
Token sync	Manual or Claude Code	Plugin	Native	Manual
Vendor lock-in	None	Yes	Yes	None
You own the site	Yes	No	No	Yes

Pick Starlight when:

• You want full control of the design and styling
• You have at least one person comfortable in code
• The yearly cost of Mintlify or Supernova matters
• You don’t need deep Figma sync (or you can fake it with embeds)

Pick Mintlify when:

• You want polished public docs with no design work
• You have a small team and the monthly cost is fine
• The features they ship (analytics, AI search) matter to you

Pick Supernova when:

• You need automated Figma → docs sync as a core feature
• You have enterprise budget and procurement is not a blocker

---

What you get out of the box

Starlight ships with the boring-but-essential stuff already done:

• Sidebar nav with auto-generated entries from your file structure
• Search powered by Pagefind, no extra service required
• Dark mode with a toggle, no setup
• Code highlighting with Shiki (same engine as VS Code)
• Mobile responsive layout that actually works
• Internationalization if you ever need it
• Table of contents generated per page
• Fast because it’s static, no JavaScript framework on the page by default

You don’t have to build any of this. You write MDX, you get a docs site.

---

Setup in 5 minutes

Open your terminal and run:

npm create astro@latest -- --template starlight

Answer the prompts. Pick a folder name (design-system-docs works). Say yes to TypeScript and yes to installing dependencies.

Then:

cd design-system-docs
npm run dev

Open http://localhost:4321 and the docs site is already running.

The structure is:

src/content/docs/
  index.mdx           ← homepage
  guides/example.mdx  ← any folder becomes a sidebar group
astro.config.mjs       ← config: site title, sidebar, integrations
src/styles/custom.css  ← your CSS overrides (more on this below)

Edit src/content/docs/index.mdx and the page hot-reloads. That is the entire build loop.

---

Make it design-system shaped

Out of the box Starlight is generic developer docs. To make it a design system site you add these:

Token pages. Write tables in MDX manually, or import a JSON file and render it as a component. The simplest version is a markdown table with the token name, value, and a swatch. The fancier version is a custom Astro component that reads tokens.json and renders a sortable table.

Color, spacing, typography pages. One MDX file per category. Each has its own swatches or specimens. Write them once, link them from the sidebar.

Component pages. One MDX file per component. Title, description, when to use, when not to use, props, usage examples, do/don’t pairs. The structure is repetitive on purpose so contributors know exactly where to add things.

Changelog. Starlight has a built-in changelog plugin. Connect it to your GitHub releases and you’re done.

The whole point of design system docs is consistency, and a folder of MDX files with a fixed template gives you that for free.

---

Embedding Figma frames live in your docs

This is the killer feature most people don’t know about.

Figma lets you embed any frame as a live iframe. The viewer can pan, zoom, and click through the prototype without leaving your docs page.

To get the embed code:

1. In Figma, select the frame you want to embed
2. Click Share in the top-right
3. Switch to the Embed tab
4. Copy the iframe code (it looks like <iframe ... src="https://embed.figma.com/...">)

To paste it into MDX:

<iframe
  src="https://embed.figma.com/file/YOUR_FILE_ID/?node-id=1%3A2&embed-host=docs"
  width="100%"
  height="450"
  style="border: 1px solid #eee; border-radius: 8px;"
  allowfullscreen
/>

Now the actual Figma frame renders inside your docs page. When designers update the file in Figma, the docs update automatically. No screenshot management, no stale images.

For static screenshots (faster page loads, no Figma dependency at runtime), drop the PNGs into public/images/ and reference them with regular markdown:

![Button variants](/images/button-variants.png)

Use embeds for live prototypes (interactive flows worth exploring), use images for stable references (specs, measurements, anatomy diagrams).

---

Style it however you want

This is where Starlight stops looking like generic dev docs and starts looking like your brand.

Level 1: CSS variables. Starlight exposes its color tokens, spacing, and typography as CSS custom properties. Override them in src/styles/custom.css:

:root {
  --sl-color-accent: #6B8F00;
  --sl-color-accent-low: #DFFF82;
  --sl-color-text-accent: #2a3a00;
  --sl-font: 'Inter', system-ui, sans-serif;
  --sl-font-mono: 'IBM Plex Mono', monospace;
}

Register the file in astro.config.mjs:

starlight({
  customCss: ['./src/styles/custom.css'],
  // ... other config
})

Level 2: Component overrides. If you want to replace specific Starlight components (the header, the sidebar, the footer), point at your own .astro files in the config:

starlight({
  components: {
    Header: './src/components/MyHeader.astro',
    Footer: './src/components/MyFooter.astro',
  },
})

Level 3: Custom landing page. The homepage doesn’t have to be Starlight’s default. Set template: splash in the frontmatter and you get a blank canvas to design your own intro page.

Level 4: Full custom layouts. If you want to break out completely, you can wrap pages in your own Astro layouts. Most teams don’t go this far. The first three levels usually cover everything.

---

Storybook: embed or link?

Short answer: link to Storybook for the full component library, embed individual stories inline only when the prose really needs them.

The case for just linking:

• Storybook is its own thing, with its own controls, args, and addons
• Embedding via iframe means an extra hosting service (Chromatic, Vercel) for Storybook itself
• Iframes are slow to load and don’t always look right inside docs
• Designers and engineers will use Storybook directly anyway

The case for embedding specific stories:

• Useful for “here is what an error state looks like” mid-paragraph
• Lets readers play with one specific variant without context switch
• Works well for hero examples on a component page

How to embed a story (if you want to):

1. Host Storybook somewhere accessible (Chromatic free tier, Vercel, or GitHub Pages)
2. Get the iframe URL: https://your-storybook.vercel.app/iframe.html?id=button--primary
3. Embed in MDX:

<iframe
  src="https://your-storybook.vercel.app/iframe.html?id=button--primary"
  width="100%"
  height="200"
  style="border: 1px solid #eee; border-radius: 8px;"
/>

In practice, most teams I have seen do this: Starlight for the docs, Storybook for component dev and QA, a single “View in Storybook →” link from each component page. Two tools, clear separation.

---

Auto-generate docs with Claude Code

This is the part that turns a blank Starlight site into a real design system in an afternoon.

Open your component library folder in Claude Code, Codex, Cursor, or another repo-aware assistant. Then ask it:

Read every component in src/components/. For each one, generate a Starlight MDX file at docs/src/content/docs/components/<component-name>.mdx. Each file should have: a title, a one-sentence description, a table of props with their types and defaults, when to use, when not to use, and one usage example.

The assistant reads the source files directly. It generates real docs from real code, not from a stale template. When a prop gets added in code, you re-run the prompt and the docs update.

You can also ask it to:

• Generate token tables from your tokens.json file
• Pull color values into a swatches MDX page
• Write a changelog entry from the latest git diff
• Convert your Figma plugin output into MDX

The pattern is: the assistant reads your repo, writes MDX into the Starlight content folder, you commit, the site rebuilds. No translation layer.

---

Deploy it

Three free options, all of which take under 5 minutes:

• Vercel. Push to GitHub, import the repo on vercel.com, click deploy. Auto-deploys on every commit.
• Netlify. Same flow as Vercel, also free.
• Cloudflare Pages. Free with unlimited bandwidth, slightly more setup.

Vercel is the most common choice. The dedicated guide below walks through the full setup including custom domains, preview deploys for pull requests, and environment variables.

---

Trade-offs (the honest version)

Starlight is not strictly better than Mintlify. It is cheaper and you own it. Things you give up:

• The polish. Mintlify ships with a really nice default look. Starlight’s default is fine but generic. You will spend time on the visual layer.
• The hosted analytics. Mintlify gives you docs analytics out of the box. With Starlight you add Plausible or PostHog yourself.
• The AI search. Mintlify has built-in AI search across your docs. Starlight has Pagefind, which is keyword-only. You can layer something on top, but it’s extra work.
• The contributor UX. Mintlify lets non-technical contributors edit in a CMS-like view. Starlight requires editing MDX files in GitHub or your editor.

If those four things matter more than $120 a month, pay for Mintlify. If they don’t, Starlight gives you everything else for free.

---

Exercise

Spin up a Starlight docs site, generate 3 component pages, deploy

45 min

1. Create the project

   Open your terminal. Run npm create astro@latest -- --template starlight. Answer the prompts: pick a folder name like design-system-docs, say yes to TypeScript, yes to install dependencies. Then cd design-system-docs and npm run dev. Open http://localhost:4321.

   • The Starlight default site loads at localhost:4321
   • You see the sidebar, the search bar, the dark mode toggle
   • The example pages render with code blocks highlighted

2. Generate 3 component docs with Claude Code

   From your existing component library folder, run claude and prompt: “Read 3 components from src/components/. For each, write a Starlight MDX file at ~/design-system-docs/src/content/docs/components/<name>.mdx with: title, one-sentence description, props table with types and defaults, when to use, when not to use, one usage example.”

   • 3 MDX files are written into the components folder
   • Each one has props pulled from the actual code, not made-up
   • When you reload the dev server, all 3 pages appear in the sidebar automatically

3. Style it to match your brand

   Open src/styles/custom.css. Override at least 3 CSS variables: --sl-color-accent, --sl-font, and one more of your choice. Register the file in astro.config.mjs under customCss. Reload and confirm the colors changed.

   • The accent color changed from Starlight default to your brand color
   • The font changed away from the default
   • The site still feels readable at the new colors (no broken contrast)

4. Embed one Figma frame and one screenshot

   Pick one component you have in Figma. Get the embed iframe code from File → Share → Embed. Paste it into the relevant MDX file. Take a screenshot of the same component, drop it into public/images/, and reference it with markdown. Reload the page.

   • The Figma frame renders live in the docs page (you can pan and zoom)
   • The screenshot also renders, as a static image
   • You can compare both side by side and decide which one to keep

5. Deploy to Vercel

   Push the project to GitHub. Go to vercel.com, click “Add New” → “Project”, import the repo, accept defaults, click deploy. After 30 seconds you have a live URL. Share it.

   • You have a vercel.app URL live on the internet
   • All your docs pages load
   • Search works on the deployed site (Pagefind builds at deploy time)