KSK Design System

複数クライアント案件を 1つのデザインシステム で高速に回すために設計された、React 製のマルチテーマ対応 UI ライブラリ。BtoB / SaaS の信頼感と EC / BtoC の購買体験、2つのドメインの設計思想を統合しています。

🔗 ライブ Storybook → https://ksk-design-system.vercel.app

133 コンポーネントを実際に操作・確認できます。

---

✨ 特徴

• マルチテーマ — Brand 色の 10 行を差し替えるだけで、全コンポーネントの見た目が自動で切り替わる（Primitive → Semantic → Bridge の 3 層トークン構造）
• アクセシブル — shadcn/ui（Radix UI ベース）+ @storybook/addon-a11y で a11y を担保
• Tailwind CSS v4 ネイティブ — @theme ベースのトークン設計
• 型安全 — React 19 + TypeScript、CVA によるバリアント管理
• 133 Web コンポーネント + 134 React Native exports — Web 133（UI 58 / パターン 52 / EC 12 / 管理 8 / シェル 3）+ RN native/ui 公開 export 134
• iOS 26 Liquid Glass 対応 — RN 側 GlassView + Button variant="glass"、Web 側 .glass CSS マテリアル

🎨 テーマ

Brand 色を差し替えるだけで業種に合わせた配色に切り替わります。

テーマ	Brand-500	想定業種
Default (Blue)	#3B82F6	汎用・SaaS・BtoB
Orange	#F97316	EC・フード・エンタメ
Green	#16A34A	ヘルスケア・サステナ・金融
Violet	#7C3AED	プレミアム・クリエイティブ・教育

🧱 技術スタック

React 19 + TypeScript / Vite / Tailwind CSS v4 / shadcn/ui（Radix UI）/ CVA / iconsax-reactjs / Storybook

Peer dependencies: react 18 or 19, react-dom, tailwindcss ^4.1（preset が同梱する safelist が Tailwind 4.1 で導入された @source inline() を使うため）

🚀 使い方

動作要件

React 19 以上が必須です。 コンポーネントは React 19 の ref-as-prop（関数コンポーネントが ref を通常の prop として受け取る仕様）を前提に実装しているため、React 18 では Function components cannot be given refs の警告が出て ref が届きません（issue #502）。

依存	必要バージョン
react / react-dom	^19.0.0
react-native（Native を使う場合）	>=0.78.0（React 19 を同梱する最初の RN）
tailwindcss（Web を使う場合）	^3.4.17 || ^4.1.0
typescript	>=5.0.0

Web (Next.js / Vite / 任意の React 環境)

npm install ksk-design-system

AI コーディング（Claude Code / Codex）を使うプロジェクトでは、続けて 1 回だけ実行します。

npx ksk-ds init

プロジェクトルートに CLAUDE.md / AGENTS.md（node_modules 内の DS ルールを指す薄いポインタ）を 設置します。AI エージェントは node_modules 配下を自動では読まないため、このファイルが無いと DS のルールが適用されません。既存ファイルはスキップされ、更新は --force で上書きします。

v1.60.0 で postinstall による自動設置を廃止しました。 install 時にプロジェクトルートへ AI 指示ファイルを書き込む挙動は、サプライチェーン検査で「同意なき AI エージェント制御面の設置」 として Critical 判定されるためです（LPM Firewall が 1.49.2 / 1.51.1 をこの理由でブロック判定）。 v1.59.0 以前から更新する場合、既に設置済みのファイルはそのまま使えます。

/* src/styles/app.css（アプリのルートで一度だけ読み込む） */
@import "tailwindcss";
@import "ksk-design-system/preset";
@import "ksk-design-system/themes/default";
@source "../../node_modules/ksk-design-system/dist";

独自ブランドのテーマを使う場合は、この後にテーマCSSをimportしてください。

