Why we open-sourced our design system — and why yours should be an AI skill

The Agentikas design system has one file. Markdown. 800 lines. Color tokens, typography decisions, three rules for primary buttons, what's used when and why.

It lives on GitHub under MIT. And the most important thing: it's written for a model to read and apply. Not to impress a design committee.

This is the decision behind it, and why we think it's the right shape for design systems in 2026.

The problem with a "traditional" design system

A traditional design system lives in Figma. It has a component library, a token manual, a rules section. The design team maintains it. The dev team "implements" it in code (React, Vue, whatever). There's an annual day where the docs get updated.

When a new screen comes up, the flow is:

1. The designer draws it in Figma respecting the components
2. The developer translates it into code respecting the components
3. Someone — a human — checks both respect the system

It works in big teams with discipline. Everywhere else, drift sets in. Five months later you have three versions of the primary button in production. When an agent or copilot starts generating UI, the problem scales — a model doesn't open Figma. It reads code. And if the code isn't the source of truth, what the model writes drifts.

The design system as a skill

At Agentikas we took a different route. The design system is a markdown file at skills/design-system.md. Three sections:

1. Tokens in machine-friendly form

## Tokens

### Colors
- `--color-primary`: #C8352A   /* Agentikas red */
- `--color-text`: #0D0D0D      /* Near-black */
- `--color-bg`: #F7F5F0        /* Warm paper */
- `--color-muted`: #6B6B6B

### Typography
- `--font-heading`: 'Playfair Display', serif
- `--font-body`: 'DM Sans', sans-serif

### Spacing
- 4-8-16-24-32-48-64 scale
- never use values outside the scale

Tokens also export as CSS variables so code consumes them directly. But the source of truth — what the model reads — is markdown.

2. Components with usage

## Primary button

```html
<button class="btn btn-primary">Call to action</button>
```

**Use when:** one primary action per section. Never two primary buttons together.
**Don't use when:** secondary actions (use `btn-secondary`), inline text links (use <a>).

Each component has example HTML, when-to-use and when-not decisions, and eventually legitimate variants. The model doesn't have to guess — it's described.

3. Brand rules with contrasted examples

## Visual voice

✅ **Use:** plenty of whitespace, one header photo per post, clear type scale.
❌ **Don't:** corporate stock (handshakes, smiling office people), saturated gradients, decoration without purpose.

✅ **Buttons:** sentence case ("Create blog"), not ALL CAPS.
❌ **Don't:** "CREATE BLOG" all caps. "Create Blog" title-case either.

Rules with contrasted examples are what models read best. A list of "don't do X" without an example sometimes gets ignored. A list that says "✅ Do X · ❌ Don't Y" gets respected more, because it grasps the pattern.

Why markdown and not JSON

There's a natural argument for design systems in structured JSON. Style Dictionary, Tokens Studio, etc., do this. Works well for tokens — colors, spacing, typography. Works poorly for rules, context, decisions.

JSON is for data. Markdown is for knowledge. A rule like "primary buttons never come in pairs" isn't data — it's a decision with reasons. In markdown you can carry the reason. In JSON, it ends up as a boolean without context and the model doesn't know why.

What we ended up with: tokens as exportable JSON, decisions as markdown. The model reads both. The designer edits the markdown. A compiler generates the JSON from the markdown as an artifact.

The effect on generation

When an author asks the editor "generate a landing for this section," the model receives in its system prompt:

1. The blog's BRAND.md (tone, vocabulary)
2. The design-system.md (tokens, components, rules)
3. The matching skill (blog-writer.md, landing-builder.md)

Generation respects all three. Not by magic — because they're described in a format the model processes natively. The components that appear in the output are those of the system. The colors are tokens. Rules are respected because they're written as rules.

The result: visual consistency between what a human builds and what a model generates converges. "Traditional design system" drift disappears, because the model doesn't read Figma — it reads markdown.

Open source: why free, why useful

Agentikas's design system lives in github.com/agentikas/agentikas-skills under MIT. Fork, copy tokens, adapt rules to your brand. Two reasons:

1. Knowledge accumulates faster when it's public. A team in Berlin improves German plural pluralization in the brand reviewer, they add it. Every German-language blog benefits instantly.
2. Standardizing the format helps the whole ecosystem. If the world's design systems are markdown skills, models know where to look. Today you know it; tomorrow Claude knows it by default.

The near future is models generating UI in your brand without you typing a thing. For that to work, your brand has to live in a format the model reads. Markdown is that format. Design it that way starting today.

---

Fork the Agentikas design system at github.com/agentikas/agentikas-skills. MIT license, no attribution required. If you add rules for your vertical, send a PR — the whole ecosystem will thank you.