同じつもりのボタンが、いつの間にか3種類になります。スタイルガイドとの違いを押さえ、部品を管理する形を作ります。
前回: JavaScriptを送らないサイト — AstroとSSG 作業場所はVMの中(Ubuntu Server)、確認はホストの Windows のブラウザです。これまで使ってきた
~/react-demo/(Vite + React)をそのまま使います。新しいライブラリは1つも入れません。
あなたのアプリに、ボタンは何種類ありますか。
「1種類です」と答えたくなります。 見た目は全部同じつもりで作っているからです。ところが、実際に自分のコードを開いて数えると、たいていそうなっていません。
- トップページのボタンは
padding: 8px 16px - 一覧ページのボタンは
padding: 10px 16px(そのときちょっと小さく見えたので足した) - 詳細ページのボタンは
padding: 8px 20px(横に文字が入りきらなかったので広げた)
色も同じです。 #2563eb と #2463eb と #1d4ed8 が混ざっています。打ち間違えたものと、別の日に選び直したものの区別が、もう付きません。
これを、「センスがないから」とか「雑だから」だと思ってしまうと、直りません。直し方が分からないからです。
原因は、もっと単純です。
毎回、その場で決め直しているからです。
新しいページを作るたびに、あなたは「このボタンの余白はいくつだったか」を思い出そうとします。思い出せないので、画面を見ながら、それらしい数字を打ちます。 そして次のページでも、また思い出せません。
一人で作っていても、これは必ず起きます。 むしろ一人のほうが起きます。聞ける相手がいないからです。
そして3か月後、あなた自身が、当時の自分の判断を思い出せません。 レビューの回で「一人でもPRを作る」と書いたのと、まったく同じ理由です。
未来の自分は、他人です。
この記事は「デザインシステムとは何か」の紹介では終わりません。トークンを定義して、ボタンを1つ作って、カタログにして、なぜそう作ったかを文章で残すところまで、実際に手を動かします。
対象レベル: 中級 / 区分: 必修
この記事でわかること
- 見た目の崩れは「毎回決め直している」ことが原因で、注意力では直らないこと。決め終わったものを1か所に置くしか手がない
- デザインシステムとスタイルガイドは別物だということ。スタイルガイドは読むもの、デザインシステムはコードとして使うもの。読むだけの規約は必ず守られなくなる
- 良い部品とは「できることが多い部品」ではないこと。使う側が色を指定できないほうが、結果として一貫する
- Storybook は入れなくてよい場面があること。役割は「部品を単体で並べて見る場所」で、それは1枚のページを自作しても達成できる
- Atomic Design はそのまま使わなくてよいこと。5段階のうち、境目が決まらない層がある
- 設計は「言葉にして残すまで」が1セットだということ。ADR は書式が軽く、一人でも続く
- 同じ情報を2か所に持った瞬間、必ずズレること。これは画面でもデータでも同じ話
- 一人でデザインシステムを作り込むのは、目的を見失った状態だということ。必要なのはトークンと、部品3つ
この記事でやること
- いま自分のコードに何色あるかを
grepで数える。感覚ではなく実数で崩れを見る src/tokens.cssにデザイントークンを書く(色・余白・角丸・文字サイズをCSS変数にする)variantを props で受けるButtonを作る。使う側が色を指定できない形にする- 部品を並べた「カタログページ」を自分で1枚作る(Storybook は入れません)
docs/adr/0001-design-tokens.mdを書いて、なぜそう決めたのかを残す
先に知る言葉
この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| デザインシステム | 見た目のルールを、文章ではなくコードとして1か所に置いたもの。使うと自動的にルールが守られる |
| スタイルガイド | 見た目のルールを文章と画像で説明したもの。読む人が守る前提で、強制力はない |
| デザイントークン | 色・余白・角丸などの決め終わった値に名前を付けたもの。--color-primary のような形で持つ |
| CSS変数(カスタムプロパティ) | CSSの中で値に名前を付ける仕組み。--name: 値 で定義し、var(--name) で使う |
| マジックナンバー | コードに直接書かれた、理由の分からない数字。padding: 13px の 13 がなぜ13なのか誰も説明できない状態 |
| variant(バリアント) | 同じ部品の種類違い。ボタンなら「主要な操作」「補助的な操作」「危険な操作」など |
| Storybook | 部品をアプリから切り離して1つずつ表示・操作できるようにする開発ツール |
| Atomic Design | 部品を大きさで5段階に分ける考え方。原子・分子・生体・テンプレート・ページ |
| ADR | Architecture Decision Record。「なぜその設計にしたか」を1件1ファイルで残す記録 |
① まず、崩れを実数で見る
「たぶん崩れている」で始めると、直したかどうかも分かりません。 数えます。
grep はテキスト処理の回でやったものです。-o で一致した部分だけを取り出し、sort | uniq -c で同じものを数えています。
6 #2563eb
3 #333333
2 #1d4ed8
1 #2463eb
1 #f5f5f5
1 #eee
この出力の読み方が、この節の全部です。
#2563ebと#1d4ed8と#2463ebは、全部「青いボタンの色」のつもりで書いたものです#333333と#eeeと#f5f5f5は、灰色のつもりです- 6色ではありません。「2色を、6回決め直した結果」です
余白も同じように数えられます。
4 padding: 8px
2 padding: 10px
2 margin: 16px
1 padding: 12px
1 gap: 6px
1 gap: 8px
10px と 12px と 6px に理由はありますか。 ほぼ確実に、ありません。そのとき画面を見て、それっぽかっただけです。これがマジックナンバーです。
ここで一度、目で見ておきます。
[スクリーンショット: 01_ボタンが3種類.png] ホストのWindowsのブラウザで ~/react-demo の画面を開き、別々のページ(または別々の場所)にあるボタンを、開発者ツールで並べて選んだ状態を撮ってください。開発者ツールの回でやった Elements パネルで、それぞれの padding と color が違っていることが見えるようにしてください。
ここで大事なのは、「汚いから直す」ではありません。
同じ意味の値が複数あると、変更が終わらなくなります。 ブランドの青を変えたい、と思ったとき、あなたは6箇所を探して、そのうちどれが「青いボタン」でどれが「リンクの青」なのかを判断しなければいけません。1箇所でも漏れると、そこだけ古い青のまま残ります。
② デザインシステムとは何か(スタイルガイドとの違い)
デザインシステムは、デザイナーがいる会社のものという印象があります。それは半分だけ当たっています。
会社でよく言われる目的は「デザイナーとエンジニアの認識合わせ」です。一人にはデザイナーがいないので、その目的は消えます。 それでも、残る目的があります。
決め終わったことを、二度と決め直さないこと。
ここで、よく混同される2つを分けます。
| スタイルガイド | デザインシステム | |
|---|---|---|
| 形 | 文章・画像・PDF | コード(CSS変数・コンポーネント) |
| 守り方 | 人が読んで守る | 使うと自動的に守られる |
| 破り方 | 読まなければ破れる | 破るには、わざわざ書き足す必要がある |
| 古くなると | 黙って嘘になる | 画面が壊れるので気づく |
| 一人での寿命 | だいたい2週間 | 消さない限り残る |
この表の一番下が本題です。
「ボタンの余白は8pxと16pxにする」と NOTES.md に書いても、3か月後のあなたはそのファイルを開きません。 開かないものは、無いのと同じです。
一方、--space-2 という名前しか使えない状態にしてしまえば、思い出す必要がなくなります。 忘れていても守れます。
デザインシステムの本質は「規律」ではなく「思い出さなくてよくすること」です。 記憶に頼る運用は、一人だと必ず失敗します。
これはESLintとPrettierの回で、インデントを人が指摘しないようにしたのと同じ構造です。人の注意力を当てにしない、という一点です。
③ デザイントークンを定義する(・その1)
ここからが実作業です。 決め終わった値に名前を付けて、1つのファイルに置きます。
新しいファイルを作ります。
エディタは VS Code でも構いません(VS CodeからVMを編集する回)。以下を書きます。
:root {
/* 色: 役割で名前を付ける。「青」ではなく「主要な操作の色」 */
--color-primary: #2563eb;
--color-primary-strong: #1d4ed8;
--color-danger: #dc2626;
--color-text: #1f2937;
--color-text-muted: #6b7280;
--color-surface: #ffffff;
--color-border: #d1d5db;
/* 余白: 4px刻みの段階だけを許す。間の数字は存在しないことにする */
--space-1: 4px;
--space-2: 8px;
--space-3: 12px;
--space-4: 16px;
--space-6: 24px;
/* 角丸 */
--radius-sm: 4px;
--radius-md: 8px;
/* 文字サイズ */
--font-size-sm: 14px;
--font-size-md: 16px;
--font-size-lg: 20px;
}
この中身より、決め方のほうが大事です。3つあります。
1つめ。色は「何色か」ではなく「何に使う色か」で名前を付けます。
--color-blue: #2563eb; /* ✗ 青をやめたら名前が嘘になる */
--color-primary: #2563eb; /* ✓ 主要な操作の色。中身は変えられる */
--color-blue にしてしまうと、ブランド色を緑に変えた瞬間に --color-blue: green; という地獄が生まれます。名前は「用途」に付けます。
2つめ。余白は「段階」にします。連続した数字を許しません。
--space-1 から --space-6 までしか無いので、10px を選ぶことができません。 選べないので、迷いません。 これが後で効いてきます。
3つめ。ここに無い値は使わない、と決めます。
トークンを作っても、その横に padding: 13px を書けるなら、何も変わっていません。
次に、これをアプリ全体に読み込ませます。src/main.jsx の先頭に1行足します。
import './tokens.css'
確認します。
--host はReactの回から使っているとおり、VMの外(Windows側のブラウザ)から見えるようにするためのものです。ブラウザで開き、開発者ツールの Elements で html 要素を選び、Styles に :root の変数が並んでいれば読み込めています。
変数は「読み込めているか」が見えにくいので、ここで一度確認しておくと後が楽です。Console で直接引くこともできます。
getComputedStyle(document.documentElement).getPropertyValue('--color-primary')
'#2563eb'
値の前後の空白は、CSS の構文解析の段階で取り除かれるので、: の後に空白を書いていても '#2563eb' がそのまま返ります。古いブラウザでは先頭に空白が付いて返ることがあったので、文字列で比較するなら .trim() を付けておくと安全です。
④ Button を1つ作る(・その2)
トークンだけでは、まだ「毎回決め直す」が止まりません。 使う側が var(--space-2) と var(--space-4) のどちらを選ぶかで、また揺れるからです。
選ばせないために、部品にします。
ディレクトリが無ければ先に作ります。
import './Button.css'
export function Button({
variant = 'primary',
size = 'md',
type = 'button',
disabled = false,
onClick,
children,
}) {
const className = ['btn', `btn--${variant}`, `btn--${size}`].join(' ')
return (
<button type={type} className={className} disabled={disabled} onClick={onClick}>
{children}
</button>
)
}
この15行で一番重要なのは、書いてあることではなく、書いていないことです。
styleを受け取っていません。classNameも受け取っていません。 つまり、使う側は、このボタンの色を変えられません。
続けてCSSを書きます。数字は1つも書きません。全部トークンです。
.btn {
font-size: var(--font-size-md);
border-radius: var(--radius-md);
border: 1px solid transparent;
cursor: pointer;
font-family: inherit;
line-height: 1.4;
}
.btn:disabled {
opacity: 0.5;
cursor: not-allowed;
}
/* サイズ: 余白はトークンの段階からしか選べない */
.btn--sm { padding: var(--space-1) var(--space-3); font-size: var(--font-size-sm); }
.btn--md { padding: var(--space-2) var(--space-4); }
.btn--lg { padding: var(--space-3) var(--space-6); font-size: var(--font-size-lg); }
/* 種類 */
.btn--primary {
background: var(--color-primary);
color: var(--color-surface);
}
.btn--primary:hover:not(:disabled) { background: var(--color-primary-strong); }
.btn--secondary {
background: var(--color-surface);
color: var(--color-text);
border-color: var(--color-border);
}
.btn--danger {
background: var(--color-danger);
color: var(--color-surface);
}
/* フォーカスの輪郭は必ず残す */
.btn:focus-visible {
outline: 2px solid var(--color-primary-strong);
outline-offset: 2px;
}
最後の :focus-visible は飾りではありません。
アクセシビリティの回で、フォーカスの輪郭を消すとキーボードで操作できなくなることをやりました。部品にしておくと、この対応が1箇所で済みます。 逆に言えば、ボタンを毎回手で書いていると、outline: none を書き忘れずに直す作業が、ボタンの数だけ発生します。
部品化のいちばん大きな利益は、見た目ではなく「正しい対応が1箇所で済む」ことです。
使ってみます。src/App.jsx の適当な場所を、こう書き換えます。
import { Button } from './components/Button'
// 中略
<Button onClick={addTask}>追加</Button>
<Button variant="secondary" onClick={clearInput}>クリア</Button>
<Button variant="danger" size="sm" onClick={removeAll}>全部消す</Button>
ブラウザで見て、3つのボタンが違う見た目で出れば成功です。Tabキーで移動して、輪郭が出ることも確かめてください。
戻し方: うまくいかなければ、App.jsx の変更を元に戻すだけで済みます。Button.jsx と Button.css は誰からも読まれないファイルとして残るだけなので、消さなくても害はありません。Gitでコミットしてから始めておくと、git checkout -- src/App.jsx で1発です。
⑤ なぜ「使う側が自由に書けない」ほうが良いのか
ここが、この記事で一番受け入れにくいところだと思います。普通、部品は「柔軟なほうが良い」と考えるからです。
こういう Button を作りたくなります。
// ✗ 一見、親切に見える
export function Button({ color, padding, radius, children }) {
return <button style={{ background: color, padding, borderRadius: radius }}>{children}</button>
}
これは、ボタンではありません。 ただの <button> に、遠回りな書き方を足しただけです。使う側は結局、毎回 color を決め直します。 つまり、冒頭の問題が1ミリも解決していません。
制約が一貫性を作ります。 「選べない」ことが機能です。
では、どうしても例外が要るときはどうするか。 例外は必ず出ます。そのときの態度を決めておきます。
| 例外の頼まれ方 | どうするか |
|---|---|
| 「ここだけ色を変えたい」 | まず断る。「なぜここだけ違うのか」を先に言葉にする |
| 言葉にできた(例: 破壊的な操作だから赤) | variant を1つ増やす。部品の側に入れる |
| 言葉にできない(なんとなく) | やらない。 揃っているほうが良い |
| 本当に1回きり(キャンペーン用など) | 部品を使わず、その場に別の要素として書く。部品に穴を開けない |
「部品に穴を開けない」が要点です。 style を1回通してしまうと、次からは全員がそこを通ります。 穴は必ず広がります。
Tailwind を使っている場合は、設定に閉じ込める
Tailwind の回を読んだ人は、「Tailwind だと bg-[#2563eb] と書けてしまうのでは」と思ったはずです。そのとおりで、任意の値を直接書ける記法があります。 これを放置すると、Tailwind でも同じ崩れが起きます。
Tailwind でのやり方は、CSS変数の代わりに、テーマ設定に色と余白を登録して、そこに名前が生えた状態にすることです。最近の Tailwind ならCSS側に @theme ブロックを書いて登録し、以降は bg-primary のような自分で決めた名前だけを使います。登録していない値は名前が存在しないので、自然に選べなくなります。
考え方はまったく同じです。 「決め終わった値に名前を付けて、名前しか使わせない」。置き場所がCSS変数か、フレームワークの設定かの違いでしかありません。設定の正確な書き方はバージョンで変わるので、公式ドキュメントを見てください(末尾にリンクを置きました)。
⑥ ドキュメント化 — Storybook を入れない判断
部品が増えると、「いまどんな部品があるのか」が分からなくなります。 アプリの画面を開いても、その部品が使われている画面まで行かないと見られないからです。
これを解決するのが Storybook です。役割は明確です。
部品を、アプリから切り離して、1つずつ表示・操作できる場所を作るツール。
「ログイン後の、エラーが出ている状態のボタン」を見るのに、実際にログインしてエラーを起こす必要がなくなります。 これは実際にありがたい機能です。
それでも、この記事では入れません。 理由を正直に書きます。
- 重い。依存パッケージが大量に増えます。node_modules の回で見たとおり、インストールされるものが増えるほど、壊れる箇所が増えます
- 設定ファイルがもう1系統増える。Vite の設定とは別に、Storybook 用のビルド設定を持つことになります
- いまの部品は1つです。 部品1つのために管理対象を1つ増やすのは、明らかに割に合いません
入れるなら、いまのアプリではなく、部品専用の別プロジェクトにしてください。 学習用のアプリに混ぜると、Storybook が壊れたときにアプリまで動かなくなります。
代わりに、同じ役割の「カタログページ」を自分で1枚作ります。 30行で済みます。
import { Button } from './components/Button'
const VARIANTS = ['primary', 'secondary', 'danger']
const SIZES = ['sm', 'md', 'lg']
export function Catalog() {
return (
<main style={{ padding: 'var(--space-6)', color: 'var(--color-text)' }}>
<h1 style={{ fontSize: 'var(--font-size-lg)' }}>部品カタログ</h1>
<h2 style={{ fontSize: 'var(--font-size-md)' }}>Button</h2>
<table>
<tbody>
{VARIANTS.map((variant) => (
<tr key={variant}>
<th style={{ textAlign: 'left', paddingRight: 'var(--space-4)' }}>{variant}</th>
{SIZES.map((size) => (
<td key={size} style={{ padding: 'var(--space-2)' }}>
<Button variant={variant} size={size}>保存する</Button>
</td>
))}
<td style={{ padding: 'var(--space-2)' }}>
<Button variant={variant} disabled>保存する</Button>
</td>
</tr>
))}
</tbody>
</table>
</main>
)
}
表示の切り替えに、ルーティングは要りません。 ルーティングの回を入れていない人でも動くように、URLの ?catalog を見るだけにします。src/App.jsx の一番上(App 関数の中の先頭)に足します。
import { Catalog } from './Catalog'
function App() {
if (window.location.search.includes('catalog')) return <Catalog />
// 以降はこれまでどおり
ブラウザで、アドレスの末尾に ?catalog を付けて開きます。
http://<VMのIPアドレス>:5173/?catalog
VMのIPアドレスは、ネットワークの回でやった ip a で確認できます。
[スクリーンショット: 02_カタログページ.png] ブラウザで ?catalog を付けて開き、3種類 × 3サイズ + 無効状態のボタンが表で並んでいる画面を撮ってください。
このページの価値は、並べたことではありません。
「同じはずのものが、並べたときに揃っていない」が、一目で分かることです。
実際、私はここで sm だけ文字色が薄く見えることに気づきました。並べるまで気づきませんでした。アプリの画面では、それぞれ別のページに散っていたからです。
Storybook が本当にやっているのも、突き詰めればこれです。 ツールが要るのは、部品が50個を超えて、状態の組み合わせが手で書ききれなくなってからで十分です。
⑦ 命名の話 — Atomic Design はそのまま使わなくていい
部品が増えると、次に困るのは置き場所と名前です。ここで必ず見つかるのが Atomic Design です。部品を大きさで5段階に分ける考え方です。
| 段階 | 例 | 一人での実用度 |
|---|---|---|
| Atoms(原子) | ボタン、入力欄、ラベル | 使える。分かりやすい |
| Molecules(分子) | ラベル+入力欄+エラー文の組 | 使える |
| Organisms(生体) | 検索フォーム全体、ヘッダー | 境目が決まらない |
| Templates(テンプレート) | 中身が空の画面レイアウト | Reactでは持て余しがち |
| Pages(ページ) | 実データが入った画面 | ふつうのページ |
正直に書きます。 Molecules と Organisms の線引きで、私は30分悩んで、答えが出ませんでした。 そして、悩んでいる間、画面は1ミリも進んでいません。
分類に悩んだ時点で、その分類はあなたのプロジェクトに合っていません。
一人でやるなら、2段階で十分です。
src/components/ … どのページでも使う部品(Button, Input, Card)
src/features/ … その画面専用のかたまり(TaskList, TaskForm)
判断基準は1つだけです。「2つ以上の画面で使うか」。 使うなら components/、使わないなら features/。迷ったら features/ に置いて、2回目に使うときに動かします。
Atomic Design を知る価値はあります。 「部品には大きさの階層がある」という視点は正しいからです。ただ、5段階をそのまま採用する必要はありません。 これはマイクロサービスの回で「有名な構成をそのまま真似しない」と書いたのと同じ話です。
⑧ 設計を言葉にする — ADR を1つ書く
ここまでで、トークンとボタンとカタログができました。これで終わりにすると、半分残ります。
3か月後のあなたが Button.jsx を開いて、こう思うからです。
「なんで
styleを受け取らないようにしてるんだ? 不便だな。足そう」
そして足します。 理由を知らないからです。そして、崩れが戻ります。
コードは「何をしているか」しか書けません。「なぜそうしたか」は書けません。 コメントで書くこともできますが、「なぜそうしなかったか」(検討して捨てた案)はコメントには入りません。
そこで使うのが ADR(設計判断の記録) です。1つの判断を、1つのファイルに、短く残します。
# 0001. 見た目の値はトークンに集約し、部品は style を受け取らない
- 状態: 採用
- 日付: 2026-09-13
## 背景
ページを増やすうちに、同じ意味の色が4つ、同じ意味の余白が5つできていた。
grep で数えたところ、青系が #2563eb / #1d4ed8 / #2463eb の3つに分かれていた。
原因は、新しい画面を作るたびに値をその場で決め直していたこと。
## 決めたこと
1. 色・余白・角丸・文字サイズは src/tokens.css に CSS変数として定義する。
2. コンポーネントのCSSに生の数値を書かない。必ず var() を使う。
3. Button は variant と size のみを受け取る。style と className は受け取らない。
## 理由
- 使う側が値を選べる限り、選び直しは必ず起きる。制約でしか止められない。
- フォーカスの輪郭など、アクセシビリティ上必須の指定を1箇所で保証したい。
## 検討して採用しなかった案
- **NOTES.md にルールを書く**: 読まなくても破れるため、2週間で守られなくなると判断した。
- **Button に color を渡せるようにする**: 一度穴を開けると全員がそこを通る。
- **Storybook を導入する**: 部品1つに対して依存と設定が重すぎる。
カタログページ(src/Catalog.jsx)で当面代替する。部品が増えたら再検討する。
## 結果として困りうること
- 例外的な見た目が必要になったとき、variant を増やす手間がかかる。
「なぜここだけ違うのか」を言葉にできない例外は、やらない方針とする。
この書式に厳密な決まりはありません。 ただ、この5つの見出しは外さないでください。
| 見出し | なぜ要るか |
|---|---|
| 背景 | 当時の状況。前提が変われば判断も変わってよい、と後で分かる |
| 決めたこと | 結論。ここだけ読めば行動できる |
| 理由 | 説得の材料。未来の自分を止めるのはこれ |
| 採用しなかった案 | 一番価値がある。同じ検討を2回しなくて済む |
| 困りうること | 正直さ。欠点を隠した記録は信用されない |
そして、ADR は書き換えません。 判断が変わったら、0002- を新しく作って、0001 の状態を「廃止(0002に置き換え)」に直します。
上書きすると、「なぜ変えたのか」が消えます。 これは Gitの履歴を残すのと、まったく同じ理由です。
忘れずに、コミットします。
ADR をコードと同じリポジトリに置くのが要点です。 別の場所(メモアプリなど)に置くと、コードを直すときに目に入りません。 目に入らない記録は、無いのと同じです。
⑨ データの持ち方も、同じ「設計」の話
ここまで見た目の話をしてきましたが、まったく同じ失敗がデータでも起きます。
たとえば、タスクに「担当者名」を持たせたくなったとします。
tasks テーブル: id | title | done | assignee_name
users テーブル: id | name | email
動きます。 タスクを取り出すだけで名前まで出るので、むしろ速いです。
そして、ユーザーが名前を変えた瞬間に嘘になります。 users.name は変わりましたが、tasks.assignee_name は昔の名前のままです。どちらが正しいのか、システムは判断できません。
同じ情報を2か所に持った時点で、ズレるかどうかは「いつ」の問題になります。 「起きるかどうか」ではありません。
正しくは、名前は users にだけ持ち、tasks は user_id だけを持ちます。 名前が要るときは、そのとき引きます。
この判断も、ADR に書く価値があります。 なぜなら、後で「毎回引くのが遅いので、名前もコピーして持とう」と言い出す日が来るからです(これを意図的にやるのがキャッシュの回でやったことです)。やってはいけないのではなく、「ズレることを承知でやる」と決めて、記録するのが正しい形です。
外部と繋ぐときの3つの型
もう1つ、必ず決めることになるのが「他のシステムとどう繋ぐか」です。選択肢は、だいたい3つしかありません。
| 型 | やり方 | 向いている場面 | 代償 |
|---|---|---|---|
| 同期で呼ぶ | 相手のAPIをその場で叩き、返事を待つ | 結果がすぐ要る(決済の可否、在庫の確認) | 相手が落ちると自分も落ちる。相手が遅いと自分も遅い |
| キューを挟む | やることをキューに積み、後で処理する | すぐでなくてよい(メール送信、画像変換) | いつ終わるか保証できない。失敗時の再実行を自分で設計する |
| 定期で取り込む | 1日1回まとめて取得して自分側に入れる | 相手が古い仕組み、量が多い、リアルタイム性が不要 | 最大1日ズレる。ズレてよいことを合意しておく必要がある |
「どれが正しいか」ではありません。「どれくらいズレてよいか」を先に決めると、自動的に1つに決まります。そして、そのズレの許容範囲こそ、ADR に書くべきことです。コードには絶対に書けません。
⑩ やりすぎない — ここで止める
最後に、この記事で一番伝えたいことを書きます。
デザインシステムは、やろうと思えばいくらでもやれます。 色を10段階の濃淡に展開し、ダークモードに対応し、部品を30個揃え、Figma と同期し……全部やった頃には、アプリが1行も進んでいません。
一人でデザインシステムを作り込むのは、「作っている気持ちになれる作業」です。 画面が進んでいないのに、進んだ気がします。
一人に必要なのは、これだけです。
| 要る | 要らない(いまは) |
|---|---|
| トークン(色・余白・角丸・文字サイズ) | 色の濃淡10段階 |
| よく使う部品3つ(Button / Input / Card) | 部品30個 |
| カタログページ1枚 | Storybook |
| ADR 数本 | デザイン仕様書 |
| — | Figma との自動同期 |
部品3つの選び方も決まっています。「もう3回書いたもの」だけを部品にします。 1回目は書く、2回目はコピーする、3回目に部品にします。
先回りして部品を作ると、たいてい形が間違っています。 使われ方をまだ知らないからです。3回書いた後なら、何が変わって何が変わらないかを、実物で知っています。
これはテストの回やマイクロサービスの回と同じ結論です。先に完璧な構造を作らない。困ってから直す。
つまずいたところ
CSS変数の値の先頭に空白が入る、と思い込んでいた。 古い説明では getPropertyValue('--color-primary') が ' #2563eb' のように空白付きで返り、.trim() が要るとされていました。いまの仕様では、宣言の値の前後の空白は CSS の構文解析で取り除かれるので、現行のブラウザは '#2563eb' を返します。=== '#2563eb' が false になったら、空白より先に、変数名の綴りと、どの要素から読んでいるかを疑ってください。
Button.css を作ったのに、スタイルが当たらなかった。 Button.jsx に import './Button.css' を書き忘れていました。素のCSSと違い、Vite ではファイルを作っただけでは読み込まれません。 ビルドツールの回でやったとおり、import されたものだけが辿られます。 開発者ツールの Elements で .btn の Styles が空だったので気づきました。
トークンを作った直後、padding: 12px を無意識に書いていた。 Button.css を書いている最中に、自分で作ったばかりのルールを自分で破りました。 手が勝手に数字を打ちます。ルールを決めても、意識では守れないという、この記事の主張の実演になってしまいました。書いた後に grep -n '[0-9]px' src/components/ で1回洗うのが確実です。
variant の名前を type にしていて、HTMLの type と衝突した。 最初 <Button type="danger"> と書いていて、<button type="danger"> という不正なHTMLが出力されました。 フォームの中で、送信のつもりではないボタンまで送信ボタンとして動いてしまい(不正な type は送信扱いになる)、原因が分かるまで時間がかかりました。type はHTMLが既に使っている属性名なので、部品の props に使ってはいけません。
Storybook を一度入れかけて、消した。 実は途中で npx storybook@latest init を走らせました。依存が数百パッケージ増え、Vite の設定と噛み合わず、起動までに10分以上かかりました。 部品が1つしかない状態でやることではなかった、というのが結論です。node_modules ごと消して戻しました(npm の回でやったとおり、node_modules は消して npm install し直せます)。
ADR の最初の1本に、30分かけて長文を書いてしまった。 長い記録は続きません。 2本目からは15行程度に抑えています。ADR は論文ではなく、「なぜ」を1つだけ残すメモです。書くのが面倒になった時点で、その仕組みは死にます。
後片づけ
この回で作ったものは、消さずに残してください。 以降ずっと使います。
開発サーバーを止めるだけで十分です。 npm run dev を動かしている端末で Ctrl + C を押します。
カタログページを消したい場合は、App.jsx の2行(import と if の行)を消せば、それだけで表示されなくなります。Catalog.jsx 自体は残しておいて構いません。
全部やめて元に戻したい場合は、コミット前なら次で戻せます。
git checkout -- . は、その日書いた全部を消します。 ファイル名を必ず指定してください。
まとめ
この回で理解できたことです。
- 見た目の崩れは、注意力の問題ではありません。 毎回その場で決め直しているという、手順の問題です。だから手順を変えるしか直りません
- スタイルガイド(読むもの)とデザインシステム(使うもの)は別物です。 一人で守れるのは後者だけです。記憶に頼る運用は必ず失敗します
- トークンは「値の一覧」ではなく「選択肢の制限」です。
--space-1から--space-6しか無いから、10pxを選べません。選べないから、迷いません - 良い部品は、できることが少ない部品です。
styleを受け取らないButtonは不便に見えますが、その不便さが一貫性の正体です :focus-visibleのような「忘れやすいが必須の対応」が1箇所で済むのが、部品化の最大の利益でした。見た目の統一は副産物です- Storybook は「部品を単体で並べて見る」ためのものです。 役割さえ分かっていれば、30行のカタログページで代替できます。入れるかどうかは、部品の数で決めます
- Atomic Design の5段階は、そのまま使わなくて構いません。 分類に悩んだ時間は、成果物を1ミリも進めません
- コードは「なぜそうしなかったか」を書けません。 それを残す場所が ADR です。未来の自分が、あなたの決定を勝手に取り消すのを止められるのは、この記録だけです
- 同じ情報を2か所に持てば、必ずズレます。 見た目でもデータでも同じです。意図的に持つなら、そう決めて記録します
- 一人でデザインシステムを作り込まないでください。 トークンと、3回書いた部品3つと、ADR 数本。それ以上は、作っている気持ちになれるだけの作業です
この回で本当に手に入れたのは、ボタンではありません。
「一度決めたことを、二度と決め直さない」という置き方です。
見た目でそれをやるとデザインシステムと呼ばれ、データでやると正しい持ち方と呼ばれ、判断そのものでやると ADR と呼ばれます。名前は違いますが、全部同じことをしています。
参考リンク
- roadmap.sh — Frontend Developer
- MDN — CSS カスケード変数(カスタムプロパティ)
- MDN — :focus-visible
- Design Tokens Community Group
- Tailwind CSS — テーマの設定
- Storybook 公式ドキュメント
- Atomic Design(Brad Frost)
- Architecture Decision Records
- ADR のテンプレート集(joelparkerhenderson)
- Material Design 3 — 大規模なデザインシステムの実例
- React 公式 — コンポーネントに props を渡す
次に読む
この記事は 【第8段階】深掘り の 18 / 30 本目です。
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
- デザイントークンと、部品を1か所に置く
- 設計判断を記録する(ADR)とデータの持ち方
この記事は、上の項目を実際に手を動かして確かめる回です。

コメント