@hienlh/ppm 0.9.81 → 0.9.83

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

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