grill-me-visual

grill-me-visual

Emits a single-file HTML questionnaire the user opens in a browser. Each question is a card in an accordion with rich visual previews. The user answers in the browser, clicks Copy, then pastes the markdown summary back into chat.

Scope

Use this skill only when the decision space is visually-shaped — UI layout, motion, typography, color, diagram shape, or content rendering rules (how code / markdown / icons / math / tables get displayed). If the decisions are text only with no visual angle, ask them in plain chat instead — the HTML overhead isn't worth it.

---

Picking a template

Two templates ship with this skill — pick by user language:

File	Use when
template.en.html	The user writes English, or asks the questions in English. All chrome strings and the demo questions are English.
template.zh.html	The user writes Chinese, or asks the questions in Chinese. All chrome strings and the demo questions are Chinese (Simplified).

Both templates share identical CSS / JS / accordion / clipboard / Mermaid wiring — only the textual content differs. Mixing languages within one file works but reads poorly; pick one and stick to it for the round.

For other languages, copy the closest fit (probably template.en.html) and translate the chrome strings — see "Translating to a third language" below.

---

Workflow per round

1. Identify the topic — what design space are we exploring this round? (e.g. "AI chat interface", "marketing landing page", "dashboard information hierarchy", "Slack-bot message styling")
2. Output the question list to chat — before opening the template. Include only decisions where the user could plausibly pick any option. Reading the template first will anchor you into filler questions and forced patterns.
3. Pick a preview pattern per question (see pattern catalog below). Pattern reuse is fine — a layout-heavy round may use UI mockup 3–4× in a row. If a question has no genuine visual angle, switch it to text-only (pattern #6) or ask it in chat.
4. Create + smoke-test the HTML file by copying the right template (see authoring flow below).
5. Hand the file path to the user and wait for their answers.
6. When they paste the markdown summary back, parse the answers. Drill until every visually-shaped decision is resolved — don't stop at one round just because the user answered everything:
   • If any answer reveals a new unresolved dependency (e.g. "Card layout" chosen → now spacing rhythm and border style matter), run another round targeting that branch
   • If answers conflict or raise new trade-offs, surface them in the next round before building
   • Only move on to building when no open visual decision remains
7. End of session: ask the user about decision capture — recommend ADR / CONTEXT.md / PRD if any decisions deserve long-term storage. Do not auto-write the doc; let the user decide.

---

Authoring flow — how to fill the template

The template is a single HTML file (~1900 lines, ~75 KB, roughly 20–25k tokens — larger than the default Read window). Don't slurp the whole file. Use these patterns:

• Bash grep -n "PATTERN:" lists what pattern each demo card uses. Delete the cards for patterns you don't need (whole <!-- QN START -->…<!-- QN END --> block) sight-unseen — no Read.
• For the survivors, grep -n "Qn START" to locate, then Read with offset + limit (~80 lines per card)
• Each card is fully self-contained between its START and END markers; you can Edit that block in one call without reading the rest of the file

Do not rewrite the template — copy it and edit only the question content.

1. Bash:  mkdir -p .grill-me-visual && cp <skill-dir>/template.<en|zh>.html <output-path>
          # <skill-dir> = the directory this SKILL.md lives in. Resolve from the
          # path the harness gave you when loading the skill.
          # <output-path> = .grill-me-visual/grill-{topic-slug}-round-{N}.html
          # — hidden top-level folder in the user's CWD (dot prefix keeps it out
          # of `ls` output and avoids colliding with the skill's own source dir
          # when running inside this repo). Decisions belong to the project
          # they're about; multi-round files cluster together; the user can
          # commit them or gitignore them at their own discretion.
          # Use a relative path with forward slashes so it works cross-platform
          # (macOS, Linux, WSL, Git Bash, PowerShell, cmd). Avoid `/tmp`
          # (missing on native Windows) and `mktemp -t ...` (semantics differ
          # between macOS and Linux).
2. Bash:  grep -n "PATTERN:" <file>  # which Qn uses which pattern
          Delete whole QN blocks for any pattern you're NOT using (markers and
          all) — no Read needed. Renumber survivors' `data-id` sequential q1…qN.
3. Edit:  replace `const TOPIC = "..."` with this round's topic
4. Edit:  replace `const ROUND = ...` if this is round N > 1
5. Edit:  replace masthead `<span class="topic">...</span>` text to match TOPIC
6. Edit:  replace the `<p class="lede">...</p>` with a roadmap-style POV sentence
7. Edit × N cards:  replace each surviving card body between its
          `<!-- ─────────── Qn START · PATTERN: ... ───────────` and
          `<!-- ─────────── Qn END ─────────── -->` markers.
          Card IDs go q1, q2, … qN; the markdown output groups answers by this id.
