各パッケージのREADMEにコンポーネントのデザインドキュメントを同梱 - #101
Open
nio-nio-nio wants to merge 13 commits into
Open
Conversation
design.pepabo.com の src/pages/inhouse/components/*.mdx にある コンポーネントごとのデザインドキュメント（概要・構成要素・使い分け・ バリエーション・ステート・アクセシビリティ・ライティング）を、 対応する32パッケージの README 末尾に「デザインドキュメント」 セクションとして追加。 npm パッケージページや AI エージェントがパッケージ単体で コンポーネントの使い方・使い分けを理解できるようにするのが目的。 - mdx の frontmatter / import / script は除去し、GitHub で レンダリング可能な Markdown に変換 - code-preview のデモは html コードブロック化 - 画像・リンクは design.pepabo.com への絶対 URL に変換 - 転載範囲は design-doc:start/end マーカーで囲み、再生成可能に Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
README へのデザインドキュメント転載（#101）は node_modules に届くものの、 エージェントの既定検索（.gitignore 尊重）では発見されず、README を 頭から部分読みした場合も末尾の転載節に到達しない問題があった。 - 各パッケージ README の冒頭に、末尾のデザインドキュメント節への導線を追加 - 各パッケージに CLAUDE.md / AGENTS.md を同梱（files フィールド未指定のため publish に自動で含まれる）。エージェントがパッケージ内のファイルを読んだ 瞬間に自動注入され、README のデザインドキュメント節へ誘導する （プロジェクト cwd 配下の node_modules で自動注入の発火を実測済み） - ルート README に、利用側リポジトリの CLAUDE.md へ貼るコピペ用 スニペットを記載した「AI エージェントと使う場合」節を追加 Co-Authored-By: Claude <noreply@anthropic.com>
itoh4126
reviewed
Aug 3, 2026
itoh4126
left a comment
itoh4126
left a comment
Contributor
There was a problem hiding this comment.
@nio-nio-nio ありがとうございます。
design-doc:start マーカーで使われる変換スクリプトは含めないんですかね？
| <tr> | ||
| <th>Negative</th> | ||
| <td><code>.-color-negative</code></td> | ||
| <td>Pepper Red (#c25d5d)</td> |
Contributor
There was a problem hiding this comment.
これはpepperのredにない値ですね（今回がというより元のページもそうなっていたのでそれを持ってきたのだろうと思われますが）、
元のページにはカラーコードはないのでカラーコードは無くてもよいのではないでしょうか…（flavor tokenごとに違いますし）
Comment on lines
+71
to
+72
| ``` | ||
| </div> |
Contributor
There was a problem hiding this comment.
フェンス閉じた後にdiv要素が記述されててレンダリング崩れるはずなので逆にしましょう!
| > | ||
| <span class="in-icon" data-icon="check" /> | ||
| <span>Neutral</span> | ||
| <div class='trailing'> |
Contributor
There was a problem hiding this comment.
Suggested change
| <div class='trailing'> | |
| <div class='_trailing'> |
のはず…（他にも同様のtypoがありました）
|
|
||
| このコンポーネントを使った UI の実装・変更を行う前に、同ディレクトリの README.md 末尾にある「デザインドキュメント (Design Documentation)」節を必ず読むこと。コンポーネントの使い分け・バリエーション・ステート・アクセシビリティ・ライティングの規約が全文記載されている（https://design.pepabo.com/inhouse/components/app-bar/ からの転載）。 | ||
|
|
||
| SCSS mixin の使い方（`style($options)` によるエイリアシング等）は README.md 冒頭の Usage 節を参照。 |
Contributor
There was a problem hiding this comment.
全体的に、README冒頭のUsageにscss mixinベースの使い方が書かれていないので実態と違った記述になってました。この文章は無くてもいいのではないでしょうか（READMEを参照せよという旨は先の段落で示せているし）
Contributor
There was a problem hiding this comment.
いや、buttonだけはUsageにmixinの使い方が書いてありました（が、これはこれで実装セクションと内容的な重複にも捉えられるのでどちらかへ集約するのが良いけれども）
レビュー指摘（#101）への対応。 - 全32パッケージの CLAUDE.md / AGENTS.md から「SCSS mixin の使い方は README.md 冒頭の Usage 節を参照」の段落を削除。Usage 節に mixin の 説明があるのは button のみで、他31パッケージでは実態と不一致だった - button の README から、デザインドキュメント「実装」節と重複する style($options) の使用例コードブロックを削除し、実装節へのアンカーに 置き換え。skeleton-style / style-with-variants の説明はここにしか ないため保持 Co-Authored-By: Claude <noreply@anthropic.com>
design.pepabo.com からの転載時、Trailing 節のデモ HTML の閉じ </div> が コードフェンスの外に出てレンダリングが崩れていたため、フェンス内に移動。 全32パッケージを走査し、同様の崩れは他にないことを確認済み。 再生成時に再発しうるため、原本 mdx または変換スクリプト側の確認が必要。 Co-Authored-By: Claude <noreply@anthropic.com>
レビュー指摘（#101 r3701299651）への対応。 要素クラスは `_trailing`（アンダースコア付き）が正しい: - packages/snackbar/_mixins.scss が `._trailing { margin-left: auto; }` を定義 - stories-web/src/components/Snackbar.tsx も `_trailing` を使用 - Mixin-based（エイリアシング）でも、独自名を付けるのはルート要素だけで 内部の要素クラスは `_` を維持するのが規約（app-bar / card の例も同様） - `class='trailing'` 5箇所を `_trailing` に修正 - Mixin-based の SCSS 例から `> .trailing { margin-left: auto; }` を削除。 typo を補うための手書きルールで、`_trailing` に直すと mixin が同じ宣言を 出力するため不要になる - Color / Inline 節のコードフェンスが途中で閉じ、2例目以降が生 HTML として 流出していたのを修正（原本の code-preview ラッパーの変換漏れ）。 正しく変換されている card README と同じ形（1ブロック1フェンス、 <br /> はフェンス内）に揃えた 原本の design.pepabo.com 側 snackbar.mdx にも同じ typo があるため別途修正する。 Co-Authored-By: Claude <noreply@anthropic.com>
design.pepabo.comの原本にはカラーコードの記載がなく、flavor tokenごとに 値が異なるため、flavor名のみの記載に修正した。 Co-Authored-By: Claude <noreply@anthropic.com>
レビュー指摘（#101）への対応。 start/endマーカーは「自動転載。手動編集しないでください」と記載していたが、 転載を行う変換スクリプトはリポジトリに存在せず、CIにも同期ジョブがない。 そのため design.pepabo.com の更新に追従する手段がなく、修正する唯一の手段 である手動編集をマーカー自身が禁じている状態だった（本PRのカラーコード 削除もこの禁止に反する編集だった）。 実態に合わせて「design.pepabo.com からの転載。更新は手動」に変更する。 start/endマーカー自体は、将来スクリプト化する際の領域指定として残す。 Co-Authored-By: Claude <noreply@anthropic.com>
全32パッケージで原本を「design.pepabo.com リポジトリの src/pages/inhouse/components/<name>.mdx」と記載していたが、このパスの 存在を確認できなかった。pepabo/design.pepabo.com は main / test の どちらのブランチも直下がビルド成果物のみで src/ が存在せず、org 内を コード検索してもヒットしない。 実際に参照できる原典は公開ページなので、そちらを指すよう修正する。 差し替えた32本のURLはいずれもHTTP 200を確認済み。 Co-Authored-By: Claude <noreply@anthropic.com>
This reverts commit 95867db.
#101 の説明で「変換スクリプトを再実行すると該当セクションだけが差し替わる」 と書いていたが、実際にはスクリプトが無く手作業で転載していた。レビュー指摘 （#101）への対応として実装する。 design.pepabo.com リポジトリの src/pages/inhouse/components/<name>.mdx を 入力に、各パッケージ README の design-doc マーカー間を冪等に差し替える。 mdx は Astro 依存のため以下の変換をかける。 - frontmatter / import / export const components / <script> を除去 - <div class="code-preview"> → ```html コードブロック化。閉じタグは列0の </div> と1:1対応しないため、div の深さを数えて対応を取る - <ColorPreview color="..." /> を除去し flavor 名のみ残す。カラーコードは flavor token ごとに変わるため README に固定値を書かない（1f93bee の再発防止） - <span class="element-mark">A</span>Foo → A. Foo（1見出しに複数並ぶ場合も対応） - <span class="note-default">*</span> → * - <a href target=_blank> → markdown リンク、相対パスは絶対URL化 - <img src="/..."> はコード例をそのまま動かせるようフェンス内も絶対URL化 - 見出しを1段下げて README の階層に整合（フェンス内は除外） 現在の32パッケージの README に対して差分ゼロ（バイト一致）を確認済み。 冪等性、および --check が差分なしで exit 0 になることも確認した。 原典パスは --source または DESIGN_DOC_SRC で指定する。原典は社内 GHE （git.pepabo.com）側にあり、github.com の pepabo/design.pepabo.com は 公開ビルド成果物のみのため参照できない。 Refs #102 Co-Authored-By: Claude <noreply@anthropic.com>
Contributor
Author
|
@itoh4126 コメントありがとうございます！ 現在の32パッケージの README に対して実行し、差分ゼロ（バイト一致）を確認しています。 カラーコードの件は の prop をテキストに出していたのが原因だったので、スクリプトでは flavor 名のみを出力するようにしました。 |
nio-nio-nio
changed the title
このリポジトリはオープンソースであるため、同梱するデザイン ドキュメントから公開範囲外のドメインへの言及とリンクを取り除く。 - コンポーネント間のリンクは、このリポジトリ内の各パッケージ README への相対リンク（../<slug>/README.md）に置き換える。 対応パッケージが無いリンクはリンク解除してテキストのみ残す - ドキュメント内の画像埋め込みは除去する。画像の除去で空になった ギャラリー用 div とその直前のラベル行もあわせて取り除く （コードフェンス内の <img> 例は相対パスのまま残す） - 「〜からの転載」「原本: 〜」といった出所の記述を、内容の説明と 再生成手段（scripts/sync_design_docs.mjs）の案内に置き換える - 変換スクリプト・ルート README・各 CLAUDE.md / AGENTS.md の 文言からも同様に除去する Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
デザインドキュメントの生成・同期はドキュメントのソース側で管理する ことにし、このリポジトリからはスクリプトと npm scripts のエントリを 削除する。生成物のマーカー・注記もスクリプトパスに依存しない文言に 更新した。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
nio-nio-nio
changed the title
itoh4126
approved these changes
Aug 12, 2026
nio-nio-nio
marked this pull request as ready for review
August 12, 2026 07:36
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
概要
コンポーネントごとのデザインドキュメント（概要・構成要素・使い分け・バリエーション・ステート・アクセシビリティ・ライティング）を、対応する 32パッケージ の README 末尾に「デザインドキュメント」セクションとして同梱しました。
目的
npm パッケージページや GitHub 上で、パッケージ単体でもコンポーネントの使い方・使い分けを参照できるようにするためです。特に AI エージェント（Claude Code など）がパッケージを参照した際に、実装 API だけでなくデザイン意図・使い分け・a11y 要件まで理解できるようになります。
内容
CLAUDE.md/AGENTS.mdを追加し、AI エージェントが README のデザインドキュメント節へ誘導されるようにしていますメンテナンスについて
同梱範囲は
<!-- design-doc:start -->/<!-- design-doc:end -->マーカーで囲んであり、このセクションは自動生成されます（冪等）。マーカー間は直接編集しないでください。🤖 Generated with Claude Code