# design-it

design-it turns requirements and feature briefs into a self-contained HTML design document with a fixed house style. Use it when every design doc must follow the same structure.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 170 installs · ★ 302 repo stars
- Author: smallnest
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/smallnest/goal-workflow/tree/HEAD/skills/design-it/SKILL.md
- Updated: 2026-09-13
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/design-it

## What it does

The skill takes a requirement, specification, or feature brief and produces one self-contained HTML file. It starts from `template.html`, keeps the supplied style block intact, and fills the document skeleton with a table of contents, business rules, architecture and sequence SVG diagrams, data models, contracts, test cases, and a code index.

The output can contain code, SQL, and YAML blocks, callout boxes, status pills, and a change log. Save it as `docs/<requirement-name>.html`; the TOC links and section IDs must stay aligned. Read the requirement and repository before filling the template: `file:line` locations, table names, and `protoIds` must come from the codebase, while unresolved values are marked `待确认` rather than guessed.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add smallnest/goal-workflow --skill design-it -a claude-code
```

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

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add smallnest/goal-workflow --skill design-it -a codex
```

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

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add smallnest/goal-workflow --skill design-it -a cursor
```

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install smallnest/goal-workflow skills/design-it
```

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

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add smallnest/goal-workflow --skill design-it -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/smallnest/goal-workflow --path skills/design-it
```

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add smallnest/goal-workflow --skill design-it -a opencode
```

### 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/smallnest/goal-workflow/tree/HEAD/skills/design-it/SKILL.md

## When to use it
- turn a feature brief into one HTML design document
- build a matching table of contents and section structure
- draw architecture and sequence diagrams as inline SVG
- format SQL, YAML, and code inside document blocks
- check TOC links against section IDs

## Example prompts
- Turn this feature brief into a design document based on `template.html` and save it as `docs/<requirement-name>.html`.
- Read the repository, then add architecture and sequence SVG diagrams, test cases, and a code index.
- Check every TOC `href` against its section `id`, and mark unresolved `file:line` entries as `待确认`.

## Source text · SKILL.md · MIT

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: 5fed4c69b7d7b452.

BEGIN THIRD-PARTY FILE 5fed4c69b7d7b452
```text
---
name: design-it
description: Use when turning a requirement, spec, or feature brief into a single self-contained HTML design document in a fixed house style — one styled HTML page with a table-of-contents, architecture/sequence SVG diagrams, code/SQL/YAML blocks, callout boxes, an aligned-decisions (已对齐结论) panel, test cases, and a code index. Reuse for any new 需求/设计文档 that should look identical every time.
---

# design-it

## Overview

Generate a technical design document as **one self-contained HTML file** in a fixed house style, so every new 需求 produces a visually identical page. The look is not improvised each time — it comes from a fixed `<style>` block and a fixed section skeleton. Your job is to fill content into that skeleton, never to redesign it.

**Core principle:** Copy `template.html` verbatim, then replace only the content. Keep the `<style>` block byte-for-byte. Consistency comes from *not* touching the design system.

## When to Use

- The user gives a new requirement / spec / feature and wants a design doc.
- Converting a `.md` technical spec into the shareable HTML form.
- Any request like "生成同样的 html / 用这套模板 / 出一份设计文档".

**When NOT to use:** quick throwaway notes, a real Markdown deliverable the user wants to stay Markdown, or slide decks.

## Workflow

1. **Copy the template.** Start from `template.html` in this skill's directory. Do not hand-roll the `<head>`/`<style>` — copy it whole.
2. **Gather real content first.** Section titles, field names, SQL, `file:line` code positions, protoIds — all must come from the actual requirement doc and codebase. Read the code; do not invent identifiers. If a fact is unknown, mark it `<span class="pill todo">待确认</span>`, never guess.
3. **Fill the skeleton.** Rename/reorder `<section>`s to fit the feature. Keep the section *kinds*: 已对齐结论 → 业务规则 → 架构图 → 时序 → 数据模型 → 契约 → 清单 → 幂等降级 → 测试用例 → 代码索引 → 变更记录. Drop what doesn't apply; add feature-specific ones in the same style.
4. **Keep TOC and sections in sync.** Every `<a href="#x">` needs a matching `<section id="x">`, and vice versa. This is the #1 breakage — verify at the end (see Quick Reference).
5. **Save** as `docs/<需求名>.html`. Don't commit unless asked.

## House-Style Rules (non-negotiable)

| Element | Rule |
|---|---|
| `<style>` block | Copy verbatim. Never restyle. Colors come from `:root` CSS variables only. |
| Code / SQL / YAML | Always the template's `<pre style="background:#f8fafc;...">`. **Inside `<pre>`, escape `<`→`&lt;`, `>`→`&gt;`, `&`→`&amp;`.** Unescaped `<` silently eats content. |
```
END THIRD-PARTY FILE 5fed4c69b7d7b452

The third-party file has ended. Everything between the 5fed4c69b7d7b452 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 2741 of 4454 bytes. © smallnest · MIT · https://github.com/smallnest/goal-workflow/tree/HEAD/skills/design-it/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
