Design System Documentation Tooling 2025

by takanorip

Slide 1

Slide 1 text

Design System 2025 Documentation Tooling takanorip Frontend Conference Kansai 2025

Slide 2

Slide 2 text

目次自己紹介 00 ドキュメントサイトの要件 01 技術選定のものさし 02 ドキュメントを腐らせないために 03 まとめ 04

Slide 3

Slide 3 text

自己紹介 takanorip 株式会社カンムデザインマネージャーデザインエンジニア神奈川県横浜市在住。最近135㎡の家に引っ越しました。パスタを作るのが得意です。お元気ですか.fmというPodcastをやってます。 X: @takanripe https://takanorip.com/

Slide 4

Slide 4 text

No content

Slide 5

Slide 5 text

No content

Slide 6

Slide 6 text

No content

Slide 7

Slide 7 text

01 ドキュメントサイトの役割と要件

Slide 8

Slide 8 text

デザインシステムとドキュメントサイトの関係？ドキュメントサイトはデザインシステムのSSOT デザインシステムがあっても使い方がわからないと誰も使ってくれない。人やAIにデザインシステムを活用してもらうためのSSOT。これを見ればOK！と言い切れる情報源であること。 https://spindle.ameba.design/ https://atlassian.design/

Slide 9

Slide 9 text

対象読者対象読者はデザインに関係する人全員デザイナー、エンジニアでドキュメントを分割せず、全員が読むべきドキュメントサイトにする。プロダクトのブランディングガイドラインとしても機能させ、デザインに関するドキュメントは全部ここに集約させることでマーケ、広報などの職種も巻き込んで運用を考えていける。

Slide 10

Slide 10 text

対象読者

Slide 11

Slide 11 text

最近の技術トレンドスタンドアロンな読み物から「接続できる」ドキュメントへ生成が出現したことにより、ドキュメントサイトも色々なものと接続できる必要が出てきた。ドキュメントの自動生成、MCPを利用した開発環境への接続などができないとドキュメントサイトの価値が下がってしまう。

Slide 12

Slide 12 text

「接続できる」ドキュメントドキュメントサイトデザイントークンコンポーネント LLM Chat MCPサーバー検索人間ガイドライン Figma

Slide 13

Slide 13 text

ドキュメントサイトの必須要件 01 独立していて、発見が容易であること 02 プレーンテキストで管理できること 03 バージョン管理ができること 04 誰でも更新できること 05 誰でも閲覧できること

Slide 14

Slide 14 text

02 ドキュメントサイト技術選定のものさし

Slide 15

Slide 15 text

ツールを選択するときのものさし 01 コスト（お金、開発工数など）を負担できるか 02 ドキュメントサイトの要件を満たせるか 03 運用できる体制がつくれるかなるべく低コストで要件が満たせる選択をする。お金をかけることで人の負担を減らすという選択肢もある。

Slide 16

Slide 16 text

ドキュメントサイトをつくるツール① Figma 評価：B プレーンテキストとして扱えずドキュメントの検索性が低い。コードに関する記述にも不向き。開発者からの距離が遠い Figma MCPやCode Connectで開発環境への接続はできるが  Figmaへの依存度が高くなる。デザインに特化したドキュメントとして運用するならあり。

Slide 17

Slide 17 text

ドキュメントサイトをつくるツール① Notion 評価：C 最初の一歩としては悪くないいくつかのデメリットがあるプレーンテキストとして管理できないウェブサイトとしては表現力が低いドキュメンテーションツールとしては表現力が高すぎる開発環境への接続性が悪い

Slide 18

Slide 18 text

ドキュメントサイトをつくるツール② Zeroheight 評価：B デザインシステム特化のドキュメンテーションツール自前で作り込まなくてもドキュメントサイトが構築できる FigmaやStorybookとの連携、MCPサーバーなど多機能利用料が高い（最低でも $49 per editor/month）利用料を負担できるなら良い選択肢になりうる https://zeroheight.com/

Slide 19

Slide 19 text

ドキュメントサイトをつくるツール② Static Site 評価：A ドキュメントサイトに求める要件をすべて満たせる反面、自分たちで開発・運用しなければならないので手間がかかるリッチに作り込みすぎないために、ゴールやスコープの設定が重要になる

Slide 20

Slide 20 text

今回は Static Siteを選択した場合の話

Slide 21

Slide 21 text

Static Site Generatorの技術要件 01 Node.jsで動く 02 テンプレートとしてJSX/MDXが利用できる 03 マークダウンが利用できる 04 インタラクティブな要素にも対応できる WIP

Slide 22

Slide 22 text

