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 bar shows progress. Click any row to jump to that component on the canvas and open its annotation panel.

The Annotate panel gives you eight structured fields: when to use a component, when not to, how to choose between variants, what accessibility requirements apply, how its slots are meant to be composed, and more. A naming convention validator sits at the top of the panel so documentation always starts from a clean, standardized foundation.

A single Suggest button uses Claude or GPT-4o's vision capabilities to generate a strong starting point for any field, reading the component's name, layer structure, variant properties, and visual appearance together. Teams bring their own API key. Manual entry and all non-AI features work without one.

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. 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. Handoff readiness status gives every annotation frame a visible state: Draft, In Review, or Ready for Handoff. 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.