Specs

Specs 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.

Surface	What it is	Where it lives
Specs 2	Figma plugin — specs on canvas, spec data on the document	Figma Community
@directededges/specs-cli	18 commands running the ecosystem plus source for analysis, versions, css, storybook, testing	packages/cli/
@directededges/specs-schema	The contract — TypeScript types and JSON Schema	packages/schema/
Documentation site	~150 pages	Source in site/
@directededges/specs-from-figma	Transform Figma → spec, with Plugin API and REST runtimes	Private, published to npm
@directededges/react-from-specs	Transform spec → React	Private, published to npm
@directededges/webcomponents-from-specs	Transform spec → Web Components (Lit)	Private, published to npm
@directededges/figma-from-specs	Transform spec → Figma canvas	Private, published to npm
from-specs	Shared spec-reading core for the emitters	Private, never published

Why computation over inference?

	Specs	Agentic Figma extraction
Speed	~1 sec (CLI) / ~10 sec (plugin) per component	~5–10 minutes per component
AI cost	Scripted — 0 tokens per component	25/50/100,000+ tokens per component
Repeatability	Deterministic and mechanical	Inference errors, gaps, and overconfidence
Output	Schema-valid YAML/MD, ready for testing and versioning	Unstructured Markdown, unpredictable to verify
Platforms	Schema-based and cross-platform	Guessing your intents

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

Part	Types	Pro
Component	Component, Variant, Variants, Metadata, RunMetadata, concern documents
Anatomy	Anatomy, AnatomyElement, ElementTypeRef, RoleConceptName, ActionEntry
Props	Props, BooleanProp, StringProp, EnumProp, SlotProp, NumberProp, PropConfigurations
Elements	Element, Elements, ElementType, ElementExtensions
Layout	Layout, LayoutNode, Sides, Corners, Position, ItemSpacing
Styling	Styles, Style, ColorStyle, Typography, Effects, GradientValue, TokenReference	TokenReference
Images	ImageValue, ImageData, ImageProp, ImageBinding, ObjectFit
Slots	Children, SlotBinding, SlotContent, SlotContentRef, Composition	all
Bindings	PropBinding, Conditional, ConditionExpression	PropBinding
Subcomponents	Subcomponent, Subcomponents, SubcomponentSource	all
Instance examples	InstanceExample, InstanceExamples	all
Assets	GlyphStructure, GlyphStructureNode
Conventions	Conventions, PlatformConventions, SpecsConventions, ValueConvention
Settings	Settings, ResolvedSettings, ColorFormat, SourceEntry

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:

Skill	Purpose
/specs.adr.create	Draft a new ADR, claim the next number, and reserve it in the index
/specs.adr.implement	Apply an ADR's type and schema changes to types, schema, tests, and changelog
/specs.adr.accept	Validate the implementation, mark the ADR accepted, and update the index

Commands

npm install -g @directededges/specs-cli
specs init     # write config/conventions/<platform>.yaml and config/settings.yaml
specs build    # scan, generate, analyze, emit, publish — the whole workspace, once

A guided walkthrough lives in Getting Started, and ONBOARDING.md is the same setup driven by Claude Code.

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

Command	What it does	Tier
specs build	Bring the workspace up to date once, then exit with the chain's code — the CI shape	Free	Exp
specs run	The same, then watch specs, data, and config and redo only what a change affects	Free	Exp

Setup

Command	What it does	Tier
specs init	Write config/conventions/<platform>.yaml and config/settings.yaml with production defaults	Free
specs skills install	Install the premerge and release orchestration skills into .claude/skills/	Free
specs migrate	Convert an older workspace layout to the current one	Free

Data in

Command	What it does	Tier
specs fetch	Download raw REST payloads — file, variables, styles — for every configured Figma source	Free
specs scan	Discover components and write a manifest you curate by ticking boxes	Free
specs applyCustomTokens	Inject $custom token objects from a mapping file into fetched data	Free
specs cache	Build the lookup tables render resolves specs against	Free	Exp

Specs out

Command	What it does	Tier
specs generate	Generate specs from fetched data, a curated manifest, or the live Figma selection with --from-bridge	Free + Pro

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

Command	What it does	Tier
specs react	Emit the React target into react/	Free + Pro	Exp
specs webcomponents	Emit the Web Components (Lit) target into webcomponents/	Free + Pro	Exp

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

Command	What it does	Tier
specs analyze	Run analyzers over the spec tree and write aggregate reports to analysis/	Free	Exp

• 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

Command	What it does	Tier
specs version	Version the spec workspace: diff, history, cut, tag, restore, figmapremerge, report	Free	Exp

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

Command	What it does	Tier
specs bridge	start, stop, status for the local bridge that reaches a running plugin	Free	Exp
specs render	Send a spec back into Figma and build the component on canvas	Free	Exp
specs storybook	init, dev, publish — a portable Storybook over the emitted trees	Free	Exp
specs testing visual	Pixel-diff the Storybook render against Figma exports, in eight explicit stages	Free	Exp

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

Specs 2 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

specsplugin.com is authoritative for how Specs 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.

	Free	Pro adds
Data	Component structure, variant evaluation, metadata	Token and style references, prop bindings, invalid combinations
Figma canvas output	Every output section, multi-column layout, all settings	Custom styling, the Examples settings, the Bridge pane
Code	The component, its contract, its stylesheet, one story per variant axis	Composition, glyphs, background images, compound stories, sticker sheets

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

Package	License
packages/schema/	CC BY 4.0
packages/cli/	MIT

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 Specs 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.