8. Sanity check BEFORE handing off. If you have browser access (Chrome MCP,
          Playwright, headless browser, etc.), open the file and verify Mermaid
          renders, fonts load, and layout holds. Always also grep-check structure:
          - `grep -c 'data-id="q' <file>` matches your intended card count (and IDs are q1…qN sequential)
          - `grep -c '<button[^>]*data-rec="1"' <file>` == card count — every question has exactly one recommended option
          - `data-value="..."` slugs are unique within each card
          Without browser access, also eyeball-check from source:
          - Mermaid `<pre class="mermaid">` blocks against the hard constraints (no `:`, no `"`, no `<`/`>`, basic shapes only)
          - Every `font-family` referenced is loaded via the Google Fonts <link> in <head>
9. Hand off.  Best-effort: launch the file in the user's default browser (skip
          silently if headless / no GUI). Then output ONE clickable markdown
          link from the user's CWD — `[<filename>](<relative-path>)` — as the
          re-open handle. No absolute path, no separate command line. If the
          user reports a Mermaid / font / layout issue, fix and re-hand.

Do not touch:

• <head> (CSS, Google Fonts, viewport meta, theme-color, copy fallback are pre-wired). Exception: when translating, swap CDN URLs if needed.
• The <script> block at the bottom (Mermaid init, accordion logic, copy/reset, dirty-flag tracking, mobile-safe clipboard fallback, tag-rec auto-inject). Exception: when translating, edit the LANG = { ... } object at the top of <script> and nothing else — see "Translating to a third language" below.
• Styles for .card / .opt / .opt-tags / .chevron / scrollbars / dark mode
• Theme variables (--paper, --ink, --clay, --moss, etc.)

If you find yourself wanting to change CSS/JS, stop and ask the user — the template already handles mobile-safe copy, font fallback (incl. Chinese), dark-mode contrast, Mermaid theming, and small-screen layout.

---

Card schema — what each card needs

Each card replaces the block between <!-- Qn START --> and <!-- Qn END -->. Open Q1 in the template for the canonical structure — copy it and substitute your content. Required slots (in order):

• data-id="qN" on the wrapping <div class="card"> (must match position in 1–N sequence)
• <span class="qnum">Qn.</span> and <span class="title-text"> in .card-header
• <p class="q-desc"> — what / why (Setting → impact). No option preview here.
• <p class="rec-hint"><b>{name}</b> — {one-line why}</p> — recommendation reasoning
• N <button class="opt opt-rich" data-value="slug" [data-rec="1"] data-label="A. …"> preset options with .opt-preview + .pros-cons + .opt-label. Letters A, B, C, … sequential; exactly one option has data-rec="1". Use as many as the decision genuinely has — if you can't find 2, ask in chat instead; if you'd need 5+, consider splitting into two questions.
• 1 <div class="opt opt-input"> for free-text "Other…" — always last, letter following the last preset.

Tags: set <span class="opt-tags"><span class="opt-tag tag-current">Current</span></span> on the option the user is using today (if any). The Recommended tag is auto-injected from data-rec="1" — don't add it by hand. To translate the recommended label, edit LANG.tagRec only.

---

Preview pattern catalog

Pick ONE pattern per question. All preset options within one question MUST use the same pattern.

Pattern	Demo card	Use when
#1 UI mockup	Q1 in template	"how it should look" — layout / container / render style
#2 CSS animation	Q2 in template	motion — loading, streaming, transition
#3 Mermaid	Q3 in template	shape of a flow / state / sequence
#4 Font	Q4 in template	typography — body, wordmark, display
#5 Code snippet	Q5 in template	content comparison — same default rendering, different content
#6 Text-only	Q6 in template	no genuine visual angle (last resort)

Open template.en.html or template.zh.html and read the matching demo card as the canonical structure to copy from. If none of these 6 fit, invent your own pattern — the preview HTML/CSS goes inside .opt-preview; keep the rest of the card structure unchanged. Add a <!-- PATTERN: ... --> comment so the next round can spot it.

1. UI mockup (inline HTML/CSS rendering of a tiny real UI)

Use this when the decision is "how the UI should look" — different layouts, container styles, render styles for the same content. Use real placeholder copy at microscale (~60–70% of real proportions), not gray-bar wireframes (those look like skeleton loaders).

2. CSS animation live demo (real @keyframes)

Use this when the decision is about motion — what to show while loading / streaming / transitioning. Animations render inline so the user actually sees them move.

The template predefines reusable keyframes in its <style> block (demo-cursor-blink, demo-dots, demo-fade-token). Reuse those for cursor / dots / fade patterns rather than defining new ones; only add new @keyframes if you need a different motion.

3. Mermaid flowchart / sequenceDiagram / stateDiagram

Use this for "process / state / control flow" decisions where the comparison is shape of the flow. Drop a <pre class="mermaid">…</pre> inside each option's .opt-preview.

Hard constraints (the template's Mermaid renderer assumes basic shapes only):

• No double quotes inside labels — write [Send] not ["Send"]
• No colons in node labels — write A[Send · message] or A[Send — message], not A[Send: message]
• No < / < / > in labels — they don't decode. Reword the condition: write D{Can retry?} not D{Retries < N?}
• Only basic shapes: id[text] id{text}. No stadium ([..]), hexagon {{..}}, parallelogram >..], asymmetric >..]
• Use flowchart TD / LR, sequenceDiagram, stateDiagram-v2, erDiagram, or classDiagram — the themed CSS overrides target these
• Do NOT add custom theme directives (%%{init: ...}%%), classDef, or inline style statements — they collide with the brand palette overrides; let the template's defaults render

