ckm:design-system

概要

ckm:design-system とは？

ckm:design-system は、デザイントークンのアーキテクチャ、コンポーネント仕様、プレゼンテーションスライド生成を 1 つの再利用可能なワークフローにまとめた design-system 用スキルです。

Primitive → Semantic → Component の 3 レイヤートークンモデルを中心に、以下を支えるリファレンスとスクリプトが含まれています。

• CSS Variable ベースのトークンシステム
• 余白・タイポグラフィスケール
• コンポーネントの状態とバリアント
• Tailwind テーマ設定
• 体系化されたスライド／ピッチデックのレイアウト

スライドの背景、カラー設計ロジック、コピーの型、レイアウト、ストーリー戦略に関する前提付きデータテーブルとテンプレートに加え、トークンとスライド構造を生成・検証するためのスクリプトが同梱されています。

想定ユーザー

ckm:design-system は次のような人を対象としています。

• 明確なトークンアーキテクチャとコンポーネント仕様リファレンスが欲しい デザインシステムリードや UI/UX デザイナー。
• 堅牢なトークンパイプライン（CSS Variables、バリデータ、Tailwind 連携のヒント）が必要な フロントエンド／React／Tailwind 開発者。
• ピッチデックを頻繁に作成し、毎回 0 ベースではなく、再利用可能でブランド一貫性のあるスライドフレームワークが欲しい ファウンダー、PM、マーケター。

Figma 的な思考でのデザインと、実装にそのまま使えるトークン、再利用可能なスライドシステムを橋渡ししたいなら、このスキルは強力な選択肢になります。

どんな課題を解決する？

ckm:design-system を使うと、次のようなことができます。

• デザイントークンの標準化：Primitive → Semantic → Component のレイヤー構造を明文化して整理できます。
• CSS トークンの生成：JSON から CSS トークンを生成し、コードベース内での利用を検証できます。
• Tailwind テーマの設計：同じトークンアーキテクチャをベースに Tailwind のテーマ計画ができます。
• コンポーネント仕様の定義：状態やバリアントを含めて仕様化し、画面をまたいでも UI の一貫性を保てます。
• ブランド一貫性のあるプレゼン設計：あらかじめ定義されたスライドレイアウト、チャート推奨、色と感情のロジック、コピーの型を使って設計できます。

UI もスライドも単発の成果物ではなく「システム」として設計・運用するための枠組みを提供します。

ckm:design-system が向いているケース

次のようなときに、このスキルの利用を検討してください。

• デザインシステム を導入／リファクタリングしており、トークンレイヤーを明確にしたい。
• トークンアーキテクチャと結びついた CSS Variables や Tailwind の設計ガイドが欲しい。
• デザイントークンを手作業で管理するのではなく、生成と検証を自動化したい。
• ピッチデック、営業資料、プロダクトデモ を継続的に作成しており、再現性のあるスライド構造が欲しい。

単発の静的 UI モックだけが必要な場合や、トークンや CSS Variables をまったく使っていない場合にはオーバースペックかもしれません。

使い方

インストールと基本セットアップ

1. ckm:design-system スキルをインストールする

Agent/skills の環境にスキルを追加します。

npx skills add https://github.com/nextlevelbuilder/ui-ux-pro-max-skill --skill design-system

このコマンドで、nextlevelbuilder/ui-ux-pro-max-skill リポジトリから design-system スキルがローカルの skills ディレクトリに取得されます。

2. コアファイルを確認する

インストール後、スキルフォルダを開いて次から確認を始めてください。

• SKILL.md – スキルの概要、利用シーン、トークンアーキテクチャ、クイックスタート用コマンド。
• references/ – トークン、コンポーネント、バリアント、Tailwind 連携の概念リファレンス。
• data/ – スライド背景、カラーロジック、コピーの型、レイアウト、タイポグラフィ、ストラテジーを定義した CSV。
• scripts/ – トークンの生成・埋め込み・検証用ユーティリティと、スライド検索用スクリプト。
• templates/design-tokens-starter.json – 独自トークンセットを定義するためのスターターテンプレート。

この構成により、「トークンだけ」「スライドだけ」「フルシステム」など、どこから採用するかをすぐに判断できます。

トークンアーキテクチャの設計

