design-it

design-it

Overview

Generate a technical design document as one self-contained HTML file in a fixed house style, so every new requirement 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 "generate the same html / use this template set / produce a design document".

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

Workflow

Copy the template. Start from template.html in this skill's directory. Do not hand-roll the <head>/<style> — copy it whole.
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.
Fill the skeleton. Rename/reorder <section>s to fit the feature. Keep the section kinds: aligned conclusion → business rules → architecture diagram → sequence → data model → contract → checklist → idempotent degradation → test cases → code index → change log. Drop what doesn't apply; add feature-specific ones in the same style.
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).
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 `<`→`<`, `>`→`>`, `&`→`&`. Unescaped `<` silently eats content.
Callout boxes	`.note` (orange, reminders/error-prone), `.tip` (blue, positive additions), `.warn` (red, risk). Use the right color for the meaning.
Diagrams	Hand-authored inline `<svg>` inside `<figure>`; text uses `.svg-t`/`.svg-s`/`.svg-title`; node fills use `:root` vars (`var(--new-bg)` etc.), matching the `.legend`.
Intro	Each section opens with one `<p class="lead">` stating what it answers.
Pills	`.pill.new/.old/.infra/.mq/.prod/.tech/.done/.todo` for status tags — reuse, don't invent classes.
Tables	Plain `<table>` — the CSS handles zebra striping and header shading.
Lang	`<html lang="zh">`; body copy in the doc's language (usually Chinese).

Common Mistakes

Redesigning the CSS. The whole point is identical output — don't "improve" colors, spacing, or fonts. Copy <style> untouched.
Unescaped angle brackets in <pre>. List<String> renders as a broken tag. Escape to List<String>.
Dead TOC links. Adding a section without its TOC entry (or renaming an id and forgetting the href). Always cross-check.
Inventing code positions. file:line, table names, protoIds must be read from the repo. Unknown → 待确认 pill, not a plausible-looking guess.
Making it a proposal. Keep it a design doc (what/how, locked decisions), not a persuasive pitch.

Quick Reference — final self-check

f="docs/<需求名>.html"
# TOC hrefs vs section ids must match exactly (no output = perfect):
diff <(grep -oE 'href="#[a-z0-9-]+"' "$f" | sed 's/.*#//;s/"//' | sort -u) \
     <(grep -oE '<section id="[a-z0-9-]+"' "$f" | sed 's/.*"//' | sort -u)
# open in browser to eyeball diagrams + code blocks render cleanly