design-blueprint

Claude Design で作成した HTML デザイン仕様を、Codex で実装向けに調整・監査するための VRT 管理リポジトリです。

ポートフォリオリポジトリのため外部 PR、一般的なサポート依頼、機能要望、通常のバグ報告は受け付けていません。

---

DISCLAIMER

このリポジトリには、架空の医薬品・疾患リファレンスアプリ用のデザイン仕様が含まれます。仕様内の医薬品・疾患・臨床情報は架空のサンプルであり、医療判断・診断・処方・服薬判断その他のいかなる医療行為にも使用してはなりません。

This repository contains design specifications for a FICTIONAL drug and disease reference app. It is NOT medical advice and MUST NOT be used for diagnosis, treatment, prescribing, or any other medical decision.

---

主な特徴

• HTML 仕様を SSOT として管理 — 各デザインは実装リポジトリ名と同じ top-level directory に置き、pages.json で VRT 対象を宣言します。
• VRT baseline 管理 — Playwright と pixelmatch で HTML 仕様の visual regression を確認します。
• DOM ベースの HTML audit — stale text、親子構造、TOC、画面契約を scripts/html-audit-rules/*.json で固定します。
• 全状態 visual review — npm run visual:manifest -- --project <project> --page <page> で [data-frame-label] ごとの crop manifest を生成し、代表画像だけでは見落とす UI 状態を確認します。
• セッション衝突監査 — npm run session:conflict-audit -- --repo . --summary と --inventory で、この repo を cwd とした Codex session と remote/project/page alias 候補を raw transcript 非出力で集計します。
• Claude Design から Codex 実装へ橋渡し — 見た目だけでなく、Flutter 実装や mock-server fixture と照合した契約を仕様に残します。

---

動かす

# 依存解決
npm ci

# Chromium をインストール
npx playwright install chromium

# HTML audit / lint / VRT
npm run html:audit:selftest
npm run html:audit
npm run session:conflict-audit:selftest
npm run session:conflict-audit -- --repo . --summary
npm run session:conflict-audit -- --repo . --inventory
npm run visual:manifest -- --project fictional-drug-and-disease-ref-flutter --page search-screen-spec
npm run lint
npm run vrt

package.json の prepare script は Husky hook を設定します。npm install または npm ci を実行していない clone では、commit / push 時の VRT が有効になりません。

---

収録プロジェクト

Project	内容
fictional-drug-and-disease-ref-flutter/	架空医薬品・疾患リファレンスアプリの検索、詳細、ブックマーク、閲覧履歴、計算ツール、Design System
resume-flutter/	Flutter Web 履歴書の Hero、職務経歴、個人開発、その他活動、スキル、Design System
fictional-drug-and-disease-ref-sample/	VRT と audit の最小サンプル

各 project は pages.json を持つ directory として検出されます。HTML と snapshot PNG は同じ project directory に閉じ、baseline 更新は npm run vrt:approve 経由で行います。

---

アーキテクチャ

HTML 仕様、DOM audit、VRT baseline、Git hook を分離しています。画面固有の契約は HTML 本文と audit rule に置き、共通 runner は project / page を pages.json から読み込みます。

graph TD
  DESIGN["Claude Design HTML specs"]
  PAGES["pages.json — page registry"]
  AUDIT["html-audit rules — DOM contracts"]
  VRT["VRT runner — Playwright / pixelmatch"]
  SNAP["snapshots/chromium — tracked baselines"]
  HOOKS["Husky hooks"]
  DESIGN --> PAGES
  PAGES --> VRT
  DESIGN --> AUDIT
  AUDIT --> HOOKS
  VRT --> SNAP
  SNAP --> HOOKS

Loading

---

開発

# 全 HTML を整形チェック
npm run lint

# HTML 仕様の構造監査
npm run html:audit

# VRT
npm run vrt

# VRT 差分を baseline として承認
npm run vrt:approve -- --project <project> --page <page>

HTML 仕様の編集

1. 対象 project の pages.json を確認します。
2. 変更する HTML を読み、画面状態・操作状態・responsive contract を把握します。
3. 大きい仕様修正や再発防止が必要な修正では、scripts/html-audit-rules/*.json に契約を追加します。
4. VRT 失敗時は .vrt-output/report/results.json の compare_file_path、golden_file_path、actual_file_path、page_file を確認します。

ライセンス

本プロジェクトは MIT License で公開しています。

サードパーティソフトウェア

ライブラリ / アセット	ライセンス	用途
Playwright	Apache-2.0	Chromium capture / VRT 実行
pixelmatch	ISC	PNG 差分比較
pngjs	MIT	PNG 読み書き
sharp	Apache-2.0	VRT comparison image composition
htmlhint	MIT	HTML lint
Prettier	MIT	HTML formatting check
Noto Sans JP	SIL OFL 1.1	Design System preview fonts