3. 3 レイヤートークンモデルを理解する

SKILL.md と references/token-architecture.md では、次の 3 段階構造を説明しています。

Primitive (raw values)
       ↓
Semantic (purpose aliases)
       ↓
Component (component-specific)

各レイヤーは次のリファレンスを使って設計します。

• references/primitive-tokens.md – ベースカラー、スペーシング、角丸、タイポグラフィのプリミティブ。
• references/semantic-tokens.md – --color-primary、--surface-elevated、--text-muted など、用途ベースの Semantic トークン。
• references/component-tokens.md – --button-bg、--card-border、--badge-pill-radius など、コンポーネント単位のトークン。

この分離によって次のようなメリットがあります。

• テーマを差し替えてもコンポーネントを書き直さずに済む。
• 実装レベル（CSS Variables、Tailwind 設定）をデザイン言語とずれずに保てる。

4. トークン用 JSON を作成・カスタマイズする

templates/design-tokens-starter.json をベースに、自分たちのトークンファイルを作ります。

典型的なワークフローは次のとおりです。

1. templates/design-tokens-starter.json をプロジェクト内にコピーし、tokens.json として保存。
2. まず Primitive の値（カラー、スペーシング、フォントサイズなど）を埋める。
3. Primitive を Semantic の役割（primary、secondary、surface、border など）にマッピング。
4. Semantic トークンを、主要な UI 要素ごとに Component トークンへ展開。

併せて次を参照します。

• references/component-specs.md – コンポーネントがトークンをどう消費するかを考える指針。
• references/states-and-variants.md – hover、focus、disabled、error などの状態とバリアント設計のためのリファレンス。

トークンの生成と検証

5. トークンから CSS Variables を生成する

SKILL.md で説明されているトークン生成スクリプトを使用します。

node scripts/generate-tokens.cjs --config tokens.json -o tokens.css

• --config はトークン定義の JSON（例: tokens.json）へのパス。
• -o は出力する CSS ファイル（例: tokens.css）。

生成された CSS には、トークンが --custom-properties として定義され、フロントエンドからそのままインポートできます。

6. コードベースでのトークン利用を検証する

コードが承認済みトークンのみを使っているか確認するには、バリデータを実行します。

node scripts/validate-tokens.cjs --dir src/

指定したディレクトリ（例: src/）内のトークン利用パターンをチェックし、次のような点を検出します。

• 本来トークン化すべきハードコード値。
• 廃止済み／定義されていないトークンの利用。

scripts/ ディレクトリには、追加のバリデータも含まれています。

• html-token-validator.py – HTML 内のトークン利用パターンをスキャン。
• slide-token-validator.py – スライド関連コンテキストにおけるトークン利用を検証。

これらを組み合わせることで、UI とスライド両方をデザインシステムと整合させられます。

7. 必要な場所にトークンを埋め込む

ドキュメントや HTML にトークンを埋め込む必要がある場合は、次のスクリプトを利用できます。

• scripts/embed-tokens.cjs – 指定したターゲットファイルにトークンを埋め込み。

具体的な使い方は、スクリプト内のコメントと SKILL.md の説明を、利用中の環境に合わせて確認してください。

Tailwind と実装上のポイント

8. Tailwind との統合を計画する

スキルには Tailwind 専用のリファレンスが含まれています。

• references/tailwind-integration.md – トークン名やスケールを Tailwind の theme 設定にマッピングするためのガイド。

これを使って次のような設計ができます。

• Primitive / Semantic トークンを Tailwind の colors、spacing、fontSize スケールへマッピング。
• Primitive から導出した primary パレットなど、トークン設計と整合した Tailwind ユーティリティクラスを保つ。

Tailwind を今すぐ使わないケースでも、トークンシステムを将来ユーティリティファースト CSS に展開する際の考え方として役立ちます。

システム化されたスライドデックの構築

このスキルの主カテゴリはデザインシステムですが、構造化されたプレゼン設計もサポートしています。

9. レイアウトとビジュアルにスライド用データテーブルを使う

data/ ディレクトリには、ベストプラクティスに基づくスライドパターンを定義した CSV が含まれます。

