# HTML Design Guidelines

Guidelines for generating distinctive, high-quality HTML pages. Read this before generating any HTML output.

---

## Anti-Slop: Forbidden Patterns

These patterns are explicitly forbidden — they signal "AI-generated template" and undermine quality. Check every page against this list before delivering.

### Typography — Forbidden Fonts as Primary `--font-body`

- **Inter** — the single most overused AI default
- **Roboto, Arial, Helvetica** — generic system fallbacks promoted to primary
- **system-ui, sans-serif alone** — no character, no intent

**Required:** Pick from the font pairings in `html-libraries.md`. Every generation should use a different pairing from the last.

### Color Palette — Forbidden Accents

- `#8b5cf6`, `#7c3aed`, `#a78bfa` — Tailwind's indigo/violet defaults
- `#d946ef` — fuchsia
- `#06b6d4` + `#d946ef` + `#f472b6` — the cyan + magenta + pink neon gradient combination
- Any palette describable as "Tailwind defaults with purple/pink/cyan accents"

**Forbidden color effects:**
- Gradient text on headings (`background: linear-gradient(...); background-clip: text;`) — screams AI-generated
- Animated glowing box-shadows (`@keyframes glow { box-shadow: 0 0 20px... }`) — always produces AI slop
- Multiple overlapping radial glows in accent colors creating a "neon haze"
- Pulsing/breathing effects on static content
- Continuous animations that run after page load (except progress indicators)

**Required accents (use these):**
- Terracotta + sage (`#c2410c`, `#65a30d`) — warm, earthy
- Teal + slate (`#0891b2`, `#0369a1`) — technical, precise
- Rose + cranberry (`#be123c`, `#881337`) — editorial, refined
- Amber + emerald (`#d97706`, `#059669`) — data-focused
- Deep blue + gold (`#1e3a5f`, `#d4a73a`) — premium, sophisticated

### Section Headers — Forbidden

- Emoji icons in section headers (🏗️ ⚙️ 📁 💻 📅 🔗 ⚡ 🔧 📦 🚀, etc.)
- Section headers that all use the same icon-in-rounded-box pattern

**Required:** Use styled monospace labels with colored dot indicators (`.section-label` + `.ve-card__label` pattern), numbered badges, or asymmetric section dividers. If an icon is genuinely needed, use inline SVG matching the palette.

### Layout — Forbidden

- Perfectly centered everything with uniform padding
- All cards styled identically with the same border-radius, shadow, and spacing
- Every section getting equal visual treatment — no hero/primary vs. secondary distinction
- Symmetric layouts where left and right halves mirror each other

### Template Clichés — Forbidden

- Three-dot window chrome (red/yellow/green dots) on code blocks
- KPI cards where every metric has identical gradient text treatment
- "Neon Dashboard" aesthetic
- Gradient meshes with pink/purple/cyan blobs in the background

### The Slop Test

Before delivering, check: **Would a developer immediately think "AI generated this"?**

Signs of slop:
1. Inter or Roboto font with purple/violet gradient accents
2. Every heading has `background-clip: text` gradient
3. Emoji icons leading every section
4. Glowing cards with animated shadows
5. Cyan-magenta-pink color scheme on dark background
6. Perfectly uniform card grid with no visual hierarchy
7. Three-dot code block chrome

If two or more are present: regenerate with Blueprint, Editorial, Paper/ink, or a specific IDE theme.

---

## Palette Cohesion Principles

**Every generated page must feel like one intentional color story.** This is the single most important readability rule.

1. **Background warmth must match accent warmth.** Terracotta accents need warm cream backgrounds (`#faf7f5`), not cool gray (`#f8f9fa`). Teal accents need cool-tinted backgrounds (`#f0fdfa`). Mixing warm accents on cool backgrounds (or vice versa) creates visual dissonance that makes pages feel generic.

2. **Text-dim must belong to the same family.** On warm backgrounds, use warm grays (`#8a7e72`, `#a69889`). On cool backgrounds, use cool grays (`#5f8a85`, `#8b949e`). Never use GitHub-style `#6b7280` on warm cream.

3. **Borders should be tinted, not neutral.** Use `rgba(0, 0, 0, 0.07)` or palette-tinted borders instead of flat `#e5e7eb`. Borders should be barely visible — felt, not seen.

