design-htmlby Garry Tan

Design HTML Skill.

A Claude Code and Codex skill for UI design: produces production-quality HTML/CSS from an agreed design direction.

Web & UI
HTML

garrytan/gstack · design-html/SKILL.mdSKILL.md

--- name: design-html description: Design finalization: generates production-quality Pretext-native HTML/CSS. (gstack) --- ## When to invoke this skill ## Confusion Protocol ## Claimed Limitations Need Evidence ## Continuous Checkpoint Mode ## Context Health (soft directive) ## Question Tuning (skip entirely if QUESTION_TUNING: false)

Front matter and section headings read from the upstream file on 2026-09-14 · 54,976 characters in full

01 What it does

What the design-html Skill Does in Claude Code and Codex

Summary, workflow and outputs, all read from the skill's SKILL.md.

From the SKILL.mdRead 2026-09-14 · not a recorded run

In the Skill's Own Terms

Generates production-quality HTML/CSS with Pretext-native text layout where text actually reflows, heights compute dynamically, and layouts adapt on resize. Works from approved mockups (/design-shotgun), CEO plans (/plan-ceo-review), design review context, or user descriptions. Routes to the correct Pretext API tier based on design complexity (simple layouts use prepare + layout; chat UIs use prepareWithSegments + walkLineRanges; editorial spreads use layoutNextLine for text-around-obstacles).

30KB overhead, zero dependencies. Produces self-contained HTML files (vendored Pretext inlined) or framework components (React/Svelte/Vue). Defaults to vanilla HTML with live reload server for immediate browser preview. Never lorem ipsum—extracts real content from mockups or generates realistic text from plans.

What it produces

Self-contained HTML file with vendored Pretext inlined, CSS custom properties from tokens, semantic HTML5, contenteditable + MutationObserver for live editing, ResizeObserver for relayout on resize, saved to ~/.gstack/projects/$SLUG/designs/<screen-name>-YYYYMMDD/finalized.html
Framework component file (React TSX/JSX, Svelte, Vue) with Pretext imports added to project dependencies, saved to ~/.gstack/projects/$SLUG/designs/<screen-name>-YYYYMMDD/finalized.[tsx|svelte|vue]
finalized.json metadata alongside HTML carrying source_mockup path, source_plan path, mode (approved-mockup/plan-driven/freeform/evolve), pretext_tier, framework choice, iteration count, date, screen name, branch
DESIGN.md file in open DESIGN.md format if user accepts extraction offer, containing CSS custom properties, font families, color palette, spacing scale, border radius, shadow values extracted from generated HTML

See the example prompt ↗

How It Works

01
Detect Design Context and Route
Checks for approved.json from /design-shotgun, CEO plans, design variants, or DESIGN.md tokens.
02
Extract Implementation Spec
If design binary available, runs prompt command on approved PNG to extract colors, typography, layout structure via GPT-4o vision.
03
Smart Pretext API Routing
Classifies design into tier: simple layouts use prepare + layout for resize-aware heights; card grids use same for self-sizing; chat UIs use prepareWithSegments + walkLineRanges for tight-fit bubbles; editorial spreads use layoutNextLine for text around obstacles.
04
Generate Pretext-native HTML
Writes single file with vendored Pretext inlined (or CDN fallback), CSS custom properties from tokens, semantic HTML5, contenteditable + MutationObserver for live editing, ResizeObserver for relayout on resize, real content extracted from mockup or plan.
05
Slop Gate Scan Before Preview
If design detector available, scans finalized page once for AI-slop patterns (purple gradients, identical card grids, generic CTAs not from mockup).

02 Find your fit

When to Use the design-html Skill

Use the design-html skill in Claude Code or Codex when the job is UI design of this kind. Fit and limits below are taken from the skill's own file.

Good Fit

Creating a dashboard, listing page, or card grid where cards need to self-size based on their content without hardcoded heights
Implementing a chat or messaging UI where bubbles need to shrinkwrap tightly to text and compute minimum width correctly
Finalizing a design after /design-shotgun approved mockup, /plan-ceo-review product strategy, or /plan-design-review context exists
Building an editorial spread, blog layout, or content-heavy page where text needs to flow around obstacles or images dynamically

Know the Boundaries

Projects requiring placeholder content or lorem ipsum—skill always generates real content extracted from mockups, plans, or user descriptions
Automated runs without human review—design detector install offer and refinement loop require user decisions via AskUserQuestion

What to Provide

Approved design mockup PNGPath to approved variant from /design-shotgun saved in approved.json, or user-provided PNG path.
CEO plan or design review notesMarkdown file from /plan-ceo-review or /plan-design-review containing product vision, UI requirements, user flows, target audience, visual feel, content structure.
DESIGN.md tokensRepository's design system file with brand colors, font family, spacing scale, border radius, shadow values.
User description for freeform modeWhen no mockup or plan exists, user provides purpose/audience, visual feel (dark/light, playful/serious, dense/spacious), content structure, reference sites.
Prior finalized.html for evolve modeExisting finalized HTML from previous session.

03 Inside the skill

Rules the design-html Skill Gives Claude Code and Codex

6 concrete instructions, defaults and limits the SKILL.md sets for the agent — the part of the file that changes the result.

