convez.ai
MCP ServerDesign & UIIntermediário
tishsingh399

Agentic Spec

tishsingh399/agentic-spec

Contrato de design system executável para agentes IA validarem contra

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP 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-spec

1 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

Estrelas
5
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
—
Issues abertas
0
Contribuidores
1

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.

npm version license node status

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_contract is a closed list. Anything else is a lint failure.
  • semantic_parts names every region a token can target.
  • required_aria and interaction_states are enumerated.
  • sources points 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:

RuleWhat it catches
missing-spec / missing-tokensfiles don't exist
bad-frontmatterYAML doesn't parse
identity-mismatchspec's component name ≠ tokens.json's
missing-token-entrytoken in token_contract has no tokens.json entry
orphan-token-entrytokens.json entry not referenced by contract
bad-token-tier / bad-token-pathentry is malformed
bad-status / bad-date / future-datemetadata is wrong
lying-checkself-reported checks.tokens_valid=true when validator says otherwise
ai-ready-gatestatus: 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:

  1. Pre-validate before writing code. "I want to use color.indigo.500 for the button — is that in the contract? No → don't write it."
  2. Generate code that respects the system on the first pass.
  3. Detect drift mechanically: spec says loading is a state; story file has no loading story → flag it.
  4. 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:

  • ✅ validate command, full ruleset, JSON output
  • ✅ init command, scaffolding
  • ✅ Type definitions for AgenticSpec / TokensContract
  • ✅ figma-console-mcp adapter shape
  • ⏳ End-to-end from-figma (needs host MCP wiring + tests)
  • ⏳ drift command (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.

Ver o original no GitHub

Bom para

Relacionados