Design System Documentation Tooling 2025

Transcript

1. Design System 2025 Documentation Tooling takanorip Frontend Conference Kansai 2025
2. 目次 自己紹介 00 ドキュメントサイトの要件 01 技術選定のものさし 02 ドキュメントを腐らせないために 03 まとめ 04
3. 自己紹介 takanorip 株式会社カンム デザインマネージャー デザインエンジニア 神奈川県横浜市在住。最近135㎡の家に引っ越しました。 パスタを作るのが得意です。 お元気ですか.fmというPodcastをやってます。 X: @takanripe https://takanorip.com/
7. 01 ドキュメントサイトの役割と要件
8. デザインシステムとドキュメントサイトの関係？ ドキュメントサイトは デザインシステムのSSOT デザインシステムがあっても使い方がわからないと誰も使ってくれない。 人やAIにデザインシステムを活用してもらうためのSSOT。 これを見ればOK！と言い切れる情報源であること。 https://spindle.ameba.design/ https://atlassian.design/
9. 対象読者 対象読者はデザインに関係する人全員 デザイナー、エンジニアでドキュメントを分割せず、 全員が読むべきドキュメントサイトにする。 プロダクトのブランディングガイドラインとしても機能させ、 デザインに関するドキュメントは全部ここに集約させることで マーケ、広報などの職種も巻き込んで運用を考えていける。
10. 対象読者
11. 最近の技術トレンド スタンドアロンな読み物から 「接続できる」ドキュメントへ 生成が出現したことにより、 ドキュメントサイトも色々なものと接続できる必要が出てきた。 ドキュメントの自動生成、MCPを利用した開発環境への接続などができな いとドキュメントサイトの価値が下がってしまう。
12. 「接続できる」ドキュメント ドキュメントサイト デザイントークン コンポーネント LLM Chat MCPサーバー 検索 人間 ガイドライン Figma
13. ドキュメントサイトの必須要件 01 独立していて、発見が容易であること 02 プレーンテキストで管理できること 03 バージョン管理ができること 04 誰でも更新できること 05 誰でも閲覧できること
14. 02 ドキュメントサイト技術選定のものさし
15. ツールを選択するときのものさし 01 コスト（お金、開発工数など）を負担できるか 02 ドキュメントサイトの要件を満たせるか 03 運用できる体制がつくれるか なるべく低コストで要件が満たせる選択をする。 お金をかけることで人の負担を減らすという選択肢もある。
16. ドキュメントサイトをつくるツール① Figma 評価：B プレーンテキストとして扱えずドキュメントの検索性が低い。 コードに関する記述にも不向き。 開発者からの距離が遠い Figma MCPやCode Connectで開発環境への接続はできるが
 Figmaへの依存度が高くなる。 デザインに特化したドキュメントとして運用するならあり。
17. ドキュメントサイトをつくるツール① Notion 評価：C 最初の一歩としては悪くない いくつかのデメリットがある プレーンテキストとして管理できない ウェブサイトとしては表現力が低い ドキュメンテーションツールとしては表現力が高すぎる 開発環境への接続性が悪い
18. ドキュメントサイトをつくるツール② Zeroheight 評価：B デザインシステム特化のドキュメンテーションツール 自前で作り込まなくてもドキュメントサイトが構築できる FigmaやStorybookとの連携、MCPサーバーなど多機能 利用料が高い（最低でも $49 per editor/month） 利用料を負担できるなら良い選択肢になりうる https://zeroheight.com/
19. ドキュメントサイトをつくるツール② Static Site 評価：A ドキュメントサイトに求める要件をすべて満たせる 反面、自分たちで開発・運用しなければならないので手間がかかる リッチに作り込みすぎないために、ゴールやスコープの設定が重要になる
20. 今回は Static Siteを選択した場合の話
21. Static Site Generatorの技術要件 01 Node.jsで動く 02 テンプレートとしてJSX/MDXが利用できる 03 マークダウンが利用できる 04 インタラクティブな要素にも対応できる WIP
22. Static Site Generatorを選ぶものさし 01 依存が少ないこと 02 新しく覚えることが少ないこと 03 機能のバランスがちょうど良いこと デザインシステムのドキュメントサイトは空き時間でメンテナンスされる。 できるだけ省エネで運用できる技術選択を意識する。 機能が多すぎると作り込みすぎてしまう、 機能が少なすぎると初期開発の工数が増加するなどの懸念がある。 チームの体制合わせてちょうど良いバランスを探ることが重要。
23. Static Site Generatorの比較 Storybook Autodocs機能を使うことで、インタラクティブなドキュメントを
 storyから生成することができる。 https://storybook.js.org/docs/writing-docs/autodocs StorybookはUIコンポーネントの開発ツールであるため、
 ドキュメントがUI中心になってしまう（開発者中心のドキュメンになってしまう）
 というデメリットもある。 UIの詳細なドキュメントはStorybookで構築し、
 デザインシステム全体のドキュメントに埋め込むのが良い。
