Skill: defineagain/design-agent (version 1.0.0)

--- name: design-agent description: Design consultation skill for AI agents. Invoke when another agent, skill, or user requests design review, design tokens, or UI美化 (UI beautification). Provides structured design prompts, DESIGN.md files, color systems, typography rules, spacing conventions, and component patterns. Use when building UI, generating HTML/React, writing newsletters, or any output where visual design matters. Also triggered by "make it look better", "apply design", "improve the UI", or "add design context". --- # Design Agent — Structured Design for AI Outputs ## What This Skill Does When another agent or skill produces UI output, it can call this skill to get a **structured design brief** — real design tokens, color systems, typography, spacing — that transforms generic AI output into distinctive, intentional design. ## Design Prompt Sources Use these tools to generate a DESIGN.md for a given project or style: | Tool | Use | |---|---| | [design-extractor.com](https://www.design-extractor.com) | Paste any URL → structured DESIGN.md with tokens | | [design/prompts](https://lnkd.in/gy8z4XRF) | Browse 31+ rendered design styles, grab AI prompts | | [typeui.sh](https://www.typeui.sh) | `npx typeui.sh pull [style]` — CLI, 57+ design skills | | [awesome-design-md](https://lnkd.in/ghx8RddV) | Real DESIGN.md files from Stripe, Linear, Vercel etc. | ## Core Design System (defaults — override per project) Stored in `references/design-tokens.md`: - Color palette (hex + use) - Typography scale - Spacing system - Component patterns - Animation/transition defaults ## Workflow ``` Another agent requests design improvement │ ▼ 1. Identify the output medium (HTML/React/Newsletter/PDF/etc.) 2. Identify the target aesthetic or reference site 3. Use design-extractor.com or typeui.sh to generate design tokens 4. Merge with references/design-tokens.md base system 5. Write a DESIGN.md into the project or skill directory 6. Downstream agents read DESIGN.md → apply consistently ``` ## VLM Review Loop (MANDATORY before finalising) Before any design is marked complete, run it through a VLM review iteration: ### Step 1 — Generate initial output Apply design tokens → produce HTML/React/PDF/etc. ### Step 2 — Capture screenshot Use `canvas` tool to snapshot the rendered output: ``` canvas(action=snapshot, node=<target>, width=1280) ``` ### Step 3 — VLM review Send the snapshot to the vision model with the design brief: ``` Review this against the DESIGN.md tokens: - Are colors consistent with the palette? - Is typography on-scale (no arbitrary sizes)? - Is spacing on the 8px grid? - Are component states correct (hover, active)? - Any visual anti-patterns (orphaned text, broken hierarchy)? Flag specific issues and suggested fixes. ``` ### Step 4 — Iterate If VLM flags issues → apply fixes → resnapshot → re-review. Repeat until VLM returns "design is consistent with tokens" or all flagged issues resolved. ### Step 5 — Final sign-off Only mark complete when VLM confirms token consistency. Log iteration count in the DESIGN.md. ``` Iteration log: - v1: Initial render — 3 issues flagged (orphaned h3, wrong accent color, spacing off grid) - v2: Fixed accent + orphaned h3 — spacing still off - v3: All clear. Approved. ``` ### VLM Review Prompts (by output type) **HTML/Newsletter:** ``` Check: color palette, typographic hierarchy, spacing grid alignment, component borders, dark/light mode if applicable. Flag any ad-hoc values. ``` **PDF (rendered as screenshot):** ``` Check: font sizes on scale, line spacing, margin consistency, image placement, page break handling. Note any text overflow or orphans. ``` **React/UI Component:** ``` Check: button/input sizes match tokens, color applied from palette, hover/active states visible, spacing between elements on grid. ``` ## Creating a Project DESIGN.md ```bash # Extract design from a reference URL # (use design-extractor.com manually, paste result into project) # Or pull a known style from typeui npx typeui.sh pull minimal # clean typographic npx typeui.sh pull editorial # magazine/longform npx typeui.sh pull brutalist # high contrast, raw npx typeui.sh pull luxury # dark, gold accents ``` ## Design Review Checklist (before shipping UI) - [ ] Colors match design tokens (no ad-hoc hex values) - [ ] Typography uses defined scale (no arbitrary font sizes) - [ ] Spacing follows the system (8px grid or defined scale) - [ ] Component states covered (hover, active, disabled, error) - [ ] Dark mode / light mode if applicable - [ ] Responsive breakpoints defined - [ ] Animation durations defined (no magic numbers like `0.3s` without tokens) ## Integration with Other Skills This skill is **designed to be called by other skills**. Any skill that produces visual output should reference this skill before generating UI. See `references/integration-guide.md` for how other skills should call design-agent. ## Key Files | File | Purpose | |---|---| | `references/design-tokens.md` | Base design token system | | `references/integration-guide.md` | How other skills call design-agent | | `assets/design-prompt-template.md` | DESIGN.md template for new projects | | `assets/example-design-standards/` | Example extracted from Vercel/Linear/Stripe |

