[tkc310]

変更内容

#26 の後にマージしてください。 このブランチは #26 の上に作っています（原則の要約に #26 の追記を含めるため）。#26 がマージされるまでは、差分に #26 のコミットも出ます。

8341-ui の部品を使うプロダクトにも、デザイン原則が DESIGN.md として届くようにしました（ADR-0019）。これまでは雛形を手でコピーし、原則は GitHub のリンクで読む前提で、プロダクト側のエージェントは原則を参照できませんでした。

使い方（プロダクト側）

npx shadcn@latest add @8341/design-md   # リポジトリ直下に DESIGN.md、docs/design-principles/ に原則の全文

プロダクト用 DESIGN.md の中身

コードから読み取れない設計の考え方だけ を書く構成にしました。トークンの値や部品の一覧はコードが正なので載せません。

1. プロダクトの前提（誰が・何のために・ドメイン・使う場面と機器・アクセシビリティ目標）
2. 画面領域ごとの UI の方向性とサービス種別
3. このプロダクトで大事にすること（体験の性格・言葉づかい・画面の構成・避けること）
4. 採用したルールと外したもの（外した必須の理由、8341-ui に足したものの「なぜ」）
5. デザイン原則（<!-- auto:principles -->。判断の順序・ルールの強さ・UI の方向性と 15 の原則の必須）

冒頭の「エージェントへ」で、空欄は hearing.md の項目で聞いて埋めること、詳しくは docs/design-principles/ の該当節だけを読むことを指示しています。

仕組み

• scripts/sync-product-design.ts: 原則の要約を docs/design-principles/ から生成（make design-md）。make check で鮮度を検査。15 の原則すべてで、必須の件数が元の文書と一致することを確認済み
• packages/ui/scripts/build-registry-assets.ts（旧 build-registry-css.ts）: DESIGN.md と原則も registry-assets/ に作る。原則の文書からはファクトリーの部分を除く。仮のトークンで実行し、配るファイルの一覧が registry.json と一致することを確認済み
• generate-registry.ts: design-md（registry:file、target は ~/DESIGN.md と ~/docs/design-principles/…。~ はプロジェクトのルート）
• design-principles/README の、配布先で切れるリンク（../ai-agents.md）を GitHub の URL にし、「プロダクトで使う」節を足した

Storybook プレビュー

なし（コンポーネントとトークンの見た目は変更なし）

完了の定義

• PR のタイトルが Conventional Commits の形式
• make check と make test が通る（CI で確認。sync-product-design --check・generate-registry --check・スキルとスライドの検査は手元で通過）
• changeset を追加した（patch。レジストリに item を追加）
• ライト / ダークの両方で見た目を確認した（見た目の変更なし）
• キーボードで操作でき、フォーカス表示が見える（該当なし）
• 新しい semantic カラーを足した場合 → 追加なし
• 値や方針を変えた場合、docs/decisions/ に ADR を足した（0019）

マージ後、main の CI が shadcn build で r/design-md.json を公開します（~ の target はこのリポジトリで初めて使うため、公開後に実際の取り込みを確認するのが安全です）。

改善ループ

• docs/improvement/log.md に 1 行追記した
• 再発防止として追加したもの: sync-product-design.ts --check（make check）、配る原則のファイル一覧の registry.json での追従

---

Generated by Claude Code