102.7K+Download
Skip to the usage guide
design-htmlby Garry Tan

Design HTML Skill.

A skill for translating an agreed design direction into HTML or framework components, with browser-based refinement.

  • Web & UI
  • HTML
Download OpenDesignView usage guide
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 HTML/CSS or framework components using Pretext for computed text layout. It starts from an approved mockup, a plan, design-review context or a user description, and routes to different Pretext APIs for simple layouts, chat bubbles and editorial spreads.

Vanilla output inlines a vendored Pretext bundle when available, but uses a CDN fallback when it is missing and may load external fonts. Framework output adds Pretext as a project dependency. The source includes local preview and refinement steps; production readiness still requires review in the target project.

What it produces

  • A finalized.html with Pretext, design tokens, semantic structure, editable text and resize-aware layout. Pretext is inlined when the vendored bundle exists; otherwise the file uses a CDN. External font links may remain.
  • 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

  1. 01
    Detect Design Context and Route

    Checks for approved.json from /design-shotgun, CEO plans, design variants, or DESIGN.md tokens.

  2. 02
    Extract Implementation Spec

    If design binary available, runs prompt command on approved PNG to extract colors, typography, layout structure via GPT-4o vision.

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

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

  5. 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
  • The workflow depends on gstack-specific tooling and reference files, with fallback paths for unavailable design or browser tools. Importing SKILL.md alone does not establish that those dependencies are installed.

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.

  1. Always Use Pretext for Text Layout

    The source requires Pretext for text layout and describes an approximately 30 KB overhead. Verify reflow and computed heights in the actual output; the requirement is not a guarantee that every layout will be correct.

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

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

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

  5. One Page per Invocation

    For multi-page designs, run /design-html once per page. Each run produces one HTML file.

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

Editorial starter example based on the source workflow; not a recorded run.

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 check your installed version’s skill list and supported tools. If this skill is absent, consult the current import guide and the upstream setup instructions. The source review is not a live compatibility test.

Download OpenDesignRead 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

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

Start with the example task above, supply the listed inputs and check the required tools. Review the output against the checklist before using it in a project.

Download OpenDesignBrowse all skills
Terminal
npx skills add https://github.com/garrytan/gstack --skill design-html