Design System

Design System — Tiered Design Intelligence

Two tiers of design knowledge. Use Tier 1 for common decisions. Dive into Tier 2 CSVs only when you need more options or unusual combinations.

Context Detection (ALWAYS do this first)

Before making any design decision, detect the project context:

1. Read package.json → Stack (Astro, SvelteKit, Next.js)
2. Read src/config/site.ts or equivalent → Industry, brand mood
3. Check design-system/MASTER.md → Project-specific overrides (HIGHEST PRIORITY)
4. Check tailwind.config or app.css → Current design tokens

If design-system/MASTER.md exists, its values ALWAYS override recommendations. The CSV data helps CREATE the initial MASTER.md — it does not overrule an existing one.

Decision Tree — When to Use Tier 2 (CSVs)

QUESTION                                          ACTION
─────────────────────────────────────────────────────────────
Standard industry palette?                     → Tier 1 inline table (Section 5)
Unusual mood/industry combo?                   → Read data/palettes.csv
Product-type-specific palette?                 → Read data/product-palettes.csv
One of the 10 standard font pairings?          → Tier 1 inline table (Section 3)
Need more font options or specific mood?       → Read data/typography.csv
Looking for a specific UI style?               → Read data/styles.csv
Need UX best practice guidance?                → Read data/ux-rules.csv
Searching for a wow effect?                    → Read data/wow-effects.csv
Standard spacing or component pattern?         → Tier 1 inline table (Section 2/6)

Rule: Try Tier 1 first. Only read CSVs when inline tables don't cover the need.

1. Design Principles

2. Spacing Scale (Tailwind v4)

Consistent spacing prevents "random padding". Always choose from this scale:

Rules:

• Between elements within a group: 2-4
• Between groups: 6-8
• Between sections: 16-24
• Never mix padding — stay consistent

3. Typography

Font Pairings (Quick Reference — 10 most common)

For 25+ more options: Read data/typography.csv

Typography Scale

Rules:

• Max 2 font families per project
• Line height: Body leading-relaxed (1.625), Headings leading-tight (1.25)
• GDPR: Fonts MUST always be self-hosted (no Google Fonts CDN)

4. Colors

Semantic Colors (always use these)

Contrast Rules

• Text on background: Minimum 4.5:1 (WCAG AA)
• Large text (24px+): Minimum 3:1
• UI elements (buttons, inputs): Minimum 3:1 against background
• Tools: contrast-ratio.com or DevTools Accessibility Panel

5. Industry Palettes (Quick Reference — 12 most common)

For 70+ more palettes (multiple moods per industry, dark variants, mood-based): Read data/palettes.csv

Usage in projects:

1. Identify the client's industry
2. Choose matching palette from table (or data/palettes.csv for more options)
3. Define as CSS custom properties in tailwind.config or app.css
4. Use consistently — no deviations without reason

Reference: For product-specific palettes covering 161 categories with deeper mood/variant matrices, see nextlevelbuilder/ui-ux-pro-max-skill v2.5.0. Hangar's palette database focuses on the most common industries — the external resource covers niche and product-specific verticals.

Product-Type Palettes

For industry-specific palette recommendations, consult data/product-palettes.csv. Each entry maps a product type to a curated primary/accent/background combination with reasoning for why these colors work for that specific industry.

Usage: When a user describes their project type (e.g., "fintech dashboard", "restaurant website", "SaaS analytics"), look up the matching product type in the CSV and use it as the starting point for the palette recommendation.

40 product types covered including: SaaS, fintech, healthcare, e-commerce, education, food, travel, real estate, fitness, nonprofit, legal, gaming, music, AI/ML, crypto, sustainability, luxury, developer tools, and more.

6. Component Patterns (Tailwind v4)

Hero Section

<section class="relative overflow-hidden bg-background px-6 py-24 sm:py-32 lg:px-8">
  <div class="mx-auto max-w-2xl text-center">
    <p class="text-sm font-medium uppercase tracking-wider text-primary">
      Overline Text
    </p>
    <h1 class="mt-2 text-4xl font-bold tracking-tight sm:text-6xl">
      Main Headline
    </h1>
    <p class="mt-6 text-lg leading-relaxed text-muted">
      Description text, max 2-3 sentences.
    </p>
    <div class="mt-10 flex items-center justify-center gap-4">
      <a href="#" class="rounded-lg bg-primary px-6 py-3 text-sm font-semibold text-white shadow-sm hover:bg-primary/90 transition">
        Primary CTA
      </a>
      <a href="#" class="text-sm font-semibold text-primary hover:text-primary/80 transition">
        Secondary Link &rarr;
      </a>
    </div>
  </div>
</section>

Card