メニュー・Popover・Tooltip・Select・Dialog の開閉アニメと Accordion の高さアニメに使う tw-animate-css は preset（preset-core）が読み込みます。DS の dependencies に入っているため、 consumer 側で別途インストールや @import "tw-animate-css"; をする必要はありません（issue #827）。

preset を使わずトークン CSS を個別 subpath で import する構成では、角丸トークン （--Radius-Surface / --Radius-Modal / --Radius-Sheet）は ksk-design-system/tokens/product-theme に含まれます（issue #553）。 product-theme を読まず Radius だけが欲しい場合は @import "ksk-design-system/tokens/radius"; を使ってください。 同様にセクション余白トークン（--Space-Section-*）も ksk-design-system/tokens/product-theme に含まれます（issue #560）。 Section Spacing だけが欲しい場合は @import "ksk-design-system/tokens/section-spacing"; を使ってください。 同様に重なり順トークン（--Z-*）と影トークン（--shadow-*）も ksk-design-system/tokens/product-theme に含まれます（issue #563）。 それぞれ単体が欲しい場合は @import "ksk-design-system/tokens/z-index"; / @import "ksk-design-system/tokens/shadow"; を使ってください。

Tailwind CSS v4 は node_modules を既定では走査しません。@source がないと、 DS 内部だけで使うレイアウト・サイズ・状態クラスが生成されず、コンポーネントの表示や操作が崩れます。 consumer 側の Tailwind と DS を同じビルドで処理するため、上記の設定をセットで使用してください。

なお preset には DS 内部ユーティリティの safelist （src/styles/source-safelist.css / 自動生成）が同梱されており、@source を書き忘れても DS のクラス CSS は生成されます（issue #258）。ただし consumer 自身のコードは consumer 側の走査対象なので、@source は引き続き推奨構成です。

DS 部品を使わない consumer は preset-core

safelist は DS 部品（Button 等）が内部で使う Tailwind クラスを、consumer が 1 つも 部品を使っていなくても生成します（safelist は約 1,150 クラス。consumer のクラスが無い状態の 実測で、出力 CSS が preset 179KB → preset-core 54KB、gzip 25.8KB → 9.8KB）。DS 部品を import しない consumer（ksk-design-system/class-names とトークンだけで UI を組む公開ページ等）は、 safelist だけを除いた preset-core を使えます。トークン・shadcn 互換の変数・アニメーション・ container 幅・scrollbar-hide・base layer のボーダー色の保険は preset と同じです。

@import "tailwindcss";
@import "ksk-design-system/preset-core";
@import "ksk-design-system/themes/default";

consumer	使う入口
DS 部品を 1 つでも使う（どこか 1 ルートでも）	ksk-design-system/preset（従来どおり。preset-core + safelist と同じ）
DS 部品を使わない（トークン・class-names だけ）	ksk-design-system/preset-core

Tailwind は CSS を 1 本にまとめるため、DS 部品を使うルートが 1 つでもあるビルドでは preset を使ってください（preset-core を選ぶと、そのルートで部品の見た目が崩れます）。 preset-core と safelist を分けて読みたい場合は @import "ksk-design-system/preset-core"; @import "ksk-design-system/safelist"; が preset と同じ結果になります。

import { Button, Input, Label } from "ksk-design-system"

export function Example() {
  return (
    <form>
      <Label htmlFor="company">会社名</Label>
      <Input id="company" name="company" defaultValue="サンプル株式会社" />
      <Button type="submit">保存</Button>
    </form>
  )
}

DSリポジトリの開発者向け検査として、npm run test:consumer:web は、配布READMEの上記例を空consumerで型検査・CSSビルドし、Node SSRからChromiumへのhydrationと操作を検査します。初回は npx playwright install chromium が必要です。

新規クライアント案件では、テーマファイルで --Primitive-Brand-500 などブランドカラーの 10 行を定義するだけで、全コンポーネントがそのブランドカラーで動作します。

This is the beginning of the README. Read the rest at the original. Read the full README ↗