4. **Surface layers create depth without fighting.** Define `--surface`, `--surface2`, and `--surface-elevated` as gradations of the same hue, not different colors.

5. **Extend every palette with semantic colors.** Every preset below should also define `--green`, `--red`, `--amber`, `--sage`, `--teal`, `--plum` (and their `*-dim` variants) that harmonize with the base palette. Richer semantic sets prevent monotony without clashing.

---

## 6 Curated Style Presets

Pick one and commit. The constrained presets (Blueprint, Editorial, Paper/Ink, Terminal Mono) are safer — they have specific requirements that prevent defaulting to generic patterns.

**IMPORTANT:** After choosing a preset, extend it with semantic colors (`--green`, `--red`, `--amber`, `--sage`, `--teal`, `--plum` + `*-dim` variants) that harmonize with the base palette. The default palette in `html-css-patterns.md` shows the full semantic structure — replicate that structure for whichever preset you choose.

### Blueprint

Technical drawing feel. Subtle grid background, deep slate/blue palette, monospace labels, precise borders.

```css
:root {
  --font-body: 'DM Sans', system-ui, sans-serif;
  --font-mono: 'Fira Code', 'SF Mono', monospace;
  --bg: #0d1421;
  --surface: #111d2e;
  --surface-elevated: #162438;
  --border: rgba(100, 160, 220, 0.12);
  --border-bright: rgba(100, 160, 220, 0.22);
  --text: #c8d8e8;
  --text-dim: #607080;
  --accent: #4a90d9;
  --accent-dim: rgba(74, 144, 217, 0.1);
}
@media (prefers-color-scheme: light) {
  :root {
    --bg: #f0f4f8;
    --surface: #ffffff;
    --surface-elevated: #e8eef4;
    --border: rgba(30, 60, 100, 0.1);
    --text: #1a2a3a;
    --text-dim: #5a7090;
    --accent: #1a5fa8;
    --accent-dim: rgba(26, 95, 168, 0.08);
  }
}
```

Background: faint dot grid (`background-image: radial-gradient(circle, var(--border) 1px, transparent 1px); background-size: 24px 24px`). Monospace labels throughout.

### Editorial

Serif headlines (Instrument Serif or Crimson Pro), generous whitespace, muted earth tones or deep navy + gold.

```css
:root {
  --font-body: 'Instrument Serif', Georgia, serif;
  --font-mono: 'JetBrains Mono', 'SF Mono', monospace;
  --bg: #0f1729;
  --surface: #162040;
  --surface-elevated: #1d2b52;
  --border: rgba(200, 180, 140, 0.08);
  --text: #e8e4d8;
  --text-dim: #9a9484;
  --accent: #d4a73a;
  --accent-dim: rgba(212, 167, 58, 0.1);
}
@media (prefers-color-scheme: light) {
  :root {
    --bg: #faf8f2;
    --surface: #ffffff;
    --surface-elevated: #f5f0e6;
    --border: rgba(30, 30, 50, 0.08);
    --text: #1a1814;
    --text-dim: #7a7468;
    --accent: #b8860b;
    --accent-dim: rgba(184, 134, 11, 0.08);
  }
}
```

### Paper/Ink

Warm cream `#faf7f5` background, terracotta/sage accents, informal feel.

```css
:root {
  --font-body: 'Plus Jakarta Sans', system-ui, sans-serif;
  --font-mono: 'Azeret Mono', 'SF Mono', monospace;
  --bg: #faf6f0;
  --surface: #ffffff;
  --surface-elevated: #fffdf5;
  --border: rgba(60, 40, 20, 0.08);
  --text: #2c2a25;
  --text-dim: #7c756a;
  --accent: #c2410c;
  --accent-dim: rgba(194, 65, 12, 0.08);
}
@media (prefers-color-scheme: dark) {
  :root {
    --bg: #1c1916;
    --surface: #262220;
    --surface-elevated: #3a3430;
    --border: rgba(200, 180, 160, 0.08);
    --text: #f0e8dc;
    --text-dim: #a09888;
    --accent: #e85d2a;
    --accent-dim: rgba(232, 93, 42, 0.1);
  }
}
```

### Terminal Mono

Green/amber on near-black, monospace everything. Developer-native.

