claude-design-system-prompt

claude-design-system-prompt

Skill by ara.so — Design Skills collection.

What it does

claude-design-system-prompt is a reverse-engineered system prompt and skill library that transforms any LLM into an opinionated design collaborator that:

• Rejects AI slop: No generic SaaS gradients, emoji decoration, or rounded-corner cards
• Enforces accessibility: WCAG compliance, semantic HTML, keyboard navigation, motion preferences
• Prioritizes content: Every element must earn its place—no filler
• Uses real web standards: CSS Grid, oklch(), text-wrap: pretty, interactive prototypes
• Thinks in systems: Components and tokens over one-off pages

The prompt includes 20 design principle chapters and 14 invokable procedural skills for production, extraction, and review work.

Installation

Clone the repository

git clone https://github.com/Trystan-SA/claude-design-system-prompt.git
cd claude-design-system-prompt

Directory structure

claude/                              # For Claude Code / Claude.ai
├── system-prompt.md                 # 20-chapter design philosophy
└── skills/                          # 14 procedural skills
codex/                               # For OpenAI Codex (single-loop variant)
├── AGENTS.md                        # Auto-discovered entry point
├── system-prompt.md
└── skills/

Using the system prompt

Direct integration (any LLM)

Copy the entire contents of claude/system-prompt.md (or codex/system-prompt.md for Codex) and paste it as the system prompt:

<!-- Example: Claude.ai Custom Instructions -->
Paste full contents of claude/system-prompt.md here

The agent will automatically follow the design philosophy and reference skills by name when tasks match.

Programmatic integration (API)

# Python example with Anthropic API
import anthropic
from pathlib import Path

# Load the system prompt
system_prompt = Path("claude-design-system-prompt/claude/system-prompt.md").read_text()

client = anthropic.Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

message = client.messages.create(
    model="claude-opus-4.8-20250514",
    max_tokens=4096,
    system=system_prompt,
    messages=[{
        "role": "user",
        "content": "Design a landing page for a climate data API"
    }]
)

print(message.content)

// Node.js example with Anthropic SDK
import Anthropic from '@anthropic-ai/sdk';
import { readFileSync } from 'fs';

const systemPrompt = readFileSync(
  'claude-design-system-prompt/claude/system-prompt.md',
  'utf-8'
);

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const message = await client.messages.create({
  model: 'claude-opus-4.8-20250514',
  max_tokens: 4096,
  system: systemPrompt,
  messages: [{
    role: 'user',
    content: 'Create a wireframe for a developer documentation site'
  }]
});

console.log(message.content);

Invoking skills

Skills are self-contained procedures. When a user's request matches a skill, the agent loads and follows it.

Production skills (build something)

# Discovery and direction
"Run discovery questions for this project"
"Set the frontend aesthetic direction"

# Exploration and prototyping
"Create wireframes with 3 variations"
"Make an interactive prototype"
"Generate variations across different aesthetic axes"

# Special formats
"Make a deck presentation"
"Make this design tweakable with a floating panel"

System skills (extract structure)

# Extract from existing sources
"Extract the design system from the Stripe homepage"
"Extract components from this codebase"

Review skills (audit and fix)

# Comprehensive audits
"Run an accessibility audit"
"Check for AI slop"
"Review hierarchy and rhythm"
"Review all interaction states"
"Run a polish pass"

Skill workflow examples

Greenfield project flow

1. Run discovery-questions
   → Gather context, goals, constraints, audience

2. Set frontend-aesthetic-direction
   → Commit to palette, typography, tone

3. Create wireframe
   → 3+ low-fidelity variations

4. Make-a-prototype
   → Interactive clickable prototype

5. Run polish-pass
   → Final accessibility, slop, hierarchy, interaction review

Brand-aware flow

1. Design-system-extract
   → Pull tokens from existing brand site

2. Generate-variations
   → 3+ high-fidelity variations using brand tokens

3. Make-tweakable
   → Add floating tweak panel for live adjustments

