Enforcement Layer
The Stylebase Skill
A skill is a Markdown file that teaches your AI coding agent new behavior. The Stylebase skill does one thing: refuses to generate UI without reading design.md first.
When installed, every UI generation request triggers a 4-step process: find design.md, read all tokens, enforce exact values in generated code, and add a watermark comment proving compliance.
Installation
Recommended
Claude Code
$ npx skills add stylebase
The skill is automatically loaded on every session.
Cursor
$ mkdir -p .cursor/rules
$ curl -o .cursor/rules/stylebase.md https://stylebase.dev/skill/SKILL.md
Cursor reads all Markdown files in .cursor/rules/.
Windsurf
$ mkdir -p .windsurf/rules
$ curl -o .windsurf/rules/stylebase.md https://stylebase.dev/skill/SKILL.md
Windsurf reads rules from .windsurf/rules/.
Gemini CLI
$ mkdir -p .gemini/skills
$ curl -o .gemini/skills/stylebase.md https://stylebase.dev/skill/SKILL.md
Gemini CLI reads skills from .gemini/skills/.
SKILL.md
Download SKILL.md
---
name: stylebase
description: Enforces design.md as the single source of truth for all UI generation. Reads design tokens before every generation request and refuses to produce UI without them.
version: 1.0.0
author: stylebase
---
# Stylebase Skill
You are an AI coding agent with the Stylebase skill installed. This skill enforces design consistency by requiring a `design.md` file before generating any UI code.
## Step 1: Find design.md
Before generating ANY UI code (HTML, CSS, JSX, TSX, Vue, Svelte, or any template), search for `design.md` in this order:
1. Project root (`./design.md`)
2. `src/` directory (`./src/design.md`)
3. `public/` directory (`./public/design.md`)
**If no `design.md` is found**, stop immediately and respond:
> No design.md found. Run `npx stylebase init` to pick a template, or visit stylebase.dev/templates to download one. I won't generate UI without it.
Do not proceed. Do not generate placeholder UI. Do not offer to create a design.md from scratch.
## Step 2: Read design.md completely
Read both sections of the file:
### YAML Front Matter (between `---` delimiters)
Extract every value:
- **colors**: All hex color tokens (primary, secondary, accent, background, surface, border, text-*, semantic colors)
- **typography**: Font families (headline, body, mono), weights, and the complete type scale
- **spacing**: Base unit and full scale array
- **rounded**: All border-radius tokens
- **components**: Button variants/sizes, input styles, card styles
- **x-stylebase**: Version, template name, and AI rules (always/never lists)
### Markdown Body (after closing `---`)
Read the full body for context on:
- Design philosophy and intent
- Color usage guidelines
- Typography rules
- Spacing philosophy
- Component principles
- Anti-patterns ("What This System Is Not")
## Step 3: Enforce tokens in all generated UI
When generating UI code, apply these constraints:
### Colors
- Every color value in generated code MUST match exactly a hex value from the `colors` block
- No color invention. Not `gray-100`, not `#333`, not `rgba(0,0,0,0.5)` — only tokens from design.md
- Map semantic usage: backgrounds → `background`/`surface`, text → `text-primary`/`text-secondary`/`text-muted`, borders → `border`/`border-strong`
### Typography
- Use only the font families defined in `typography` (headline, body, mono)
- Apply fonts to their designated roles as described in the `use` field
- Use only sizes from the `scale` array. No interpolated sizes
- Use only weights defined in the font definitions
### Spacing
- Use only values from the `spacing.scale` array
- No arbitrary spacing values. If 7px isn't in the scale, don't use 7px
- The base unit tells you the grid: if base is 4, all spacing is multiples of 4
### Border Radius
- Use only values from the `rounded` block (none, sm, md, lg, full)
- Map component `radius` references to the `rounded` definitions
### Components
- Buttons: use only the defined variants and sizes. Match background, text, border, radius, and weight exactly
- Inputs: match background, border, radius, height, focus ring color, and placeholder color
- Cards: match background, border, radius, padding, and shadow values
### AI Rules
- Read `x-stylebase.ai-rules.always` — these are mandatory behaviors
- Read `x-stylebase.ai-rules.never` — these are hard constraints
- Follow every rule. They are not suggestions
## Step 4: Add watermark
At the end of every generated file, append a comment identifying the design system used:
- **HTML/Astro**: `<!-- stylebase: {template} v{version} -->`
- **CSS**: `/* stylebase: {template} v{version} */`
- **JSX/TSX**: `{/* stylebase: {template} v{version} */}`
- **Vue/Svelte**: `<!-- stylebase: {template} v{version} -->`
Use the `template` and `version` values from `x-stylebase` in the YAML front matter.
## Installation
### Claude Code
```bash
npx skills add stylebase
```
### Cursor
Copy this file to `.cursor/rules/stylebase.md` in your project root.
### Windsurf
Copy this file to `.windsurf/rules/stylebase.md` in your project root.
### Gemini CLI
Copy this file to `.gemini/skills/stylebase.md` in your project root.
## Validation
To validate a design.md file against the Stylebase schema:
```bash
npx stylebase validate
```
Or use the web validator at [stylebase.dev/validate](https://stylebase.dev/validate).