デザインシステムは「ボタン量産」で死ぬ：コンポーネント設計と運用を小さく育てる

「デザインシステムを作ろう」と、画面ごとに見つけたボタンを別コンポーネントへ切り出す。最初の1週間は速く進みます。

PrimaryButton、PrimaryButtonLarge、SubmitButton、SaveButton、DangerButtonOutline。Figmaに出てきた見た目をそのまま部品にすれば、Storybookにもすぐ並べられます。しかし、名前と値の重複はその時点では見えません。

数週間後にブランドカラーを少し濃くすると、11個のボタンを順番に開いて同じ色を直すことになります。どこまで変更したか確認できず、1個直すたびに他のボタンとの差分が増えます。これは実装速度ではなく、変更経路を設計していないことが原因です。

これは部品の問題じゃありません。設計と運用の問題です。デザインシステムは、ボタンをたくさん作ると死にます。少ない部品を、正しい粒度と名前で持ち、チームで壊さず育てる仕組みがないと、ただの「使われないUIフォルダ」になる。今日はそこを、Claude Codeを横に置きながら、小さく始めて育てる順番で書きます。

この記事の要点

• デザインシステムの主役はボタンの数ではなく、コンポーネントの粒度・命名・バリアント設計と、チームでの運用ルール。ここが崩れると即破綻する。
• バリアントは「見た目」で増やさず「意味」で持つ。variant="blue"ではなくvariant="primary"。色や余白の値そのもの(トークン層)はDesign Tokensの実装ガイドに分離して、この記事はその上のコンポーネントと運用に集中する。
• Storybookは「部品カタログ」ではなく仕様書として使う。Storyにない状態はレビューもテストもできない。
• Claude Codeには「全部作って」ではなく「Buttonだけ、既存API互換で、Story付きで」と粒度を切って渡す。境界が曖昧だと巨大差分でレビュー不能になる。
• いきなり全部を整えない。よく使う1部品から始め、PRレビューと最低限のCIで品質を固定し、安全だと分かった範囲を少しずつ広げる。

Claude Codeに任せる範囲と人が判断する範囲

Claude Codeへ渡すのは、既存コードの棚卸し、限定した1部品の実装、Story、テスト、変更一覧です。ブランドの意味、公開API、例外を共通仕様へ入れるか、マージしてよいかは人が決めます。

作業	Claude Codeに任せる範囲	人が判断する範囲
棚卸し	Button利用箇所、raw value、既存variantの一覧	同じ意味として統合してよいか
実装	指定ディレクトリ内の1部品と互換props	公開API、名称、廃止時期
Story／テスト	全状態のStory、a11y／visual test、実行結果	文言、読み上げ順、キーボード操作の自然さ
公開	差分、影響画面、ロールバック手順の提示	PR承認、段階展開、例外の許可

デザインシステムは「部品集」ではなく約束事

最初に誤解を解きます。デザインシステムは、ボタンやカードを集めたフォルダのことではありません。

デザインシステムはチーム全員が守る約束事です。「保存ボタンはこの形」「危険な操作はこの色」「フォームの間隔はこの広さ」。この約束が言葉とコードで固定されているから、誰が画面を作っても揃います。部品はその約束を運ぶ容器です。

だから作るときの問いも変わります。「どんな部品が要るか」ではなく、まず「何を揃えたいのか、誰が決めるのか、どうやって壊れないようにするのか」。この順番を飛ばすと、見た目ごとのボタンが増え続けます。

そしてもうひとつ。色・余白・文字サイズといった「素の値」をどう管理するかは、この記事では深追いしません。そこはトークン層という別レイヤーの話で、Claude CodeでDesign Tokensを実装する実践ガイドに分けてあります。この記事は、トークンができている前提で、その上に乗るコンポーネントと運用に軸足を置きます。

コンポーネントの粒度：迷ったら「分けない」

設計でいちばん事故るのが粒度です。細かく分けすぎても、大きく作りすぎても痛い。

