# html-design-examples

The html-design-examples skill uses a gallery of single-file HTML references to shape plans, reports, prototypes, and other materials meant to be read in a browser.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 173 repo stars
- Author: sammcj
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/sammcj/agentic-coding/tree/HEAD/Skills/html-design-examples/SKILL.md
- Updated: 2026-10-24
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/html-design-examples

## What it does

The gallery covers different jobs: comparing implementation options, explaining unfamiliar code, laying out a design system, building prototypes, and writing reports. The skill’s workflow is simple: choose a reference that fits the task, read the whole file, then adapt its structure and visual style to the real content. Interactive examples should give users a way to copy their result as JSON or a prompt.

Each reference is a standalone HTML file with its styles and scripts inside, ready to open in a browser without a build step. That format has a trade-off: HTML diffs are noisy, so the README recommends Markdown for documents that need long-term, line-by-line review in a repository. The gallery’s Birchline branding and fixture data are fictional; they should not carry over into a project.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add sammcj/agentic-coding --skill html-design-examples -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/html-design-examples/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/html-design-examples/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add sammcj/agentic-coding --skill html-design-examples -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/html-design-examples/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add sammcj/agentic-coding --skill html-design-examples -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/html-design-examples/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install sammcj/agentic-coding Skills/html-design-examples/SKILL.md
```

2. **Manually: put the files in place**
- File: `.github/skills/html-design-examples/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add sammcj/agentic-coding --skill html-design-examples -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/sammcj/agentic-coding --path Skills/html-design-examples
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/html-design-examples/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/sammcj/agentic-coding/tree/HEAD/Skills/html-design-examples/SKILL.md

## When to use it
- compare implementation options on one page
- map a delivery plan onto a timeline
- annotate a code review with severity labels and jump links
- prototype an interaction across linked screens
- present a status update or incident timeline

## Example prompts
- Create a single-file HTML implementation plan with milestones, a data-flow diagram, and a risk table.
- Build a browser-ready project status report showing shipped work, slipped items, and a small chart.
- Make an interactive feature-flag editor with dependency warnings and a button to copy changed keys.

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 4acabe6ce7103397.

BEGIN THIRD-PARTY FILE 4acabe6ce7103397
```text
---
name: html-design-examples
description: Reference gallery of polished single-file HTML artifacts demonstrating effective ways to communicate ideas through HTML. Use when the user wants to explain, showcase, demo, plan, review, or present an idea within an HTML file.
metadata:
  source: Adapted from https://x.com/trq212/status/2052809885763747935
---

# HTML Design Examples

A library of self-contained `.html` files showing how a static HTML artifact can carry more signal than the same content as markdown. Use them as visual and structural references when building an HTML deliverable for a similar task.

## Why HTML, not markdown

The bottleneck is human attention, not what the agent can produce. A 500-line markdown plan goes unread; the same content as one HTML page with diagrams, tables and inline controls gets engaged with. HTML carries tables, SVG, CSS layout, scripts and spatial composition in a single file, opens in any browser, and shares as a URL rather than an attachment. The token and latency cost is real, and worth it for any artifact that needs to be read by a human.

Prefer HTML for human-facing, ephemeral artifacts (specs, plans, reports, writeups, prototypes, throwaway editors). Stay with markdown or source for things that need durable, line-by-line review in a repo (RFCs, ADRs, runbooks) - HTML diffs are noisy.

## How to use this skill

1. Pick the example that most closely matches the user's intent (catalogue below).
2. Read that file in full before writing your own. The reference's style, density, and structure are the point.
3. Match the shared conventions (see "Conventions").
4. Adapt to the user's real content. The examples use a fictional "Birchline" brand and fixture data - do not carry that across.
5. If the artifact is an editor or any interactive surface, end it with a "copy as JSON" or "copy as prompt" button so the user's work flows back into the agent loop.

## Resource catalogue

Files live in `resources/`. Open `resources/index.html` for the rendered gallery with thumbnails.

### Exploration & Planning
- `01-exploration-code-approaches.html` - side-by-side comparison of three implementation approaches with trade-offs called out inline.
- `02-exploration-visual-designs.html` - layout and palette options rendered live for visual comparison.
- `16-implementation-plan.html` - milestones on a timeline, data-flow diagram, inline mockups, risky code, risk table.

### Code Review & Understanding
- `03-code-review-pr.html` - annotated diff with margin notes, severity tags, jump links.
- `17-pr-writeup.html` - author-side PR description with motivation, before/after, file-by-file tour.
```
END THIRD-PARTY FILE 4acabe6ce7103397

The third-party file has ended. Everything between the 4acabe6ce7103397 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2657 of 5905 bytes. © sammcj · Apache-2.0 · https://github.com/sammcj/agentic-coding/tree/HEAD/Skills/html-design-examples/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