Always Use Pretext for Text Layout
Even if the design looks simple, Pretext ensures correct height computation on resize. The overhead is 30KB. Every page benefits.
Real Content Only, Never Placeholder Text
When a mockup exists, extract text from it. In plan-driven mode, use content from the plan. In freeform mode, generate realistic content based on user description.
Source of Truth Fidelity Over Code Elegance
When an approved mockup exists, pixel-match it. If that requires width: 312px instead of a CSS grid class, that's correct.
Surgical Edits in Refinement Loop, Never Regenerate
Use Edit tool to make targeted changes, not Write tool to regenerate entire file. The user may have made manual edits via contenteditable that must be preserved.
One Page per Invocation
For multi-page designs, run /design-html once per page. Each run produces one HTML file.
AI-slop Blacklist Enforced by Default
Never include purple/blue gradients, cream-and-serif palette, gradient text, generic 3-column feature grids, identical card grids, center-everything layouts, kickers above headings, hero metric rows, decorative blobs, glowing edges, stock photo placeholders, generic CTAs, rounded-corner cards with drop shadows, emoji decoration, generic testimonials, or cookie-cutter split heroes—unless approved mockup contains one, DESIGN.md blesses it, or user explicitly asks with tradeoff stated once.

04 Put it to work

Install design-html in Claude Code or Codex

One npx skills add command, then a first task in your agent and a checklist for the result.

Add design-html to Claude Code, Codex or Your Agent

Run in your project; the installer asks which agent to add it to.

Terminal

npx skills add https://github.com/garrytan/gstack --skill design-html

Generic skills CLI form for design-html/SKILL.md; the repository may document its own path.

Give the Skill a First UI Design Task

Written in the skill's own terms; replace the bracketed parts with your material.

Starter prompt

Finalize the design for our [product name] landing page. I have an approved mockup from /design-shotgun at [path to approved.json]. The page needs a hero section with dynamic text that reflows on resize, a 3-card feature grid where cards self-size based on content, and a pricing table. Use our brand colors from DESIGN.md and make sure all text is editable in the browser so I can tweak copy live. Output as vanilla HTML first so I can preview immediately, then I'll ask for a React component version once the design is locked.

Source: written from the SKILL.md in the skill's own terms.

Check the First Result

What the SKILL.md itself says a correct result looks like:

Live reload server started at http://localhost:PORT/finalized.html so user can resize window to verify text reflows dynamically and click any text to verify contenteditable layout recomputes instantly
Approved mockup PNG shown inline for visual comparison during refinement loop if one exists, otherwise user feedback during loop is source of truth for plan-driven or freeform modes
Fonts loaded confirmation via document.fonts.ready gate before first prepare() call to ensure text metrics are correct for Pretext layout computation
User confirms 'done' / 'ship it' / 'looks good' / 'perfect' in refinement loop after testing resize behavior and live text editing, max 10 iterations before offering to continue or call done

In OpenDesign import design-html from its SKILL.md link: Plugins → Add → Skill → Import from link, then pick it in the top bar.

Download OpenDesign Read the quickstart

05 Open source, traceable

Source, License and Verification

Where this page's facts come from, and when they were last checked.

Author: Garry Tan
Repository: github.com/garrytan/gstack Branch main
Skill file: design-html/SKILL.md Content checksum recorded at verification; commit 71f6048
License: MIT From LICENSE.
Repository stars: 132,921 GitHub snapshot taken 2026-09-14 for the whole garrytan/gstack repository, which contains 7 skills in this catalog. Not a rating or usage count for design-html.
Verified by OpenDesign: 2026-09-14 Source file, path, license text and star count were checked. Not bundled in OpenDesign main (checked 2026-08-28); a live run has not been recorded on this page.

Inside the SKILL.md

When to invoke this skillWorks with approved mockups, CEO plans, design review context, or user descriptions for production HTML/CSS
Preamble (run first)Runs gstack-skill-start, reads STATUS lines, handles degraded mode, follows GSTACK_INSTRUCTION blocks for onboarding/consent
Plan Mode Safe OperationsAllowed operations in plan mode: codex exec/review, writes to ~/.gstack/, plan file, open for artifacts
Skill Invocation During Plan ModeSkill instructions are executable not reference; AskUserQuestion satisfies end-of-turn; ExitPlanMode only after workflow completes
AskUserQuestion FormatTool resolution branches on SESSION_KIND; spawned auto-chooses recommended; Conductor uses prose; failure fallback handling
Artifacts Sync (skill start)Acts on skill-start output: GBrain hint, ARTIFACTS_SYNC health, one-time privacy consent gate via GSTACK_INSTRUCTION
Model-Specific Behavioral Patch (claude)Todo-list discipline, think before heavy actions, dedicated tools over Bash—preferences subordinate to skill instructions
VoiceGStack voice: lead with point, concrete details, tie choices to user outcomes, direct about quality, bounded closers
Context RecoveryRecovers recent artifacts, reviews, timeline, decisions, latest checkpoint; suggests next skill if RECENT_PATTERN implies one
Writing StyleGloss curated jargon first use, frame questions in outcomes, short sentences active voice, skip if EXPLAIN_LEVEL: terse
Completeness Principle — Boil the OceanAI makes completeness cheap; recommend full coverage; Completeness: X/10 when options differ in coverage
Confusion ProtocolFor high-stakes ambiguity STOP, name it, present 2-3 options with tradeoffs, ask—not for routine coding

The Skill's Own Description

“Design finalization: generates production-quality Pretext-native HTML/CSS. (gstack)”

Front-matter description from SKILL.md. The full file is about 54,976 characters. Read the full file on GitHub.

06 Before you install

Questions About the design-html Skill

Answers come from the SKILL.md as read on 2026-09-14, not from a recorded run.

Does this work with my React/Svelte/Vue project or only vanilla HTML?

Both. Step 2.5 detects your framework in package.json and asks whether you want vanilla HTML (self-contained preview file, recommended for first pass) or a framework-native component with Pretext hooks. Vanilla defaults if no framework detected. For framework output you choose TypeScript or JavaScript.

Design HTML

Run design-html on a Real UI Design Task.

Download OpenDesign, import design-html from its SKILL.md link, paste the prompt above, and read the plan before the result.

Download OpenDesign Browse all skills