Awesome Design

awesome-design

Turn a blank project into one with a consistent visual language — fast. Source collection: https://github.com/voltagent/awesome-design-md

What DESIGN.md is

A single plain-text file (DESIGN.md) that captures the full visual identity of a product: colors · typography · spacing · component patterns · layout rules · brand voice.

AI agents read it before generating UI so every component matches the system. Think of it as a CLAUDE.md for design.

When to invoke this skill

• Starting a new project and you want a reference aesthetic
• Working on UI without a design system (→ create one from scratch)
• User says "make it look like Vercel / Linear / Stripe / etc." (→ pick from collection)
• After design-consultation produces a system (→ convert it into a DESIGN.md)

Step 1 — Decide: Pick or Create?

Ask the user one question:

"Do you want to base the design on an existing brand style, or start from your own system?"

• Existing brand → go to Step 2A (pick from collection)
• Custom / from scratch → go to Step 2B (generate)

Step 2A — Pick from the awesome-design-md collection

Point the user to the collection and help them pick the closest match.

10 categories — map the user's project to one:

Instruction to user:

1. Go to https://github.com/voltagent/awesome-design-md
2. Pick the brand closest to your target aesthetic
3. Copy its DESIGN.md into your project root
4. Proceed to Step 3

Caveat (always state this):

These are third-party brand specs. Use as a reference/starting point — adapt colors, naming, and voice to avoid trademark issues. Don't ship someone else's brand identity as your own.

Step 2B — Generate a custom DESIGN.md from scratch

Run design-consultation first if the user doesn't have a system yet. Then generate a DESIGN.md following this structure:

# DESIGN.md — [Project Name]

## Brand Identity
- **Personality**: [3 adjectives]
- **Voice**: [tone description]
- **Positioning**: [what this product is and for whom]

## Color System
- Primary: `#XXXXXX` — [usage]
- Secondary: `#XXXXXX` — [usage]
- Background: `#XXXXXX`
- Surface: `#XXXXXX`
- Text primary: `#XXXXXX`
- Text muted: `#XXXXXX`
- Accent: `#XXXXXX` — [for highlights, CTAs]
- Error / Warning / Success: `#XX` `#XX` `#XX`

## Typography
- Heading font: [font name] — weights [X, X]
- Body font: [font name] — size [Xpx base]
- Mono font: [font name] — [for code/labels]
- Scale: [xs/sm/base/lg/xl/2xl with px values]

## Spacing & Layout
- Base unit: [Xpx]
- Grid: [X columns, Xpx gutter]
- Max content width: [Xpx]
- Border radius: [sm: Xpx / md: Xpx / lg: Xpx / pill: Xpx]

## Component Patterns
- Buttons: [primary / secondary / ghost — describe shape, padding, hover]
- Cards: [background, border, shadow, padding]
- Inputs: [border style, focus ring, placeholder]
- Navigation: [style, active state, mobile behavior]
- Icons: [library, size, stroke weight]

## Motion & Interaction
- Transition: [duration, easing]
- Hover: [lift, glow, or color shift]
- Loading: [skeleton / spinner / shimmer]

## Do / Don't
- DO: [2–3 rules that reinforce the brand]
- DON'T: [2–3 anti-patterns to avoid]

Fill every field. Vague entries ("nice colors") are useless to an agent.

Step 3 — Wire DESIGN.md into the project workflow

After the file exists in the project root:

1. Add to the project's CLAUDE.md:

   ## Design system
   Read DESIGN.md before generating any UI. Every component must match it.
   

2. Use with frontend-design / design-html: When invoking either skill, tell it: "Follow DESIGN.md — it's in the project root."

3. Use with design-review / design-shotgun: Reference DESIGN.md as the canonical spec during review passes.

4. Update DESIGN.md when the system evolves — treat it as living documentation.

Relation to other design skills

awesome-design sets the system. The other skills USE the system.