feat(registry): 8341-ui を使うプロダクトに DESIGN.md と design-principles を配る @8341/design-md を追加

.changeset/product-design-md.md

@@ -0,0 +1,5 @@
+---
+'8341-ui': patch
+---
+
+レジストリに `@8341/design-md` を追加しました。`npx shadcn@latest add @8341/design-md` で、リポジトリ直下にプロダクト用の DESIGN.md、`docs/design-principles/` にデザイン原則の全文が置かれます。DESIGN.md には、コードから読み取れない設計の考え方（プロダクトの前提、画面領域ごとの UI の方向性とサービス種別、大事にすること、外した必須）と、原則の必須の要約だけを書きます。

.claude/skills/ds-build-ui/SKILL.md

@@ -9,8 +9,8 @@ description: このデザインシステムを使って画面やフォームを
 
 文書は大きいので、**全文ではなく必要な節だけ** を読む（見出しで探して、その節を読む）。
 
-0. プロダクトの DESIGN.md。無ければ `templates/PRODUCT-DESIGN.md` から作り、UI の方向性とサービス種別を決める。`design-principles` スキルの手順（ヒアリング → 方向性 → 特化ルール → 原則 → WCAG）に従う
-1. `DESIGN.md` は次の節だけ: 「9. Agent Prompt Guide」のクイックリファレンス、「7. Do's and Don'ts」、「4. Component Stylings」の一覧と、使うコンポーネントの節。色や余白を決めるときだけ「2. Color Palette & Roles」「5. Layout Principles」
+0. プロダクトの DESIGN.md の「プロダクトの前提」〜「採用したルールと外したもの」。無ければ `npx shadcn@latest add @8341/design-md` で置き（このリポジトリの中なら雛形は `templates/PRODUCT-DESIGN.md`）、（ ）のままの欄を `docs/design-principles/hearing.md` の項目で聞いて埋める
+1. 8341-ui の `DESIGN.md`（このリポジトリ直下）は次の節だけ: 「9. Agent Prompt Guide」のクイックリファレンス、「7. Do's and Don'ts」、「4. Component Stylings」の一覧と、使うコンポーネントの節。色や余白を決めるときだけ「2. Color Palette & Roles」「5. Layout Principles」
 2. `docs/rulebook/02-accessibility.md` の「必須ルール」の表（A1〜A16）
 3. フォームやボタンの文言を書くときだけ `docs/rulebook/05-writing.md`
 4. 使うコンポーネントのストーリー（`packages/ui/src/components/ui/<Name>/index.stories.tsx`）

DESIGN.md

@@ -19,7 +19,7 @@
 
 - **基盤のデザインシステム**: 特定のプロダクトに属さず、複数のプロダクトで使い回す
 - **画面設計のルール**: [design-principles](./docs/design-principles/README.md) を採用する。適用順は UI の方向性 → サービス別の特化ルール → 原則 → WCAG 2.2
-- **UI の方向性とサービス種別**: 基盤では決めない。各プロダクトの DESIGN.md で決める（雛形: `templates/PRODUCT-DESIGN.md`）
+- **UI の方向性とサービス種別**: 基盤では決めない。各プロダクトの DESIGN.md で決める（`npx shadcn@latest add @8341/design-md` で置く。雛形は `templates/PRODUCT-DESIGN.md`）
 - **原則とトークン・コンポーネントの対応**: `docs/rulebook/01-principles.md`
 - **必須ルールを外した項目**: なし。タップ領域 44px、文字のコントラストを一律 4.5:1、リンクの下線必須、二重のフォーカス線は、design-principles の必須より厳しくしている
 

Makefile

@@ -74,8 +74,9 @@ tokens: ## トークンの CSS・Tailwind テーマ・Figma JSON を生成する
 palette: ## palette.config.json から primitive カラーを生成し直す
 	pnpm --filter $(TOKENS) palette
 
-design-md: ## DESIGN.md の表をトークンから更新する
+design-md: ## DESIGN.md の表をトークンから、プロダクト用の雛形の原則を docs/design-principles から更新する
 	pnpm --filter $(TOKENS) design-md
