Design documentation

A living documentation system built into Particles — write standards, usage guidelines, and branding pages as typed block documents whose embeds resolve against your token branch at render time. Docs that reference your tokens can never go stale. Design documentation is available on the Team plan and above. The knowledge graph explorer, release-pinned snapshots, and AI-drafted guidelines require the Business plan.

What it is

Doc pages live inside a project alongside your tokens, branches, and releases. Each page is a sequence of typed blocks — rich text, headings, and live embeds — stored and versioned on your branch. When you view a doc page, every embed resolves against the branch you are on, so the documentation always reflects the current state of your design system.

Mention any token, component, or doc page with [[token:name]] or [[doc:slug]] syntax and Particles auto-creates a backlink. The freshness engine watches those references: when a referenced token changes value, the doc is flagged as potentially outdated so authors know what to review.

Block types

Component-doc scaffolding

Every component in your Figma component graph can generate its own doc page scaffold automatically. Particles analyses the component anatomy, enumerates the tokens it binds, identifies any hardcoded gaps, and produces a ready-to-publish page with an anatomy diagram, a binding table, and placeholder sections for usage guidance and do/don't examples.

In Studio, open the component graph view for a component and click Generate doc. The scaffold lands as a draft in your doc pages — edit it, fill in the guidelines, and publish when ready. The coverage widget on your project dashboard tracks how many components have a published doc page, so you can see and close documentation gaps at a glance.

Doc search

All doc pages are indexed for hybrid semantic search. Search from the command palette in Studio or from the Figma plugin's Guidelines panel. Results are ranked by relevance across page titles, headings, and body text — the same embedding infrastructure that powers token search.

Freshness engine

When a token or component referenced in a doc page changes — value, alias target, scope, or name — Particles marks that page with a freshness warning. Authors see a banner identifying which references changed and a diff of what the old and new values were. Once reviewed and the page updated or confirmed as still accurate, the warning clears.

Figma Guidelines panel

Select any component on the Figma canvas and open the Guidelines tab in the Particles plugin. If that component has a published doc page, it renders inline — anatomy diagram, usage guidelines, do/don't examples, and the WCAG contrast checks — all read-only, always the live version from your branch.

Use the search bar in the Guidelines tab to find any doc page by keyword or semantic intent without leaving Figma. Results link directly to the relevant section so designers can read the specification for any component or token without switching tools.

Knowledge graph explorer

An interactive canvas that renders everything in your project as a connected graph — doc pages, tokens, components, themes, and WCAG contrast checks — with edges for every relationship. Edges from explicit [[mentions]] or authored links are drawn solid; edges derived from token bindings or component usage are dashed.

Click any node to open its detail panel without leaving the graph. Filter by node type, zoom to a subgraph around a single token, or trace the full neighbourhood of a component from Figma binding through to the doc pages that describe it.

Release-pinned doc snapshots

When you publish a release, Particles snapshots the rendered HTML of every doc page at that moment and attaches it to the release. You can then read the documentation exactly as it was for any past release — useful for audits, handoffs, and debugging regressions in a shipped version.

Navigate to Releases → [version] → Docs in Studio to browse the snapshot. The snapshot URL is also included in the release.published webhook payload under data.exports.docs-html and data.exports.docs-md.

AI-drafted usage guidelines

For any component that has been analysed via the component graph, Particles can draft a usage-guidelines section automatically. The draft is grounded in the component's anatomy, its token bindings, and the writing style of your existing published doc pages — so it matches your team's conventions rather than generic output.

Click Draft with AI on any doc page scaffold. The draft lands as an editable block — review, refine, and publish when ready. Nothing is auto-published; an author must confirm every change.

CI export & particles docs export

The release.published webhook payload includes signed export URLs for rendered Markdown and HTML versions of all doc pages at that release:

{
  "event": "release.published",
  "data": {
    "version": "1.4.0",
    "exports": {
      "tailwind-v4":  ".../export?format=tailwind-v4",
      "docs-md":      ".../releases/1.4.0/docs/export?format=md",
      "docs-html":    ".../releases/1.4.0/docs/export?format=html"
    }
  }
}

You can also export docs locally or in CI with the CLI:

# Export all doc pages for the current release as Markdown
particles docs export --format md --output docs/

# Export as HTML
particles docs export --format html --output dist/docs/

# Export a specific release
particles docs export --version 1.4.0 --format md --output docs/

The CLI reads particles-ui.json for the project ID and API credentials, writing one file per doc page into the output directory. Filenames match the doc page slug.

Stakeholder share links

Any doc page can be shared with stakeholders who do not have a Particles login. In Studio, click Share on a page to generate a signed, expiring read-only link. The recipient sees the rendered page — live embeds included — without needing to create an account.

Plan availability