@hienlh/ppm 0.9.80 → 0.9.81

package/.opencode/skills/preview/references/html-design-guidelines.md

@@ -0,0 +1,393 @@
+# 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.