Skip to main content

​
What are Ditto specs?

Ditto specs integrate Ditto with your design system. A .ditto.md file lives next to a design system component (a Button, a Dialog, a Card) and declares its text surfaces: every piece of user-facing copy the component renders, whether passed as props, children, or hardcoded in the component. The Specs CLI syncs the style guide rules that apply to those surfaces from Ditto into the file, so the rules sit in the repo next to the component they govern. The file is metadata; nothing imports it at runtime. It is there so that:
  • Context is scoped to the design element. An agent editing a Dialog reads the Dialog’s surfaces and rules, not the whole style guide.
  • Usage is enforced for agents. The spec names each surface, its tags, and its maxLength, so copy for that component goes through the rules every time it is written or edited.
  • Ambiguity and token spend go down. The agent gets the rules already matched to the component by tag, instead of reasoning over every rule in the workspace.

​
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 its role in the design system.
  3. Pull style guide rules from Ditto with ditto-spec pull. The CLI matches rules to surfaces by tag.
  4. Agents read the spec when writing or editing copy for the component and follow its rules.