Concept

Concept

Generate an interactive HTML page for $ARGUMENTS, open it in the browser, and monitor for user decisions.

Step 0 — Load Extensions

Check for optional overrides. Use Glob to verify each path exists before reading. Do NOT call Read on files that may not exist — skip missing files silently (no output).

1. Global: ~/.claude/skills/concept/SKILL.md + reference.md
2. Project: {project}/.claude/skills/concept/SKILL.md + reference.md
3. Merge: project > global > plugin defaults

Step 0.5 — Concept Mode (asked once, at the start)

Before Step 1 runs for the first iteration, settle which kind of concept the user wants. Three modes exist:

| Mode | What the page is | Templates in scope | |---|---|---| | decision | Pure decision concept — non-visual alternatives to weigh (architecture, strategy, library, approach, …) | decision (plus free for surrounding analysis) — no mockups | | design | Pure design concept — visual directions / mockups / click-dummies | design only — no decision views, no decision iteration | | mixed | Both — the visual call AND the non-visual calls belong to the same concept | design iteration(s) carrying decision views where the question is about the mock, and/or a separate decision iteration where it stands on its own (entangled-questions rule in 1a) |

Ask unless it is already obvious. If the invocation prompt names the mode, or it can be derived unambiguously — "design me the settings page" → design; "which auth library should we take" → decision; "concept for the onboarding: the flow, the screens and which state library" → mixed; a caller skill (e.g. /tune-rethink, /setup-cleanup) that pins the template → that — skip the question and proceed. Otherwise ask exactly ONE AskUserQuestion with the three modes, mixed first and marked "(Recommended)", one line of description each (what the page will contain). Whenever the prompt allows two readings, lean towards mixed — a decision-only page hides the visual consequences, a design-only page hides the trade-offs behind the visuals. Do NOT prefix this question with "Erstmal in Ruhe durchlesen" — no inline result precedes it. A typed "Other" answer is a real answer ({PLUGIN_ROOT}/deep-knowledge/decision-format.md).

The mode is decided once per concept, not once per iteration. Later iterations (Step 5c) still pick their own template through the 1a check — the mode only says which templates are in scope. Feedback that pulls the concept the other way ("zeig mir das mal als Mockup" on a decision concept) widens the mode silently; no second question.

Count preferences — recommendations, not instructions

These keep the page scannable for the user. They are Claude's defaults, not user instructions: an explicit count from the user always wins, and Claude may deviate when the content genuinely demands it.

• Decision concepts and decision/comparison views: prefer 7 alternatives

set against each other. Fewer when the problem honestly has fewer distinct answers — never pad with near-duplicates to reach seven. More than seven gets unreadable; fold minor variants into one card instead.

• Design concepts: prefer 3 main designs, each **clearly — even

excessively — different** from the other two (unless the user asked for subtle variants). Show each design in its relevant states/screens (1a: "a screen is a logical state"). Fine-tuning within one direction is a later iteration's job, not designs 4 to 7.

• Mixed concepts combine both: 7 on the decision side, 3 on the design

side.

Step 1 — Pick Template, then Content Variant

1a. Pick the template — per iteration

A concept page is a stack of iterations, and each iteration independently picks its own layout template — decision, free, or design. This check runs every time an iteration is created (the first one, and every one appended later via tune/rethink/iterate) — it is NOT a one-time, page-level decision. Iteration 1 may be a decision round, iteration 2 a fullscreen design round, iteration 3 a decision round again; nothing forces the page to stay on one template throughout.

Pick via the strict ordered check below — first matching template wins, free is the explicit fallback when neither of the first two applies. Do NOT skip the order; free must never be chosen while design or decision would also fit.

Order of evaluation (mandatory, per iteration):

1. Is this iteration primarily VISUAL?

The options this iteration puts up for decision are primarily visual — layouts, design directions, screen composition, visual arrangement, a click-through flow, screen-by-screen UI design, any "design me / sketch / lay out a UI" task. If the output needs maximum viewport real estate and per-screen (and, with 2+ competing designs, per-design) feedback → design. Stop.

design is almost always a click-dummy. If a design has 2+ screens, the mockup's own buttons/links MUST be wired to navigate between screens (not just styled rectangles) — clicking "Continue" on screen 1 lands on screen 2, "Back" returns, etc. See deep-knowledge/templates.md § Template: design for the data-screen-link attribute pattern.

