Agentic Spec
tishsingh399/agentic-spec
Contrato de design system executável para agentes IA validarem contra
Ver no GitHubMCP server que gera especificações de design systems legíveis por máquina a partir do Figma. Cria um contrato fechado (tokens, variantes, ARIA obrigatória) que agentes IA como Claude podem validar e respeitar antes de gerar código, eliminando inventos de tokens e estados perdidos.
Instalação
npx convez-ai tishsingh399/agentic-spec1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Sincronizar Figma com especificações que Claude/Cursor respeitam
- Validar que código gerado por IA usa tokens e variantes corretos
- Documentar design systems com contrato fechado (token_contract, semantic_parts, ARIA)
Veredito

Solução madura e bem pensada para o problema real de design systems à deriva. Preenche um gap genuíno entre Figma/Storybook e agentes IA, com validação rigorosa e contrato fechado que força conformidade. Recomendado para equipes que usam IA para gerar UI e precisam de garantias de qualidade.
README
A tradução para o português deste README ainda está na fila.
agentic-spec
Generate machine-readable design system specs that AI agents can read, validate against, and extend. Bridges Figma → spec → code.
Reference implementation: Clementine DS — the spec format originated there. Mintlify docs · Live Storybook · Notion docs.
What this is
Design systems usually ship two artifacts: a component library and a Storybook. Both drift from documentation the moment the first PR lands. When an AI agent (Claude, Cursor, an MCP server) is asked to use the system, the agent has nothing concrete to anchor to and reliably:
- invents tokens that don't exist (
color.brand.primary) - skips required ARIA (focus ring,
aria-busy) - misses interaction states (focus, loading, error)
- picks the wrong variant for the context
agentic-spec ships a third artifact — a per-component index.md + tokens.json pair — with a closed contract the agent must respect:
token_contractis a closed list. Anything else is a lint failure.semantic_partsnames every region a token can target.required_ariaandinteraction_statesare enumerated.sourcespoints the agent at the exact code, story, and token files.
The spec format is the one used in Clementine DS, an agentic React design system with 3-tier tokens (primitive → semantic → component) and one spec per component.
Install
npm install -g agentic-spec
# or use without installing:
npx agentic-spec --help
Requires Node 18+.
Commands
agentic-spec init <name>
Scaffold a new spec for a component.
agentic-spec init tooltip --out ./specs --ds-version "tina-ds@HEAD"
# ✓ Wrote ./specs/tooltip/index.md
# ✓ Wrote ./specs/tooltip/tokens.json
Fills in defaults for status (Draft), last_verified (today), code/storybook/token paths. You fill in semantic_parts, token_contract, and the prose body.
agentic-spec validate <dirs...>
Validate one or more spec directories. Exits non-zero on any error.
agentic-spec validate ./specs/button ./specs/modal
# PASS button (./specs/button)
# tokens: 13 in contract, 13 in tokens.json · states: 6 · parts: 5
# FAIL modal (./specs/modal)
# tokens: 4 in contract, 4 in tokens.json · states: 4 · parts: 5
# error ai-ready-gate status=AI-Ready requires checks.aria_correct=true (checks.aria_correct)
Checks:
| Rule | What it catches |
|---|---|
missing-spec / missing-tokens | files don't exist |
bad-frontmatter | YAML doesn't parse |
identity-mismatch | spec's component name ≠ tokens.json's |
missing-token-entry | token in token_contract has no tokens.json entry |
orphan-token-entry | tokens.json entry not referenced by contract |
bad-token-tier / bad-token-path | entry is malformed |
bad-status / bad-date / future-date | metadata is wrong |
lying-check | self-reported checks.tokens_valid=true when validator says otherwise |
ai-ready-gate | status: AI-Ready requires all 5 checks to be true |
Add --json for machine-readable output (good for CI).
agentic-spec from-figma <url> (in progress)
Generate a spec from a Figma component via southleft/figma-console-mcp. The CLI defines the adapter shape (src/extract/figma-mcp.ts) and the snapshot→spec mapping. The actual MCP transport is provided by the host agent (Claude Code, Cursor) — agentic-spec is deliberately decoupled from any specific MCP client.
See ROADMAP.md for the integration shape.
Example
The examples/button/ directory contains a real spec (the Button from Clementine DS) you can validate:
agentic-spec validate examples/button
# PASS button (examples/button)
# tokens: 15 in contract, 15 in tokens.json · states: 6 · parts: 5
The contract is 15 component-tier tokens (button.bg.default, button.fg.on-filled, button.border.focus, ...) — each one references a semantic token, which references a primitive. The validator checks every link in the chain.
The spec format in 30 seconds
---
component: button
ds_version: clementine-ds@HEAD (2026-06-08 verified)
status: AI-Ready
last_verified: 2026-06-08
category: Component
required_aria: [aria-label, aria-disabled, aria-busy]
semantic_parts:
root: The native <button> — owns interactive state, focus ring
label: Text content
icon-leading: Optional leading icon
token_contract:
- button.bg.default
- button.bg.hover
- button.border.focus
# ... closed list of 15 component-tier tokens
interaction_states: [default, hover, focus, active, disabled, loading]
checks:
aria_correct: true
structure_correct: true
states_complete: true
tokens_valid: true
no_invented_styles: true
sources:
code: { path: packages/ui/src/components/Button.tsx, framework: react }
storybook: { path: apps/storybook/stories/Button.stories.tsx }
tokens: { semantic_light: packages/tokens/src/semantic-light.json }
---
# Human-readable docs go below.
Why this matters
When the contract is explicit and closed, an agent can:
- Pre-validate before writing code. "I want to use
color.indigo.500for the button — is that in the contract? No → don't write it." - Generate code that respects the system on the first pass.
- Detect drift mechanically: spec says
loadingis a state; story file has noloadingstory → flag it. - Onboard fast: every component is documented in the same place, same shape.
This is the missing link between MCP-style "I can read Figma" tooling and "I can write code that matches the system."
Roadmap
See ROADMAP.md. Short version:
- ✅
validatecommand, full ruleset, JSON output - ✅
initcommand, scaffolding - ✅ Type definitions for
AgenticSpec/TokensContract - ✅ figma-console-mcp adapter shape
- ⏳ End-to-end
from-figma(needs host MCP wiring + tests) - ⏳
driftcommand (compare spec ↔ TSX ↔ Storybook) - ⏳ Watch mode for live validation
- ⏳ GitHub Action for PR validation
License
MIT — see LICENSE.
By Tina Singh. Working on agentic tooling at the design ↔ code boundary.