Styleguide

Styleguide

Create a comprehensive design language for any project. This is the starting point for all design work — it defines the "why" behind every visual choice.

When to Use

• User wants to create or define a visual identity for a project
• User asks "what fonts/colors should I use?"
• User is starting a new website, app, or product and needs design direction
• User wants a coherent design language across multiple deliverables
• User asks for "brand style" or "design system" guidance (strategic, not technical)

When NOT to Use

• User wants to generate actual images → use media-plugin/image-generation
• User wants to search for stock photos → use media-plugin/image-sourcing
• User wants to audit WCAG contrast → use design-system

Styleguide Creation Workflow

Step 1: Project Discovery

Gather these inputs from the user (ask if not provided):

Step 2: Aesthetic Profile Selection

Choose an aesthetic profile from references/aesthetic-profiles.md that matches the project discovery. Each profile provides default directions for typography, color, spacing, imagery, and motion.

The profile is a starting point, not a rigid template. Customize based on the specific project needs.

Step 3: Typography Strategy

Select a font pairing from references/font-pairings.md.

Define:

• Heading font — what emotion does it carry?
• Body font — is it readable at small sizes?
• Monospace (if applicable) — for code, data, or technical content
• Weight strategy — which weights will be used and where (e.g., Bold for H1, Medium for H3, Regular for body)
• Scale — reference design-system for type scale ratios (Major Third 1.250 is a safe default)

Step 4: Color Strategy

Build a palette using references/color-moods.md.

Define:

• Primary — the dominant brand color (60% of visual space)
• Secondary — supporting color (20-30%)
• Accent — for CTAs, highlights, attention (5-10%)
• Neutrals — text, backgrounds, borders (gray scale)
• Semantic — success/warning/error/info
• Dark mode strategy — invert, dim, or separate palette?

For technical implementation (palette generation, WCAG contrast checking), reference design-system.

Step 5: Imagery & Media Direction

Define the visual style for all media assets:

• Photography style — moody, bright, editorial, candid, abstract, documentary
• Illustration style — flat, 3D, hand-drawn, isometric, line art
• Icon library — Lucide (clean, consistent), Heroicons (Tailwind ecosystem), Tabler (largest selection). Use media-plugin/icon-library to fetch.
• Image sourcing — use media-plugin/image-sourcing with specific search queries
• Image generation — use media-plugin/image-generation with style-consistent prompts
• Video/motion — use media-plugin/video-generation if applicable

For prompt crafting, use the media-prompt-craft skill to translate this direction into specific prompts and queries.

Step 6: Output Styleguide Document

Produce a structured markdown document using this template:

# [Project Name] Design Language

## Aesthetic Direction
- **Profile**: [name from aesthetic-profiles.md]
- **Personality**: [3-5 adjectives]
- **Inspiration**: [reference sites/brands]
- **Key principle**: [one sentence that captures the design philosophy]

## Typography
- **Heading**: [font name] — [why this font]
- **Body**: [font name] — [why this font]
- **Monospace** (if applicable): [font name]
- **Pairing rationale**: [why these fonts work together]
- **Weight strategy**: H1=Bold(700), H2=SemiBold(600), H3=Medium(500), Body=Regular(400)
- **Scale**: [ratio] — xs(12) sm(14) base(16) lg(18) xl(20) 2xl(24) 3xl(30) 4xl(36) 5xl(48)
- **Google Fonts import**: `@import url('https://fonts.googleapis.com/css2?family=...')`

## Color System
| Role | Hex | Usage |
|------|-----|-------|
| Primary | #___ | Main brand, CTAs, links |
| Secondary | #___ | Supporting elements |
| Accent | #___ | Highlights, badges, attention |
| Neutral-900 | #___ | Primary text |
| Neutral-700 | #___ | Secondary text |
| Neutral-400 | #___ | Placeholder, disabled |
| Neutral-100 | #___ | Backgrounds, cards |
| Neutral-50 | #___ | Page background |
| Success | #___ | Positive states |
| Warning | #___ | Caution states |
| Error | #___ | Error states |

**Dark mode**: [strategy — inverted, dimmed, or separate palette]

## Imagery Direction
- **Photography**: [style + mood + example search queries for media-plugin/image-sourcing]
- **Illustrations**: [style + example prompts for media-plugin/image-generation]
- **Icons**: [library choice + style rationale — use media-plugin/icon-library]

## Spacing & Layout
- **Grid**: [4px or 8px base unit]
- **Density**: [compact / balanced / spacious]
- **Max content width**: [e.g., 1280px]
- **Section padding**: [e.g., 64px vertical, 24px horizontal]
- **Card padding**: [e.g., 24px]
- **Component spacing**: [e.g., 16px between cards]

## Motion & Interaction
- **Philosophy**: [subtle / expressive / none]
- **Page load**: [staggered reveal / fade in / instant]
- **Hover states**: [lift / glow / color shift / scale]
- **Transitions**: [duration and easing — e.g., 0.3s cubic-bezier(0.4, 0, 0.2, 1)]

## Cross-Plugin Implementation Guide
- **Palette & WCAG**: use `design-system` for palette generation and contrast checking
- **Icons**: use `media-plugin/icon-library` to fetch SVGs from [chosen library]
- **Stock photos**: use `media-plugin/image-sourcing` with these queries: [list]
- **Generated visuals**: use `media-plugin/image-generation` with these prompts: [list]
- **Presentations**: apply this styleguide when using `office-plugin/pptx`

Tips

• Always start with the audience, not the aesthetics — design for the people using it
• A styleguide should feel inevitable for THIS project, not generic
• Fewer, stronger choices beat many weak ones — commit to a direction
• Test your font pairing at actual sizes before committing — some fonts that look good at 48px fall apart at 14px
• The styleguide is a living document — update it as the project evolves