"Screen" is a logical state, not a full page. A screen can be a distinct view (welcome → credentials → success), but it can also be a meaningful state of the same view (modal closed → modal open → form submitted, tab A → tab B, collapsed drawer → expanded drawer, empty list → populated list). Every state the user should be able to give feedback on separately becomes its own ``.

Several competing visual directions (e.g. 21 layout variants that don't fit a 340px card) are several designs within the same design iteration, each with its own data-design wrapper and its own 1..n screens (count preference: 3 main designs, distinctly different — see Step 0.5) — not variant cards, and not a second, duplicate "— visuell" pass through a decision iteration. See the Architecture spec (docs/superpowers/specs/2026-08-03-concept-per-iteration-design-mode-design.md) for the markup shape.

Single-screen, single-design (exactly one data-screen): no screen-nav, no per-screen feedback textarea — the dock shows ONLY the general-notes textarea. A static single-screen design needs no click-dummy wiring. Do NOT invent artificial "screens" to justify the template; if the artefact has no meaningful secondary states, one screen is correct.

Design system: the mockup MUST follow the project's existing design system (colors, typography, component shapes, spacing) unless the user explicitly asks for a different style in the request. Check design-tokens.*, theme.*, tailwind.config.*, Figma tokens via the design MCP, or the existing UI code before inventing a look.

Optional annotation layer: when Claude has a concrete, element-level question about a specific spot in the mock, pin it there instead of (or in addition to) the general feedback dock — see § Annotation Layer (optional) below. Skip it entirely when there is nothing that specific to ask; it is not a default addition to every design iteration.

Optional views: alongside the ≥1 design, this same design iteration MAY also hold section[data-view] — fullscreen, non-visual questions with their own TOC entry, switched exactly like a design (see deep-knowledge/templates.md § Views (optional)). Two kinds ship as templates: decision (2..n named alternatives, bi-state per alternative) and comparison (2..n concrete candidates side by side, verdict per option, optional criteria matrix); count preference 7 per view (Step 0.5). In design mode (Step 0.5) views are out of scope — the non-visual questions belong to a later decision iteration only when the user widens the mode. Rule of thumb — view vs. its own decision iteration: if the question is about the artefact in front of the user (they need to look at, or click through, the mock to answer sensibly) → a view inside this iteration. If the question stands on its own, independent of any one screen → its own decision iteration one round later. Views are never mandatory and never a substitute for the ≥1 design — an iteration that is only questions is a decision iteration, not a design one with zero designs.

1. Are there ≥2 substantive non-visual alternatives?

Multi-option evaluation where the user must pick from 2+ mutually-exclusive alternatives (architecture, tech, strategy, library, approach, …). If there are explicit variants A/B/C with pros/cons to weigh → decision. Stop. Count preference: 7 alternatives compared (Step 0.5). In design mode (Step 0.5) this step is skipped — visual-only concepts do not get a decision iteration.

1. Otherwise → FREE.

Only reach this step after 1 AND 2 have both been ruled out. Analysis, walkthrough, brainstorm, explainer, timeline, status deep-dive, retro, post-mortem — structured content that has no forced variant framing. Tri-state is opt-in per section (Claude adds it only where a finding genuinely needs user evaluation).

Entangled questions split across iterations (the mixed mode, Step 0.5). If a concept's visual questions (which layout / design direction) and its non-visual questions (which architecture / which library / which strategy) are entangled, do NOT mix them into one layout. Split them: a decision iteration for the non-visual call, a separate design iteration for the visual one. This is the fix for the "same decision, written twice" failure — mockups do not fit into 340px variant cards, so stop trying to fit them there.

| Template | Layout signature | |---|---| | design | Fullscreen content, overlay decision panel (☰ FAB top right, collapsed by default), speech-bubble feedback dock on the 💬 FAB bottom right (same 60px circle as ☰; collapsed by default; general / per-design / per-screen / per-view comments), design switcher when ≥2 designs, view segments alongside it when ≥1 optional view (§ Views (optional)), device-view toggle bottom-left when ≥2 form factors | | decision | Sidebar (~80/~20), variant cards, tri-state per variant | | free | Sidebar (~80/~20), Claude-authored freeform body, optional tri-state per section |

design is the canonical name; prototype is accepted as a legacy alias (older pages/prompts) and is normalised to design — see deep-knowledge/templates.md § applyIterationTemplate().

Set data-iteration-template="..." on each ` — this is the **authoritative** value per iteration. applyIterationTemplate() copies the active iteration's value onto on every showIteration() call, so always **mirrors the active iteration** rather than being a page-level constant. This projection is what lets collectDecisions and all existing template-scoped CSS/JS keep branching on unchanged. See deep-knowledge/templates.md` for the full layout reference.

1a-ii. If template is design: declare the target form factors

Before writing any mockup, decide which form factors the app or site being designed actually ships on, and declare them on the iteration section: data-viewports="desktop tablet phone" (the order is the click-cycle order), plus data-viewport-default and data-orientations where they differ from the defaults. Portrait and landscape are shown side by side at once in tablet/phone mode, so a reviewer compares them without switching.

Derive the answer from evidence, not assumption — a responsive web app in the repo, a mobile manifest, the user's own words ("app", "website", "mobile-only"). When it is genuinely a desktop tool, declare nothing: the toggle then never renders and the layout is exactly what it was before device views existed. When it is phone-only, declare data-viewports="phone" and the page opens straight into the phone frames.

Declaring device views constrains the mockup markup — no `, , or inside a screen, no vh/vw units, no position: fixed, no #id selectors in mock CSS. See deep-knowledge/templates.md` § Responsive device views for what each of those does once the screen is cloned into a frame.

1b. If template is decision: pick a content variant

The decision template has six content sub-variants that shape the variant cards:

| Variant | When to use | Interactive elements | |---------|------------|---------------------| | analysis | Data analysis, metrics review, findings | Tri-state per finding, priority selectors | | plan | Implementation plans, roadmaps, migration strategies | Checkboxes to approve/skip steps, effort tags, comments per step | | concept | Architecture concepts, design proposals, feature specs | Tri-state per variant, rate options, comment fields | | comparison | Technology comparison, option evaluation | Criteria matrix, weight sliders, winner selection, tri-state per option | | dashboard | Status overviews, metric dashboards, health checks | Filters, toggles, expandable sections | | creative | Brainstorming, ideation, mind maps | Add/remove ideas, grouping, voting |

Design and free templates have no sub-variants — their body is content-specific (design = visual mockup(s); free = Claude-authored).

These are recommendations, not rigid categories. Mix elements across variants, create hybrid layouts, or invent new structures when the content calls for it.

Step 2 — Generate HTML

Build a single self-contained HTML file. Requirements:

Localisation (mandatory — do NOT hard-code German/English)

Read the [ui-locale: xx] hint injected by prompt.knowledge.dispatch. If the hint is absent, infer from the user's chat language (the language they are writing to Claude in THIS conversation). Then:

1. Set `` on the generated page.
2. Render every user-facing label (decision panel, buttons, feedback dock,

screen counter, warnings, confirms, placeholders) from the matching column of the UI Locale table in deep-knowledge/templates.md § UI Locale.

1. If the user's locale isn't a column in the table yet (fr, hi, ja,

pt-br, zh, …), Claude MUST translate every key inline at generation time and also append a new column to the table in templates.md so the next session has it cached. Fallback per-key: en value if translation is impossible.

User-authored content (concept title, subtitle, variant descriptions, pro/con lists, mockup copy, finding text, …) is always in the user's language — same rule, same locale hint. Do not mix languages inside one page.

Design

• Modern, clean design with dark/light mode toggle
• Responsive layout (works on any screen size)
• No external dependencies — all CSS/JS inline
• Professional typography, spacing, and color palette
• Subtle animations for interactions (toggle, expand, submit)

Page Header (keep it lean)

The ` inside .concept-content` renders the concept title ONCE.

• `` with the concept title
• Optional: one short subtitle line for session context. Omit if not needed.
• Theme toggle button

DO NOT render the iteration title/intro in the page header — that duplicates context and burns vertical space before the user reaches actual content. The iteration title (e.g. "Iteration 3 · Visual design concept") and its intro paragraph live INSIDE the active `, as a compact .iteration-intro` block right after the opening tag.

Decision Panel Layout (template-specific)

Panel layout depends on the template picked in Step 1a:

| Template | Panel mode | Extras | |---|---|---| | decision | Fixed sticky sidebar (~20% screen width), always visible | — | | design | Overlay panel (360px slide-in from right), toggled by the ☰ FAB top right | Feedback dock as a speech bubble anchored to the 💬 FAB bottom

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Jerry0022
• Source: Jerry0022/dotclaude
• License: MIT

Install and usage instructions live in the source repository linked above.