Spectacular

Spectacular turns a Figma component into a compact, schema-valid specification — and then turns that specification into working code, Figma canvas documentation, analysis reports, and a versioned record of how the component changed. A Figma plugin and a command-line interface produce the same output, from the same schema.

Evaluating styles and layers across variants is a differencing problem, not a judgment call, so a script does it in about a second per component for zero AI tokens. What a spec deliberately leaves out — behavior, accessibility nuance, motion, naming taste — is where agents and engineers are good, and that work happens downstream against a record they can trust.

The record is the point. When Figma, agents, engineers, and CI all read from the same spec, change stops being a handoff and starts being a sync.

Open the plugin · Set up the CLI · Explore the schema · Docs

Background reading: Components as data · Spec-driven UI component development

The ecosystem

The CLI installs some dependencies and the private transform packages for you (but not storybook, you do that); the plugin compiles specs-from-figma and figma-from-specs from source.

Why computation over inference?

Schema: what Specs record

@directededges/specs-schema is the contract. TypeScript types and JSON Schema describe the same structure at all times, the package carries no logic, and both the CLI and the Figma plugin consume it rather than defining their own shapes. One spec accounts for every layer and property of a component, consistently across its variants.

npm install @directededges/specs-schema

Exports are type-only but for two runtime constants, DEFAULT_CONVENTIONS and DEFAULT_SETTINGS. JSON Schema ships five addressable subpaths — component, concern, metadata, conventions, settings — alongside the TypeScript types. Every type has a page under Schema, and CONSTITUTION.md governs what may change and how.

Further reading: Component contracts and schemas.

Decision records

Schema changes are proposed and tracked through Architecture Decision Records in adr/. Each one records the context, the options considered, and the decision; accepted ADRs publish to the docs site automatically.

Contributions are welcome. Clone the repo, run npm install at the root, and use npm run build and npm test to validate changes. All packages use Vitest with globals enabled. This repo ships Claude Code skills for the full ADR lifecycle:

Setting up a workspace

Two paths to the same workspace. Neither is a lesser version of the other — the CLI is a command-line tool first, and the agent path drives those same commands.

Command by command, following Getting Started:

npm install -g @directededges/specs-cli
specs init       # write config/conventions/<platform>.yaml and config/settings.yaml
# add your Figma file key to config/settings.yaml, and FIGMA_TOKEN to .env
specs fetch      # pull the file, variables, and styles
specs scan       # write the manifest, then tick the components you want
specs build      # generate, analyze, emit every platform, publish Storybook — once

The first build emits every platform, because nothing has said otherwise yet. The trees it creates are then the standing answer: delete webcomponents/ and later runs stop emitting there. Naming steps explicitly — --only react — also counts as saying otherwise.

With an agent, three steps:

npm install -g @directededges/specs-cli
specs skills install    # writes the procedures into .claude/skills/

Then tell Claude Code:

Follow the specs-cli.workspace.setup skill to set up a Spectacular workspace here.

It handles install, config, token setup, fetch, curation, the first build, and a running Storybook — stopping twice: once for which components to spec, once for which of the icon, state and role passes to run. The only prerequisites are Node 20.19+, a Figma file URL, and a Figma personal access token.

Commands

Two commands do everything in order. The rest are the steps they run, and each reads what the one before it wrote.

data/ ──► data/<alias>.manifest.md ──► specs/ ──┬──► react/src/
  ▲              ▲                               ├──► webcomponents/src/
  │              │                               └──► storybook/content/
specs fetch    you tick the boxes

Exp marks an experimental command — usable, but its flags and output may still change.

Whole workspace

Setup

Data in

Specs out

This is the one command a license changes. Free output carries full component structure; Pro output adds token references, prop and visibility bindings, composition, and invalid variant combinations.

Further reading: Figma component specs on command.

Code out

Both targets write the same five artifacts, documented one page each under Code: the contract, the scaffold, the stylesheet, its CSS variables, and Storybook stories. Behavior comes from role concepts declared in the spec rather than from per-component code.

Further reading: Generating code from specs.

Analysis

• props — every prop across the library, and which components share one
• styling — token and raw-value usage across the spec tree
• dependencies — what composes what, and the blast radius of a change
• keys — naming consistency across properties and elements
• roles — which role concepts are declared, and where they are missing

Versioning

Versioning classifies a workspace diff, cuts a version folder, writes ledger entries, and produces an itemized changelog — including a pre-merge report for a Figma branch before anyone merges it.

Figma, Storybook, and visual testing

render closes the loop: a spec authored or edited outside Figma becomes a real component on the canvas. See Render to Figma, Storybook, and Testing.

The Figma plugin

Spectacular selects a component or component set, draws a visual specification onto the canvas, and caches the machine-readable spec data on the document — ready to copy into an LLM or read over the bridge.

Six output sections are drawn on canvas: Anatomy, Props, styling inventory, Modes, Layout, and Data. Seven panes control them:

• Specs — every spec already generated in the document, to re-run, inspect, or copy as YAML or JSON.
• Create — generate a spec from the current selection, with progress as it goes.
• Canvas Output — control the spec frames drawn on the canvas.
• Settings — sections, format, detail level, props, variants, elements, examples, foundations, layout and multi-column layout, and custom styling.
• Bridge — an opt-in local WebSocket on port 9001 that lets the CLI read the current selection, or build a component from a spec.
• Account — license activation and tier state.
• About — version and links.

Figma best practices covers what the plugin expects of a well-built library.

Documentation

spectacular.systems is authoritative for how Spectacular is intended to work; this repository is authoritative for what the code does.

• Command line — overview, workflows, and one page per command with its flags
• Schema — one page per type, plus the deep style, typography, and effects property trees
• Figma — plugin output sections and formatting
• Code — what specs react and specs webcomponents emit, artifact by artifact
• Storybook — the portable Storybook over the emitted trees
• Versioning — change classification, history, identity, reports
• Guides — 19 how-tos for specific features, from variant layering to code-only props
• Settings — one page per convention and setting
• Roles — role concepts, inventory, and precedence
• Releases — merged schema and CLI changelogs

The site's Decision Records section is generated from adr/ at build time, so an accepted ADR publishes itself.

Further reading

• Components as data — why a component is better held as a record than as a drawing
• Spec-driven UI component development — the loop this ecosystem is built around
• Component contracts and schemas — what belongs in a contract, and what does not
• Figma component specs on command — generating specs from the command line
• Generating code from specs — React and Web Components from a spec

Free and Pro

Everything is usable free. Nothing is time-limited, watermarked, or withheld — a free spec is a complete, valid spec, and a free React component renders. Pro connects a component to your token system, its other components, and every state it can be in.

Pro is $10/month. Purchase a license, or read Licensing for keys, metering, and the full gating detail.

Issues

Check the existing issues before opening a new one. For a bug, include:

• Figma version and operating system
• Steps to reproduce
• Expected versus actual behavior
• Screenshots, if they help

For a feature request, include a clear description, the use case, and any relevant mockups.

Questions are welcome in the Slack community.

Licensing

When extending or reusing the schema, credit Nathan Curtis, link to this repository and to the license, and indicate any modifications you made.

"This project uses the Spectacular UI Component Schema by Nathan Curtis of Directed Edges, licensed under CC BY 4.0."

Disclaimer: This is an independent project and is not officially affiliated with Figma Inc.