Spec-driven development

Why spec-driven

Agents are good at writing React once they know which components to reach for. GitHub Spec-Kit, AWS Kiro, and Claude Code plan mode all produce spec.md / tasks.md artifacts — none of them know the Hex UI catalog. Hex UI closes that loop with recipes, a resolver, and a verifier. No server. No runtime. Same copy-the-code distribution.

The four MCP tools

These compose with the existing 7 tools (search_components, get_component, …) — the agent chooses the one that matches its intent.

• resolve_spec— deterministic keyword + tag matching against every component’s schema. Give it a brief, get a ranked shortlist with whenToUse / whenNotToUse reasons. No LLM call server-side.
• list_recipes — catalog of every recipe: slug, title, component list, token budget.
• get_recipe— full recipe: ordered steps, union of npm peer deps, post-install checklist (author-written plus items auto-derived from each step’s commonMistakes and accessibilityNotes).
• verify_checklist— cross-check what the agent claims it installed against the registry’s internal-dependency graph. Flags missing deps (combobox without popover + command) and returns the recipe’s checklist for the agent to walk.

// MCP tool call
{
  "name": "resolve_spec",
  "arguments": { "brief": "build me a settings page with notifications toggle" }
}

// → ranked component + recipe matches
{
  "recipes": [
    { "slug": "settings-page", "score": 20, "matchReason": ["recipe slug contains \"settings\""] }
  ],
  "components": [
    { "component": "switch", "score": 6, "whenToUse": "Use for settings that take effect immediately..." }
  ]
}

Recipes

Six recipes ship in-tree. Each is a static JSON file in registry/recipes/ with ordered install steps and a post-install checklist. Authoring a new recipe is a single file under packages/registry/src/recipes/<slug>.recipe.ts; the build step compiles it and merges checklist items derived from each component’s AI hints.

• Auth form (auth-form) — Login / signup with validation + error surface.
• Settings page (settings-page) — Grouped cards + form fields + per-section save.
• Pricing table (pricing-table) — Three-tier grid with highlighted plan.
• Data table view (data-table-view) — Search + paginated table + row actions.
• Destructive confirm (confirm-destructive) — Typed-name confirmation flow.
• Command palette (command-palette) — Cmd-K dialog with grouped actions.

CLI shortcut

If you’re driving Hex UI from a shell instead of an MCP client, the CLI exposes the same surface:

# Discover recipes
hex recipe list

# Install every component in a recipe + print its checklist
hex recipe add settings-page

hex recipe add <slug> runs hex add for every step in order, then prints the checklist as plain markdown the agent can paste into a PR body.

How an agent uses this

1. The human writes a brief (or Spec-Kit produces a spec.md).
2. Agent calls resolve_spec; sees a recipe ranks first.
3. Agent calls get_recipe for the full step list + checklist.
4. Agent installs the components (via MCP get_component or hex add).
5. Agent calls verify_checklist to confirm nothing is missing, then walks the checklist.

See the MCP Server page for wiring into Claude Code or Cursor.