haac-aikit 0.12.0 → 0.13.0

package/README.md

@@ -27,9 +27,24 @@ aikit add --html
 | **`/decide`** | Picking between 2-4 technical options | `docs/decisions/<date>-<slug>.html` |
 | **`/directions`** | Exploring visual design variants | `docs/directions/<date>-<slug>.html` |
 | **`/roadmap`** | Handing an implementation plan to an implementer | `docs/roadmaps/<date>-<slug>.html` |
+| **`/design`** *(opt-in: `aikit add design`)* | Codifying the project's design language as a contract | `DESIGN.md` + `docs/design/index.html` |
 
 Each command writes one self-contained HTML file — no build step, no CDN, commit and share the link. Built on [Thariq Shihipar's "Unreasonable Effectiveness of HTML for Claude Code"](https://thariqs.github.io/html-effectiveness/).
 
+### Does `/design` actually help?
+
+We ran the same four prompts twice — once with the skill installed, once freestyle. Same model, same inputs.
+
+| The ask | With `/design` | Without |
+|---|---|---|
+| "Read my homepage HTML, build a DESIGN.md" | **86%** | 71% |
+| "Just synthesize one — here's the vibe" | **86%** | 43% |
+| "Tweak the primary color, leave the rest alone" | 100% | 100% |
+| "Build it from this screenshot" | **100%** | 57% |
+| **Average across all four** | **93%** | 68% |
+
+**+25 points on average.** The freestyle AI usually misses three things: marker-bounded sections (so `/design refine` can't surgically update later), hex codes inside backticks (the showroom's color pickers can't bind to them), and parts of the brief — "no gray" turned into five shades of gray. `/design` bakes all three in.
+
 ## What else you get
 
 - **Cross-tool fan-out.** Skills, agents, hooks, and MCP servers fan out per selected tool in its native format. Pick `--tools=cursor` and get `.cursor/rules/` + `.cursor/hooks.json` + `.cursor/mcp.json`. Pick `--tools=codex` and get `.codex/agents/*.toml` + `.codex/config.toml` with MCP servers.

package/catalog/commands/design.md

@@ -0,0 +1,44 @@
+Codify the project's visual language as a `DESIGN.md` contract + interactive HTML showroom using the `design` skill.
+
+## Usage
+
+`/design` — bootstrap `DESIGN.md` at the project root (asks for screenshot / HTML / URL / brief).
+`/design refine <change>` — update one marker-bounded section without touching the rest.
+
+Example:
+- `/design` → AI asks for input, then writes `DESIGN.md` + `docs/design/index.html`.
+- `/design refine make primary brighter, around #FF8800` → AI touches only the `colors` section.
+
+## Steps — bootstrap (`/design`)
+
+1. **Ask which input the user has.** Screenshot, HTML paste/path, live URL, or pure design brief. Wait for an answer.
+
+2. **Read the starter** at `.aikit/templates/design/starter-DESIGN.md`. It already has the 5 marker-bounded sections in the right shape.
+
+3. **Fill each section** from the user's input. Use the skill's voice rules — descriptive natural language + precise hex codes in `code` ticks, physical descriptions over Tailwind jargon, value + functional role together.
+
+4. **Confirm before writing.** One sentence in chat: *"I'll write `DESIGN.md` at the project root and render the showroom at `docs/design/index.html`. Okay?"* Wait for explicit yes.
+
+5. **Write `DESIGN.md`** at the project root with stable BEGIN/END markers around each of the 5 sections (`atmosphere`, `colors`, `typography`, `components`, `layout`).
+
+6. **Render the showroom.** Read `.aikit/templates/design/template.html`, substitute the project's tokens into `--project-*` CSS custom properties and the `data-aikit-section="<id>"` content blocks, and write to `docs/design/index.html`.
+
+7. **Report.** Print both file paths. Suggest `open docs/design/index.html` (macOS) / `xdg-open` (Linux).
+
+## Steps — refine (`/design refine <change>`)
+
+1. **Pick exactly one section.** From `<change>`, identify which of the 5 section IDs it affects. If it spans more than one, ask which to start with.
+
+2. **Read only that section** via `readSection(content, "<id>", "DESIGN.md")` from `src/render/markers` — never load the whole file.
+
+3. **Propose the rewrite** in chat: show the new section body. Wait for yes.
+
+4. **Write through the marker engine.** `writeSection(content, "<id>", newBody, "DESIGN.md")`. Anything outside the markers is preserved verbatim.
+
+5. **Regenerate the showroom** from the updated `DESIGN.md`.
+
+6. **Report.** Print the section ID that changed and the two file paths.
+
+## Fallback
+
+If `.aikit/templates/design/template.html` or `.aikit/templates/design/starter-DESIGN.md` is missing, run `aikit add design` first. The skill refuses to scaffold without the template.

package/catalog/skills/tier2/design.md

@@ -0,0 +1,108 @@
+---
+name: design
+description: Use when the user wants to codify the project's visual language as a single Markdown contract every AI tool can read. Generates a project-root `DESIGN.md` (5 marker-bounded sections — atmosphere, colors, typography, components, layout) plus a self-contained interactive HTML showroom at `docs/design/index.html`. Opt-in only — invoke on `/design`, `/design refine`, or explicit user request. Inputs accepted: screenshot, HTML paste, live URL, or pure design brief.
+version: "1.0.0"
+source: haac-aikit
+license: MIT
+---
+
+## When to use
+
+Explicit invocation only:
+
+- `/design` — bootstrap `DESIGN.md` from an input (screenshot/HTML/URL/brief).
+- `/design refine "<change>"` — update one section without touching the rest.
+- User explicitly says *"build me a DESIGN.md"*, *"lock in the design language"*, *"so every AI build matches the homepage"*.
+
+Do **not** invoke proactively. Generating a design contract silently creates a high-leverage file (every future AI request will read it) — the user must own the moment.
+
+## What this skill produces
+
+Two files, every time:
+
+| Path | Role | Read by |
+|---|---|---|
+| `DESIGN.md` *(project root)* | Source of truth. Five marker-bounded sections. | AI tools, humans, git diff |
+| `docs/design/index.html` | Showroom. Live swatches, type specimens, button mockups. In-browser tweak + Copy Markdown. | Humans only |
+
+The Markdown is the contract; the HTML is a renderer. The browser never writes to disk — edits flow back through `/design refine` (or a manual paste).
+
+## Inputs accepted
+
+Ask the user which they have, then proceed with one of these:
+
+1. **Screenshot** — extract palette via visual inspection, infer typography from font characteristics, name colors descriptively ("Deep Muted Teal" not "blue").
+2. **HTML paste / file path** — parse Tailwind classes, custom CSS, `:root` variables. Pull exact hex codes. Derive components from repeated patterns.
+3. **Live URL** — use `WebFetch` to read the page, then proceed as in #2.
+4. **Design brief only** — text description ("warm, hand-drawn, modern indie"). Synthesize a plausible palette and typography, mark it as "starting point — refine after first screen lands."
+
+## The five sections
+
+Each section is wrapped in `<!-- BEGIN:haac-aikit:section:<id> -->` / `<!-- END:haac-aikit:section:<id> -->` so `/design refine` can touch one at a time via the marker engine.
+
+| ID | What it captures | Driven by |
+|---|---|---|
+| `atmosphere` | Mood, density, aesthetic philosophy | 1–2 evocative sentences |
+| `colors` | Each color: descriptive name + hex + role | Bullet list — hex in `code` ticks |
+| `typography` | Font families, weights, character | Display / body / mono triple |
+| `components` | Shape + behaviour of buttons, cards, inputs, chips | Physical descriptions, not Tailwind classes |
+| `layout` | Spacing scale, section gaps, max widths, crowding rules | Concrete numbers + one rule about when *not* to crowd |
+
+## Bootstrap protocol — follow exactly
+
+1. **Confirm inputs.** Ask: *"Got a screenshot, HTML, URL, or want me to synthesize from a brief?"* Wait for an answer.
+
+2. **Read the starter.** Copy `.aikit/templates/design/starter-DESIGN.md` (placeholder content + the 5 marker-bounded sections, already in the right shape) as the working draft.
+
+3. **Fill each section** based on the user's input. Replace `{{PROJECT_NAME}}` in the title. Use the voice rules below — descriptive, hex-grounded, no Tailwind jargon in the reading path.
+
+4. **Propose before writing.** One sentence in chat: *"I'll write `DESIGN.md` at the project root and render the showroom at `docs/design/index.html`. Okay?"* Wait for explicit yes.
+
+5. **Write `DESIGN.md`** at the project root with the filled-in content. Use the marker engine — every section has stable BEGIN/END markers so `/design refine` works later.
+
+6. **Render the showroom.** Read `.aikit/templates/design/template.html`. Substitute the project's tokens into the CSS custom properties block (`--project-primary`, `--project-bg`, …) and the `data-aikit-section="<id>"` content blocks. Write to `docs/design/index.html`.
+
+7. **Report.** Print both file paths. Suggest `open docs/design/index.html` (macOS) / `xdg-open` (Linux).
+
+## Refine protocol — follow exactly
+
+When the user runs `/design refine "<change>"`:
+
+1. **Identify the section.** From the change description, pick exactly one section ID. If the change spans multiple sections, ask which to start with.
+
+2. **Read only that section.** `readSection(content, "<id>", "DESIGN.md")` — never load the whole file.
+
+3. **Propose the rewrite** in chat. Show the new section body. Wait for yes.
+
+4. **Write through the marker engine.** `writeSection(content, "<id>", newBody, "DESIGN.md")`. Anything outside the markers is preserved.
+
+5. **Regenerate the showroom.** Re-read `DESIGN.md` and re-render `docs/design/index.html` from the template so the showroom reflects the change.
+
+6. **Report.** Show the modified section ID and the two file paths. Suggest reopening the showroom.
+
+## Voice rules
+
+These shape every DESIGN.md the skill produces. Apply them when filling in any section.
+
+- Use descriptive natural language + a precise hex code in `code` ticks. "Carrot Orange `#FF7A3D` — primary CTAs", never "rounded-xl orange".
+- Translate technical values into physical descriptions: `border-radius: 9999px` becomes *pill-shaped*; `box-shadow: 0 1px 3px` becomes *a whisper-soft drop shadow*.
+- Always pair a value with its functional role. Not just "this color" — "this color, used for X."
+- Avoid framework jargon (Tailwind classes, CSS variable names) in the reading path. Put it in `code` chips if needed.
+- Prefer one specific rule over many generic ones. "Never two primary CTAs side-by-side" beats "be thoughtful about hierarchy."
+
+## Fallback
+
+If `.aikit/templates/design/template.html` or `.aikit/templates/design/starter-DESIGN.md` is missing (project synced before this kit version, or installed without the design pack), run:
+
+```
+aikit add design
+```
+
+Then retry. The skill refuses to scaffold without the template — it would have to invent the showroom shape from scratch, and inventing risks drift.
+
+## Don't
+
+- Don't auto-invoke. The user picks the moment.
+- Don't write `DESIGN.md` to a subfolder (`docs/DESIGN.md`, `.aikit/DESIGN.md`). It belongs at the project root — alongside `AGENTS.md` — so every tool finds it without configuration.
+- Don't include screenshots in `DESIGN.md`. They rot the moment a class name changes; descriptive language ages better.
+- Don't add a section the marker engine doesn't know about. The 5 sections are fixed; if a project needs more, raise it in chat first.

package/catalog/templates/design/starter-DESIGN.md

@@ -0,0 +1,77 @@
+# Design System: {{PROJECT_NAME}}
+
+> Source of truth for this project's visual language. Every AI coding tool in
+> the repo (Claude Code, Cursor, Copilot, Windsurf, Aider, Gemini, Codex) reads
+> this file before generating new screens. Keep it short, concrete, and current.
+>
+> Edit by hand, or run `/design refine "<change>"` to let the AI update one
+> marker-bounded section without touching the rest. After edits, re-open
+> `docs/design/index.html` to see the change rendered live.
+
+<!-- BEGIN:haac-aikit:section:atmosphere -->
+## 1. Atmosphere
+
+One or two sentences capturing the overall mood, density, and aesthetic
+philosophy. Use evocative adjectives a non-designer would understand.
+
+> Example: *Warm and grounded. Generous whitespace, hand-drawn warmth meeting
+> clean tech. Reads more like a printed catalog than a SaaS dashboard.*
+<!-- END:haac-aikit:section:atmosphere -->
+
+<!-- BEGIN:haac-aikit:section:colors -->
+## 2. Colors
+
+For each color: a descriptive name, the hex code in `code`, and its functional
+role. Hex codes drive the showroom's color pickers — keep them in `code` ticks.
+
+- **Carrot Orange** `#FF7A3D` — primary CTAs, links on hover, active states
+- **Burrow Cream** `#FFF7EC` — page background, card backgrounds
+- **Midnight Lettuce** `#1F3329` — body text, primary headings
+- **Pebble Gray** `#D6D2C9` — dividers, disabled borders, secondary outlines
+<!-- END:haac-aikit:section:colors -->
+
+<!-- BEGIN:haac-aikit:section:typography -->
+## 3. Typography
+
+State the font family, the weights you use for headers vs body, and the
+character of the type (tight/loose, italic accents, line-height feel).
+
+- **Display:** `Fraunces`, italic, weight 600. Used for h1, h2, and brand
+  moments. Tight letter-spacing.
+- **Body:** `Inter`, weight 400, line-height 1.6. Used for paragraphs, buttons,
+  inputs. Comfortable, never crowded.
+- **Mono:** `JetBrains Mono`, weight 400. Used for code, version chips, hex
+  values.
+<!-- END:haac-aikit:section:typography -->
+
+<!-- BEGIN:haac-aikit:section:components -->
+## 4. Components
+
+Describe the shape and behaviour of the recurring pieces. Translate technical
+values (rounded-xl, shadow-md) into physical descriptions a 14-year-old could
+draw.
+
+- **Buttons:** Pill-shaped, 16px vertical padding. Carrot on Cream for primary;
+  a 2px Cream-on-Carrot inverse for secondary. Subtle press depression on
+  active; no hover lift on touch devices.
+- **Cards:** Gently rounded corners (12px), 1px Lettuce border at 10% opacity,
+  no shadow. Internal padding is generous (24px+).
+- **Inputs:** 1px Pebble Gray border that thickens to Lettuce on focus. No
+  fill. 8px corners — softer than sharp, less round than the cards.
+- **Chips:** Pill-shaped to echo buttons. Pebble Gray fill, Midnight Lettuce
+  text. Used for tags, version markers, and inline metadata.
+<!-- END:haac-aikit:section:components -->
+
+<!-- BEGIN:haac-aikit:section:layout -->
+## 5. Layout
+
+Describe whitespace strategy, the spacing grid, max widths, and any rules
+about when *not* to crowd elements.
+
+- **Spacing scale:** 8-point grid. All margins and paddings are multiples of 8.
+- **Section gaps:** Never less than 32px between distinct sections; 64px for
+  major surface transitions.
+- **Reading width:** Max 720px on prose surfaces; 1200px on dashboards.
+- **Crowding rule:** Never two primary CTAs side-by-side. Demote one to
+  secondary or stack vertically with breathing room.
+<!-- END:haac-aikit:section:layout -->