• data/slide-backgrounds.csv – スライドタイプ（hero、vision、team、testimonial、CTA、problem、solution など）ごとの推奨背景イメージの種類、オーバーレイ、配置。
• data/slide-color-logic.csv – 感情（frustration、hope、fear、relief、trust、urgency、curiosity など）と背景スタイル、テキストカラー、アクセントの使い方の対応関係。
• data/slide-typography.csv – スライドタイプ別タイポグラフィガイド（情報階層、強調など）。
• data/slide-layout-logic.csv – フック、problem、solution、proof、traction、CTA、timeline、features など、ストーリーの目的と感情に基づくレイアウトパターン。
• data/slide-layouts.csv – グリッド、左右分割、hero 構成、アニメーション提案など、具体的な CSS 構造のヒントを含むレイアウトパターン。

これらのテーブルをスクリプトやスプレッドシート、自作のデックジェネレーターに読み込むことで、「なんとなくのデザイン」ではなく、ストーリーと感情設計に基づいた一貫性のあるスライドを生成できます。

10. 実績あるコピーの型でスライド原稿を組み立てる

data/slide-copy.csv には、スライドタイプごとに最適化されたコピーライティングの型が定義されています。例：

• AIDA (Attention → Interest → Desire → Action)
• PAS (Problem → Agitate → Solution)
• 4Ps (Promise → Picture → Proof → Push)
• Before-After-Bridge
• QUEST
• Star-Story-Solution

各行には次のような項目が含まれます。

• formula_name と keywords
• 構造化された components
• use_case と example_template
• emotion_trigger と slide_type

これらを利用すると、次のことが可能です。

• 特定の型に沿ってスライドコピーを下書きするよう、エージェントにプロンプトを出す。
• ピッチデックや営業資料のコピーを、異なる資料間でも同じ型で標準化する。

11. デック全体のストラテジーを選ぶ

data/slide-strategies.csv は、デック全体の構成パターンを定義しています。たとえば：

• YC Seed Deck
• Guy Kawasaki 10/20/30
• Series A Deck

各ストラテジーには次の情報が含まれます。

• 推奨スライド枚数
• タイトル、problem、solution、traction、market などのシーケンス
• 目的、想定オーディエンス、トーン
• ナラティブと感情の起伏カーブ

これにより次が可能になります。

• 選んだストラテジーに基づいて、デック全体のスライドアウトラインを自動生成する。
• デザインシステムとストーリー構成を同じフレームの中で設計する。

12. スライド関連スクリプトを活用する

scripts/ ディレクトリには、スライドワークフロー向けのユーティリティが含まれています。

• scripts/generate-slide.py – スライド生成ロジックの中核（自作デックジェネレーターやパイプラインに組み込み可能）。
• scripts/search-slides.py と scripts/slide_search_core.py – キーワードやコンテキストから、適切なスライドパターンやストラテジーを検索するユーティリティ。
• scripts/fetch-background.py – data/slide-backgrounds.csv のガイドラインをもとに、Pexels / Unsplash などから背景画像を取得する補助スクリプト。

これらはあくまでビルディングブロックなので、自身の環境や自動化要件に合わせてそのまま使う／改造するかを選べます。

リファレンスとドキュメントの使い方

13. リファレンスを実装チェックリストとして使う

references/ フォルダは、単なる読み物ではなく、デザインシステム構築時のチェックリストとしても機能します。

• references/token-architecture.md – Primitive / Semantic / Component のレイヤー構造を確認。
• references/primitive-tokens.md – ベーストークンセットが十分かどうかをチェック。
• references/semantic-tokens.md – 各 Semantic トークンに明確な用途があるか確認。
• references/component-tokens.md – トークンを具体的なコンポーネントへマッピング。
• references/component-specs.md – コンポーネントの状態、バリアント、インタラクション、アクセシビリティ考慮点を整理。
• references/states-and-variants.md – hover、focus、active、disabled、error、success などの状態漏れを防止。

デザインレビューやデザインから実装へのハンドオフ時にこれらを活用し、デザイナーと開発者の認識を揃えてください。

スキルを自分たちのスタックに合わせる

14. 段階的に統合する

このスキルを最初からすべて採用する必要はありません。よくある段階的な導入パターンは次のとおりです。

