Web Design Skill

繁體中文 · English

A visual-first Agent Skill for designing and reconstructing high-quality websites with explicit art direction, approved visual targets, structured decomposition, asset locking, responsive continuity, and render-based QA.

Current version: v1.6.1

Author: max0821
Official source: https://github.com/max0821/web-design-skill
License: MIT
Commercial use: Allowed

This is a community-built Skill and is not an official OpenAI Skill.

What's new in v1.6.1

This patch makes visual closure an explicit final step. For the latest visual state, the agent must produce fresh renders at every required viewport and compare the complete page against the approved target again, whether or not a fix loop occurred. The pass includes typography, borders/frames/dividers, spacing/rhythm, and regression review. Any later visual change invalidates that evidence and reopens the final gate.

Lint, type checks, source inspection, old screenshots, or a comparison made before the latest fix cannot substitute for Final Re-comparison.

If latest-state renders are missing or stale, the task remains incomplete. The agent keeps Final Re-comparison blocked, records the unverified capability in reason/evidence, and cannot say the work is finished or ready to close.

The same 1.6.1 release now also aligns the written contract with machine validation: manifest schema 2 adds completion conditions, required viewports, target/revision/time identity, structured render evidence, non-waivable completion gates, and correct Semantic Versioning precedence for prereleases.

What changed in v1.6.0

This release incorporates findings from a real reference-to-code implementation where isolated assets passed review but their final assembly still drifted:

• Typography Feasibility Gate — verify an implementation-ready font, exact strings, glyph coverage, licensing, loading, fallbacks, and multilingual pairing before approving typography-led targets; search Google Fonts first when no brand font is required.
• Optical glyph exceptions — correct one narrow or wide glyph locally instead of distorting the tracking of every label.
• Persistent Design Element Sheet — keep the sheet inspectable and synchronize accepted crop, edge cleanup, optical, role, and construction changes through implementation and QA.
• Assembly Contract — lock each significant element's role, scope, instance count, transforms, topology, shared anchors, safe areas, collisions, and responsive behavior before coding.
• Geometry Integrity Gate — measure reference coverage, containment, clearance, border connectivity, alignment, and collisions after desktop/mobile rendering.
• Asset hygiene — distinguish dirty source assets from CSS treatment problems and repair the smallest non-destructive layer first.

See CHANGELOG.md for the complete version history.

Demo: generated concept → implemented website

This real project shows the difference between asking Codex to generate a visual directly and using web-design to carry an approved direction into an implemented website.

A. Visual generated directly by Codex	B. Website implemented with the web-design Skill

Image A establishes the visual direction. Image B is the rendered website result produced after the Skill workflow translated that direction into implementation-ready typography, live content, reusable elements, assembly rules, responsive structure, and visual QA.

The point is not simply which screenshot looks better. The Demo shows the Skill's actual job: turning a strong visual concept into a website that can be implemented, inspected, corrected, and verified without discarding the approved design language. Values shown in the screenshots are demonstration content and are not presented here as production benchmark claims.

Project vision

This repository is intended to grow from a personal introduction page into an AI-guided learning project. The page introduces the author, while a left-side project navigator opens focused chat assistants for topics such as GitHub, analytics, conversion design, and web design.

Each assistant is backed by a reusable SKILL: a set of practical rules, workflows, boundaries, and quality checks. The goal is for a learner to move from reading an introduction, to asking the right question, to making a change in their own project, and finally to verifying the result. After following the project, the learner should be able to turn their own introduction page into a project with topic-specific AI helpers.

The Traditional Chinese README contains the fuller product concept and example sidebar structure: README.zh-TW.md.

Distribution

web-design follows the Agent Skills open format and is prepared for skill-only plugin submission. The GitHub repository remains the canonical public source. See SUBMISSION.md for copy-ready listing material.

Why this exists

Most AI website workflows jump directly from a text brief to HTML. That is fast, but it often produces generic layouts and a large gap between an attractive visual concept and the final implementation.

web-design inserts a structured design-to-code stage between concept and implementation:

Understand
→ Progressive Clarification
→ Lock Scope
→ Locked Execution TODO
→ Art Direction
→ Typography Feasibility
→ Visual Exploration
→ User Reaction
→ Approved Visual Target
→ Decompose
→ Coherence Contract
→ Resolve Assets
→ Design Element Sheet
→ Assembly Contract
→ Asset QA / Lock
→ Implement
→ Render
→ Geometry Integrity
→ Compare
→ [Fix 1–3 → Re-render → Geometry Integrity → Compare]*
→ Final Re-comparison
→ Complete

