NAOQ Design Note

デザインとコードの学習ノート

デザインシステムのドキュメントとは?書く内容と公開例の読み方を解説

デザインシステムのドキュメントとは?書く内容と公開例の読み方を解説

PR記事内に広告が含まれています。

ボタンや入力欄の部品をきれいにそろえたのに、チームの人が別の場面で勝手に色を変えたり、似た部品を作り直したりしてしまう、と悩んだことはありませんか。

部品があっても「いつ、どう使うか」が伝わっていなければ、ルールは守られません。

この記事では、デザインシステムのドキュメントとは何か、ドキュメントに書く内容、公開されているデジタル庁デザインシステムやMaterial Designなどのドキュメントの読み方を、見本を使って初心者向けに解説します。

この記事の見本は、サイトの配色ではなく、架空のサービスの配色(青系)で描いています。見本の部品は押しても動きません。

デザインシステムのドキュメントの基本

まずは、デザインシステムのドキュメントとは何か、なぜ部品だけでなく文書が必要なのかを押さえましょう。

デザインシステムのドキュメントとは

デザインシステムのドキュメントとは、部品やルールの使い方を文章と例でまとめ、チームの全員がいつでも読めるようにした説明書のことです。

デザインシステムとは、色・文字・余白のルールや、ボタンなどの部品(コンポーネント)を、チームで共有して使い回すための仕組みのことです。

ドキュメントには、たとえば色や余白の値の一覧、部品の一覧と使い方、ルールを変えるときの決まりなどが書かれます。

UXリサーチの調査機関であるNielsen Norman Groupは、デザインシステムの部品集には、部品の名前・説明・属性・状態・コードの例などを含めると説明しています(Design Systems 101 – Nielsen Norman Group(英語))。

ここでの属性とは、色・サイズ・形・文言など、部品ごとに変えられる設定のことです。

コードの例まで載せるのは、開発者がそれをもとに、デザインどおりの部品を画面に組み込めるようにするためです。ドキュメントは、デザイナーだけでなく開発者も読むものなのです。

部品だけでは使い方が伝わらない

ドキュメントが必要なのは、部品そのものを見ても「どの場面で使うのか」「なぜその形なのか」までは分からないからです。

使い方が伝わらないと、使う人がその場の判断で部品を選んだり直したりするため、せっかくそろえた見た目が少しずつ崩れていきます。

たとえば、目立つ色の「プライマリーボタン(いちばん押してほしい操作のボタン)」が部品として用意されていても、「1画面に1つだけ使う」というルールが書かれていなければ、画面に何個も並べてしまう人が出てきます。

理由まで書いてあれば、ドキュメントに載っていない場面でも「このルールの目的から考えると、こうすべきだ」と判断する手がかりになります。

新しくチームに入った人が、先輩に一つずつ聞かなくてもルールを学べることも、ドキュメントの大きな役割です。

デザインシステムのドキュメントに書くこと

ここからは、部品1つ分のドキュメントに何を書けばよいかを、ボタンを例に見ていきます。

部品1つ分に書く基本の項目

部品1つ分のドキュメントには、「それは何か」「いつ使うか」「いつ使わないか」「どんな種類と状態があるか」をそろえて書きます。

この4つがあれば、使う人が「この場面でこの部品を使ってよいか」「どの見た目を選べばよいか」を自分で判断できるからです。

項目書く内容ボタンでの例
名前と概要部品の名前と、何をするための部品か操作を実行するための部品
使いどころどんな場面で使うか送信・保存・申し込みなどの操作
使わない場面使ってはいけない場面と、代わりに使う部品別のページへ移動するだけならリンクを使う
構成部品がどんなパーツでできているか背景・文字・アイコン(任意)
種類役割やサイズの違いプライマリー(主な操作)・セカンダリー(補助的な操作)、大・中・小
状態操作に応じた見た目の変化通常・ホバー(マウスを重ねたとき)・フォーカス(キーボードで選んだとき)・押せない状態
良い例・悪い例迷いやすい使い方の比較プライマリーボタンは1画面に1つ
アクセシビリティ誰でも使えるための決まり文字と背景のコントラスト、押せる範囲の大きさ

アクセシビリティとは、障害の有無や年齢、使う環境にかかわらず、誰でも情報を得て操作できるようにすることです(詳しくはアクセシビリティとは?で解説しています)。

これらを1ページにまとめると、たとえば次のようなドキュメントになります。

ボタン

送信・保存・申し込みなど、操作を実行するための部品です。

使いどころ

フォームの送信、設定の保存、商品の購入など、押すと何かが実行される場面。

使わない場面

