Creating Custom Design Systems

Custom design systems let you capture brand rules and reuse them across all future projects. You can generate a DESIGN.md from visual inputs or author one manually.

Generating from Visual Inputs

Use the Design System mode to extract design tokens automatically:

From a Screenshot

1. Select Design System mode.
2. Upload a screenshot of the interface or brand material.
3. Type a brief: "Extract the design system from this screenshot."
4. The agent analyses colours, typography, spacing, and component styles.
5. A DESIGN.md is produced with all 9 sections filled.

From a Brand Guide PDF

1. Upload the brand guide PDF.
2. The agent reads the PDF, extracts hex colours via grep, and maps fonts and components.
3. The result is a structured DESIGN.md with accurate brand tokens.

From a URL

1. Provide a URL to a live website.
2. The agent fetches the page and analyses its visual language.
3. Tokens are extracted and written to DESIGN.md.

From a Text Brief

1. Describe your brand in plain language: "A fintech startup with a trust-focused, clean aesthetic. Primary colour is deep navy. Use Inter for body and a geometric sans for headings."
2. The agent interprets the brief and generates a DESIGN.md.

Brand-Spec Extraction Protocol

When extracting from visual inputs, the agent follows a strict protocol:

1. Locate — find brand assets in the input (screenshots, PDFs, URLs).
2. Download — fetch and store assets locally.
3. Grep for hex — extract actual hex colour values from the source.
4. Write brand-spec.md — document the extracted tokens.
5. Vocalise — describe the findings to the user.

The agent never guesses brand colours from memory. This is enforced by the anti-ai-slop craft rule. If a colour cannot be extracted, the agent uses an honest placeholder (— or a grey block) rather than a fabricated value.

Authoring Manually

You can author a DESIGN.md by hand. In the Desktop app, create a design-system folder with the following structure:

design-systems/my-brand/
├── manifest.json
├── DESIGN.md
├── tokens.css
├── components.html
└── preview/
    └── preview.png

manifest.json

{
  "schema": "od-design-system-project/v1",
  "name": "My Brand",
  "slug": "my-brand",
  "category": "Productivity & SaaS",
  "tokens": "tokens.css",
  "designMd": "DESIGN.md",
  "components": "components.html",
  "preview": "preview/preview.png"
}

DESIGN.md Structure

Follow the 9-section schema:

# My Brand

> Category: Productivity & SaaS

## 1. Visual Theme & Atmosphere
Clean, professional, trust-focused...

## 2. Color Palette & Roles
| Role | Token | Hex |
|------|-------|-----|
| Primary | `--color-primary` | `#1a237e` |
| Secondary | `--color-secondary` | `#3949ab` |
| Accent | `--color-accent` | `#ff6f00` |
| Neutral | `--color-neutral` | `#f5f5f5` |

## 3. Typography Rules
...

## 4. Component Stylings
...

## 5. Layout Principles
...

## 6. Depth & Elevation
...

## 7. Do's and Don'ts
...

## 8. Responsive Behavior
...

## 9. Agent Prompt Guide
...

tokens.css

Define CSS custom properties that match your DESIGN.md colour and typography rules:

:root {
  --color-primary: #1a237e;
  --color-secondary: #3949ab;
  --color-accent: #ff6f00;
  --color-neutral: #f5f5f5;
  --font-body: 'Inter', sans-serif;
  --font-heading: 'Space Grotesk', sans-serif;
}

components.html

Optional showcase of sample components (buttons, cards, inputs) using the design tokens. This helps the agent understand how components should look.

Validation

Use the Desktop app's Validate action (Settings → Design Systems) to validate your manifest. This checks that:

• manifest.json has the correct schema version.
• Referenced files (DESIGN.md, tokens.css, components.html) exist.
• The H1 in DESIGN.md matches the name in manifest.json.
• The > Category: metadata line is present.

Using Your Custom System

Once the folder is created, the system appears in the picker on the next load. Select it as you would any built-in system.