```css
:root {
  --font-body: 'Geist Mono', 'SF Mono', Consolas, monospace;
  --font-mono: 'Geist Mono', 'SF Mono', Consolas, monospace;
  --bg: #0a0e14;
  --surface: #12161e;
  --surface-elevated: #222836;
  --border: rgba(80, 250, 123, 0.06);
  --text: #c8d6e5;
  --text-dim: #5a6a7a;
  --accent: #50fa7b;
  --accent-dim: rgba(80, 250, 123, 0.08);
}
@media (prefers-color-scheme: light) {
  :root {
    --bg: #f4f6f8;
    --surface: #ffffff;
    --border: rgba(0, 80, 40, 0.08);
    --text: #1a2332;
    --text-dim: #5a6a7a;
    --accent: #0d7a3e;
    --accent-dim: rgba(13, 122, 62, 0.08);
  }
}
```

Background: faint dot grid. Everything monospace. CRT glow optional (CSS only, no animation).

### Swiss Clean

White, geometric sans, single bold accent, visible grid. Minimal and precise.

```css
:root {
  --font-body: 'DM Sans', system-ui, sans-serif;
  --font-mono: 'Fira Code', 'SF Mono', monospace;
  --bg: #ffffff;
  --surface: #f8f8f8;
  --surface-elevated: #ffffff;
  --border: rgba(0, 0, 0, 0.08);
  --text: #111111;
  --text-dim: #666666;
  --accent: #0055ff;
  --accent-dim: rgba(0, 85, 255, 0.06);
}
@media (prefers-color-scheme: dark) {
  :root {
    --bg: #111111;
    --surface: #1a1a1a;
    --surface-elevated: #2a2a2a;
    --border: rgba(255, 255, 255, 0.08);
    --text: #f0f0f0;
    --text-dim: #888888;
    --accent: #3b82f6;
    --accent-dim: rgba(59, 130, 246, 0.08);
  }
}
```

### Warm Signal

Cream paper, bold sans, terracotta accents. Confident, modern. Same as Paper/Ink but bolder.

Uses Plus Jakarta Sans + Azeret Mono, terracotta `#c2410c` accent. See Paper/Ink preset above — Warm Signal is the same palette with higher contrast headings and stronger section dividers.

---

## Typography Rules

### Font Pairings (12 options — rotate, never repeat consecutively)

| Body / Headings | Mono / Labels | Feel | Use for |
|---|---|---|---|
| DM Sans | Fira Code | Friendly, developer | Blueprint, technical docs |
| Instrument Serif | JetBrains Mono | Editorial, refined | Plan reviews, decision logs |
| IBM Plex Sans | IBM Plex Mono | Reliable, readable | Architecture diagrams |
| Bricolage Grotesque | Fragment Mono | Bold, characterful | Data tables, dashboards |
| Plus Jakarta Sans | Azeret Mono | Rounded, approachable | Status reports, audits |
| Outfit | Space Mono | Clean geometric, modern | Flowcharts, pipelines |
| Sora | IBM Plex Mono | Technical, precise | ER diagrams, schemas |
| Crimson Pro | Noto Sans Mono | Scholarly, serious | RFC reviews, specs |
| Fraunces | Source Code Pro | Warm, distinctive | Project recaps |
| Geist | Geist Mono | Vercel-inspired, sharp | Modern API docs |
| Red Hat Display | Red Hat Mono | Cohesive family | System overviews |
| Libre Franklin | Inconsolata | Classic, reliable | Data-dense tables |

The first 5 pairings are recommended for most use cases.

### Load via Google Fonts

```html
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=Fira+Code:wght@400;500&display=swap" rel="stylesheet">
```

Always use `display=swap` for fast rendering. Include system font fallback in `font-family` stack.

### Typography by Content Voice

For prose-heavy pages, match fonts to content voice:

| Voice | Fonts | Best For |
|-------|-------|----------|
| Literary / Thoughtful | Literata, Lora, Newsreader, Merriweather | Essays, personal posts, long-form |
| Technical / Precise | IBM Plex Sans + Mono, Geist + Geist Mono | Documentation, READMEs, API refs |
| Bold / Contemporary | Bricolage Grotesque, Space Grotesk, DM Sans | Product pages, announcements |
| Minimal / Focused | Source Serif 4 + Source Sans 3, Karla + Inconsolata | Tutorials, focused reading |