• トークンだけ導入 – templates/design-tokens-starter.json、generate-tokens.cjs、validate-tokens.cjs だけ使い、トークンパイプラインから整備を始める。
• スライドだけ導入 – 既存のデザインシステムはそのままに、data/ の CSV と scripts/generate-slide.py を使って資料だけ標準化する。
• フルシステム導入 – トークン、コンポーネント、スライド構造を組み合わせ、プロダクト UI とピッチデックを横断する統合ブランドシステムを構築する。

まずは、いちばん喫緊の課題を解決する部分から始め、徐々に広げていくとスムーズです。

FAQ

ckm:design-system は UI キットですか？ それともデザイントークンエンジンですか？

主に デザインシステムとトークンアーキテクチャのためのスキル であり、そこに構造化されたスライドシステムが付属します。Figma 用の UI キットは同梱していませんが、次のものを提供します。

• 3 レイヤーのトークンアーキテクチャ
• トークン生成・検証スクリプト
• コンポーネント仕様と状態のリファレンス

提供されるトークンやコンポーネント構造は、Figma やその他のデザインツールにも容易に反映できます。

Tailwind や React なしでも使えますか？

はい、使えます。Tailwind 連携は references/tailwind-integration.md にドキュメント化されていますが、必須ではありません。トークンは標準的な CSS Variables として生成されるため、どんなスタックでも利用できます。

• Vanilla CSS や CSS Modules
• styled-components などの CSS-in-JS ソリューション
• Web Components やその他フレームワーク向けのデザイントークン

プレゼン資料にはどう役立ちますか？

このスキルはスライドデックを デザインシステムの一部 として扱います。

• data/slide-layouts.csv と data/slide-layout-logic.csv でレイアウトパターンと CSS 構造を定義。
• data/slide-backgrounds.csv と data/slide-color-logic.csv でスライドタイプや感情とビジュアルの関係を定義。
• data/slide-copy.csv と data/slide-strategies.csv でコピーの型とデック構成パターンを提供。
• generate-slide.py や search-slides.py のようなスクリプトで生成と検索を自動化。

これにより、毎回ゼロから作るのではなく、ブランド一貫性のあるスライドを再現性高く構築できます。

付属の CSV データはそのまま使う必要がありますか？

いいえ。これらの CSV は 前提付きのデフォルト です。次のように扱えます。

• すぐにピッチデックを作りたい場合は、そのまま利用する。
• 自社のブランドボイスやビジュアルスタイルに合わせてフォークし、カスタマイズする。
• 同じスクリプトパターンを活かしつつ、中身のデータを丸ごと自前のものに差し替える。

デザイントークンだけに関心がある場合、どこから始めればいいですか？

UI 実装とトークンにだけ集中したい場合は、次のステップがおすすめです。

1. SKILL.md を読み、「When to Use」と「Token Architecture」のセクションを確認。

2. references/token-architecture.md と Primitive / Semantic / Component の各トークンリファレンスを開く。

3. templates/design-tokens-starter.json をコピーして tokens.json を作成。

4. 次のコマンドを実行：

   node scripts/generate-tokens.cjs --config tokens.json -o tokens.css
   node scripts/validate-tokens.cjs --dir src/
   

これだけで、スライドシステムに触れなくても、稼働するトークンパイプラインを構築できます。

ckm:design-system は小規模プロジェクトにも向いていますか？

利用は可能ですが、特に効果を発揮するのは次のような状況です。

• 複数メンバーが UI や資料作成に関わる。
• 一貫性やスケーラビリティが重要。
• 今後ブランドやプロダクトを継続的にアップデートしていく予定がある。

単発のランディングページや、一度きりの社内プレゼンだけであれば、フルシステムはやや重いかもしれません。その場合でも、トークンアーキテクチャやスライドのコピー・レイアウトの型だけを軽量に拝借する、といった使い方ができます。

スキルに何が含まれているかを一覧で確認するには？

skills ブラウザやファイルエクスプローラーで design-system スキルのディレクトリツリーを確認し、特に次の項目を見てください。

• SKILL.md
• data/
• references/
• scripts/
• templates/design-tokens-starter.json

これらを見れば、ネストされたリファレンスやヘルパースクリプトを含む全体像が把握でき、自分たちのワークフローにどの部分を取り込むか判断しやすくなります。