html-generator

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: html-generator
description: Use when generating branded HTML pages and components from a design system. Creates standalone HTML components and composes them into full pages with embedded CSS, responsive design, and brand integration.
version: 2.9.1
allowed-tools: Read, Write, Glob, Grep, Bash
user-invocable: false
---

# HTML Generator Skill

Create distinctive, branded HTML pages and standalone components from a design system.

## The Critical Understanding

HTML page creation is **design-system-driven composition**, not template filling. Each component is a standalone design artifact that works independently AND as part of a composed page. Every section should feel crafted by a senior designer — intentional, distinctive, unforgettable.

- **What you receive**: a design system (canvas-philosophy.md + design-system.md) with design tokens, component catalog, and brand identity.
- **What you create**: standalone HTML components + a composed single-file HTML page.
- **The standard**: work that makes the viewer stop scrolling. Bold, distinctive, never generic.

## When Called

Invoked by `/html-page` and `/html-page-quick`. Receives: design system files (canvas-philosophy.md + design-system.md), brand philosophy (brand-philosophy.md or sub-identity overrides), component selections, any reusable components from `components/`, content, and style constraints from `references/web-style-constraints.md`.

## Two Output Modes

- **Component generation** — individual standalone components: a complete HTML fragment with embedded `<style>`, design tokens via CSS custom properties, prop/slot metadata comments, viewable independently with token fallbacks.
- **Page composition** — assemble components into one `.html` file: shared `:root` tokens, responsive wrapper with meta viewport, components in order with consistent spacing, nav top + footer bottom, single deduplicated `<style>` block, minimal `<script>` only when the style requires it.

File format, boilerplate, and the full component/page structure are in `references/html-technical.md`.

## Part 1: Design Thinking Process

Before writing any HTML, internalize the design system:

0. **Verify brand exists** — if no `design-system.md` in the project, STOP and suggest `/design-html` first. If no `brand-philosophy.md`, suggest `/brand-extract` first. Never proceed with default/example values.
1. **Read the canvas philosophy** — absorb its aesthetic movement, not just rules.
2. **Load design tokens** — colors, fonts, spacing become CSS custom properties.
3. **Understand the style** — read enforcement blocks from `references/web-style-constraints.md`.
4. **Consider the content** — what is the page's purpose? Who sees it? What should they feel?
5. **Plan differentiation** — what makes THIS page visually memorable vs. generic?

### The Differentiation Test

Before generating, ask: "Could this page belong to any brand?" If yes, push harder. Then ask: **"What is the ONE thing someone will remember about this page?"** — a dramatic type scale, a surprising color moment, an unexpected layout break. If you cannot name it, the design is not distinctive enough.

Incorporate the canvas philosophy's unique movement and spirit, unexpected layout choices (asymmetry, overlap, grid-breaking), typography as art, atmosphere (gradient meshes, noise, patterns, depth shadows), and brand personality through micro-interactions.

### Intentionality Over Intensity

**Match implementation complexity to the aesthetic vision.** Maximalist designs need elaborate code with extensive animation and layered effects; minimalist or refined designs need restraint, precision, and careful spacing/typography. The key is intentionality, not intensity — a Swiss design executed with mathematical precision is as powerful as a Memphis design executed with wild energy. Never apply "bold" uniformly; calibrate to the style.

## Part 2: Brand Integration

### Design Tokens → CSS Custom Properties

Read the project's `design-system.m