---

## Quality Checklist

Before delivering any HTML page:

- **Squint test**: Blur your eyes. Can you still perceive hierarchy? Are sections visually distinct?
- **Swap test**: Would replacing fonts and colors with a generic dark theme make this indistinguishable? If yes, push the aesthetic further.
- **Theme toggle (MANDATORY)**: Toggle button MUST be present (first child of `<body>`). Switch between light and dark using the button. Both themes should look intentional, not broken. See `html-css-patterns.md` → "Theme Toggle Button".
- **Information completeness**: Does the page actually convey what was asked? Pretty but incomplete is a failure.
- **No overflow**: Resize the browser. No content should clip or escape its container. Every grid/flex child needs `min-width: 0`. Side-by-side panels need `overflow-wrap: break-word`.
- **Mermaid zoom controls**: Every `.mermaid-wrap` must have zoom controls (+/−/reset/expand), Ctrl/Cmd+scroll zoom, click-and-drag panning, and click-to-expand. See `html-css-patterns.md`.
- **File opens cleanly**: No console errors, no broken font loads, no layout shifts.

---

## Depth Tier System

Vary card depth to signal importance. Hero sections dominate; reference sections stay compact.

```css
/* Default — flat, no shadow */
.ve-card {
  background: var(--surface);
  border: 1px solid var(--border);
  border-radius: 10px;
  padding: 16px 20px;
}

/* Elevated — KPIs, key sections */
.ve-card--elevated {
  background: var(--surface-elevated);
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08), 0 1px 2px rgba(0, 0, 0, 0.04);
}

/* Recessed — code blocks, secondary content */
.ve-card--recessed {
  background: color-mix(in srgb, var(--bg) 70%, var(--surface) 30%);
  box-shadow: inset 0 1px 3px rgba(0, 0, 0, 0.06);
}

/* Hero — executive summaries, focal elements */
.ve-card--hero {
  background: color-mix(in srgb, var(--surface) 92%, var(--accent) 8%);
  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.08), 0 1px 3px rgba(0, 0, 0, 0.04);
  border-color: color-mix(in srgb, var(--border) 50%, var(--accent) 50%);
}
```

Rule: Don't make everything elevated — when everything pops, nothing does.

---

## Content-Type Routing

When deciding how to render content:

| Content type | Approach | Why |
|---|---|---|
| Architecture (text-heavy) | CSS Grid cards + flow arrows | Rich card content needs CSS control |
| Architecture (topology-focused) | **Mermaid** | Visible connections need automatic edge routing |
| Flowchart / pipeline | **Mermaid** | Automatic node positioning |
| Sequence diagram | **Mermaid** | Lifelines need automatic layout |
| Data flow | **Mermaid** with edge labels | Connections need auto-routing |
| ER / schema diagram | **Mermaid** | Relationship lines between entities |
| State machine | **Mermaid** | State transitions with labeled edges |
| Mind map | **Mermaid** | Hierarchical branching |
| Class diagram | **Mermaid** | Inheritance lines with auto-routing |
| C4 architecture | **Mermaid** `graph TD` + `subgraph` | Native C4 hardcodes its own styles |
| Data table | HTML `<table>` | Semantic markup, accessibility, copy-paste |
| Timeline | CSS (central line + cards) | Simple linear layout |
| Dashboard | CSS Grid + Chart.js | Card grid with embedded charts |
| Simple A→B→C flows in slides | CSS Pipeline cards | Mermaid renders too small for simple linear flows |

---

## AI Image Generation

If `/ck:ai-multimodal` skill is available and image generation is appropriate, it can be used for hero banners, conceptual illustrations, and decorative accents that establish the page's visual tone.

**When to use:** Hero banners, conceptual illustrations for abstract systems, educational diagrams benefiting from artistic rendering, decorative accents reinforcing the aesthetic.

**When to skip:** Anything Mermaid or CSS handles well. Generic decoration that doesn't convey meaning. Data-heavy pages where images would distract. Always degrade gracefully — the page should stand on its own with CSS and typography alone.

For `--slides` presentation-grade output, consider invoking `/ck:ui-ux-pro-max` for richer style selection and distinctive font/palette pairing.