create-design-doc

create-design-doc

Read the input document (idea/requirements document) passed in $ARGUMENTS,as a UX/UI designer expertgenerate a full set of UI/UX design materials.

The reason this skill exists is to create design materials that show "what it looks like, in what situations, and how it is used" before prototype development, and to detect expectation gaps before development by incorporating user feedback and revisions. Therefore, deliverables must alwaysinclude "Assumptions and Interpretations" at the beginning, and **"Feedback Perspectives" at the end**.

The assumed usage scenario is a format where "the user is the PO (Product Owner), and the AI brings materials to the approval meeting and explains them."The main focus of review is storyboard.png(a single tall image that explains each screen's display elements in Japanese along the flow of the main scenario), andwireframes/*.html と screens/*.png are positioned as its components/implementation materials.

Reason for adopting HTML wireframes instead of Figma

Figma has no file generation API and is unsuitable for agent generation. HTML is adopted because it allows browser checking, screenshot documentation, and direct reuse for implementation.

Recommended execution timing

It is optimalbeforeentering prototype/full development, once the idea document and validation plan (including PoC results) are settled. If there is a flow for defining behavior and detailed specifications,execute this skill immediately before it, and use the approved materials as input for specification definition. For the same point on the planning side, refer to create-pitch-deck/SKILL.md in the "Recommended execution timing" section.

Persona

The executor acts as a UX/UI designer expert and always works while asking the following questions.

When, where, and for what purpose will the intended user open this screen?
Is the purpose of the screen narrowed down to one? Is the priority of information appropriate?
Are states (empty, loading, error, normal) taken into consideration?
Are colors, typography, and spacing consistent (not deviating from design tokens)?
Does the experience break down between PC and mobile?
Is the explanation such that the PO can understand at first glance "why this screen behaves this way"?(The explanation of display elements in the storyboard is the core of this skill)

Coordination: consistency with create-pitch-deck (concept-brief.md, recommended execution order)

This skill and create-pitch-deck are consistent through the shared agreement document concept-brief.md (the schema is references/concept-brief-schema.md). Planning (create-pitch-deck) and the design (this skill) are artifacts created separately, and this is a mechanism to prevent situations where "what they say is contradictory"; both skills have the same procedure (equivalent to Step 1 and Step 9).

Recommended execution order: create-design-doc → create-pitch-deck。 create-pitch-deck incorporates this skill's artifact (storyboard.png / screens/*.png) into the "Screens and Operation Flow" slide, so running this skill first makes generation on the pitch side smoother. As for concept-brief.md, whichever is run first drafts it.

Even in the reverse order (create-pitch-deck has already been run first), there is no problem. After running this skill, create-pitch-deck をre-run with the screen materials in place, the "Screens and Operation Flow" slide is inserted (for details, see create-pitch-deck/SKILL.md 's integration section).
To reliably share between the two skills, in both invocationsspecify the same --brief <path> explicitly (because the default values differ directly under each skill's artifact directory, they are not shared automatically without specification).--brief It is recommended to specify directly under the input document directory(example: ideas/<name>/concept-brief.md). By placing it in the same location as the input document, the side that runs later can reliably discover it --output regardless of the default value of .

Usage

Pass the path of the idea/requirements document (directory or file list) as an argument. If there is no argument or it is ambiguous, confirm with the user in Step 2.

If the output directory is not specified by the user, design/
--brief <path> can specify the location of concept-brief.md (default <output>/concept-brief.md. As above, specifying directly under the input document directory is recommended)
Priority order when reading large input documents: When a directory is passed, first README.md(overview/ status) → judgment gate "Judgment" section (finalized conclusions) → Go/No-Go criteria and success criteria comparison table (02-poc-plan.md etc.) in that order, then read the main text. By grasping the key points quickly and then checking the details, rework can be reduced even when there are many documents
Usage example: When using the idea consideration flow (01-brainstorm.md 〜 03-poc/) as input, ideas/<name>/ pass it as is

Artifacts

File	Content	Positioning
`design/storyboard.html` → `design/storyboard.png`	A single vertical page explaining each screen one by one along the flow of the main scenario (templates/storyboard-template.html）	Main focus of the review
`design/design-doc.md`	Premises and interpretation / Assumed users and main scenario / Screen list (display elements column required) / Information design / Design tokens / Feedback perspectives. For detailed structure, see references/design-doc-structure.md	Review aid/record
`design/flow.png`	Screen transition diagram (overall overview). A single inline SVG (templates/flow-diagram-template.html) converted to PNG with Playwright. Do not duplicate roles with storyboard (seereferences/design-doc-structure.md )	For grasping the overall structure
`design/wireframes/*.html`	Main-screen self-contained HTML wireframes. Conventions are references/wireframe-guidelines.md	Implementation assets
`design/screens/*.png`	PC/mobile screenshots of each wireframe (Playwright). Also serve as storyboard parts	Implementation assets / storyboard parts

Flow

Step 1: Check concept-brief.md

--brief Check the path specified by （default <output>/concept-brief.md. Recommended: directly under the input document directory).

If it exists: Read it as required input. If you feel there is a contradiction with the results of the document reading in Step 2, do not overwrite concept-brief.md without permission; clarify the contradiction and confirm with the user.
If it does not exist: Based on the document reading in Step 2, references/concept-brief-schema.md draft it using the template . Attach sources to each item. Present it to the user at the same time as the outline confirmation in Step 3, and write out the finalized version after obtaining approval.

Step 2: Read the input documents

Read the target documents and grasp the purpose, requirements overview, PoC results, and unresolved questions (for priorities, see Usage).

Step 3: Present the screen list + main scenario outline and obtain user approval (mandatory gate)

Present to the user together the screen list (one line for each screen's purpose), the main scenario (phase breaks and step overview for each phase), and the Step 1 concept-brief.md draft (if drafted). Make the phase breaks consistent with "Assumed users and main scenarios" in design-doc.md and the "phase headings" in storyboard.html.Do not proceed to Step 4 until approval is obtained. Do not generate without approval.

Step 4: Prepare a venv and install Playwright

First, check for the existence of python3 .

command -v python3 >/dev/null || echo "python3 が見つからない"

If not installed, stop the process and explain how to install it (macOS: brew install python3. For other environments, follow the official instructions for each environment).

python3 -m venv "_/design-doc/.venv" 2>/dev/null || true
"_/design-doc/.venv/bin/pip" install -q playwright
"_/design-doc/.venv/bin/playwright" install chromium

To avoid polluting the global environment, always install into a venv dedicated to the skill. The venv location (_/design-doc/.venv) may be a temporary work area outside the repository (e.g., /tmp/<work>/venv), and the path is not fixed.If a venv has already been created in another skill or another session (with Playwright installed), you may reuse it as is without recreating it（pip install is an idempotent operation that does not break the existing environment, so it is harmless to run without checking for existence).playwright install chromium downloads the browser body (over 100MB), so it takes time.

In the command examples below, the venv Python is denoted as "${DESIGN_DOC_VENV_PY}"(e.g., _/design-doc/.venv/bin/python3).

Step 5: Generate

Order: screen transition diagram → wireframes → screenshots → Storyboard → design-doc.md。

Screen transition diagram: templates/flow-diagram-template.html and rewrite the lanes, nodes, edges, and legend within a single <svg> (do not use a hybrid of div lanes and a separate svg).
```
"${DESIGN_DOC_VENV_PY}" "${CLAUDE_SKILL_DIR}/scripts/capture_screenshot.py" \
  --html "<output>/flow.html" --out "<output>/flow.png" --width 1440 --height 720 --full-page
```
${CLAUDE_SKILL_DIR} is not expanded / in an unconfigured environment, read it as the absolute path of the directory where this SKILL.md file is located (e.g., skills/create-design-doc）。
Wireframe: for each screen templates/wireframe-template.html and copy references/wireframe-guidelines.md rewrite to the screen content according to (design tokens must be the same values as design-doc.md.position: sticky / fixed is not used).

Screenshot: capture both PC and mobile for each wireframe.

"${DESIGN_DOC_VENV_PY}" "${CLAUDE_SKILL_DIR}/scripts/capture_screenshot.py" \
  --html "<wireframe.html>" --out "<output>/screens/<screen>-desktop.png" --width 1440 --height 900 --full-page
"${DESIGN_DOC_VENV_PY}" "${CLAUDE_SKILL_DIR}/scripts/capture_screenshot.py" \
  --html "<wireframe.html>" --out "<output>/screens/<screen>-mobile.png" --width 375 --height 812 --full-page

Storyboard (main deliverable): templates/storyboard-template.html and, following the phase divisions and scenario order approved in Step 3, arrange the following for each phase.
- ①Screen screenshot of each step (<img src="screens/<screen>-desktop.png"> referenced in . Do not use iframe or inline combination of wireframe markup. The reason is templates/storyboard-template.html see the comment at the beginning)
- ②Screen name and purpose (one heading line)
- ③Japanese description of displayed elements(what is displayed on this screen, and what the user sees and operates. Align with the "Displayed elements" column in the screen list of design-doc.md)
- ④Transition condition to the next screen (arrow + label)
At phase transitions, insert the .phase-title heading.
```
"${DESIGN_DOC_VENV_PY}" "${CLAUDE_SKILL_DIR}/scripts/capture_screenshot.py" \
  --html "<output>/storyboard.html" --out "<output>/storyboard.png" --width 1000 --full-page \
  --allow-local-refs
```
storyboard.html は screens/*.png is relatively referenced, so add --allow-local-refs (permitted targets are <img src> / srcset / CSS image references, only raster images (.png/.jpg/.jpeg/.gif/.webp) that actually exist under the document directory. Embedded references such as iframe/object, absolute paths,file://・../ escape, and external URLs continue to be blocked). Do not add it for capturing wireframes or flow.html.
design-doc.md: references/design-doc-structure.md Create with the section structure of. The "Displayed elements" column in the screen list is mandatory. Feedback perspectives should be 3 to 5 items, and should be concrete questions you actually want the user to confirm.

Step 6: Verify

Wireframe, flow.html, storyboard.html allmechanically verify layout breakage for (flow.html must also always be executed like wireframe).

# ワイヤーフレーム・flow.html（strict: data URI とページ内 fragment のみ許容）
"${DESIGN_DOC_VENV_PY}" "${CLAUDE_SKILL_DIR}/scripts/check_overflow.py" "<html>"
# storyboard.html（screens/*.png の相対参照のみ追加許容）
"${DESIGN_DOC_VENV_PY}" "${CLAUDE_SKILL_DIR}/scripts/check_overflow.py" "<output>/storyboard.html" --allow-local-refs

If FAIL, fix the HTML, regenerate, and then rerun the validator. Do not treat it as complete until it PASSes. In addition, visually check all screenshots (both PC/mobile) and storyboard.png, and references/wireframe-guidelines.md confirm that there is no breakage according to the "Mobile screenshot visual check perspectives" in .

Step 7: Search for create-pitch-deck deliverables

create-pitch-deck whether it was executed first and a self-contained HTML slide has already been generated, search with Glob(default path _/pitch-deck/*.html should not be hard-coded directly. This is because the user may have changed the --output path.create-pitch-deck does not generate PPTX). If found, reference it in the Step 8 cross-consistency check. If not found, treat it as "create-pitch-deck not executed".

Step 8: Cross-consistency check with concept-brief.md

Cross-check the generated design-doc.md, screen list, and storyboard against concept-brief.md.

Whether there are contradictions in target users, main scenarios, scope, and tone & manner
Step 7 で create-pitch-deck If the deliverables of are found, cross-check the consistency between winning strategy and screen design / inclusion of out-of-scope features / inconsistencies in terminology and naming / missing correspondence between issues and solution UI

If a contradiction is detected, do not automatically fix either concept-brief.md or this deliverable; present to the user whether to "fix concept-brief.md or fix this deliverable".

Step 9: Feedback reflection loop

When reflecting user feedback, modify the relevant wireframe, storyboard, or doc (and concept-brief.md if necessary), then re-execute Steps 5–8.

Verification

After generation, always run the validator and confirm completion with the following 5-stage gate (.claude/rules/verification.md compliant).

Identify: check_overflow.py Treat execution of and its exit code as completion (execute for all of wireframe, flow.html, and storyboard.html)
Execute: "${DESIGN_DOC_VENV_PY}" "${CLAUDE_SKILL_DIR}/scripts/check_overflow.py" "<html>" Run newly for all targets
Read: Check the entire output (PASS/FAIL, failure list) and the exit code
Verify: Confirm that there are 0 failures, that there is no breakage upon visual inspection of both PC/mobile screenshots and storyboard.png, and that there are no unresolved contradictions in the Step 8 cross-consistency check
Declare: Declare completion only when the validator PASSes for all targets and visual inspection and cross-consistency check are complete. Do not claim completion based on guesses such as "it probably isn't broken".

check_overflow.py At minimum, check the following.

There is no overflow that induces horizontal scrolling on both PC (1440px) and mobile (375px)
Self-contained in a single file (the only references allowed in the default strict mode are data URIs of permitted MIME types and in-page fragments. In addition to external URLs, relative paths, absolute paths, andfile:// are also detected as violations because they would be missing or unresolvable in single-file distribution). At runtime as well, block and record all requests other than to the document body itself, and FAIL if there is even one
Validate only storyboard.html with --allow-local-refs (<img src="screens/..."> / srcset / CSS image references: only raster images (.png/.jpg/.jpeg/.gif/.webp) that actually exist under the document directory are additionally allowed. Embedded references such as iframe/object, absolute paths,file://・../ escape, and missing references are not allowed)

Common failures

Problem	Workaround
Dummy data remains as placeholders such as "Sample" or "Test"	Use specific, realistic content such as plausible product names, prices, and dates
Horizontal scrolling occurs on mobile	`check_overflow.py` always perform, and`@media (max-width: 480px)` etc. to make it single-column
In mobile full-page screenshots, the bottom navigation etc. floats at an awkward height	`position: sticky` / `fixed` do not use. Use static placement within the normal flow (see`templates/wireframe-template.html` reference)
The token values differ between design-doc.md and the wireframes	`references/design-doc-structure.md` design tokens and `wireframes/*.html` の `:root` to the same values
The storyboard becomes just a collection of screens and does not convey the "flow"	Always include phase headings and transition conditions (arrows + labels), and arrange them in the scenario order
The feedback perspectives become formulaic	Make 3–5 items into "specific questions you actually want to confirm with users"

Notes

wireframes/*.html・flow.html・storyboard.html CDN, external fonts, and external images must not be used at all, and JavaScript itself is completely prohibited (<script> is not allowed regardless of whether there is body text. inline event handler attributes andjavascript: URLs are also not allowed. Complete using only static visual expression). Local file references are also prohibited in principle (images must be embedded as data URIs). The exception is only the relative reference to screens/*.png in storyboard.html, and during validation and capture --allow-local-refs is explicitly allowed (the permitted targets are limited to raster images from <img src> / srcset / CSS image references. Embedding local HTML via iframe/object etc. is not allowed)
venv is a build tool and not a generated artifact._/ commit it if placed under (_/ は .gitignore ). If placed in a temporary area outside the repository, it is not subject to commit in the first place
Output destination directory (design/ etc.) if it does not exist, create it with mkdir -p before writing out

Final report

When complete, briefly report the following.

Absolute paths of the generated deliverables (storyboard.png / design-doc.md / flow.png / wireframes / screens)
validation result (PASS/FAIL for each target)
Path of concept-brief.md and whether it is newly drafted / loaded from existing
Step 8 mutual consistency check result (presence/absence of contradictions,create-pitch-deck presence/absence of deliverables)
One sentence summarizing the design policy

Reference files

Read only when necessary.

references/design-doc-structure.md — Section structure of design-doc.md, design token description format, and role division of flow/storyboard
references/wireframe-guidelines.md — Required requirements for HTML wireframes, prohibition of position sticky, and mobile visual confirmation perspectives
references/concept-brief-schema.md — Schema of concept-brief.md (create-pitch-deck shared with)
templates/flow-diagram-template.html — Template for a screen transition diagram (single inline SVG)
templates/wireframe-template.html — Template for a wireframe
templates/storyboard-template.html — Template for a storyboard (the main review artifact)

Execution in a sandbox environment

The main flow of this skill (Steps 1–3, HTML editing in Step 5, Step 9) can be executed in a sandbox environment. Network access is required only for Step 4's pip install playwright と playwright install chromium(only during initial setup; not needed from the second time onward when reusing an already installed venv), and the Playwright launch process in Steps 5–6 (it only operates a local Chromium and performs no external communication, but the initial browser download requires network access). Only these commands are executed with the sandbox disabled. The default output destination (design/) and the default brief path are both inside the workspace, but --output / --brief if you specify an absolute path or a relative path containing ../ , writing outside the workspace may occur, so in that case choose the output destination at your own responsibility.