+	node scripts/sync-product-design.ts
 
 tw-merge: ## クラス統合の設定（tw-merge-config.ts）を更新する
 	pnpm --filter $(TOKENS) tw-merge

README.md

@@ -100,6 +100,14 @@ export function SignUp() {
 }
 ```
 
+**4. DESIGN.md を置く** — 画面を作る人とエージェントが、コードから読み取れない設計の考え方（プロダクトの前提と、[デザイン原則](./docs/design-principles/README.md)の必須）を共有するためのファイルです。
+
+```bash
+npx shadcn@latest add @8341/design-md   # リポジトリ直下に DESIGN.md、docs/design-principles/ に原則の全文
+```
+
+DESIGN.md の「プロダクトの前提」「画面領域ごとの方向性」を埋めてから画面を作ります（エージェントに頼むと、足りない項目を聞きながら埋めます）。トークンや部品の一覧は書きません。それはコードが正です。
+
 <details>
 <summary>npm パッケージとして使う（公開した場合）</summary>
 

docs/decisions/0019-product-design-md.md

@@ -0,0 +1,24 @@
+# 0019 8341-ui を使うプロダクトに DESIGN.md と design-principles をレジストリで配る
+
+- 日付: 2026-10-23
+- 状態: 採用
+
+## 背景
+UI の方向性とサービス種別は各プロダクトの DESIGN.md で決める（ADR-0007）。しかし 8341-ui の部品を shadcn で取り込んだプロダクトには、原則もプロダクト用 DESIGN.md も届かなかった。雛形 `templates/PRODUCT-DESIGN.md` を手でコピーし、原則は GitHub のリンクで読む前提で、プロダクト側のエージェントは原則を参照できなかった。ファクトリーで作ったデザインシステムには原則が入るのに、部品を使うだけのプロダクトには入らない差があった。
+
+## 決定
+- shadcn のレジストリに `@8341/design-md`（`registry:file`）を足す。`npx shadcn@latest add @8341/design-md` で、リポジトリ直下に `DESIGN.md`、`docs/design-principles/` に原則の全文が置かれる（`target` の `~` はプロジェクトのルート）
+- プロダクト用 DESIGN.md には **コードから読み取れない設計の考え方だけ** を書く。プロダクトの前提、画面領域ごとの UI の方向性とサービス種別、このプロダクトで大事にすること、外した必須とその理由、8341-ui に足したものの理由。トークンの値や部品の一覧は書かない（コードが正）
+- DESIGN.md の「デザイン原則」は `<!-- auto:principles -->` にし、`scripts/sync-product-design.ts` が `docs/design-principles/` から判断の順序・ルールの強さ・UI の方向性と各原則の「必須」を生成する。`make check` で鮮度を検査する
+- 配るファイルは `packages/ui/scripts/build-registry-assets.ts`（旧 `build-registry-css.ts`）が `registry-assets/` に作る。原則の文書からは `<!-- factory:start -->` 〜 `<!-- factory:end -->` を取り除く（利用側はファクトリーではない）
+- 配る原則のファイル一覧は `generate-registry.ts` が `docs/design-principles/` から作り、`registry.json` の `--check` で追従させる
+
+## 理由
+- 部品の取り込みと同じ shadcn の仕組みに乗せれば、プロダクト側の手順が 1 行増えるだけで済み、版を固定したレジストリ（`r/v<版>/`）で原則の版もそろう
+- トークンや部品の仕様を DESIGN.md に写すと、コードと二重管理になり古くなる。コードから読み取れない判断の軸だけを置けば、DESIGN.md は短く保て、エージェントが毎回読んでも負担が小さい（ADR-0018）
+- 原則の必須の要約を生成にすれば、原則を直したときにプロダクト用の雛形が古くならない
+
+## 影響・トレードオフ
+- 原則の更新を取り込むと DESIGN.md が上書きになる。手順（作業用のブランチで取り込み、`auto` の範囲と `docs/design-principles/` だけを採用する）を DESIGN.md の末尾に書いた
+- npm パッケージで使う場合は、この仕組みは使えない（shadcn のレジストリだけ）。必要になったら別の配り方を検討する
+- 原則の必須は要約で、推奨・レビュー項目・理由は `docs/design-principles/` の全文を読む

docs/decisions/README.md

@@ -22,6 +22,7 @@
 | [0016](./0016-component-structure.md) | コンポーネントのディレクトリ構造を PascalCase とコロケーションにする | 採用 |
 | [0017](./0017-slides.md) | スライドを HTML のデッキとしてトークンから組む（ds-slides） | 採用 |
 | [0018](./0018-progressive-disclosure.md) | エージェント向けの文書を必要なときだけ読み込む構成にする | 採用 |
+| [0019](./0019-product-design-md.md) | 8341-ui を使うプロダクトに DESIGN.md と design-principles をレジストリで配る | 採用 |
 
 ## テンプレート
 

docs/design-principles/README.md

@@ -97,7 +97,7 @@ WCAG 2.2 の Level A と AA の達成基準のうち、配色、文字、レイ
 
 #### スキルとして使う（Claude Code・Cursor・Codex）
 
-このディレクトリのルールは、このリポジトリのスキルとして使える。スキルの置き場所とエージェントごとの読み込み方は [`docs/ai-agents.md`](../ai-agents.md) に書いている。
+8341-ui のリポジトリでは、このディレクトリのルールをスキルとして使える。スキルの置き場所とエージェントごとの読み込み方は [8341-ui の docs/ai-agents.md](https://github.com/tkc310/8341-ui/blob/main/docs/ai-agents.md) に書いている。
 
 **スキル**: `design-principles`（`.claude/skills/design-principles/SKILL.md`）
 - デザイン作業時に読み込まれる手順とルーター
@@ -114,7 +114,11 @@ WCAG 2.2 の Level A と AA の達成基準のうち、配色、文字、レイ
 **新しいデザインシステムを丸ごと作る**: `ds-factory` スキル（デザインシステムファクトリー）が、このルールとヒアリングの結果から、8341-ui をひな形に別リポジトリのデザインシステムを生成する（[`docs/factory.md`](../factory.md)）。
 
 <!-- factory:end -->
-**ルールへのフィードバック**: 対話中にルールの改善点（ギャップ、曖昧さ、適合しないルール、繰り返される例外）が見つかった場合、エージェントがユーザーに伝え、このリポジトリの `docs/design-principles/` への編集を提案する。プロダクト固有の例外は、そのプロダクトの DESIGN.md に記録する。
+#### 8341-ui を使うプロダクトで使う
+
+`npx shadcn@latest add @8341/design-md` を実行すると、このディレクトリがプロダクトの `docs/design-principles/` に、各ルールの必須をまとめた DESIGN.md がリポジトリ直下に置かれる。プロダクトの前提（UI の方向性、サービス種別、外した必須）は、その DESIGN.md に書く。配られたこのディレクトリは直接編集しない。
+
+**ルールへのフィードバック**: 対話中にルールの改善点（ギャップ、曖昧さ、適合しないルール、繰り返される例外）が見つかった場合、エージェントがユーザーに伝え、[8341-ui](https://github.com/tkc310/8341-ui) の `docs/design-principles/` への編集を提案する。プロダクト固有の例外は、そのプロダクトの DESIGN.md に記録する。
 
 ## 注意事項
 

docs/improvement/log.md

@@ -4,6 +4,7 @@
 
 | 日付       | 種別     | 内容                                                                                                                                                                                                                                                              | 再発防止                                                                                                      |
 | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| 2026-10-23 | 機能 | 8341-ui を使うプロダクトに、DESIGN.md と design-principles を配るレジストリ item `@8341/design-md` を追加。DESIGN.md はコードから読み取れない考え方（プロダクトの前提・画面領域ごとの方向性・大事にすること・外した必須）と原則の必須の要約だけにし、トークンや部品の一覧は載せない | ADR-0019。原則の要約は `scripts/sync-product-design.ts` が docs/design-principles から生成し、`make check` で鮮度を検査。配布する原則のファイル一覧も registry.json の --check で追従 |
 | 2026-10-23 | 文書 | design-principles の原則「削る」に、部品を組み合わせたページで不要なセカンダリラベルや説明を避け、関係をレイアウトで伝えるルールを追加（必須 3・推奨 1・レビュー 3）。WCAG 3.3.2・1.3.1 を緩めないよう、見えるラベルと構造は残す条件を明記。ルールブック 01・05 と DESIGN.md の Don't に反映 | 原則のレビュー項目に追加（design-review で確認される）。05 文言で `supportText` をラベルの言い換えに使わないと明記 |
 | 2026-10-21 | 開発体験 | スキルの一覧 `docs/skills.md` を追加し、README・AGENTS.md・CONTRIBUTING・ai-agents.md からリンク（重複していた表は一覧へのリンクに置き換え）。文書を必要なときだけ読み込むよう、大きいスキル（design-principles・ds-factory・ds-slides・ds-storybook-preview）を本体と段階ごとの文書に分け、AGENTS.md に読み込みの方針を追加 | ADR-0018。`scripts/check-skills.ts`（name・description・一覧の網羅・本体 2,000 字以内・リンク切れ・参照されない文書）を `make check` に追加 |
 | 2026-10-20 | 機能 | 発表用のスライドを作るスキル `ds-slides` を追加。HTML のデッキを semantic トークンだけで組み（`scripts/slides/`）、design-principles の原則をスライドに落としたルールを 07 章にまとめた | ADR-0017。`make slides-check`（ソースの S1〜S20 の検査と deck.css の監査）を `make check` に組み込み、見本 `scripts/slides/examples/sample.html` を毎回検査 |

docs/rulebook/01-principles.md

@@ -14,7 +14,7 @@ design-principles のルールは、次の順で適用する。後のルール
 4. **WCAG 2.2 の達成基準**（必須はどの段階からも緩めない）
 
 8341-ui は複数のプロダクトで共有する基盤なので、1 と 2 は決めない。
-UI の方向性とサービス種別は、8341-ui を使う各プロダクトの DESIGN.md で決める（雛形: [`templates/PRODUCT-DESIGN.md`](../../templates/PRODUCT-DESIGN.md)）。
+UI の方向性とサービス種別は、8341-ui を使う各プロダクトの DESIGN.md で決める。プロダクトには `npx shadcn@latest add @8341/design-md` で、DESIGN.md（雛形: [`templates/PRODUCT-DESIGN.md`](../../templates/PRODUCT-DESIGN.md)。コードから読み取れない考え方と原則の必須）と `docs/design-principles/` を配る（ADR-0019）。
 8341-ui が受け持つのは 3 と 4 であり、どのサービス種別でも組み立てられる部品とトークンを用意する。
 
 ## ウェブデザインの原則との対応

package.json

@@ -15,7 +15,7 @@
     "build": "pnpm build:tokens && pnpm --filter 8341-ui build",
     "build:storybook": "pnpm build:tokens && pnpm --filter 8341-ui-storybook build",
     "storybook:preview": "pnpm build:storybook && pnpm --filter 8341-ui-storybook preview:publish",
-    "check": "pnpm build:tokens && vp check && vp run -r check && depcruise packages apps && node scripts/slides/check.ts && node scripts/check-skills.ts",
+    "check": "pnpm build:tokens && vp check && vp run -r check && depcruise packages apps && node scripts/slides/check.ts && node scripts/check-skills.ts && node scripts/sync-product-design.ts --check",
     "test": "pnpm build:tokens && vp run -r test",
     "test:vrt": "pnpm build:tokens && pnpm --filter 8341-ui test:vrt",
     "test:e2e": "pnpm build:tokens && pnpm --filter 8341-ui-storybook test:e2e",

packages/ui/package.json

@@ -52,7 +52,7 @@
     "test:vrt": "vp test --project vrt",
     "figma:publish": "figma connect publish",
     "registry": "node scripts/generate-registry.ts",
-    "registry:build": "node scripts/build-registry-css.ts && shadcn build ./registry.json -o ../../apps/storybook/public/r"
+    "registry:build": "node scripts/build-registry-assets.ts && shadcn build ./registry.json -o ../../apps/storybook/public/r"
   },
   "dependencies": {
     "8341-ui-tokens": "workspace:*",