24. Static Site Generatorの比較 Storybook import type from import from const typeof export default { } ; { } ; meta = { component: , tags: [ ], } satisfies < >; meta; Meta Button Button Meta Button "@storybook/react-vite" "./Button" "autodocs"
25. Static Site Generatorの比較 Astro 最近SSGといえばこれ、感がある。多機能で大体なんでもできる。 柔軟性は高いが、独自のテンプレート構文など覚えることが多い。 https://astro.build/ React、Vue、など複数のフレームワークを同時に埋め込むことができるので、 複数フレームワークに対応したUIコンポーネントがある場合は便利かも。 個人的には片手間で運用するには重すぎる、という印象がある。 運用する体力があり、ドキュメントサイトを作り込みたい場合に適している。
26. Static Site Generatorの比較 Astro examples pages/components/button react/button vue/button iframeで埋め込み
27. Static Site Generatorの比較 Eleventy とにかく薄いSSG。v3でES Modulesに対応した。 めちゃくちゃ薄いので、依存がめちゃくちゃ少ない。個人的な推しSSG。 tsxやMDXを利用することも可能だがあくまでもテンプレートとして機能するだけ。 インタラクティブなUIを構築したい場合は自分で頑張るか ` ` コンポーネント経由でReactやVueを使う方法がある。 https://www.11ty.dev/docs/plugins/is-land/ is-land ドキュメントもそんなに手厚くないので、それなりに11tyに詳しい人がいないと
 運用していくのが難しいかも。
28. Static Site Generatorの比較 Eleventy < = > . ( , (target) => { component = (target. ( )); component. (target); }); </ > < = = ></ > script type script is-land on:visible type import is-land "module" "preact" "import" "preact" "preact-component.js" // Define once for any number of Preact islands. Island addInitType getAttribute default async const await import
29. Static Site Generatorの比較 Vike 必要な要素を組み合わせて構築するタイプのSSG。 AstroとEleventyの中間。 プログレッシブエンハンスメント的な思想のもとに開発されている。 https://vike.dev/ 任意のUIフレームワークをインテグレートできる。 React、Vue、SolidJSはインテグレート用のパッケージが用意されている。 個人的には現状ベストな選択肢。
31. ドキュメントサイトを構築するうえで大事なこと 01 背伸びをしないこと 02 やらないことを決めること 03 運用まで考えること（作っておわりにしないこと）
32. 03 ドキュメントサイトを腐らせないために
33. コンテンツを自動で生成できるようにする 集合知を活用して、 自分たちが考えるべきことを減らす LLMにドキュメントを生成してもらう = 集合知を活用する 自分たちが書くべきところとLLMに書かせる部分を切り分けて設計する。 LLMにドキュメントを生成してもらう = 集合知を活用する 自分たちが書くべきところとLLMに書かせる部分を切り分けて設計する。
34. ドキュメントを書くことから始める デザインシステムに変更を加えるときは ドキュメントを先に書く デザインや開発が終わってから後からドキュメントを更新する流れだと ドキュメントの更新をサボる人が出てくる。 先にドキュメントを書いてしまうことで更新が漏れることを防げるし、 Design Docとしても使える。
35. 人間の読みやすさをおろそかにしない 読みやすいデザイン、書き方、構成 LLM全盛の時代でも人間の読みやすさから逃げないこと。 人間が読みやすいことは機械の読みやすさにもつながる。 コンテンツの構成（情報設計）とタイポグラフィが大事 ジャンプ率 行間のリズム 横幅
36. 人間の読みやすさをおろそかにしない タイポグラフィについて勉強しよう オンスクリーン タイポグラフィ 事例と論説から考えるウェブの文字表現 https://bnn.co.jp/products/9784802512077 ウェブタイポグラフィ 美しく効果的でレスポンシブな欧文タイポグラフィの設計 https://wgn-obs.shop-pro.jp/?pid=152092905
37. 04 まとめ
38. まとめ 01 「接続できる」ドキュメントを目指す 02 要件とコストのバランスを考える 03 プレーンで薄すぎず厚すぎずなものを選ぶ 04 運用のことまで考えて選択する 05 デザインをサボらない
39. 株式会社カンムでは フロントエンドエンジニアを 積極採用中です！ https://herp.careers/v1/kanmu/wLpZGU-SdHKC
40. Thank You!