別のページへ移動するだけの場合は、ボタンではなくリンクを使います。

種類

保存する キャンセル

プライマリー(塗りつぶし・主要な操作)/セカンダリー(枠線のみ・補助的な操作)

見本A:ボタンのドキュメントの例。概要・使いどころ・使わない場面・種類を1ページにまとめる

見本Aのように、文章は短く、部品の実物を添えて書くと、読む人がすぐに使い方をイメージできます。

「使わない場面」に移動はリンクと書いているのは、ユーザーが「ボタンは押すと何かが実行される」「リンクは押すと別のページへ移る」と、押した結果を予想して使っているためです。

コードでも役割どおりにボタンとリンクを作り分けておくと、キーボードでの操作や、画面の文字を音声で読み上げる機能でも正しく扱われます(詳しくはリンクとボタンの違いとは?で解説しています)。

状態(通常・ホバー・押せない状態など)は、文章だけでなく、それぞれの見た目を並べて載せておきましょう。

保存する
通常
保存する
ホバー(マウスを重ねたとき):少し濃くする
保存する
フォーカス(キーボードで選んだとき):外側に線を出す
保存する
押せない状態:色を薄くし、理由を近くに書く

状態ごとの見た目を並べておくと、デザイナーは作り忘れに気づけ、開発者は「ホバーのときはどう見せるのか」を聞き直さずに済みます。

押せない状態の「理由を近くに書く」とは、たとえばボタンのそばに「必須項目をすべて入力すると押せるようになります」と添えることです。理由がないと、ユーザーはなぜ押せないのか分からず、先へ進めなくなってしまいます。

使わない場面と良い例・悪い例を書く

ドキュメントで特に役立つのは、「使ってはいけない場面」と、迷いやすい使い方の良い例・悪い例です。

「使ってよい」ことだけが書いてあると、使う人は「書いていない場面でも使ってよい」と受け取ってしまうためです。

たとえば「プライマリーボタンは1画面に1つ」というルールは、次のように悪い例と良い例を並べると、文章だけより確実に伝わります。

入力した内容を保存しますか?

保存する 下書きにする キャンセル
NG:プライマリーボタンが3つあり、どれが主な操作か分からない

入力した内容を保存しますか?

保存する 下書きにする キャンセル
OK:主な操作だけをプライマリーにし、ほかは控えめな種類にしている

NGの見本では、3つのボタンが同じ強さで並んでいるため、ユーザーはどれを押せばよいのか迷います。

OKの見本では、「保存する」だけを塗りつぶしたボタンにし、ほかを枠線や文字だけのボタンにしたことで、主な操作がひと目で分かります(ボタンの種類はUIボタンの種類と使い分けで詳しく解説しています)。

ドキュメントでは、このような比較に「なぜNGなのか」を一言添えておくと、似た場面に出会ったときにも応用できます。

小さく始めて、更新し続ける

ドキュメントは、最初から完璧なものを目指さず、必要なところから小さく書き始めて、部品を変えるたびに一緒に更新していくのがコツです。

立派なドキュメントを作ろうとすると、完成までに時間がかかるうえ、書き直しが大変になって更新が止まり、実際の部品と内容が食い違ったまま放置されやすいためです。

古い内容が残ったドキュメントは、ないよりかえって混乱を招くことがあります。

はじめは、次の3つから書き始めると取りかかりやすいでしょう。

  1. 色・文字・余白などの値の一覧
    「メインの色は〇〇」「本文の文字サイズは〇〇」のように、何度も使う値と、その名前をまとめます。
  2. 部品の一覧と使い方
    よく使う部品から順に、「部品1つ分に書く基本の項目」の表の項目を埋めていきます。
  3. 更新のルール
    「部品を変えたら、同じ日にドキュメントも直す」「変えた日と内容を更新履歴に書く」のように、誰がいつ直すかを決めます。

更新履歴(いつ、何を変えたかの記録)があると、使う人が「前と見た目が違うのは、ルールが変わったからだ」と気づけます。

公開されているドキュメントの読み方

企業や行政機関の中には、自分たちのデザインシステムのドキュメントを誰でも読める形で公開しているところがあります。

自分でドキュメントを書く前に、公開されているものを読むと、どんな項目をどう書けばよいかの良いお手本になります。

デジタル庁デザインシステム

日本語で読めるお手本としておすすめなのが、デジタル庁が公開しているデジタル庁デザインシステムです。

主に行政機関や公共機関のWebサイト向けに作られていますが、公式サイトでは、行政機関かどうかを問わず誰でも無料で利用できると案内されています(はじめて本ウェブサイトを見る方へ)。