よくある失敗は、「再利用できそう」という理由だけでButtonをButtonWrapper・ButtonInner・ButtonLabel・ButtonIconに分けることです。1個のボタンを置くのに4つの公開APIを理解する必要が生まれ、利用側の負担が増えます。

最初の判断基準は次の3つで十分です。

• 3回以上、別の画面で同じものが出てきたら部品にする。1〜2回ならその場で書く。
• propsで分岐が3つを超えそうなら、別コンポーネントへの分割を考える。
• 「これは何?」と一言で説明できる単位で切る。説明に「と」が2回入ったら分けすぎ、または大きすぎる。

粒度の言葉として、Atomic Design(原子→分子→生物→テンプレート→ページ)は便利な地図です。ただし、最初から5階層を固定する必要はありません。「単体で意味を持つ部品(Button、Input)」と「それらを組んだ塊(SearchForm、Card)」の2段で始め、実際の再利用箇所が増えてから階層を足します。

下の表を、部品化する前のレビュー基準にします。

サイン	部品にする	その場で書く
同じ見た目の出現回数	3回以上	1〜2回
内部の状態(loading/error等)	状態を持つ	持たない静的表示
チームでの呼び名	名前で会話に出る	名前がまだ無い
デザインでの扱い	Figmaでコンポーネント化済み	1回限りの装飾

迷ったときは「分けない」。あとから分けるのは簡単ですが、散らばった部品を統合するのは地獄です。

命名：見た目で名づけると、半年後に詰む

BlueButton、LargeButton、OutlineButtonのように見た目で名前を付けると、配色やサイズの方針を変えた時点で名前と実装が食い違います。

ブランドカラーが青から緑になった瞬間、BlueButtonは嘘になります。でもコードの何百箇所で使われていて、リネームは怖い。だから誰も直さず、緑色のBlueButtonという地雷が残る。

教訓は一つです。名前は「役割」でつける。

• 良い名前：primary(主要な操作)、danger(取り消せない操作)、secondary(補助)、ghost(背景に溶ける)
• 悪い名前：blue、red、big、outline(全部「見た目」)

役割で名づけておけば、青を緑に変えてもprimaryはprimaryのまま。意味が変わらないから、コードを触らずに配色だけ差し替えられます。これはトークン層と地続きの話で、primaryという役割名が、トークン側のaction.background.primaryのような意味ベースの値につながっているのが理想です。

コンポーネント名も同じ発想です。SaveButtonのように「特定の用途」を名前に焼き込むと、保存以外で使えなくなる。Buttonにvariantと用途を渡す形にして、名前は汎用に保ちます。命名規則はチームで1枚のメモにして、Claude Codeにも読ませておくと、生成されるコードがブレません。

動く確認コード: Buttonのバリアントを固定する

ここがコンポーネント設計の核心です。バリアント(variant)とは、同じ部品の「見た目や振る舞いの種類」のこと。ボタンなら主要・危険・補助、サイズなら小中大、といった軸です。

問題は、軸が増えると組み合わせが掛け算で爆発することです。variant 4種 × size 3種 × loading × disabled……と素朴に考えると、検証すべき状態が数十通りになる。ここを設計でどう潰すかで、運用のラクさが決まります。

掛け算を抑える方法は3つです。

1. 軸を直交させる。variantとsizeとstateは互いに独立にする。「dangerのときだけsizeが効かない」みたいな例外を作らない。例外が1個あるだけで、使う人は全組み合わせを疑い始めます。
2. 状態はbooleanで持つ。loading、disabledはvariantに混ぜず、独立したフラグにする。PrimaryLoadingButtonのような名前は作らない。
3. デフォルトを必ず決める。何も指定しなくても安全に動く既定値(primary/md)を用意する。これで「とりあえず置く」が壊れません。

この設計を素直にコードへ落とすと、軸が増えても破綻しません。下は、class-variance-authority(CVA、Tailwindのクラスをバリアント単位で管理するライブラリ)を使った、コピペで動くButtonです。