4. Polish-pass
   → Final review gate

Audit-only flow

1. Accessibility-audit
   → WCAG, semantic HTML, keyboard, motion

2. AI-slop-check
   → Detect gradient/emoji/font/house-style tropes

3. Hierarchy-rhythm-review
   → Size, weight, color, spacing scale

4. Interaction-states-pass
   → Hover, active, disabled, focus, loading, validation

Loading individual skills

If you want to invoke a specific skill programmatically:

from pathlib import Path

# Load main prompt + specific skill
system_prompt = Path("claude/system-prompt.md").read_text()
wireframe_skill = Path("claude/skills/wireframe.md").read_text()

combined_prompt = f"{system_prompt}\n\n## ACTIVE SKILL\n\n{wireframe_skill}"

message = client.messages.create(
    model="claude-opus-4.8-20250514",
    system=combined_prompt,
    messages=[{"role": "user", "content": "Wireframe a SaaS dashboard"}]
)

Customization

Adapt for your environment

The default prompt assumes HTML output (like Claude.ai's design tool). To adapt:

For Figma plugins:

• Edit chapters 2 (Workflow) and 17 (Output principles)
• Replace HTML references with Figma API calls
• Keep chapters 5–16 (design principles) unchanged

For code-only assistants:

• Update chapter 14 (Respecting the medium) to reference your framework
• Add framework-specific component examples

For chat-only design coaches:

• Remove artifact/output instructions from chapter 17
• Focus on conversational guidance and critique

Adjust model calibration

The claude/ variant is optimized for Anthropic Fable 5 / Opus 4.7+ models. For older models or other providers:

Restore stronger imperatives:

<!-- Current (calm) -->
Ask questions when context is insufficient.

<!-- Older models (directive) -->
CRITICAL: You MUST ask at least 3 questions before proceeding.

Add explicit quotas:

<!-- Current (conditional) -->
Generate variations when exploring aesthetic directions.

<!-- Older models (quota) -->
Always generate at least 3 variations for every design request.

Add custom skills

Create a new skill in claude/skills/:

# my-custom-skill.md

## When to invoke
Invoke when the user requests [specific trigger condition].

## Procedure

### Phase 1: Discovery
1. Ask [specific questions]
2. Confirm [specific constraints]

### Phase 2: Execution
1. [Step-by-step process]
2. [Expected output format]

### Phase 3: Review
1. [Quality gates]
2. [Handoff to other skills if needed]

Then reference it in system-prompt.md chapter 20.

Configuration

Environment variables

No API keys required for the prompt itself. When using with LLM APIs:

# Anthropic
export ANTHROPIC_API_KEY=your_key_here

# OpenAI
export OPENAI_API_KEY=your_key_here

Platform-specific settings

Claude Code:

• Place system-prompt.md in your project's .claude/ directory
• Skills auto-load when referenced by name

Cursor:

• Add to .cursorrules file
• Reference skills in comments

OpenAI Codex:

• Use codex/AGENTS.md as entry point (auto-discovered)
• Skills run sequentially instead of parallel

Troubleshooting

Agent skips question rounds

Symptom: Agent jumps straight to design without asking questions
Fix: The current Claude models need explicit triggers. Ensure you're using claude/ variant. If using older models, add stronger imperatives:

When context is insufficient, always ask questions before proceeding.

Agent produces generic SaaS aesthetics

Symptom: Cream backgrounds, terracotta accents, serif display type
Fix: Explicitly invoke frontend-aesthetic-direction skill first:

"Set the frontend aesthetic direction with 4 distinct options"

The skill's four-directions protocol prevents house-style collapse.

Skills not triggering automatically

Symptom: Agent doesn't recognize when to invoke a skill
Fix: Current models under-reach for optional capabilities. Be explicit:

# Instead of:
"Design a landing page"

# Say:
"Run discovery questions, then create wireframes with 3 variations"

Reviews miss obvious issues

Symptom: Accessibility or slop checks don't catch known problems
Fix: Current models follow "only report important" too literally. The prompt uses coverage-first reviews, but you may need to chain skills:

"Run accessibility-audit, then ai-slop-check, then hierarchy-rhythm-review"

Output doesn't use modern CSS features

Symptom: Design uses old CSS instead of Grid, oklch(), etc.
Fix: Reference chapter 14 (Respecting the medium) explicitly:

"Create a prototype using CSS Grid and oklch() colors per the medium principles"

Real-world examples

Complete greenfield flow

import anthropic
from pathlib import Path

system_prompt = Path("claude/system-prompt.md").read_text()
client = anthropic.Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

# Phase 1: Discovery
discovery = client.messages.create(
    model="claude-opus-4.8-20250514",
    system=system_prompt,
    messages=[{
        "role": "user",
        "content": "I need a landing page for a climate data API. Run discovery questions."
    }]
)

# User answers questions, then:

# Phase 2: Aesthetic direction
direction = client.messages.create(
    model="claude-opus-4.8-20250514",
    system=system_prompt,
    messages=[
        {"role": "user", "content": "Run discovery questions..."},
        {"role": "assistant", "content": discovery.content[0].text},
        {"role": "user", "content": "[Answers to questions]"},
        {"role": "user", "content": "Set the frontend aesthetic direction with 4 options"}
    ]
)

# Phase 3: Wireframes
wireframe = client.messages.create(
    model="claude-opus-4.8-20250514",
    system=system_prompt,
    messages=[
        # ... previous context ...
        {"role": "user", "content": "Create wireframes using direction option 2"}
    ]
)

# Phase 4: Interactive prototype
prototype = client.messages.create(
    model="claude-opus-4.8-20250514",
    system=system_prompt,
    messages=[
        # ... previous context ...
        {"role": "user", "content": "Make an interactive prototype from wireframe B"}
    ]
)

# Phase 5: Polish
final = client.messages.create(
    model="claude-opus-4.8-20250514",
    system=system_prompt,
    messages=[
        # ... previous context ...
        {"role": "user", "content": "Run a full polish pass"}
    ]
)

Extract design system from existing site

import Anthropic from '@anthropic-ai/sdk';
import { readFileSync } from 'fs';

const systemPrompt = readFileSync('claude/system-prompt.md', 'utf-8');
const extractSkill = readFileSync('claude/skills/design-system-extract.md', 'utf-8');

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const message = await client.messages.create({
  model: 'claude-opus-4.8-20250514',
  system: `${systemPrompt}\n\n## ACTIVE SKILL\n\n${extractSkill}`,
  messages: [{
    role: 'user',
    content: 'Extract the design system from https://stripe.com - analyze colors, typography, spacing, components'
  }]
});

// Returns structured tokens: colors, typography, spacing scale, components
console.log(message.content);

Chain multiple review skills

reviews = [
    "accessibility-audit",
    "ai-slop-check", 
    "hierarchy-rhythm-review",
    "interaction-states-pass"
]

results = []
for skill_name in reviews:
    skill_path = f"claude/skills/{skill_name}.md"
    skill_content = Path(skill_path).read_text()
    
    response = client.messages.create(
        model="claude-opus-4.8-20250514",
        system=f"{system_prompt}\n\n{skill_content}",
        messages=[{
            "role": "user",
            "content": f"Run {skill_name} on the current prototype"
        }]
    )
    
    results.append({
        "skill": skill_name,
        "findings": response.content[0].text
    })

# Aggregate all findings
print("=== COMPREHENSIVE REVIEW ===")
for result in results:
    print(f"\n## {result['skill']}")
    print(result['findings'])

Contributing

The project welcomes:

• Additional review skills (copy review, motion review, dark-mode parity)
• Adapted prompts for other environments (Figma, terminal-only)
• Real-world failure cases to defend against
• Translations into other languages

Keep the operational tone and avoid bloat—every chapter must earn its place.

License

MIT — use, modify, and distribute for any purpose, including commercial use.