Skip to main content
The Specs CLI is in alpha. The file format and CLI interface may change between releases.

​
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.
  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. 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 — install the CLI and configure your project
  • Commands — full reference for all CLI commands
  • Ditto Spec Files — format and structure of .ditto.md files
  • Agent Skills — interactive workflows for Claude Code and Cursor