import { forwardRef, type ButtonHTMLAttributes } from "react";
import { cva, type VariantProps } from "class-variance-authority";
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

// Tailwindのクラス衝突を解決しつつ結合する小さなヘルパー
function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

// バリアントは「軸」ごとに独立して定義する（直交させる）
const buttonVariants = cva(
  [
    "inline-flex items-center justify-center gap-2 rounded-md font-medium",
    "transition-colors focus-visible:outline-none focus-visible:ring-2",
    "focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
  ],
  {
    variants: {
      // 見た目ではなく「役割」で名づける
      variant: {
        primary: "bg-blue-600 text-white hover:bg-blue-700 focus-visible:ring-blue-600",
        secondary: "border border-gray-200 bg-white text-gray-900 hover:bg-gray-50",
        danger: "bg-red-600 text-white hover:bg-red-700 focus-visible:ring-red-600",
        ghost: "text-gray-900 hover:bg-gray-100",
      },
      size: {
        sm: "h-8 px-3 text-sm",
        md: "h-10 px-4 text-sm",
        lg: "h-12 px-6 text-base",
      },
    },
    // 何も指定しなくても安全に動く既定値を必ず置く
    defaultVariants: { variant: "primary", size: "md" },
  }
);

export interface ButtonProps
  extends ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  // 状態はvariantに混ぜず、独立したフラグで持つ
  loading?: boolean;
}

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
  { className, variant, size, loading = false, disabled, children, ...props },
  ref
) {
  return (
    <button
      ref={ref}
      className={cn(buttonVariants({ variant, size }), className)}
      disabled={disabled || loading}
      aria-busy={loading || undefined} // 読み上げソフトに「処理中」を伝える
      {...props}
    >
      {loading ? (
        <span
          aria-hidden="true"
          className="h-4 w-4 animate-spin rounded-full border-2 border-current border-r-transparent"
        />
      ) : null}
      <span>{children}</span>
    </button>
  );
});

色の値を直書きしている部分(bg-blue-600等)は、運用が育ったらトークン由来のCSS変数に置き換えます。その手順はDesign Tokensの実装ガイドにまとめてあるので、ここではコンポーネントの形に集中してください。大事なのは、variantが役割名で、loadingが独立フラグで、既定値があること。この3点が守られていれば、軸を足しても壊れません。

新しいwarningバリアントを足す前に、dangerとの違いを一文で説明します。説明できなければ、新しいバリアントではなく既存の使い方を直す問題です。バリアントは資産ですが、増えるたびに検証すべき組み合わせも増えます。

Storybook：カタログではなく「仕様書」として書く

Storybookを「作った部品を眺める場所」だと思っていると、もったいない使い方になります。

Storybookは動く仕様書として使います。「このボタンには主要・危険・補助・loading・disabledの状態がある」という約束を固定する場所です。Storyにない状態はレビューにも自動テストにも載りません。

ポイントは2つ。全状態を1つのStoryに並べることと、a11yチェックを最初から有効にすることです。Storybookのa11yアドオンはparameters.a11y.testを"error"にすると、アクセシビリティ違反をテスト失敗として扱えます(これは公式の現行APIです)。

import type { Meta, StoryObj } from "@storybook/react-vite";
import { Button } from "./Button";

const meta = {
  title: "Design System/Button",
  component: Button,
  parameters: {
    layout: "centered",
    // a11y違反をCIで失敗にする（現行の公式オプション）
    a11y: { test: "error" },
  },
  argTypes: {
    variant: { control: "select", options: ["primary", "secondary", "danger", "ghost"] },
    size: { control: "select", options: ["sm", "md", "lg"] },
    loading: { control: "boolean" },
    disabled: { control: "boolean" },
  },
} satisfies Meta<typeof Button>;

export default meta;
type Story = StoryObj<typeof meta>;

