renolation/english
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
english/.opencode/skills/preview/references/html-design-guidelines.md
renolation 10d660cbcb init
2026-04-12 01:06:31 +07:00

15 KiB
Raw Permalink Blame History

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.

: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.

: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.

: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.

: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.

: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

<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.

/* 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.