Skip to content

Documentation

Creating .md files

A complete guide to authoring DESIGN.md and SKILL.md bundles that work seamlessly with AI coding tools.

Example files

Download a working example

A complete, production-ready design system bundle you can study, adapt, and use as a starting point. Both files are fully annotated with rules, token values, and component patterns.

↓Download DESIGN.md↓Download SKILL.md

What is a design system bundle?

A bundle is a pair of Markdown files, DESIGN.md and SKILL.md, that AI coding tools read to understand your design system. When placed in a project, they use them to generate UI that matches your style automatically, without you describing it each time.

Think of them as a persistent brief. Instead of writing “use a dark background, sharp corners, monospace prices, and uppercase labels” on every prompt, you write it once in DESIGN.md, and the AI carries those rules through every interaction in that project.

The two files have different responsibilities. DESIGN.md defines the visual language: colours, type, spacing, components. SKILL.md defines the behavioural layer: how to make decisions, handle states, structure code. Together they give any AI tool a complete picture of your system.

DESIGN.md vs SKILL.md: what's the difference?

The two files answer different questions. DESIGN.md answers “what does it look like?” SKILL.md answers “how should the AI think?” You need both, and mixing their content is the most common mistake beginners make.

DESIGN.md

What does it look like?

  • Colour tokens with exact hex values
  • Type scale: sizes, weights, tracking
  • Spacing scale and layout rules
  • Border radius conventions
  • Component Tailwind class strings
  • Do / Don't visual constraints

SKILL.md

How should the AI think?

  • When to use a modal vs. drawer vs. page
  • Responsive layout decisions
  • How each UI state should behave
  • Accessibility defaults to always apply
  • Code conventions and file structure
  • Microcopy and UX writing rules

A useful test: if a rule involves a specific value (a hex code, a pixel size, a Tailwind class), it belongs in DESIGN.md. If a rule involves a decision or a condition (when to do X, how to handle Y), it belongs in SKILL.md.

Quick examples