// 全状態を1画面に並べる「仕様書」Story
export const AllStates: Story = {
  render: () => (
    <div className="flex flex-wrap items-center gap-3">
      <Button variant="primary">保存する</Button>
      <Button variant="secondary">キャンセル</Button>
      <Button variant="danger">削除する</Button>
      <Button variant="ghost">あとで</Button>
      <Button size="sm">Small</Button>
      <Button size="lg">Large</Button>
      <Button disabled>Disabled</Button>
      <Button loading>Loading</Button>
    </div>
  ),
};

Claude Codeにこのファイルを任せるなら、「Buttonの公開propsを読んで、全variant・全size・loading・disabled・キーボードフォーカスが見えるStoryを足して。既存Storyは消さないで」と頼みます。Storybook自体の育て方はClaude CodeでStorybook開発を育てる実践ガイドに詳しいので、カタログ運用やテスト連携を深掘りしたい人はそちらへ。

一貫性をテストで担保する：現行のVitest addonを使う

2026年7月時点で、ViteベースのStorybookは@storybook/addon-vitestが公式の推奨経路です。Storyをブラウザ上のコンポーネントテストへ変換し、前の節で指定したparameters.a11y.test = "error"もCIの失敗条件にできます。旧@storybook/test-runnerを前提にした記事をそのままコピーしないでください。

npx storybook@latest init
npx storybook add @storybook/addon-a11y
npx storybook add @storybook/addon-vitest
npx playwright install chromium
npm run test:storybook -- --run

package.jsonのtest:storybookはvitest --project=storybookにします。Vitest addonはVite系frameworkまたは対応するNext.js Vite統合が前提です。該当しない構成では、公式のtest-runner fallbackを選びます。設定条件はVitest addon公式資料と移行ガイドで確認してください。

ビジュアル差分をローカルに持つ場合は、重要なStoryだけをPlaywrightで撮ります。日付やランダムIDを固定し、アニメーションを止めないと毎回差分が出ます。

初回だけは対象アプリでnpx playwright test tests/button.visual.spec.ts --update-snapshotsを実行し、人が基準画像を確認してリポジトリへコミットします。基準画像がないままCIへ送ると、比較対象がないため最初の実行は失敗します。

import { expect, test } from "@playwright/test";

test("Buttonの全状態", async ({ page }) => {
  await page.goto("http://127.0.0.1:6006/iframe.html?id=design-system-button--all-states");
  await expect(page).toHaveScreenshot("button-all-states.png", {
    fullPage: true,
    animations: "disabled",
  });
});

自動a11yテストは万能ではありません。ラベル欠落や一部のコントラスト問題は検出できますが、「文言が文脈に合うか」「キーボード操作が自然か」は人が確認します。この境界はアクセシビリティ対応の実践ワークフローで扱っています。

3つのUse case

Use case 1: SaaS管理画面のButtonを統合する

管理画面では保存、招待、削除、再実行などの操作が増え、同じ意味のボタンが画面ごとに別実装になりがちです。Claude Codeには、Button利用箇所、直書き色、loading／disabled状態を一覧化させ、既存APIを壊さない互換propsと1画面分の移行差分を作らせます。

人は「主要操作は各画面に1つ」「削除は確認ダイアログを通す」といった業務ルールを決めます。最初の出力は全画面の一括置換ではなく、利用箇所の表、移行対象1画面、Story、テスト結果です。

入力: 開始commit、Button利用箇所、変更可能なディレクトリ、実行するテスト。

出力: 利用箇所の表、互換props、1画面分の差分、Story、テスト終了コード。

人の確認: 主要操作と危険操作の意味、公開API、移行順、マージ可否。

Use case 2: ホワイトラベル製品でブランドを切り替える

顧客ごとに色や角丸が違う製品では、primitive tokenだけをブランド別に持ち、action.background.primaryなどのsemantic tokenは共通にします。Claude Codeにはブランド別JSONからCSS変数を生成する処理と、Storybook上のテーマ切替を任せます。