4. Font comparison (same text rendered in each font candidate)

Use this for typography decisions — body system, wordmark, display headline, etc.

Important: if any candidate is a Latin-only font (Source Serif 4, Inter Tight, Geist, etc.), the differences only show on Latin characters — non-Latin scripts (Chinese, Japanese, etc.) fall back to the system font on every option. If the user is comparing for a CJK product and you want the difference to read in mixed Latin + CJK, use a mixed sample explicitly.

Mandatory: load every candidate font. Referencing font-family: 'Geist' in an inline style without loading it = silent fallback to system, and the comparison is broken.

The template's <head> already loads: Source Serif 4 (serif display/body), Manrope (sans), Noto Sans SC + Noto Serif SC (Chinese fallbacks). To add more, append &family=<Name>:<spec> to the Google Fonts <link> URL — copy the spec from fonts.google.com (spaces become +).

5. Code snippet comparison (same default rendering, different content)

Use this when the decision is about the content of code — competing data shapes, algorithms, API signatures, prompt formats, config schemas — and each option is a small snippet of code with the same look.

The template provides a .code-snippet component for the default rendering — header with language tag, then a syntax-highlighted <pre> body. Drop it inside each option's .opt-preview:

<div class="code-snippet">
  <div class="code-head"><span class="code-lang">typescript</span></div>
  <pre><span class="tok-kw">const</span> x = <span class="tok-num">1</span>;</pre>
</div>

Optional highlight token classes: .tok-kw (keyword), .tok-id (identifier), .tok-str (string), .tok-num (number), .tok-cmt (comment). Plain text inside <pre> is fine — highlighting is decorative.

If the decision is instead about how content should be rendered (line numbers vs syntax highlight for code, table style for tabular data, emoji vs SVG for icons, KaTeX vs MathJax for math, etc.), that's a UI mockup question (pattern #1), not a content-snippet question — the "UI" you're comparing is the rendering component itself.

6. Text-only decision

For decisions with no visual angle (e.g. "should the AI greet the user proactively?"), use opt-rich but put only <ul class="pros-cons"> inside .opt-preview — no visual mockup. The "all-or-none preview" rule means ALL options in this question must be text-only.

For genuinely open-ended questions where some options have "no UI" (e.g. silent greeting = blank screen), use a plain .opt with no opt-rich:

<button type="button" class="opt" data-value="none" data-label="A. None">
  <span class="key">A.</span>None (stay with current)
</button>

---

Content rules (apply to every question)

1. q-desc structure: setting → impact. Explain when the decision applies and what it affects. Do not preview the options inside q-desc.
2. rec-hint is the cross-option comparison, one sentence framing why the recommended option wins over the alternatives. <b>{option name}</b> — {reason it beats the other choices}. Don't just restate the recommended option's pros — those go in its pros-cons list. rec-hint answers "why this one and not the others"; pros-cons answers "what are the trade-offs of this specific option in isolation".
3. Every preset option needs <ul class="pros-cons"> with 2–3 <li class="pro"> and 1–2 <li class="con">. Pros first, then cons. Exception: pure-affordance options like "None" in nullable questions.
4. All-or-none preview — within one question, either every preset option has a .opt-preview mockup, or none does. Pattern #6 (text-only) is the all-none case: every option's .opt-preview holds only pros/cons, no mockup. Don't mix mocked options with plain .opt (no opt-rich) options in the same question.
5. Recommended option gets data-rec="1" — that single attribute drives both the (recommended) suffix in the markdown output and the auto-injected Recommended tag in the UI. Don't write the tag span by hand.
6. tag-current is manual, tag-rec is automatic. Add <span class="opt-tag tag-current">Current</span> inside <span class="opt-tags">…</span> when the user is doing this thing today. The recommended tag appears automatically wherever data-rec="1" is set — see rule 5.
7. D-option placeholder must be context-specific — e.g. "Other container style…" not generic "Other…".
8. Lede uses agent's roadmap POV — frame it as the agent's spine of decisions ("From X to Y to Z — these N decisions define …"), not as instructions to the user ("Answer these N questions about …").

---

Translating to a third language

The two shipped templates are kept structurally identical — their <script> bodies are byte-identical after the LANG object — and differ in exactly two places:

1. The LANG = { ... } object at the top of <script> — all strings that JS emits dynamically (markdown output, button states, warning text, the Recommended tag label).
2. Inline HTML chrome strings — masthead eyebrow / topic, lede, output-panel title, button labels (Copy / Reset / warn-row goto+force), done-banner title + CTA, the tag-current label, every demo card's body.

To add a new language: copy whichever template is closest, swap (1)+(2), and diff the JS body against the original to confirm nothing else drifted. Run diff <(awk '/^const dark = matchMedia/,/^<\/script>/' template.en.html) <(awk '/^const dark = matchMedia/,/^<\/script>/' template.NEW.html) — it must be empty.