# SpecUI

> A `.specui/` folder plus a small CLI that turns your design system into a contract humans and coding agents can both read.

SpecUI is a design system in your repository: a `.specui/` folder holding tokens, components, patterns, assets, and rules, plus a `specui` CLI to scaffold it, validate it, sync a registry index, pull shadcn items, export tokens, and wire coding agents through AGENTS.md, rules, skills, and MCP.

Package: `@logicplanes/specui` · CLI command: `specui` · Docs site: https://logicplanes.github.io/specui/docs/ · Source: https://github.com/logicplanes/specui

## Quick install

```bash
npx @logicplanes/specui@latest init --name "My Product" --preset web-app --agents-md --ci github
npx specui validate .specui --strict
npx specui get button
```

## Documentation

Each link below is the page on the docs site. For a single-file ingest, use [https://logicplanes.github.io/specui/llms-full.txt](https://logicplanes.github.io/specui/llms-full.txt) — every page concatenated as plain markdown.


## How-to guides

- [Agent prompts](https://logicplanes.github.io/specui/docs/agent-prompts): Two autonomous prompts to install SpecUI in an existing app or start a new one with a coding agent driving the design end to end.
- [Agents & MCP](https://logicplanes.github.io/specui/docs/agents-and-mcp): AGENTS.md, the .specui agent docs, custom rules and skills, and the specui MCP server.
- [CI/CD](https://logicplanes.github.io/specui/docs/ci-cd): Gate pull requests with specui validate, strict mode, and GitHub Actions.

## Reference

- [CLI reference](https://logicplanes.github.io/specui/docs/cli): Every specui command — create, manage, distribute, and agent tooling.

## Getting started

- [Concepts](https://logicplanes.github.io/specui/docs/concepts): The mental model — contract, registry, layouts, tokens, and the agent loop.

## Community

- [Contributing](https://logicplanes.github.io/specui/docs/contributing): Contributing to the open-source specui CLI, and documenting your own SpecUI project.

## How-to guides

- [DESIGN.md bridge](https://logicplanes.github.io/specui/docs/designmd): Keep SpecUI as the source of truth and export DESIGN.md for tools that expect it.
- [Distribution](https://logicplanes.github.io/specui/docs/distribution): Move SpecUI trees between repos with load, link, push, pull, import, export, update, and diff.

## Getting started

- [FAQ](https://logicplanes.github.io/specui/docs/faq): Short answers about SpecUI, installation, agents, shadcn, and CI.

## Community

- [Introduction](https://logicplanes.github.io/specui/docs): What SpecUI is, the problem it solves, and how the documentation is organized.

## Reference

- [init reference](https://logicplanes.github.io/specui/docs/init-reference): Every flag and preset for specui init and specui new.

## Getting started

- [Install](https://logicplanes.github.io/specui/docs/install): Install the specui CLI globally or per-project, and verify your environment.

## How-to guides

- [Interop](https://logicplanes.github.io/specui/docs/interop): Export SpecUI to DESIGN.md, DTCG, Tailwind, CSS, and JSON — and compare versions.

## Intro

- [Documentation overview](https://logicplanes.github.io/specui/docs/overview): A map of every page in the SpecUI docs and where to start.

## Getting started

- [Quick start](https://logicplanes.github.io/specui/docs/quick-start): Scaffold SpecUI, register a component, validate, and optionally pull from a registry — in about ten minutes.

## How-to guides

- [Registries](https://logicplanes.github.io/specui/docs/registries): specui get — pulling shadcn/ui and custom registry items into your contract.
- [Scenarios](https://logicplanes.github.io/specui/docs/scenarios): End-to-end workflows — new apps, design-system repos, monorepos, agent teams, and migrations.

## Reference

- [Schema](https://logicplanes.github.io/specui/docs/schema): Required files and folders in .specui/ — the reference both humans and validate use.
- [Specification](https://logicplanes.github.io/specui/docs/spec): The normative SpecUI standard — purpose, layouts, agent protocol, validation.

## How-to guides

- [Tokens & components](https://logicplanes.github.io/specui/docs/tokens-and-components): Register tokens, components, assets, and patterns before you write application code.
- [Troubleshooting](https://logicplanes.github.io/specui/docs/troubleshooting): Common specui errors, validate failures, and how to fix them.
- [Validation](https://logicplanes.github.io/specui/docs/validation): What specui validate checks, strict mode, JSON output, and the doctor command.

## For agents and LLMs

- [Full docs as a single text file](https://logicplanes.github.io/specui/llms-full.txt) — all pages concatenated, no chrome.
- [Per-page markdown](https://logicplanes.github.io/specui/docs-md/install) — `/docs-md/<slug>` for any docs page.
- [Wiki source in the repo](https://github.com/logicplanes/specui/tree/dev/wiki) — `wiki/*.md` is the canonical source.
- [MCP server](https://logicplanes.github.io/specui/docs/agents-and-mcp/) — `specui mcp start` for MCP-aware agents.
- [Agent prompts](https://logicplanes.github.io/specui/docs/agent-prompts/) — copy-paste prompts to install SpecUI with a coding agent.

## Project links

- [npm](https://www.npmjs.com/package/@logicplanes/specui)
- [GitHub](https://github.com/logicplanes/specui)
- [Issues](https://github.com/logicplanes/specui/issues)
- [MIT licensed](https://github.com/logicplanes/specui/blob/dev/LICENSE)