人が判断するのは、コントラスト基準、ロゴ利用条件、顧客固有の例外を共通APIへ入れるかどうかです。出力にはブランドごとの差分表とa11y結果を含め、顧客名や未公開画像をプロンプトへ貼らないようにします。

入力: 匿名化したブランドtoken、共通semantic token、対象Story、コントラスト基準。

出力: ブランド別CSS変数、テーマ切替、差分表、a11y結果。

人の確認: ブランド規約、ロゴ条件、例外の扱い、顧客データを利用してよいか。

Use case 3: レガシーCSSからtoken候補を抽出する

長く運用したサイトでは、似た青色や余白が数十種類残ります。Claude Codeにいきなり置換させず、CSS／TSXからraw valueを抽出し、出現回数、利用画面、近い値の候補をCSVへまとめさせます。その表を人が確認してから、semantic tokenへの対応を決めます。

エージェントへ任せるのは調査、候補表、限定した1コンポーネントの変更、テストです。似た色を同じ意味として統合してよいか、ブランドや警告表示に影響しないかは人が判断します。

入力: 対象CSS／TSX、除外パス、開始commit、変更を許可する1コンポーネント。

出力: raw valueのCSV、統合候補、影響画面、限定差分、visual test結果。

人の確認: 色の意味、警告／ブランドへの影響、統合候補の採否、展開順。

チームでの運用とガバナンス：誰が、何を、どう決めるか

部品ができても、チームで使われ続けなければ意味がありません。ここが運用の話です。

「誰が変更を承認するか」を決めないと、デザインシステムは担当者ごとの判断へ戻ります。 あるPRでprimaryの色を変え、別のPRで理由を知らずに戻す、といった競合が起きます。

最低限、次の3つを文書にします。

1. オーナーを決める。1人でも委員会でもいい。「バリアント追加・トークン変更はこの人/この場でレビュー」という窓口を1つにする。
2. 追加のハードルを上げる。新バリアント・新コンポーネントは、既存で代替できないことを一文で説明してからPRを出すルールにする。増やすより減らすほうが難しい資産だからです。
3. 変更の影響範囲を出す。primaryの色を変えるPRには「どの画面に影響するか」を添える。Claude Codeに「Buttonのvariant="primary"を使っている箇所を一覧化して」と頼むと、この棚卸しが速いです。

依頼の粒度も運用の一部です。Claude Codeに渡す範囲を切らないと、レビュー不能な巨大差分が返ってきます。下のような作業ルールをCLAUDE.mdに書いておくと、毎回同じ品質で動きます。

デザインシステム作業ルール:
- 触ってよいのは src/components, src/styles, .storybook, tests のみ。
- バリアントや色を変えるときは、旧名と新名、影響する画面を必ず一覧にする。
- 新コンポーネントには TypeScript props、キーボード操作、Storybook story、a11y メモを必ず含める。
- 完了報告の前に test:storybook -- --run と重要Storyのvisual testを実行する。
- フォーカス挙動に触れる変更は、手動確認の手順を添える。

ガバナンスというと堅苦しいですが、要は「壊す前に一拍置く仕組み」です。小さいチームなら、この5行のルールと窓口1人で十分回ります。

小さく始めて育てる：最初の2週間の順番

最後に、ゼロから始める人向けの順番を置きます。部品を先に量産せず、設計・仕様化・テスト・運用を1部品で一周させます。

• 1〜2日目：いちばん使う部品を1つだけ選ぶ(たいていButton)。既存の使われ方を全部洗い出し、何種類の見た目があるかを表にする。ここで初めて「本当に必要なバリアント」が見える。
• 3〜5日目：Buttonを役割ベースの命名・直交バリアント・既定値ありで1個だけ実装する。全状態のStoryを書く。この時点で他の部品には手を出さない。
• 2週目前半：a11yチェックをCIに繋ぐ。PRで自動的に違反が止まる状態を作る。重要Storyのビジュアルテストも1本足す。
• 2週目後半：運用ルール(オーナー・追加のハードル・影響範囲)を5行で書く。CLAUDE.mdに入れる。ここで初めて2つ目の部品(InputやCard)に進む。