path: assets/design-prompt-template.md
content: # DESIGN.md — [Project Name]

**Generated by:** design-agent
**Date:** YYYY-MM-DD
**Style:** [minimal / editorial / brutalist / luxury / custom]
**Medium:** [HTML / React / PDF / Newsletter / etc.]

---

## Colors

| Token | Value | Use |
|---|---|---|
| `--color-bg` | `#XXXXXX` | |
| `--color-surface` | `#XXXXXX` | |
| `--color-border` | `#XXXXXX` | |
| `--color-text` | `#XXXXXX` | |
| `--color-muted` | `#XXXXXX` | |
| `--color-accent` | `#XXXXXX` | |

## Typography

| Token | Value | Use |
|---|---|---|
| `--font-sans` | `XXXX` | |
| `--font-serif` | `XXXX` | |
| `--font-mono` | `XXXX` | |

### Scale
| Step | Size | Use |
|---|---|---|
| `--text-xs` | | |
| `--text-sm` | | |
| `--text-base` | | |
| `--text-lg` | | |
| `--text-xl` | | |
| `--text-2xl` | | |
| `--text-3xl` | | |
| `--text-4xl` | | |

## Spacing

`--space-1` through `--space-24` (8px grid)

## Animation

| Token | Value |
|---|---|
| `--duration-fast` | |
| `--duration-base` | |
| `--duration-slow` | |

## Components

### Button
```css
/* tokens here */
```

### Card
```css
/* tokens here */
```

### Input
```css
/* tokens here */
```

## Design Review Checklist

- [ ] Colors from tokens — no ad-hoc hex
- [ ] Typography from scale — no arbitrary font sizes
- [ ] Spacing from grid — no magic numbers
- [ ] Component states (hover, active, disabled, error) defined
- [ ] Dark mode / light mode handled
- [ ] Responsive breakpoints defined
- [ ] Animation durations from token set

path: assets/example-design-standards/vercel-minimal.md
content: # DESIGN.md — Vercel-Inspired Minimal

**Style:** Minimal / Developer-focused / Editorial
**Use for:** SaaS dashboards, developer tools, landing pages

## Colors
```css
--color-bg: #000000;
--color-surface: #111111;
--color-border: #222222;
--color-text: #ffffff;
--color-muted: #666666;
--color-accent: #ffffff;  /* white on black is the accent */
--color-accent-subtle: #333333;
```

## Typography
```css
--font-sans: 'Geist', 'Inter', system-ui, sans-serif;
--font-mono: 'GeistMono', 'JetBrains Mono', monospace;
--text-xs: 12px; --text-sm: 14px; --text-base: 16px;
--text-lg: 18px; --text-xl: 24px; --text-2xl: 32px;
--text-3xl: 48px; --text-4xl: 64px;
```

## Spacing
8px grid — `--space-1` (4px) through `--space-24` (96px)

