> ## Documentation Index
> Fetch the complete documentation index at: https://developer.dittowords.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Overview of Ditto spec files and the Specs CLI for AI-assisted content governance

<Info>
  The Specs CLI is in **alpha**. The file format and CLI interface may change between releases.
</Info>

## What are Ditto specs?

A `.ditto.md` file lives next to a component and declares its **text surfaces** — every piece of user-facing copy the component renders, whether passed as props, `children`, or hardcoded in the component itself. The CLI syncs matching style guide rules from the Ditto platform into each file, co-locating content governance directly in your design system alongside the components themselves.

The file is pure metadata; nothing imports it at runtime. Ditto spec files serve three consumers:

* **Agents** read them as fast-path context when writing or editing copy for a component.
* **The CLI** syncs style guide rules from the Ditto platform whose tags match each file's surface tags.
* **Humans** review content decisions in pull requests.

## How it works

1. **Scaffold** a spec for a component with [`ditto-spec scaffold`](/ditto-specs-cli-reference/commands#scaffold).
2. **Add surfaces and tags** — one entry per piece of user-facing text, tagged by semantic role.
3. **Pull** style guide rules from the platform with [`ditto-spec pull`](/ditto-specs-cli-reference/commands#pull). The CLI matches style guide rules to Ditto specs by tag intersection.
4. **Agents read the spec** at authoring time and follow the style guide rules when writing or editing copy.

## Next steps

* [Setup](/ditto-specs-cli-reference/setup) — install the CLI and configure your project
* [Commands](/ditto-specs-cli-reference/commands) — full reference for all CLI commands
* [Ditto Spec Files](/ditto-specs-cli-reference/spec-files) — format and structure of `.ditto.md` files
* [Agent Skills](/ditto-specs-cli-reference/agent-skills) — interactive workflows for Claude Code and Cursor