<article class="group rounded-2xl border border-border/50 bg-surface p-6 shadow-sm transition hover:shadow-md">
  <div class="aspect-video overflow-hidden rounded-xl bg-muted/10">
    <img src="..." alt="..." class="h-full w-full object-cover transition group-hover:scale-105" />
  </div>
  <div class="mt-4">
    <p class="text-xs font-medium uppercase tracking-wider text-primary">Category</p>
    <h3 class="mt-1 text-lg font-semibold">Title</h3>
    <p class="mt-2 text-sm text-muted line-clamp-2">Description...</p>
  </div>
</article>

Button Variants

<!-- Primary -->
<button class="rounded-lg bg-primary px-5 py-2.5 text-sm font-semibold text-white shadow-sm hover:bg-primary/90 transition">
  Primary
</button>

<!-- Secondary / Outline -->
<button class="rounded-lg border border-primary px-5 py-2.5 text-sm font-semibold text-primary hover:bg-primary/5 transition">
  Secondary
</button>

<!-- Ghost -->
<button class="rounded-lg px-5 py-2.5 text-sm font-semibold text-primary hover:bg-primary/5 transition">
  Ghost
</button>

Section with Overline

<section class="px-6 py-16 sm:py-24 lg:px-8">
  <div class="mx-auto max-w-7xl">
    <div class="mx-auto max-w-2xl text-center">
      <p class="text-sm font-medium uppercase tracking-wider text-primary">Overline</p>
      <h2 class="mt-2 text-3xl font-bold sm:text-4xl">Section Title</h2>
      <p class="mt-4 text-lg text-muted">Optional description text.</p>
    </div>
    <div class="mt-12 grid gap-8 sm:grid-cols-2 lg:grid-cols-3">
      <!-- Cards / Content here -->
    </div>
  </div>
</section>

Navigation (Mobile-Ready)

<header class="sticky top-0 z-50 border-b border-border/50 bg-background/80 backdrop-blur-lg">
  <nav class="mx-auto flex max-w-7xl items-center justify-between px-6 py-4">
    <a href="/" class="text-xl font-bold">Logo</a>
    <div class="hidden items-center gap-8 md:flex">
      <a href="#" class="text-sm font-medium text-muted hover:text-foreground transition">Link</a>
      <a href="#" class="rounded-lg bg-primary px-4 py-2 text-sm font-semibold text-white">CTA</a>
    </div>
    <!-- Mobile: Burger menu with JS/Alpine -->
  </nav>
</header>

Footer

<footer class="border-t border-border/50 bg-surface">
  <div class="mx-auto max-w-7xl px-6 py-12 lg:px-8">
    <div class="grid gap-8 sm:grid-cols-2 lg:grid-cols-4">
      <!-- Column 1: Logo + Description -->
      <!-- Columns 2-4: Link groups -->
    </div>
    <div class="mt-12 border-t border-border/30 pt-8 text-center text-sm text-muted">
      &copy; {{YEAR}} {{COMPANY_NAME}}. All rights reserved.
      <span class="mx-2">|</span>
      <a href="/imprint" class="hover:text-foreground transition">Imprint</a>
      <span class="mx-2">|</span>
      <a href="/privacy" class="hover:text-foreground transition">Privacy Policy</a>
    </div>
  </div>
</footer>

7. Wow Factor Techniques (Quick Reference — 9 most common)

For 15+ more effects with performance ratings: Read data/wow-effects.csv

8. Persistence (Optional)

For projects with multiple pages: create design-system/MASTER.md in the project root.

# Design System — [Project Name]

## Colors
- Primary: #2C3E50
- Secondary: #E67E22
- CTA: #27AE60
- Background: #F8F9FA

## Fonts
- Heading: Outfit (600, 700)
- Body: Outfit (400)
- Google Fonts: https://fonts.google.com/specimen/Outfit

## Spacing
- Section Padding: py-16 sm:py-24
- Card Padding: p-6
- Grid Gap: gap-8

## Wow Factor
- Glassmorphism cards with backdrop-blur
- Staggered scroll reveal on feature grid

Claude reads this file automatically and follows it. Page-specific overrides: design-system/pages/{pagename}.md.

Rules

1. Consistency > Creativity — Better uniform than every section different
2. Max 2 fonts — Never more, even if it would be "creative"
3. Spacing from the scale — No arbitrary px values
4. Check contrast — WCAG AA is mandatory, not optional
5. Mobile First — Desktop layout is the extension, not the other way around
6. Self-hosted fonts — GDPR. Always.
7. Performance — No heavy animations at the cost of LCP
8. MASTER.md overrides all — If it exists, follow it. CSVs inform, MASTER.md decides.
9. Stack-agnostic design — This skill provides design decisions. Code patterns come from the stack skills (Astro, SvelteKit, etc.).
10. Tier 1 first — Check inline tables before reading CSVs. Save tokens.