How to use Sistema

A practical walkthrough — from setting up your project to running plays end-to-end.

Adding a DESIGN.md to your project

A DESIGN.md file is a short, structured description of your product's visual language — written specifically for AI coding tools to read before generating design system artifacts. It lives at the root of your repository alongside CLAUDE.md or similar agent context files.

ℹ

What is DESIGN.md? A plain-text file that describes a design system's visual language — colors, typography, spacing, components — in a format AI coding tools can read and act on. Introduced by Google Stitch. Read the spec →

Run the Generate a DESIGN.md play

Open the Generate a DESIGN.md play, fill in your project context, and paste the prompt into Claude Code or your preferred AI coding agent.

Save the output as DESIGN.md

Place it at the root of your project. The file format follows the Google Labs DESIGN.md convention — a brief spec covering color, typography, spacing, shape, and key component decisions.

my-project/
├── DESIGN.md          ← place it here
├── CLAUDE.md          ← or alongside this
├── src/
└── ...

Reference it in future prompts

Once the file exists, every subsequent play in the playbook can reference it. The agent reads DESIGN.md to stay consistent with your established decisions rather than starting from scratch each time.

Read DESIGN.md first, then implement the Button component using the token values defined there.

Referencing KB content in prompts

The Sistema knowledge base is publicly accessible at stable URLs. Every play in the playbook already includes fetch instructions pointing to specific KB pages — but you can reference any KB content directly in your own prompts.

Browse to the content you need

Find the relevant page in the knowledge base. Each design system has guidance, implementation docs, and token assets — organized by category.

Use the page URL in your prompt

Tell the agent to fetch the page before generating. The KB serves raw markdown via the /raw/ endpoint, which agents can read directly.

Fetch https://sistema-bay-seven.vercel.app/raw/design-systems/material/guidance/foundations/color-system and use it as the reference for generating color role tokens.

Or use the bundle endpoint for multiple files

The /bundle/ endpoint returns all files in a category as a single markdown document — useful when the agent needs the full picture of a topic.

Fetch https://sistema-bay-seven.vercel.app/bundle/design-systems/material to get all Material Design 3 guidance, then generate a token architecture for a mobile-first product.

URL patterns

/kb/design-systems/material/guidance/foundations/color-system → rendered page

/raw/design-systems/material/guidance/foundations/color-system → raw markdown

/bundle/design-systems/material → all files concatenated

Running a playbook end-to-end

Here's a complete example of using Sistema to build the color layer of a new design system — from a seed color to deployable CSS custom properties. This is Stages 1–3 in sequence.

Stage 1Define the system

Open the Generate a DESIGN.md play. Fill in your product context — company name, product type, primary brand color. Paste into Claude Code. Save the output as DESIGN.md.

# DESIGN.md — Meridian Analytics

## Color
Primary: Blue (#2563EB). Semantic token model — no raw values in components.
Themes: light (default) + dark.
...

Stage 2Generate primitive tokens

Open the Generate a Color Scheme play. Enter your primary color. The play tells the agent to fetch Material Design 3's color system from Sistema as a structural reference, then generate your palette in the same format.

/* Generated: Meridian primitive palette */
--color-blue-10: #EFF6FF;
--color-blue-20: #DBEAFE;
...
--color-blue-60: #2563EB;  /* primary */
...

Stage 3Map semantic roles

Open the Map an Existing Palette to Semantic Roles play. Paste in the primitive tokens from Stage 2. The agent assigns each primitive to the correct semantic role — background, surface, primary, on-primary, etc. — producing deployable CSS custom properties for light and dark themes.

:root {
  --color-background: var(--color-gray-10);
  --color-surface: #FFFFFF;
  --color-primary: var(--color-blue-60);
  --color-on-primary: #FFFFFF;
  ...
}

[data-theme="dark"] {
  --color-background: var(--color-gray-100);
  --color-primary: var(--color-blue-40);
  ...
}

At this point you have a committed, structured color system. Continue to Stage 4 to specify and implement components using these tokens.