## Key Rules
- Dark backgrounds with white text throughout
- Mono font for labels, metadata, code
- Sans for headings and body
- Minimal border-radius (2-4px max)
- No decorative gradients — pure flat design
- Generous whitespace, tight typographic control


path: references/design-tokens.md
content: # Design Tokens — Base System

## Color Palette

### Brand Neutral (Dark)
| Token | Hex | Use |
|---|---|---|
| `--color-bg` | `#0F0F0F` | Page background |
| `--color-surface` | `#1A1A1A` | Card / panel surface |
| `--color-border` | `#2A2A2A` | Borders, dividers |
| `--color-text` | `#F5F5F5` | Primary text |
| `--color-muted` | `#888888` | Secondary text, labels |
| `--color-accent` | `#6366F1` | Links, focus states, CTAs |

### Light Mode Override
| Token | Hex | Use |
|---|---|---|
| `--color-bg` | `#FAFAFA` | Page background |
| `--color-surface` | `#FFFFFF` | Card surface |
| `--color-border` | `#E5E5E5` | Borders |
| `--color-text` | `#111111` | Primary text |
| `--color-muted` | `#666666` | Secondary text |

### Semantic Colors
| Token | Hex | Use |
|---|---|---|
| `--color-success` | `#22C55E` | Success states |
| `--color-warning` | `#F59E0B` | Warning states |
| `--color-error` | `#EF4444` | Error states |
| `--color-info` | `#3B82F6` | Info / links |

## Typography

### Type Scale (ratio: 1.25 — Major Third)
| Step | Size | Use |
|---|---|---|
| `--text-xs` | 12px / 0.75rem | Labels, captions |
| `--text-sm` | 14px / 0.875rem | Secondary text, metadata |
| `--text-base` | 16px / 1rem | Body copy |
| `--text-lg` | 20px / 1.25rem | Lead text |
| `--text-xl` | 24px / 1.5rem | H4, card titles |
| `--text-2xl` | 30px / 1.875rem | H3 |
| `--text-3xl` | 38px / 2.375rem | H2 |
| `--text-4xl` | 48px / 3rem | H1, display |

### Font Families
```css
--font-sans: 'Inter', system-ui, -apple-system, sans-serif;
--font-serif: 'Georgia', 'Times New Roman', serif;
--font-mono: 'JetBrains Mono', 'Fira Code', monospace;
--font-display: 'Inter', var(--font-sans);  /* override per project */
```

### Weights
```css
--font-normal: 400;
--font-medium: 500;
--font-semibold: 600;
--font-bold: 700;
```

### Line Height
```css
--leading-tight: 1.25;   /* headings */
--leading-normal: 1.5;  /* body */
--leading-relaxed: 1.75; /* longform / newsletter */
```

## Spacing (8px Grid)

```css
--space-1:  4px;
--space-2:  8px;
--space-3:  12px;
--space-4:  16px;
--space-5:  20px;
--space-6:  24px;
--space-8:  32px;
--space-10: 40px;
--space-12: 48px;
--space-16: 64px;
--space-20: 80px;
--space-24: 96px;
```

## Border Radius

```css
--radius-sm:  4px;   /* buttons, inputs */
--radius-md:  8px;   /* cards, panels */
--radius-lg:  12px;  /* modals, overlays */
--radius-xl:  16px;  /* large containers */
--radius-full: 9999px; /* pills, avatars */
```

## Shadows

```css
--shadow-sm:  0 1px 2px rgba(0,0,0,0.05);
--shadow-md:  0 4px 6px rgba(0,0,0,0.07), 0 2px 4px rgba(0,0,0,0.05);
--shadow-lg:  0 10px 15px rgba(0,0,0,0.1), 0 4px 6px rgba(0,0,0,0.05);
--shadow-xl:  0 20px 25px rgba(0,0,0,0.1), 0 10px 10px rgba(0,0,0,0.04);
```

## Animation