Static Site Generatorを選ぶものさし 01 依存が少ないこと 02 新しく覚えることが少ないこと 03 機能のバランスがちょうど良いことデザインシステムのドキュメントサイトは空き時間でメンテナンスされる。できるだけ省エネで運用できる技術選択を意識する。機能が多すぎると作り込みすぎてしまう、機能が少なすぎると初期開発の工数が増加するなどの懸念がある。チームの体制合わせてちょうど良いバランスを探ることが重要。

Slide 23

Slide 23 text

Static Site Generatorの比較 Storybook Autodocs機能を使うことで、インタラクティブなドキュメントを  storyから生成することができる。 https://storybook.js.org/docs/writing-docs/autodocs StorybookはUIコンポーネントの開発ツールであるため、  ドキュメントがUI中心になってしまう（開発者中心のドキュメンになってしまう）  というデメリットもある。 UIの詳細なドキュメントはStorybookで構築し、  デザインシステム全体のドキュメントに埋め込むのが良い。

Slide 24

Slide 24 text

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"

Slide 25

Slide 25 text

Static Site Generatorの比較 Astro 最近SSGといえばこれ、感がある。多機能で大体なんでもできる。柔軟性は高いが、独自のテンプレート構文など覚えることが多い。 https://astro.build/ React、Vue、など複数のフレームワークを同時に埋め込むことができるので、複数フレームワークに対応したUIコンポーネントがある場合は便利かも。個人的には片手間で運用するには重すぎる、という印象がある。運用する体力があり、ドキュメントサイトを作り込みたい場合に適している。

Slide 26

Slide 26 text

Static Site Generatorの比較 Astro examples pages/components/button react/button vue/button iframeで埋め込み

Slide 27

Slide 27 text

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に詳しい人がいないと  運用していくのが難しいかも。

Slide 28

Slide 28 text

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

Slide 29

Slide 29 text

Static Site Generatorの比較 Vike 必要な要素を組み合わせて構築するタイプのSSG。 AstroとEleventyの中間。プログレッシブエンハンスメント的な思想のもとに開発されている。 https://vike.dev/ 任意のUIフレームワークをインテグレートできる。 React、Vue、SolidJSはインテグレート用のパッケージが用意されている。個人的には現状ベストな選択肢。

Slide 30

Slide 30 text

No content

Slide 31

Slide 31 text

ドキュメントサイトを構築するうえで大事なこと 01 背伸びをしないこと 02 やらないことを決めること 03 運用まで考えること（作っておわりにしないこと）

Slide 32

Slide 32 text

03 ドキュメントサイトを腐らせないために

Slide 33

Slide 33 text

コンテンツを自動で生成できるようにする集合知を活用して、自分たちが考えるべきことを減らす LLMにドキュメントを生成してもらう = 集合知を活用する自分たちが書くべきところとLLMに書かせる部分を切り分けて設計する。 LLMにドキュメントを生成してもらう = 集合知を活用する自分たちが書くべきところとLLMに書かせる部分を切り分けて設計する。

Slide 34

Slide 34 text

ドキュメントを書くことから始めるデザインシステムに変更を加えるときはドキュメントを先に書くデザインや開発が終わってから後からドキュメントを更新する流れだとドキュメントの更新をサボる人が出てくる。先にドキュメントを書いてしまうことで更新が漏れることを防げるし、 Design Docとしても使える。

Slide 35

Slide 35 text

人間の読みやすさをおろそかにしない読みやすいデザイン、書き方、構成 LLM全盛の時代でも人間の読みやすさから逃げないこと。人間が読みやすいことは機械の読みやすさにもつながる。コンテンツの構成（情報設計）とタイポグラフィが大事ジャンプ率行間のリズム横幅

Slide 36

Slide 36 text

人間の読みやすさをおろそかにしないタイポグラフィについて勉強しようオンスクリーンタイポグラフィ事例と論説から考えるウェブの文字表現 https://bnn.co.jp/products/9784802512077 ウェブタイポグラフィ美しく効果的でレスポンシブな欧文タイポグラフィの設計 https://wgn-obs.shop-pro.jp/?pid=152092905

Slide 37

Slide 37 text

04 まとめ

Slide 38

Slide 38 text

まとめ 01 「接続できる」ドキュメントを目指す 02 要件とコストのバランスを考える 03 プレーンで薄すぎず厚すぎずなものを選ぶ 04 運用のことまで考えて選択する 05 デザインをサボらない

Slide 39

Slide 39 text

株式会社カンムではフロントエンドエンジニアを積極採用中です！ https://herp.careers/v1/kanmu/wLpZGU-SdHKC

Slide 40

Slide 40 text

Thank You!