What is DESIGN.md?

A design system file that defines visual identity tokens for frontend code generation.

A DESIGN.md is a structured Markdown file that captures your project's complete visual identity — colors, typography, spacing, component styling rules, layout principles, motion guidelines, and anti-patterns — in a single source of truth. Yukkai reads this file (or its in-app equivalent) and applies every token automatically when generating frontend code, ensuring visual consistency across screens, components, and sessions.

Overview

When you build user interfaces with an AI agent, one of the biggest challenges is consistency: the agent might pick a slightly different shade of blue on each render, choose a new font for every page, or ignore spacing conventions you established earlier. DESIGN.md solves this by codifying every design decision into machine-readable tokens that the agent consults before writing a single line of code.

A design system in Yukkai consists of two layers:

Layer What it holds How it's stored
Structured tokens Individual color hex values, font families, spacing scale, border radius Discrete parameters (primary_color, font_family, etc.)
Raw content (DESIGN.md) Component styling rules, layout principles, motion & interaction guidelines, anti-patterns Full Markdown text in raw_content

The structured tokens give the agent quick access to exact values, while the raw Markdown captures the intent behind those values — when to use them, how to combine them, and what to avoid.

How it works

1. Creation

You can create a design system in two ways:

From the app: Navigate to Settings → Agents & Skills → Designs (or simply ask the AI), then fill in the token fields and write your guidelines in the content editor.

From a DESIGN.md file: If you already have a DESIGN.md file, paste it into the chat or point the agent to it. The agent will:

  1. Parse the Markdown sections.
  2. Extract colors, typography, and spacing into structured parameters.
  3. Call design(create) with both the individual token fields and the complete raw content — never one without the other.

2. Activation

Once created, a design system can be activated for a specific workspace. When the agent generates frontend code in that workspace, it automatically retrieves the active design's tokens and applies them. You can also associate a design with a workspace via workspace_path; changing directories auto-activates the linked design if one exists.

3. Code generation

Before generating any frontend code, the agent checks for an active design system. If one exists, it:

  • Pulls the full token set (colors, fonts, spacing, radius).
  • Reads the raw_content for component, layout, and motion rules.
  • Respects every anti-pattern listed (e.g., "no pure black", "no emoji in the UI").
  • Never invents colors or fonts that aren't defined in the design.

The raw_content is always the richest source — if it exists, the agent prefers it over the structured tokens alone.

How to use it

Creating your first design system

Ask Yukkai:
"Create a design system with primary color #1A1C1E, accent #B5A642,
font family Inter, compact spacing, and a 12px border radius.
Activate it for my current project."

The agent will call the design tool with each token as a separate parameter and your full guidelines in raw_content.

Importing an existing DESIGN.md

If a colleague hands you a DESIGN.md file:

  1. Share the file in the chat.
  2. The agent reads its content and parses the structured sections.
  3. Colors, typography, and spacing are extracted into discrete parameters.
  4. The complete Markdown is stored in raw_content so nothing is lost.
  5. Activate it for your workspace to start generating consistent code.

Exporting a design system

You can export any design system as a DESIGN.md file, making it portable across teams and projects. This is useful for sharing brand guidelines with external collaborators or version-controlling your design tokens.

Managing multiple designs

You can create and store several design systems — for example, a light theme and a dark theme, or separate identities for different products. Only one can be active per workspace at a time. Switch between them by activating the one you need.

Examples

Example token set

Token Value Usage
primary_color #1A1C1E Primary text, key UI surfaces
secondary_color #8C2727 Secondary accents, badges
accent_color #B5A642 Call-to-action buttons, highlights
background_color #E9E1D4 App background
surface_color #FFFFFF Cards, elevated surfaces
font_family Inter Body text, labels
heading_family Inter Headings (can differ from body)
spacing_scale compact Density of padding/margins
border_radius 12px Corner rounding for cards, buttons

Example raw content sections

The raw_content field of a DESIGN.md typically includes these sections:

  • Overview — A short philosophy of the design ("clean, editorial, warm but minimal").
  • Components — Per-component rules: "Buttons use the accent color with 12px radius and 14px vertical padding."
  • Layout Principles — Grid system, container widths, responsive breakpoints.
  • Motion & Interaction — "Transitions are 200ms ease-out; hover states lift 2px."
  • Anti-Patterns — Explicit constraints: "No pure black (#000000) — use #1A1C1E instead. No emoji in the UI."

Apple-inspired design (real-world example)

One user's observed preference: 

Background: #FFFFFF
Alternate:  #F5F5F7
Text:       #1D1D1F
CTA Blue:   #0071E3
Accent:     #E8679A  (Yukkai Pink)

These tokens are saved as a design system and applied automatically whenever frontend code is generated for that workspace.

Tips

Do

  • Always include raw_content — it carries the context that structured tokens alone can't express (component rules, anti-patterns, motion guidelines).
  • Define anti-patterns explicitly — phrases like "no pure black" or "no gradients on text" are treated as hard constraints, not suggestions. The agent will respect them.
  • Set workspace_path — linking a design to a project directory means it auto-activates when you switch into that folder, so you never have to remember.
  • Use the structured tokens for exact values — hex codes, font names, pixel sizes. Use raw_content for when and how to apply them.
  • Export and version-control your DESIGN.md — treat it like any other source file. It's your project's visual contract.
  • Keep one design active per workspace — this prevents token conflicts when generating code.

Don't

  • Don't omit raw_content when creating from a file — the agent needs both structured tokens and the full Markdown. One without the other loses information.
  • Don't invent colors or fonts at code-generation time — if a token isn't in the active design, it shouldn't appear in the output. Add it to the design system first.
  • Don't ignore spacing scale — compact, default, and spacious affect how the agent interprets padding and margins across components. Pick one and stick with it.
  • Don't forget to activate — a created but inactive design has no effect on code generation. Always activate after creating (or associate it with a workspace path).

Pro tips

  • Multiple themes: Create separate light and dark design systems. Switch between them by activating the one you need before generating code for a specific theme.
  • Team sharing: Export your DESIGN.md, commit it to your repo, and have teammates import it. Everyone gets identical tokens.
  • Iterate safely: Update tokens in the design system and regenerate code — the agent will pick up the new values automatically on the next generation pass.
  • Reuse across media: A design system isn't limited to frontend code. It can also inform image and video generation, ensuring visual consistency across all media your project produces.

Last updated: July 19, 2026