```css
--duration-fast:   100ms;  /* micro-interactions, toggles */
--duration-base:   200ms;  /* buttons, hovers, standard transitions */
--duration-slow:    400ms;  /* modals, panels, reveals */
--ease-default:    cubic-bezier(0.4, 0, 0.2, 1);
--ease-in:          cubic-bezier(0.4, 0, 1, 1);
--ease-out:         cubic-bezier(0, 0, 0.2, 1);
--ease-bounce:      cubic-bezier(0.34, 1.56, 0.64, 1);
```

## Breakpoints

```css
--bp-sm:  640px;
--bp-md:  768px;
--bp-lg:  1024px;
--bp-xl:  1280px;
--bp-2xl: 1536px;
```

## Component Tokens

### Button
```css
--btn-height:     40px;
--btn-padding-x:  16px;
--btn-radius:     var(--radius-sm);
--btn-font-size:  var(--text-sm);
--btn-font-weight: var(--font-medium);
```

### Input
```css
--input-height:   40px;
--input-padding:  12px;
--input-radius:   var(--radius-sm);
--input-border:   1px solid var(--color-border);
--input-focus:    2px solid var(--color-accent);
```

### Card
```css
--card-padding:   var(--space-6);
--card-radius:    var(--radius-md);
--card-bg:        var(--color-surface);
--card-shadow:    var(--shadow-sm);
```

## Z-Index Scale

```css
--z-base:    0;
--z-dropdown: 100;
--z-sticky:   200;
--z-overlay:  300;
--z-modal:    400;
--z-toast:    500;
```


path: references/integration-guide.md
content: # Integration Guide — How Other Skills Call design-agent

## When to Call This Skill

Any skill that generates visual output should check whether design-agent is needed:

| Skill | Call design-agent when... |
|---|---|
| `article-writing` | Generating HTML newsletters or formatted articles |
| `pdf-generator` | Creating styled PDFs with headers, typography |
| `novel-editor` | Generating HTML scene excerpts or HTML chapter previews |
| `writer` | Producing formatted long-form output with visual hierarchy |
| Any skill generating HTML/React | First output of a UI component or page |

## How to Call

### From another skill's SKILL.md

Add to the calling skill's description field:
```
Also invoke design-agent when the user asks to improve, style, or beautify
any visual output, or when the skill generates HTML/React/PDF for the first time.
```

### From an agent (human request)

```
User: Make this newsletter look better
→ Agent calls design-agent
→ design-agent provides design tokens + workflow
→ agent applies them to newsletter HTML
```

### From a script

```bash
# Extract design from a reference URL manually
# Then read design-tokens into context
cat references/design-tokens.md
```

## Calling Pattern

When design-agent is called, it expects:

1. **The output medium** — HTML, React, PDF, Newsletter, etc.
2. **The reference style** — a URL, a style name (minimal/editorial/brutalist/luxury), or "use defaults"
3. **The content to be styled** — the raw output before design is applied

design-agent then returns:
- Design tokens (merged base + reference)
- A `DESIGN.md` file written to the project directory
- A design review checklist response

## What to Tell design-agent

When invoking, include:
- What you're building (newsletter, UI panel, PDF page, etc.)
- Any existing brand tokens or reference URLs
- The target aesthetic (corporate, editorial, playful, luxury, etc.)
- Whether this is a one-off or an ongoing project (affects token depth)

## Design Review Before Shipping

Any visual output generated by another skill should pass through the design-agent checklist:

```
- Colors from tokens (no ad-hoc hex)
- Typography from scale (no arbitrary font sizes)
- Spacing from grid (no magic numbers)
- Component states defined
- Animation durations from token set
```

If the calling skill can't apply all tokens (e.g., PDF output), it should note which tokens are unresolvable and document why.

## Creating a Project DESIGN.md

Once design-agent has provided tokens, the calling skill should write a `DESIGN.md` into the project directory:

```markdown
# DESIGN.md — Project Name

## Colors
<!-- from design-agent tokens -->

## Typography
<!-- from design-agent tokens -->

## Spacing
<!-- from design-agent tokens -->

## Components
<!-- project-specific components -->
```

This becomes the single source of truth for design in that project, replacing ad-hoc instructions.

Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)