DESIGN.mdPrimary button: bg-[#F0F0F0] text-[#080808] rounded-sm px-5 py-2.5
SKILL.mdUse a primary button only once per page. Secondary actions use the ghost variant.
DESIGN.mdError text: text-red-500 text-xs font-mono
SKILL.mdError messages: state what happened, then what to do. Never say “an error occurred.”

DESIGN.md without SKILL.md gives the AI paint but no technique. SKILL.md without DESIGN.md gives the AI good process but generic output. A strong bundle needs both.

DESIGN.md: visual language

DESIGN.md defines the visual rules of your system. It should be opinionated and specific. The AI reads it as a set of instructions, not a reference document. Write it accordingly.

1. Opening summary

Start with one or two sentences describing the visual character of the system. This primes the AI before it reads the details.

# DESIGN.md: Monolith Design System
Version: 1.0.0

A dark, minimal system for developer tools.
Sharp edges, monospace data, high contrast.

2. Colour palette

Provide exact hex values with semantic names. Include a usage note for each. Never leave the AI to infer what a colour is for.

## Colour Palette

| Token | Hex | Usage |
|---|---|---|
| `background` | `#080808` | Page background |
| `surface` | `#0D0D0D` | Cards, modals |
| `border` | `#1C1C1C` | Default borders |
| `text-primary` | `#F0F0F0` | Headlines |
| `text-secondary` | `#808080` | Body text |
| `accent` | `#F0F0F0` | CTA buttons (inverted) |

Never use opacity to create colour variants.
Always use a named token.

3. Typography

Specify font family, the full size scale, weight usage, line-height, and letter-spacing. Include which role uses which size. If you use a specific font for data (e.g. monospace for prices), state it explicitly.

## Typography

Font: Geist Sans for UI, Geist Mono for data.

| Role   | Size | Weight | Tracking |
|--------|------|--------|----------|
| H1     | 2rem | 600    | -0.015em |
| Body   | 14px | 400    | 0        |
| Label  | 10px | 500    | 0.2em    |

- Labels: text-[10px] tracking-[0.25em] uppercase
- Prices: always font-mono
- Never use italic

4. Spacing

Define your spacing scale and when to use each step. State any global layout conventions like page padding or max-width rules.

## Spacing

Base unit: 4px.

| Step | Value | Use |
|------|-------|-----|
| 1    | 4px   | Icon gaps |
| 4    | 16px  | Component padding |
| 6    | 24px  | Card padding |
| 16   | 64px  | Page sections |

Page padding: px-6 sm:px-10 lg:px-16
No max-width. Full-width layouts only.

5. Border radius

State your rounding convention clearly and list the exceptions. The AI will apply this globally.

## Border Radius

Use rounded-sm (2px) everywhere.
Exception: avatar buttons use rounded-full.

Never use rounded-lg or larger.

6. Component patterns

For each major component, provide the exact Tailwind class string. This is the most valuable part of DESIGN.md. The AI will reproduce these exactly instead of guessing.

## Components

### Button: Primary
<button className="px-5 py-2.5 bg-[#F0F0F0] text-[#080808]
  text-sm font-medium rounded-sm tracking-wide
  hover:bg-white transition-colors">
  Label
</button>

### Input
<input className="w-full px-3 py-2 bg-[#111111]
  border border-[#1C1C1C] rounded-sm text-sm
  text-[#F0F0F0] placeholder:text-[#707070]
  focus:outline-none focus:border-[#444444]
  transition-colors" />

7. Do / Don't

Short, imperative rules. These override everything else. The AI treats them as hard constraints.

## Do / Don't

Do:
- Use border for separation, never background changes
- Use font-mono for prices, IDs, and counts
- Use transition-colors on every interactive element

Don't:
- Don't use drop shadows on non-floating elements
- Don't use gradients
- Don't use text-white. Use text-[#F0F0F0]

SKILL.md: behaviour rules

SKILL.md tells the AI how to work, not just what things look like, but how to make decisions. Think of it as a senior designer's mental model written down. While DESIGN.md is about pixels, SKILL.md is about judgment.

1. Component selection rules

Tell the AI when to use a modal vs. a drawer, an icon vs. a label, a skeleton vs. a spinner. These are decisions that come up constantly and have no visual answer in DESIGN.md.

## Component Selection

Modal vs. Drawer vs. Page:
- Modal: confirmations, short forms (≤4 fields)
- Drawer: filters, settings, long forms on mobile
- New page: multi-step flows, anything needing a URL

Never put a table inside a modal.

2. Responsive strategy

Define how layouts adapt at each breakpoint. Specify what collapses on mobile. AI tools handle responsive layouts better with explicit rules than with vague direction.

## Responsive Strategy

- Mobile: single column, everything stacked
- sm (640px): 2-column grids permitted
- lg (1024px): persistent sidebar, multi-column
- Tables on mobile: horizontal scroll only,
  never truncate data

3. State handling

Define how each UI state looks: loading, empty, error, success, disabled. Include code snippets for each.

## State Handling

Error:
<p role="alert" className="text-xs font-mono text-red-500 mt-1">
  Error message here.
</p>

Empty state: always include icon + heading
+ explanation + CTA.

Disabled: opacity-40 + cursor-not-allowed.
Never hide disabled elements.

4. Accessibility defaults

Define focus behaviour, required ARIA patterns, and contrast minimums. The AI will apply these consistently without needing a reminder on every prompt.

## Accessibility

Focus ring: focus-visible:ring-1 ring-[#F0F0F0]/30
Icon-only buttons: always include aria-label
Modals: role="dialog" + aria-modal="true"
Alerts: role="alert" for errors (announces immediately)
Semantic HTML: use nav, main, footer, article

5. Code conventions

Define Tailwind class ordering, component naming conventions, file structure, and when to use server vs. client components.

## Code Conventions

Class order: layout → flex/grid → spacing
→ typography → background → border
→ effects → transitions → pseudo-classes

'use client' only when component needs:
useState, useEffect, event handlers,
or browser APIs. Everything else: server.

6. UX copy rules

Define how microcopy should be written. Button labels, error messages, empty states, and confirmation dialogs each have their own conventions.

## UX Copy

Buttons: verb + noun. "Upload files" not "Upload".
Errors: what happened + what to do.
  "Payment failed. Check your card details."
Empty: explain why, not just that it's empty.
Confirmations: state consequence, not action.
  "This permanently deletes the listing."
  Not "Are you sure?"

File structure and naming

Both files should be named exactly DESIGN.md and SKILL.md (uppercase). Place them in the root of the project directory. Most AI coding tools scan for Markdown files in the working directory automatically.

my-project/
├── DESIGN.md       ← visual rules
├── SKILL.md        ← behavioural rules
├── CLAUDE.md       ← optional: project-specific overrides
├── src/
└── package.json

If you have a CLAUDE.md file already, you can reference your bundles from it with @DESIGN.md to include them inline. This is useful if you want to add project-specific overrides on top of a purchased bundle.

How to use with AI coding tools

Drop both files into the root of your project. Claude Code and most other AI coding tools read all Markdown files in the working directory at the start of each session. No extra configuration needed.

You can also reference them explicitly in your first prompt:

Read DESIGN.md and SKILL.md, then build a login form.

Or load them via CLAUDE.md so they apply automatically to every session:

# CLAUDE.md

@DESIGN.md
@SKILL.md

This project uses React 19 and Next.js 16.

Once loaded, the AI will apply your design system rules to every component it generates in that session, without needing to be told each time.

Writing style tips

  • Write in imperative voice

    Say "Use #F0F0F0 for primary text" not "Primary text is usually #F0F0F0." AI tools perform better with direct instructions than with descriptive prose.

  • Be specific with values

    Exact hex codes, rem values, and pixel sizes. Vague descriptions like "dark grey" or "subtle shadow" leave too much room for interpretation.

  • Include code snippets

    A Tailwind class string is worth a paragraph of explanation. For each component pattern, include the exact JSX you want the AI to reproduce.

  • Keep it dense, not long

    AI tools perform better with scannable files than long prose. Use tables, code blocks, and bullet lists. Aim for under 500 lines per file.

  • State your rules, then your exceptions

    Define the global rule first ("use rounded-sm everywhere") then list the exceptions ("except avatars: rounded-full"). The AI applies the rule unless it hits an exception.

  • Use Do / Don't sections

    Hard constraints are the most valuable part of a design system file. "Never use drop shadows on non-floating elements" prevents hundreds of bad outputs.

  • Version your files

    Add a version line at the top (e.g. "Version: 1.2.0"). Buyers can track updates, and you can increment it when you make breaking changes.

  • Test it before selling

    Open a fresh AI coding session, load your files, and ask it to build 3 or 4 different components. Check for consistency. Fix anything that looks off.

Common mistakes

  • Too much prose, not enough values

    A file that reads like a brand manifesto gives the AI nothing to work with. AI tools need numbers, class names, and rules. Not philosophy.

  • Describing the same thing twice

    If your colour table lists text-primary as #F0F0F0, you don't also need "Headlines should be light coloured" in a paragraph below. Duplication creates conflict when values drift.

  • Missing states

    Most design systems document the default state and forget loading, empty, error, and disabled. The AI will guess for any state you don't define.

  • No Do/Don't section

    This is where your strongest opinions live. Without it, the AI will make reasonable but wrong choices, like adding a drop shadow to a card, or using rounded-lg instead of rounded-sm.

  • Vague component descriptions

    "Buttons should look clean and professional" tells the AI nothing. "Buttons use bg-[#F0F0F0] text-[#080808] rounded-sm tracking-wide" tells the AI everything.

  • Mixing DESIGN.md and SKILL.md content

    Decision rules in DESIGN.md and visual values in SKILL.md confuse the AI's reading order. Keep them strictly separated: values go in DESIGN.md, judgment goes in SKILL.md.

What makes a bundle worth buying?

Buyers are paying for precision and depth. A bundle that covers 10 components with exact class strings is worth more than one that covers 40 components vaguely. Specificity is the product.

The best-selling bundles on Didot tend to share a few traits:

  • They cover a coherent visual identity, not a random collection of styles.
  • Every component pattern includes the complete Tailwind class string, not a description of it.
  • The SKILL.md covers at least 4 of the 6 key decision areas: component selection, responsive strategy, state handling, accessibility, code conventions, and UX copy.
  • They've been tested in a real project before listing.
  • The preview screenshots show real AI-generated output using the bundle.

Ready to sell?

Once you've created and tested your bundle, connect your Stripe account and list it on Didot. Set a price, upload preview images, and publish. Didot handles payments, file delivery, and download links. You just maintain the files.