たとえばボタンのページは「概要」「使い方」「アクセシビリティ」に分かれていて、「使い方」にはボタンのサイズや配置の考え方、重要度に合わせたスタイルの使い分け、押せない状態(無効化)にするときの注意点などが書かれています。

「概要」には、デザインツールFigma(画面のデザインを作るための定番のツール)のデータや、HTML・React(画面を作るためのプログラミングの道具)で書かれたコードへのリンクもまとめられていて、デザインと開発の両方から同じ部品を参照できるようになっています。

デザインデータやコードを自分の制作物に使う場合は、出典の書き方などの利用上の注意事項を確認してください。

Material DesignとApple Human Interface Guidelines

海外の代表的な例としては、GoogleのMaterial Design(英語)と、Appleのヒューマンインターフェイスガイドラインがあります。

Material Designは、Androidアプリなどで使われるGoogleのデザインシステムで、各部品のページに、使い方のガイドライン、寸法などの仕様、アクセシビリティの説明がまとめられています。

Appleのヒューマンインターフェイスガイドラインは、iPhoneやMacなどApple製品のアプリを作るための指針で、日本語版も公開されています。

ボタンのページを例にすると、「おすすめの使い方(Best practices)」「スタイル」「ボタンに書く内容」「役割」に加えて、iPhoneやMacなど「機種ごとの注意点」が分けて書かれています(Buttons – Human Interface Guidelines(英語))。

Webサイトではなくアプリ向けのルールも多いので、そのまま真似するのではなく、「何をどの順番で書いているか」という書き方の参考として読むのがおすすめです。

読むときのコツ

公開されているドキュメントは、全部を最初から読むのではなく、部品を1つ決めて、複数のデザインシステムで見比べるのが効率的です。

同じ部品でも、デザインシステムによって呼び方や分け方、重視するポイントが違うため、比べることで「どこでも共通している大事なルール」が見えてくるからです。

  • 「使わない場面」や注意点を探す
    どのデザインシステムでも、失敗しやすいポイントほど丁寧に書かれています。
  • ページの見出しの並びをメモする
    見出しの並びは、そのままドキュメントの項目の型として使えます。
  • 理由が書かれている箇所に注目する
    「なぜそうするのか」が分かると、自分のサイトに合うかどうかを判断できます。

実践のポイント

デザインシステムのドキュメントで陥りやすい失敗と、よくある疑問をまとめます。

注意点・よくある間違い

  • 最初から全部の部品を完璧に書こうとして、いつまでも公開できないことがあります。
    よく使う部品から書き始め、足りないところは使いながら足していきましょう。
  • 部品を直したのに、ドキュメントを直し忘れることがあります。
    部品の変更とドキュメントの更新を1つの作業として扱い、更新履歴も残しましょう。
  • 「使ってよい場面」だけを書き、「使ってはいけない場面」を書かないことがあります。
    迷いやすいところほど、悪い例とその理由を添えましょう。
  • 文章だけで説明し、部品の実物や見た目の例を載せないことがあります。
    見た目の違いは文章では伝わりにくいので、状態や種類の見本を並べましょう。

よくある質問

  • Q. ドキュメントはどこに書けばいい?
    A. チームの全員が開けて、すぐに直せる場所であればどこでもかまいません。
    デザインツールのファイルの中に説明用のページを作る方法や、社内のWiki(NotionやConfluenceなど、チームの誰でも書き足せる共有ページ)にまとめる方法があります。
    大切なのは、置き場所を1か所に決めて、古い版を残さないことです。
  • Q. 一人で作っているサイトにもドキュメントは必要?
    A. 長く運営するサイトなら、簡単なものでも書いておくと役立ちます。
    数か月後の自分が「このボタンは何のために作ったんだっけ」と迷わずに済むためです。
    最初は値の一覧と、部品ごとの一言メモだけでも十分です。
  • Q. 公開されているデザインシステムのルールをそのまま使ってもいい?
    A. 考え方を参考にするのはよい学び方ですが、そのまま使う場合は利用条件を確認しましょう。
    また、行政サービス向け・アプリ向けなど、それぞれ想定している場面が違うため、自分のサイトに合うかどうかを考えてから取り入れることが大切です。

まとめ

デザインシステムのドキュメントとは、部品やルールの使い方を文章と例でまとめた説明書で、部品だけでは伝わらない「いつ使うか・なぜそうするか」をチームで共有する役割があります。

部品ごとに概要・使いどころ・使わない場面・種類と状態・良い例と悪い例を書き、小さく始めて部品と一緒に更新し続けることがポイントです。

まずはデジタル庁デザインシステムのボタンのページを開き、どんな見出しが並んでいるかを書き出してみてください。