Creating Design Systems

Create, import, and activate design systems for your projects.

Overview

A Design System in Yukkai is a reusable, structured visual identity for a project — colors, typography, spacing, border radii, shadows, component guidelines, layout principles, motion rules, and anti-patterns. Think of it as a single source of truth that keeps every screen, page, and component visually consistent.

Instead of hardcoding #0071E3 in a hundred files, you define it once as --blue inside a design system. When you need to rebrand or tweak a palette, you update the design system — not every individual file.

Design systems are managed through Yukkai's built-in design tool. Each system is stored independently and can be activated (associated) with a specific workspace path, so that the AI agent working on that project automatically applies the correct tokens and guidelines.

How it works

A design system contains two layers of information:

1. Design tokens (structured fields)

These are the machine-readable properties stored in the design system record:

Field Description Example
primary_color Main brand color #0071E3
secondary_color Supporting color #E8789A
background_color Page background #FFFFFF
surface_color Cards, panels, elevated surfaces #F5F5F7
accent_color Highlight / call-to-action accent #AF52DE
success_color Positive states (success, OK) #34C759
warning_color Caution states #FF9500
error_color Error / danger states #FF3B30
font_family Body text font stack Inter, -apple-system, sans-serif
heading_family Heading font (if different) SF Pro Display, Inter, sans-serif
border_radius Global corner rounding 12px
spacing_scale Spacing preset compact, default, or spacious

2. Raw content (DESIGN.md)

A free-form Markdown document with structured sections:

  • Overview — Mood, references, visual metaphor
  • Color Palette — Token tables for backgrounds, text, accents, borders
  • Typography — Font stacks, type scale, typographic rules
  • Spacing — Scale and usage rules
  • Border Radius — Corner radius tokens
  • Shadows — Elevation tokens
  • Components — Implementation specs for navigation, cards, buttons, etc.
  • Layout Principles — Ordering, max-widths, responsive behavior
  • Motion & Interaction — Animations, easing, stagger, accessibility
  • Iconography — Icon sources and mappings
  • Anti-Patterns — Explicit list of things to avoid

When a design system is activated on a workspace, the AI agent uses both the structured tokens and the raw DESIGN.md content to generate code that matches your visual identity.

How to use it

Create a design system

Use the design tool with the create action. Only the name field is required; everything else is optional and can be filled in later. 

design → create
  name: "My App"
  description: "Clean, modern UI for a productivity app"
  primary_color: "#1A1C1E"
  accent_color: "#5E5CE6"
  font_family: "Inter, sans-serif"
  border_radius: "12px"
  spacing_scale: "default"
  workspace_path: "/Users/me/projects/my-app"
  raw_content: |
    # DESIGN SYSTEM — My App

    ## Overview
    Minimal, focused, fast.

    ## Color Palette
    ...

    ## Anti-Patterns
    ❌ No drop shadows on text.

List your design systems

design → list

Returns all stored design systems with their ID, colors, typography, and associated workspace.

Get full details

design → get
  id: "yukkaicom"

Returns the complete design system including the full DESIGN.md content.

Update a design system

design → update
  id: "yukkaicom"
  primary_color: "#0066CC"

You can update individual fields or replace the entire raw_content.

Activate / Deactivate

Activating a design system associates it with your current workspace. The AI agent will then automatically reference the design tokens and guidelines when generating code for that project. 

design → activate
  id: "yukkaicom"

design → deactivate
  id: "yukkaicom"

Import from an existing DESIGN.md

If you already have a Markdown file following the DESIGN.md format, you can import it directly: 

design → import_md
  name: "Imported System"
  content: |
    # DESIGN SYSTEM — My Project
    ...

Export

Export a design system to a standalone DESIGN.md file: 

design → export
  id: "yukkaicom"

Delete

design → delete
  id: "yukkaicom"

Examples

Example 1: Minimal dark-mode system

Create a design system for a dark-themed dashboard:

  • primary_color: #0A0A0A
  • background_color: #0A0A0A
  • surface_color: #1C1C1E
  • accent_color: #0A84FF
  • success_color: #30D158
  • error_color: #FF453A
  • font_family: Inter, -apple-system, sans-serif
  • border_radius: 8px
  • spacing_scale: compact

In the raw_content section, you'd document specific rules like: 

## Anti-Patterns
❌ No pure white backgrounds (#FFFFFF) — always use --surface.
❌ No borders brighter than rgba(255,255,255,0.12).
❌ No text below 14px on dark backgrounds.

Example 2: Spacious marketing site

A marketing page with lots of whitespace:

  • spacing_scale: spacious
  • border_radius: 24px
  • primary_color: #0071E3
  • secondary_color: #E8789A
  • accent_color: #AF52DE
  • font_family: SF Pro Text, Inter, -apple-system, sans-serif
  • heading_family: SF Pro Display, Inter, -apple-system, sans-serif

The DESIGN.md would include section spacing rules like: 

## Spacing Rules
- Vertical section padding: --space-32 (128px) minimum.
- Between eyebrow and title: --space-4.
- Between title and body: --space-6.
- Max content width: 1200px centered.

Tips

  1. Start with tokens, then add raw content. Create the design system with just a name and colors first. You can always update it later with a full DESIGN.md once you've refined the visual direction.
  2. Activate before generating code. When the design system is activated on your workspace, the AI agent automatically applies the correct tokens — no need to re-paste the color values in every prompt.
  3. Use anti-patterns aggressively. The "what NOT to do" section is often more useful than the "what to do" section. Be explicit: list every visual choice you want to prevent (e.g., "no drop shadows on text", "no pure black backgrounds").
  4. Keep type scales responsive. Use clamp() for font sizes in your DESIGN.md so they adapt across breakpoints. For example: clamp(2.25rem, 4.5vw, 3.5rem).
  5. Document component-level details. The more specific your component specs (exact heights, border colors, hover states), the more consistently the agent will reproduce them across files.
  6. One design system per project. While you can have multiple systems stored, activate only one per workspace to avoid token conflicts.
  7. Export to share. Use export to generate a standalone DESIGN.md file. You can commit it to your repo so non-AI tools and developers also have access to the design spec.
  8. Re-import to iterate. If you hand-edit a DESIGN.md file outside of Yukkai, use import_md to bring those changes back into the managed design system.

Last updated: July 19, 2026