この順番の肝は、1部品で「設計・仕様化・テスト・運用」のフルセットを一周させてから広げることです。10部品を浅く作るより、1部品を深く固めるほうが、結局ぜんぶ速い。テーブルやフォームのような複雑な部品も、この一周ができてから着手すれば崩れません(テーブルの具体はテーブルコンポーネントの実装ガイドにあります)。

最新の仕様やAPIは、Storybook公式ドキュメントで確認しながら進めてください。バージョンで書き方が変わる部分があります。

Pitfall: 部品量産・見た目命名・一括移行を避ける

失敗の原因は、Figmaに見えた差をそのまま別コンポーネントへし、blueやlargeのような見た目を公開名へ入れ、最後に全画面を一括置換することです。変更経路と意味が分散し、レビュー対象が大きくなります。

直し方は、利用箇所を先にCSVへ出し、役割名のvariantへまとめ、1部品・1画面ずつ移すことです。各PRでStory、a11y、visual test、影響画面を確認します。似ているだけで意味が違う値は統合せず、判断できない候補はレポートに残して人が決めます。

よくある質問

Q. デザインシステムとコンポーネントライブラリは何が違うんですか? コンポーネントライブラリは部品の集合(コード)です。デザインシステムはそれに加えて、命名規則・使い方のルール・運用の約束・ドキュメントまで含む、もっと広い概念です。部品だけ作ってルールが無いものは、ライブラリではあってもデザインシステムとは呼びにくいです。

Q. 最初からAtomic Designの5階層で作るべき? 不要です。「単体で意味を持つ部品」と「それを組んだ塊」の2段で始め、実際の再利用に合わせて増やします。最初から5階層を固定すると、利用実績のないフォルダだけが増えます。考え方の地図として使い、構造は必要になってから追加します。

Q. バリアントはいくつまで持っていい? 数の上限より「一文で他と区別できるか」で判断します。primaryとsecondaryとdangerの違いは一言で言える。新しく足すバリアントが既存と一文で区別できないなら、それは増やすサインではなく使い方を見直すサインです。増えるほど検証コストが掛け算で増える点も忘れずに。

Q. デザインシステムの「正本」はFigmaとコードのどっち? チームで先に1つ決めてください。両方を正本にして双方向同期を始めると、どちらも安心して変更できなくなります。実務では「コードを正本にし、Figmaは入力として差分レポートを作る」運用が崩れにくいです。色や余白の値の管理はDesign Tokensの実装ガイドに分けてあります。

Q. Claude Codeにデザインシステムを丸ごと作らせていい? 「全部作って」は失敗します。範囲が曖昧でレビュー不能な巨大差分になるからです。「Buttonだけ、既存API互換で、Story付きで」のように1部品ずつ切って渡し、CLAUDE.mdに作業ルールを置くのがコツです。境界を切るのは人間の仕事、加速は機械の仕事、という分担にすると安定します。

チーム導入の相談先

Claude Codeを使ったコンポーネント設計、Storybook導入、既存UIの棚卸しや運用ルール作りで詰まっている場合は、研修・相談ページで導入範囲を整理できます。主CTAはこの相談ページだけに絞ります。

実際に試した結果

2026年7月22日に、この記事のTypeScript／TSXコード3件をファイルへ抽出し、esbuildで構文変換しました。Button本体、StorybookのAllStates、Playwrightのvisual testはいずれも構文エラーなしでした。コードフェンス、内部リンク、Storybook公式URL、a11y.test = "error"、Vitest addonの実行コマンドも検査しています。

この検証は実アプリでの描画やキーボード操作まで合格したという意味ではありません。依存パッケージとStorybookをこのサイトへ導入していないため、対象プロジェクトでnpm run test:storybook -- --runとvisual testを実行し、最後に人がキーボード操作と読み上げ順を確認してください。最初に行う作業は、既存Buttonの使われ方を一覧化し、移行対象を1部品に絞ることです。