同じボタンが3種類できる理由 — デザインシステム

デザインシステム。同じ形のボタンのカタログと色見本、余白を測る定規。

同じつもりのボタンが、いつの間にか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つ

この記事でやること

  1. いま自分のコードに何色あるかを grep で数える。感覚ではなく実数で崩れを見る
  2. src/tokens.css にデザイントークンを書く(色・余白・角丸・文字サイズをCSS変数にする)
  3. variant を props で受ける Button を作る。使う側が色を指定できない形にする
  4. 部品を並べた「カタログページ」を自分で1枚作る(Storybook は入れません)
  5. docs/adr/0001-design-tokens.md を書いて、なぜそう決めたのかを残す

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
デザインシステム見た目のルールを、文章ではなくコードとして1か所に置いたもの。使うと自動的にルールが守られる
スタイルガイド見た目のルールを文章と画像で説明したもの。読む人が守る前提で、強制力はない
デザイントークン色・余白・角丸などの決め終わった値に名前を付けたもの。--color-primary のような形で持つ
CSS変数(カスタムプロパティ)CSSの中で値に名前を付ける仕組み。--name: 値 で定義し、var(--name) で使う
マジックナンバーコードに直接書かれた、理由の分からない数字。padding: 13px の 13 がなぜ13なのか誰も説明できない状態
variant(バリアント)同じ部品の種類違い。ボタンなら「主要な操作」「補助的な操作」「危険な操作」など
Storybook部品をアプリから切り離して1つずつ表示・操作できるようにする開発ツール
Atomic Design部品を大きさで5段階に分ける考え方。原子・分子・生体・テンプレート・ページ
ADRArchitecture Decision Record。「なぜその設計にしたか」を1件1ファイルで残す記録

① まず、崩れを実数で見る

「たぶん崩れている」で始めると、直したかどうかも分かりません。 数えます。

bash
$ cd ~/react-demo
$ grep -rhoE '#[0-9a-fA-F]{3,8}' src/ | sort | uniq -c | sort -rn

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回決め直した結果」です

余白も同じように数えられます。

bash
$ grep -rhoE '(padding|margin|gap): *[0-9]+px' src/ | sort | uniq -c | sort -rn
      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つのファイルに置きます。

新しいファイルを作ります。

bash
$ cd ~/react-demo
$ nano src/tokens.css

エディタは 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'

確認します。

bash
$ npm run dev -- --host

--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) のどちらを選ぶかで、また揺れるからです。

選ばせないために、部品にします。

bash
$ nano src/components/Button.jsx

ディレクトリが無ければ先に作ります。

bash
$ mkdir -p ~/react-demo/src/components
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つも書きません。全部トークンです。

bash
$ nano src/components/Button.css
.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行で済みます。

bash
$ nano src/Catalog.jsx
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つのファイルに、短く残します。

bash
$ mkdir -p ~/react-demo/docs/adr
$ nano ~/react-demo/docs/adr/0001-design-tokens.md
# 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の履歴を残すのと、まったく同じ理由です。

忘れずに、コミットします。

bash
$ cd ~/react-demo
$ git add docs/adr/0001-design-tokens.md src/tokens.css src/components src/Catalog.jsx
$ git commit -m "feat: デザイントークンとButtonを追加し、判断をADRに記録"

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 自体は残しておいて構いません。

全部やめて元に戻したい場合は、コミット前なら次で戻せます。

bash
$ cd ~/react-demo
$ git status          # 何が変わったかを先に見る
$ git checkout -- src/App.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 と呼ばれます。名前は違いますが、全部同じことをしています。

参考リンク


次に読む

この記事は 【第8段階】深掘り の 18 / 30 本目です。

記事
← 前の記事JavaScriptを送らないサイト — AstroとSSG
→ 次の記事一人でもmainに直接コミットしない — PRとレビュー

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

Frontend›Design Systems
  • デザイントークンと、部品を1か所に置く
  • 設計判断を記録する(ADR)とデータの持ち方

この記事は、上の項目を実際に手を動かして確かめる回です。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次