The core idea is simple: treat the approved visual concept as a design specification, not as disposable inspiration.

What makes it different

Progressive design discovery

Instead of front-loading a long questionnaire, the Skill asks only the highest-impact unresolved question, usually with 2–4 concrete options.

Visual-first exploration

For visually important marketing pages, redesigns, and brand-heavy work, the Skill can establish the visual direction before committing to final frontend code.

Approved Visual Target

Once the user approves a concept, that target becomes the primary visual source of truth. The Skill should not casually re-roll the entire page later.

Four-way decomposition

Before implementation, the approved target is decomposed into four implementation artifacts:

• Block Map — page sections and vertical flow.
• Layer Map — visual stack, overlaps, imagery, UI overlays, decoration, and z-order.
• Text Map — semantic copy, text hierarchy, emphasis, wrapping, and live text rules.
• Geometry Map — proportions, anchors, bounding regions, crop regions, and negative space.

A cross-cutting Token Map acts as the coherence contract shared by all four maps.

Locked Execution TODO

Once the page job, content model, scope, and current direction are clear enough to act, the Skill immediately exposes an evidence-backed TODO. Every required item has a deliverable, completion condition, and evidence; exactly one item stays in progress while work remains, zero remain at completion, and changed design inputs reopen affected downstream work.

Asset Resolution Plan

Each significant visual layer is classified before implementation:

• live HTML/UI
• CSS or SVG
• existing/cropped asset
• clean local regeneration
• omit or simplify

This keeps text, buttons, metrics, and exact UI out of generated raster images whenever possible.

Design Element Sheet + Asset Production Gate

For screenshot/reference-to-code work, the Skill prepares a separate element sheet before final implementation. It can include verified typography specimens (A–Z, a–z, 0–9, punctuation, and multilingual samples), icons, arrows, lines, frames, HUD parts, patterns, textures, and decorative motifs. An Asset Manifest maps each significant element to its source, production medium, output, QA evidence, and lock state.

Image-generated lettering remains reference-only until verified. Semantic text stays live HTML, simple geometry prefers CSS/SVG, and complex raster assets are exported individually rather than improvised from contaminated full-page crops.

The sheet remains an active QA surface after coding starts. An Assembly Contract records how isolated elements become a composition: semantic role, instance count, mirrored/rotated derivatives, path connectivity, shared coordinates, z-order, safe areas, collision constraints, and responsive changes. It supplements the Layer and Geometry Maps rather than becoming a fifth map.

Local regeneration + asset locking

If one asset is unusable, regenerate the smallest useful asset instead of redrawing the entire approved page. Once accepted, the asset is locked so later generations do not drift the target.

Visual coherence

The Skill explicitly checks:

• typography system
• visual grammar
• design tokens
• asset style contracts
• composition continuity
• focal hierarchy and attention budget
• image/text relationship
• motion language
• responsive continuity
• brand drift
• coherence QA

Render-based QA

The Skill reviews the rendered page, not source code alone. Before visual comparison, the Geometry Integrity Gate measures reference coverage, content containment, frame clearances, line connectivity, shared alignment, and decorative collisions. Each refinement pass fixes only the 1–3 dominant mismatches with the largest perceptual impact. A fresh Final Re-comparison then closes typography, borders, spacing, and full-page regression for the latest visual state, even when no fix was required.

Design-to-code model

flowchart TD
    A[Brief / Existing Site / Reference] --> R[Lock Page Job and Scope]
    R --> T[Locked Execution TODO]
    T --> B[Art Direction]
    B --> U[Typography Feasibility]
    U --> C[Visual Exploration]
    C --> D{User Approved?}
    D -- No --> C
    D -- Yes --> E[Approved Visual Target · LOCK]
    E --> F[Block Map]
    E --> G[Layer Map]
    E --> H[Text Map]
    E --> I[Geometry Map]
    F --> J[Coherence Contract / Token Map]
    G --> J
    H --> J
    I --> J
    J --> K[Asset Resolution Plan]
    K --> S[Design Element Sheet / Asset Manifest]
    S --> V[Assembly Contract]
    S --> L[Local Asset Generation / Extraction]
    V --> N[Asset QA · LOCK]
    L --> N
    N --> M[HTML / CSS / SVG]
    M --> O[Render]
    O --> W[Geometry Integrity]
    W --> P[Visual Comparison]
    P --> X{Material Mismatch?}
    X -- Yes --> Q[Fix 1–3 Dominant Mismatches]
    Q --> O
    X -- No --> Y[Final Re-comparison]
    Y -- Mismatch --> Q
    Y -- Pass --> Z[Complete]

