Designing a plugin that treats documentation as a design artifact, not an afterthought.

A component library without documentation is a tool without instructions. Designers detach components they don't understand. Developers implement them inconsistently. New team members build mental models from whatever they can infer. The knowledge that explains when to use a Primary button versus a Secondary one, or why a Card's slot accepts certain components and not others, lives in someone's head or in a doc no one opens.

The problem isn't that teams don't care about documentation. It's that writing it is slow, unstructured, and disconnected from the actual design file. By the time a component ships, there's no time left to document it properly. And when there is time, the documentation ends up somewhere else — a Notion page, a Confluence article, a shared doc that was accurate on the day it was written and hasn't been updated since. It drifts. It gets ignored. Eventually it becomes a liability.

The premise behind canon is simple: documentation that exists next to the component it describes is always more likely to be current than documentation that lives somewhere else. When a component changes, the frame attached to it is right there. When a developer opens the file for handoff, the context they need is already visible. When a designer joins a team and tries to understand the system, they don't have to go hunting.

canon keeps documentation in the file, on the canvas, connected to the component. Open the plugin and the Library view scans your entire file, surfacing every master component sorted by documented versus undocumented status. A coverage percentage and health score show exactly where your system's knowledge gaps are. Click any row to jump to that component on the canvas and open its annotation panel.

The Annotate panel gives you structured fields: design rationale, when to use, when not to, variant decision guidance, accessibility notes, slot composition, contribution rules, evolution notes, related components, and token usage. A naming convention validator sits at the top so documentation always starts from a clean, standardized foundation.

Suggest all fires parallel AI requests for every empty field at once and populates them top to bottom in order. Individual field suggests work the same way. Teams bring their own Anthropic or OpenAI API key. Every non-AI feature works without one.

The Foundations tab documents your token inventory — variables, text styles, paint styles, and effect styles — grouped by prefix and type. Each group gets its own description, usage notes, and do and don't fields.

When you're ready to share, canon exports your entire documented system as a self-contained HTML doc site. No server, no dependencies. Open it in a browser and get a searchable, filterable reference with sidebar navigation, coverage health indicators per page, and a dark, light, or neutral theme switcher.

When you're ready to hand your system to an AI coding agent, canon exports CLAUDE.md and AGENTS.md in one click. Drop either file into your codebase and the agent knows when to use every component, when not to, how to choose between variants, and what accessibility requirements apply. The content is your team's human-authored documentation — not generated on export. Figma MCP gives agents eyes. Canon gives them judgment.

The temptation with any AI-powered tool is to make generation the primary action. The problem is that AI-generated documentation you haven't read is documentation you haven't written. It might be 80 percent right and 20 percent confidently wrong in ways that only surface when a developer implements something incorrectly six months later.

canon is built around a different principle: every field is an editable textarea that grows as you type. The Suggest button fills it in, but the designer owns it. AI-generated content carries a visible indicator until the user makes their first edit, marking a clear distinction between what was generated and what was confirmed. That distinction matters for trust, and trust is what makes documentation actually get used.

The early version of canon had one look: dark. Near-black surface, structured typographic hierarchy, amber accent. It worked. But it assumed every Figma file was dark by default, and real design system files are not. A plugin that drops visually jarring documentation frames into a light-mode file isn't a tool teams will keep around.

The annotation frame system was redesigned as three discrete themes — dark, light, and neutral — each with a fully resolved color set derived from the same structural decisions. The accent color is also configurable: teams can replace the default amber with any hex value to match their system's personality. The plugin panel stays dark always. The canvas output adapts. Both surfaces look like they belong where they are.

The framework setting compounds this. Teams declare their design framework during onboarding — Material Design, Carbon, Fluent, Human Interface Guidelines, or none — and every AI suggestion generated from that point forward uses the right vocabulary and pattern conventions for that system. A Button/Primary in a Material system has different usage expectations than the same component in Carbon. The AI should know the difference, and now it does.

Two features address the documentation lifecycle problem most tools ignore. Stale detection fingerprints a component's structure at the moment it's documented and compares it on every subsequent open, surfacing a warning when the component has changed and the docs haven't caught up. Status gives every component a visible state: Draft, In Review, Ready for Handoff, or Deprecated. When a component marked Ready gets updated, canon automatically reverts it to Draft. A developer can't be misled by documentation that looks current but isn't.

The thumbnail badge places a coverage indicator on the file's cover frame so anyone browsing a team's Figma home can see the state of the system before opening it. The design is a tick-mark dial — a ghost ring with a single mark tracking coverage around the circumference. One metric, no decoration. The color shifts across three thresholds as coverage improves.

Component health scoring evaluates every documented component across six observable criteria and surfaces the result in the Library view, giving design system leads a precise signal about what needs attention rather than a vague sense that something is incomplete.

A plugin that stores data in a Figma file is a guest in someone else's house. Early in the build, the storage model used one pluginData key per field per component — a pattern that produces readable code but multiplies silently across a 200-component file into hundreds of kilobytes of hidden overhead.

The final storage strategy consolidates all per-component data into a single JSON blob under one key, abbreviates internal field names, and omits empty fields entirely. Nine total keys in the entire codebase, down from 21 in the first draft. A component with nothing documented writes nothing to the file. The worst-case footprint on a fully documented 200-component library is under 1% of a typical Figma file's total size.

The AI integration surfaced a less obvious constraint. Figma plugin panels run in a sandboxed iframe with a null origin — and every major AI provider blocks null-origin requests at the API level, regardless of what the plugin manifest declares. The solution was a lightweight Cloudflare Worker that sits between the plugin and the AI providers, adding the correct headers and forwarding the user's API key through without storing it. The Worker adds zero configuration burden for end users and costs nothing at typical usage volumes. It's the kind of architectural problem that only becomes visible once you're deep in the build — and the kind that separates a plugin that ships from one that doesn't.

Performance at scale surfaced a second class of constraint. On a 4000-component file, the wrong init sequence locks the plugin for 30 seconds before anything renders. The solution was a layered gate system: a single O(1) pluginData flag skips expensive traversals entirely when no components have been documented; a settings snapshot skips annotation sync when nothing has changed since the last open; a coverage cache skips a full document scan on every badge redraw. Each gate was added in response to a real freeze on a real file. The plugin opens in under three seconds on Carbon v11, IBM's design system, which has over 4000 components.