From 616d1a7d9625b11de7c73a407cb3d5b5d51e3c27 Mon Sep 17 00:00:00 2001 From: Kota Shirakura Date: Sat, 23 Aug 2025 20:33:22 +0900 Subject: [PATCH] chore(bmad): automate wireframe screenshot embedding + add screen transitions section - UX agent: add create-front-end-spec-from-wireframe command and dependency - New task: create-front-end-spec-from-wireframe.md (Playwright screenshot + template render) - Template: add Wireframe Screenshots section and Screen Transitions section - Installer: include prewarm for Python Playwright and conventions for output paths --- bmad-core/agents/ux-expert.md | 2 + .../create-front-end-spec-from-wireframe.md | 65 +++++++++++++++++++ bmad-core/templates/front-end-spec-tmpl.yaml | 38 +++++++++++ tools/installer/lib/file-manager.js | 20 ++++++ 4 files changed, 125 insertions(+) create mode 100644 bmad-core/tasks/create-front-end-spec-from-wireframe.md diff --git a/bmad-core/agents/ux-expert.md b/bmad-core/agents/ux-expert.md index 47f36b23..cc71b4ec 100644 --- a/bmad-core/agents/ux-expert.md +++ b/bmad-core/agents/ux-expert.md @@ -55,6 +55,7 @@ persona: commands: - help: Show numbered list of the following commands to allow selection - create-front-end-spec: run task create-doc.md with template front-end-spec-tmpl.yaml + - create-front-end-spec-from-wireframe: run task create-front-end-spec-from-wireframe.md - generate-ui-prompt: Run task generate-ai-frontend-prompt.md - exit: Say goodbye as the UX Expert, and then abandon inhabiting this persona dependencies: @@ -64,6 +65,7 @@ dependencies: - create-doc.md - execute-checklist.md - generate-ai-frontend-prompt.md + - create-front-end-spec-from-wireframe.md templates: - front-end-spec-tmpl.yaml ``` diff --git a/bmad-core/tasks/create-front-end-spec-from-wireframe.md b/bmad-core/tasks/create-front-end-spec-from-wireframe.md new file mode 100644 index 00000000..c16a5751 --- /dev/null +++ b/bmad-core/tasks/create-front-end-spec-from-wireframe.md @@ -0,0 +1,65 @@ + + +# Create Front-end Spec from Local Wireframe (Auto Screenshot) + +## Purpose +ローカルHTMLワイヤーフレームを自動でヘッドレスブラウザで撮影し、スクリーンショットをフロントエンド仕様に埋め込んだうえで、テンプレートに沿って仕様書を生成します。 + +## Inputs +- screen_id: 画面ID（例: AD-033） +- wireframe_html_path: ローカルHTMLワイヤーフレームの絶対パス +- project_root: プロジェクトルートの絶対パス（例: /Users/xxx/work/your-project） + +## Defaults +- 仕様書出力先: `documents/frontend_spec/{{screen_id}}.md` +- スクリーンショット出力先: `documents/assets/{{screen_id}}-wireframe.png` +- テンプレート: `{root}/templates/front-end-spec-tmpl.yaml` + +## Steps +1. Python Playwright をプリウォーム（環境に未導入なら導入） +2. Chromium で `file://` スキームのローカルHTMLを開き、1280x720 で撮影 +3. 画像を `documents/assets/{{screen_id}}-wireframe.png` に保存 +4. テンプレート `front-end-spec-tmpl.yaml` を用いて仕様書を作成 + - 変数: `screen_id`, `wireframe_screenshot_relpath`（例: `../assets/{{screen_id}}-wireframe.png`） +5. 生成された仕様書に「Wireframe Screenshots」セクションが含まれることを確認 + +## Execution Notes +- 撮影後に画像パスを相対に変換し、仕様書から参照可能にします。 +- 既存ファイルがある場合は追記/更新の方針をユーザーに確認してください。 + +## Commands +```bash +# 1) Ensure playwright env is ready (idempotent) +python3 -m pip install --user playwright +python3 -m playwright install chromium + +# 2) Take screenshot +python3 - <<'PY' +from playwright.sync_api import sync_playwright +import os +screen_id = os.environ.get('BMAD_SCREEN_ID') +html = os.environ.get('BMAD_WIREFRAME_HTML') +project_root = os.environ.get('BMAD_PROJECT_ROOT') +out_abs = os.path.join(project_root, 'documents', 'assets', f"{screen_id}-wireframe.png") +os.makedirs(os.path.dirname(out_abs), exist_ok=True) +with sync_playwright() as p: + b = p.chromium.launch() + page = b.new_page(viewport={"width":1280, "height":720}) + page.goto(f"file://{html}") + page.wait_for_timeout(1200) + page.screenshot(path=out_abs) + b.close() +print(out_abs) +PY + +# 3) Render from template (tooling-dependent - example placeholder) +# bmad render --template {root}/templates/front-end-spec-tmpl.yaml \ +# --out documents/frontend_spec/${BMAD_SCREEN_ID}.md \ +# --var screen_id=${BMAD_SCREEN_ID} \ +# --var wireframe_screenshot_relpath=../assets/${BMAD_SCREEN_ID}-wireframe.png +``` + +## Elicitation +本タスクは非対話で実行可能ですが、出力先が既存の場合は上書き可否の確認が必要です。 + + diff --git a/bmad-core/templates/front-end-spec-tmpl.yaml b/bmad-core/templates/front-end-spec-tmpl.yaml index 1cb8179a..7e66e3e4 100644 --- a/bmad-core/templates/front-end-spec-tmpl.yaml +++ b/bmad-core/templates/front-end-spec-tmpl.yaml @@ -102,6 +102,39 @@ sections: **Breadcrumb Strategy:** {{breadcrumb_strategy}} + - id: screen-transitions + title: Screen Transitions + instruction: | + Document how users move between screens at an application level. + + - Use Mermaid flow diagrams to visualize transitions + - Include decision points (permissions, confirmations) as diamond nodes + - Prefer concise labels for nodes and edges + - Reflect destructive actions (disable/delete) as in-place flows if no navigation occurs + sections: + - id: global-transitions-diagram + title: Global Transitions Diagram + type: mermaid + mermaid_type: graph + template: "{{screen_transitions_diagram}}" + examples: + - | + graph TD + A[Entry: Menu / Deep Link] --> P{Permission OK?} + P -- No --> X[403 / Redirect] + P -- Yes --> L[/Screen List/] + L -- Create --> M[Type Select Modal] + M --> N[/Screen New/] + N -- Save/Cancel --> L + L -- Edit --> E[/Screen Edit/:id/] + E -- Save/Cancel --> L + L -- Disable --> D{Confirm?} + D -- Yes --> API1[POST /disable]\nSuccess → Reload List + D -- No --> L + L -- Delete --> C{Confirm?} + C -- Yes --> API2[DELETE /:id]\nSuccess → Reload List + C -- No --> L + - id: user-flows title: User Flows instruction: | @@ -144,6 +177,11 @@ sections: Clarify where detailed visual designs will be created (Figma, Sketch, etc.) and how to reference them. If low-fidelity wireframes are needed, offer to help conceptualize layouts for key screens. elicit: true sections: + - id: wireframe-screenshots + title: Wireframe Screenshots + instruction: | + If a local HTML wireframe exists, capture a screenshot automatically and embed it here. Provide relative path usable from the spec location. + template: "![{{screen_id}} Wireframe]({{wireframe_screenshot_relpath}})" - id: design-files template: "**Primary Design Files:** {{design_tool_link}}" - id: key-screen-layouts diff --git a/tools/installer/lib/file-manager.js b/tools/installer/lib/file-manager.js index df386da8..a872156c 100644 --- a/tools/installer/lib/file-manager.js +++ b/tools/installer/lib/file-manager.js @@ -115,6 +115,26 @@ class FileManager { files: [], }; + // Prewarm setup to reduce first-run latency for UX wireframe flows + // These commands are safe to run multiple times. + manifest.prewarm = [ + { + name: 'python-playwright', + description: + 'Install Python Playwright and Chromium browser for headless screenshots', + commands: [ + 'python3 -m pip install --user playwright', + 'python3 -m playwright install chromium', + ], + }, + ]; + + // Conventions for auto-generated UI specs and assets + manifest.conventions = { + frontend_spec_output: 'documents/frontend_spec/{{screen_id}}.md', + wireframe_screenshot: 'documents/assets/{{screen_id}}-wireframe.png', + }; + // Add file information for (const file of files) { const filePath = path.join(installDir, file);