Loading

Repository structure

web-design-skill/
├── README.md
├── README.zh-TW.md
├── LICENSE
├── CHANGELOG.md
├── SUBMISSION.md
├── submission/
│   ├── listing.en.md
│   ├── listing.zh-TW.md
│   └── review-notes.md
├── dist/
│   └── web-design-skill-v1.6.1.zip
└── web-design/
    ├── SKILL.md
    ├── README.md
    ├── README.zh-TW.md
    ├── LICENSE
    ├── agents/
    │   └── openai.yaml
    ├── assets/
    │   └── design-gates.template.json
    ├── scripts/
    │   ├── check_design_gates.py
    │   └── check_version.py
    └── references/
        ├── approved-target-and-composition.md
        ├── art-direction-and-exploration.md
        ├── decomposition-and-assets.md
        ├── design-system.md
        ├── execution-and-production-gates.md
        ├── render-fidelity-contract.md
        ├── responsive-and-interaction.md
        ├── visual-coherence-contract.md
        ├── visual-qa.md
        └── workflow-examples.md

Install

Install with ChatGPT

Paste this repository URL into ChatGPT:

https://github.com/max0821/web-design-skill

Then say:

Install the Agent Skill in /web-design from this repository.
Preserve the original files, directory structure, and version.
Ask me to confirm before installation.

On ChatGPT environments that support Skills and can read public GitHub repositories, ChatGPT may be able to prepare the Skill directly from the repository. Installation can still require an explicit confirmation step, and this flow may not be available on every account or client.

From GitHub source

If direct installation from the repository is not available:

1. Clone or download this repository.
2. Package the web-design/ folder as a ZIP if your Skills interface requires an archive.
3. Open the Skills interface in ChatGPT or another compatible Agent Skills client.
4. Import/upload the Skill.
5. Select web-design in a new chat and test it.

The actual Skill folder is web-design/. Its folder name intentionally matches name: web-design in SKILL.md.

Quick version test

After installing, ask:

Do not perform design work.

Based only on the currently loaded web-design Skill, answer:
1. What is metadata.version?
2. What four Maps are created after an Approved Visual Target?
3. What is the Asset Resolution Plan?
4. If one approved visual asset is dirty, should you regenerate the whole page or only that local asset?
5. How does the Skill prevent target drift?
6. Does design discovery use a long questionnaire or progressive option-based clarification?
7. When must the Locked Execution TODO appear, and what evidence does each item require?
8. What must the Design Element Sheet and Asset Manifest contain before implementation?
9. What does the Assembly Contract record, and why is it not a fifth Map?
10. What must pass in the Geometry Integrity Gate before completion?
11. When must Final Re-comparison run, and which three visual areas require explicit closure?

For v1.6.1, expected fingerprints include:

• metadata.version: 1.6.1
• Startup Receipt with local/remote version status and confirmed capabilities
• FULL / LITE workflow classification and phase gates
• read-only version check through version.json
• evidence-backed Locked Execution TODO with one item in progress
• Block / Layer / Text / Geometry Maps
• Asset Resolution Plan
• Design Element Sheet and Asset Manifest before final implementation
• persistent Element Sheet synchronization
• Assembly Contract before implementation
• Geometry Integrity after every required viewport render
• Final Re-comparison for the latest visual state, even when no fix occurred
• explicit typography, border, spacing, and regression closure evidence
• schema 2 completion conditions, required viewports, revision/time freshness, and non-waivable final gates
• typography feasibility and local optical glyph exceptions
• optional machine validation through check_design_gates.py
• local regeneration
• asset locking
• progressive option-based clarification
• Typography System / Visual Grammar / Token Map / Asset Style Contract
• author/license metadata

Quality target

The Skill treats quality as four connected concerns:

• Design Intent — the page has a deliberate visual and business thesis.
• Visual Fidelity — implementation preserves the approved target.
• Visual Coherence — typography, assets, surfaces, composition, motion, and responsive states belong to one design language.
• Implementation Integrity — the result remains semantic, maintainable, accessible, and compatible with the user's architecture.

License

Copyright © 2026 max0821.

This project is licensed under the MIT License. Commercial use, modification, redistribution, and private use are allowed, provided that the original copyright and MIT License notice are retained.

See LICENSE for the full license text.

Versioning

The visible version is synchronized in four places:

1. SKILL.md → metadata.version
2. SKILL.md → visible Version: line near the top
3. agents/openai.yaml → interface.short_description
4. version.json → canonical remote version check source

See CHANGELOG.md for release history.