# kaze-design-system

> Minimal React design system for dashboards, landing pages and Japanese UI: warm neutral grays, 78 components, SVG charts with zero dependencies, light/dark themes, typography tuned for CJK text

kaze-design-system is a React 18/19 + TypeScript design system with 78 components in two layers: Application UI (dashboards, business apps) and Marketing (landing pages, importable from `kaze-design-system/marketing`). It is built around a warm neutral gray palette, optimized for Japanese typography (PALT enabled globally), uses CSS custom properties for theming (light/dark via `data-theme`, cool palette via `data-palette="cool"`, compact density via `data-density="compact"`), and ships as ESM with peer dependencies on react and react-dom (lucide-react optional).

## Installation

```bash
npm install kaze-design-system
```

```tsx
import "kaze-design-system/css/all";
import { Button, Card, Badge } from "kaze-design-system";
import { Hero, PricingGrid } from "kaze-design-system/marketing";
```

## Full API reference

- [Full API reference (llms-full.txt)](https://kaze-design-system.vercel.app/llms-full.txt): every component with props, types, and usage examples
- [Interactive docs](https://kaze-design-system.vercel.app/docs/components): live previews of every component

## Components

### フォーム

- [Button](https://kaze-design-system.vercel.app/docs/components/button): ボタンコンポーネント
- [FAB](https://kaze-design-system.vercel.app/docs/components/fab): フローティングアクションボタン
- [Input](https://kaze-design-system.vercel.app/docs/components/input): テキスト入力
- [NumberField](https://kaze-design-system.vercel.app/docs/components/number-field): 通貨対応数値入力
- [Select](https://kaze-design-system.vercel.app/docs/components/select): セレクトボックス
- [Combobox](https://kaze-design-system.vercel.app/docs/components/combobox): 入力しながら候補を絞り込んで選ぶフォーム部品（WAI-ARIA の combobox + listbox）。既定の絞り込みはひらがな・カタカナ・全角半角・大文字小文字を区別せず、IME 変換中の Enter や矢印キーは無視します。選択肢が少なく絞り込みが不要なら Select を使います。
- [DatePicker](https://kaze-design-system.vercel.app/docs/components/date-picker): 日付入力とカレンダーのポップオーバー（WAI-ARIA の Date Picker Dialog）。値は "YYYY-MM-DD" の文字列で、Date のタイムゾーンずれが起きません。era="japanese" で「令和8年10月29日」の和暦表示になり、入力は 2026/10/29・20261029・令和8年10月29日・R8.10.29・全角数字を受け付けます。祝日データは持たないので、休業日などは isDateDisabled で渡します。
- [Checkbox](https://kaze-design-system.vercel.app/docs/components/checkbox): チェックボックス
- [Radio](https://kaze-design-system.vercel.app/docs/components/radio): ラジオボタン
- [Textarea](https://kaze-design-system.vercel.app/docs/components/textarea): テキストエリア
- [Switch](https://kaze-design-system.vercel.app/docs/components/switch): オン・オフを切り替えるトグルスイッチコンポーネント。ラベル付きで使用可能。
- [FormField](https://kaze-design-system.vercel.app/docs/components/form-field): フォームフィールド
- [FilterPill](https://kaze-design-system.vercel.app/docs/components/filter-pill): フィルター用ピル型トグルボタン
- [SegmentedControl](https://kaze-design-system.vercel.app/docs/components/segmented-control): 単一選択のセグメント切り替え。期間（1W / 1M / 3M / 1Y）や表示モードの切り替えに。

### データ表示

- [Card](https://kaze-design-system.vercel.app/docs/components/card): カードコンポーネント
- [Badge](https://kaze-design-system.vercel.app/docs/components/badge): バッジ
- [StatusBadge](https://kaze-design-system.vercel.app/docs/components/status-badge): データ状態（live / stale / missing / manual / loading）を一目で示すバッジ。内部で Badge をラップし、適切な tone・ラベル・role=status を自動付与します。ダッシュボード系 UI で各指標の鮮度表示に最適。
- [Table](https://kaze-design-system.vercel.app/docs/components/table): テーブル
- [Metric](https://kaze-design-system.vercel.app/docs/components/metric): メトリクス表示
- [Avatar](https://kaze-design-system.vercel.app/docs/components/avatar): アバター
- [BarList](https://kaze-design-system.vercel.app/docs/components/bar-list): ランキングリスト
- [Tracker](https://kaze-design-system.vercel.app/docs/components/tracker): 時系列ステータス
- [Watermark](https://kaze-design-system.vercel.app/docs/components/watermark): 透かし表示

### チャート

- [BarChart](https://kaze-design-system.vercel.app/docs/components/bar-chart): 水平棒グラフコンポーネント。データの比較を直感的に表示。
- [DonutChart](https://kaze-design-system.vercel.app/docs/components/donut-chart): SVGベースのドーナツチャート。凡例とセンターラベル付き。
- [Sparkline](https://kaze-design-system.vercel.app/docs/components/sparkline): インラインのミニ折れ線グラフ。テーブルやメトリクスの横に配置。
- [LineChart](https://kaze-design-system.vercel.app/docs/components/line-chart): 時系列データの折れ線 / 面グラフ。複数系列、凡例での表示切替、ホバーとキーボードのツールチップに対応。SVG 手書きで依存ゼロ。
- [ColumnChart](https://kaze-design-system.vercel.app/docs/components/column-chart): 縦棒グラフコンポーネント。複数系列をグループ表示・積み上げ表示で比較できる。カテゴリや期間の比較向け。
- [Heatmap](https://kaze-design-system.vercel.app/docs/components/heatmap): 2次元の密度を単一色相の濃淡で見せるヒートマップ。曜日×時間帯などの行×列（matrix）と、日別カレンダー（calendar）に対応。
- [CategoryBar](https://kaze-design-system.vercel.app/docs/components/category-bar): 構成比を1本の帯で見せるコンポーネント。予算消化やストレージ使用量の内訳、NPS の分布に。
- [ChartLegend](https://kaze-design-system.vercel.app/docs/components/chart-legend): チャート共通の凡例。onToggle を渡すと系列の表示 / 非表示を切り替えるボタンになる。LineChart / ColumnChart の内部でも使用。

### フィードバック

- [Alert](https://kaze-design-system.vercel.app/docs/components/alert): ユーザーに重要な情報を伝えるアラートコンポーネント。情報・成功・警告・エラーと中立の 5 バリアント。
- [Progress](https://kaze-design-system.vercel.app/docs/components/progress): 処理の進捗状況を視覚的に表示するプログレスバーコンポーネント。サイズ・カラー・ラベル対応。
- [Meter](https://kaze-design-system.vercel.app/docs/components/meter): メーター（既知範囲の値表示）
- [Skeleton](https://kaze-design-system.vercel.app/docs/components/skeleton): コンテンツの読み込み中に表示するスケルトンプレースホルダーコンポーネント。
- [EmptyState](https://kaze-design-system.vercel.app/docs/components/empty-state): データが存在しない場合に表示する空状態コンポーネント。sm / md / lg の3サイズに対応し、テーブルセル内の小さな表示からページ全体の大きな表示まで使い分けられます。role="status" が自動付与されます。
- [Spinner](https://kaze-design-system.vercel.app/docs/components/spinner): 読み込み中を伝える小さな表示。色は周りの文字色を受け継ぐ。
- [TypingIndicator](https://kaze-design-system.vercel.app/docs/components/typing-indicator): 相手が入力中であることを示す、順に明るくなる 3 つの点。
- [Toast](https://kaze-design-system.vercel.app/docs/components/toast): トースト通知

### ナビゲーション

- [Tabs](https://kaze-design-system.vercel.app/docs/components/tabs): タブナビゲーション
- [Sidebar](https://kaze-design-system.vercel.app/docs/components/sidebar): サイドバーナビゲーション
- [TopBar](https://kaze-design-system.vercel.app/docs/components/topbar): トップバー
- [Link](https://kaze-design-system.vercel.app/docs/components/link): 文中に置くリンク。外部サイトへは external で新しいタブと ↗ を付ける。
- [Breadcrumb](https://kaze-design-system.vercel.app/docs/components/breadcrumb): 現在のページ位置を階層的に表示するパンくずリストコンポーネント。
- [Pagination](https://kaze-design-system.vercel.app/docs/components/pagination): ページ分割されたコンテンツをナビゲートするページネーションコンポーネント。
- [Stepper](https://kaze-design-system.vercel.app/docs/components/stepper): 複数ステップの進行状況を表示するステッパーコンポーネント。ウィザードやフォームに最適。
- [Disclosure](https://kaze-design-system.vercel.app/docs/components/disclosure): 単一項目の展開/折りたたみ UI（コラプシブル）。HTML の <details>/<summary> の代替として、ブラウザ間のマーカー位置ズレを解消し、kaze のトークンで余白・色・フォントを統一します。内部的には <button> + 領域分けで構築し、aria-expanded/aria-controls を付与、Escape キーで閉じる操作にも対応。FAQ コンポーネントが複数 Q&A の束であるのに対し、Disclosure はテーブル内の補足やヘルプテキストなど任意の場所に単品で挿入できます。

### オーバーレイ

- [Dialog](https://kaze-design-system.vercel.app/docs/components/dialog): ダイアログ
- [Drawer](https://kaze-design-system.vercel.app/docs/components/drawer): 画面の端から出るモーダルパネル。Dialog と同じ挙動（フォーカストラップ・背景の inert 化・スクロールロック・Escape・背景クリック・閉じアニメ・フォーカス復帰）で、フィルターや詳細表示のように一覧を見たまま操作したい場面に向きます。モバイル幅では side="bottom"（ボトムシート）を推奨します。
- [Tooltip](https://kaze-design-system.vercel.app/docs/components/tooltip): ツールチップ
- [Popover](https://kaze-design-system.vercel.app/docs/components/popover): クリックで開く非モーダルの浮遊パネル。Dialog と違い背景は操作でき、Escape・外側クリックで閉じてトリガーにフォーカスを戻します。ホバーで出る補足は Tooltip、メニュー項目は Dropdown を使います。
- [HelpButton](https://kaze-design-system.vercel.app/docs/components/help-button): ラベルの横に配置する「?」ボタン。クリックで詳細説明の popover が開きます。outside click / ESC キーで閉じ、Portal でレンダリングされるためスクロールや z-index の影響を受けません。Tooltip（ホバー起動・一時表示）と異なり、クリックで開閉する永続モードを提供します。
- [Dropdown](https://kaze-design-system.vercel.app/docs/components/dropdown): ドロップダウンメニュー
- [CommandPalette](https://kaze-design-system.vercel.app/docs/components/command-palette): コマンドパレット

### レイアウト

- [Layout (AppLayout)](https://kaze-design-system.vercel.app/docs/components/layout): アプリレイアウト
- [Divider](https://kaze-design-system.vercel.app/docs/components/divider): 区切り線
- [Grid](https://kaze-design-system.vercel.app/docs/components/grid): レスポンシブ対応のグリッドレイアウト。ブレイクポイントごとのカラム数を prop で制御。
- [Search](https://kaze-design-system.vercel.app/docs/components/search): 検索入力
- [Logo](https://kaze-design-system.vercel.app/docs/components/logo): ロゴ
- [Icon](https://kaze-design-system.vercel.app/docs/components/icon): アイコン
- [Heading](https://kaze-design-system.vercel.app/docs/components/heading): セマンティックな見出しコンポーネント。レベル1〜6、説明テキスト、ボーダー付きに対応。
- [Text](https://kaze-design-system.vercel.app/docs/components/text): 汎用テキストコンポーネント。variant / size / weight / color / align を prop で制御。LP や UI で独自 CSS なしにテキストを扱える。
- [VisuallyHidden](https://kaze-design-system.vercel.app/docs/components/visually-hidden): 画面には出さず、読み上げソフトにだけ伝える文字を包む。

### リスト

- [List](https://kaze-design-system.vercel.app/docs/components/list): アイテム一覧を表示するリストコンポーネント。アイコン・説明・アクション付き。
- [DescriptionList](https://kaze-design-system.vercel.app/docs/components/description-list): 用語と説明のペアを表示する定義リストコンポーネント。
- [Timeline](https://kaze-design-system.vercel.app/docs/components/timeline): 時系列のイベントを縦に表示するタイムラインコンポーネント。

### マーケティング

- [AnnouncementBar](https://kaze-design-system.vercel.app/docs/components/announcement-bar): ページ最上部に置く 1 行のお知らせ帯
- [Navbar](https://kaze-design-system.vercel.app/docs/components/navbar): マーケティングサイト用ナビゲーションバー
- [Hero](https://kaze-design-system.vercel.app/docs/components/hero): ヒーローセクション
- [Section](https://kaze-design-system.vercel.app/docs/components/section): 汎用セクションラッパー
- [SplitSection](https://kaze-design-system.vercel.app/docs/components/split-section): 画像＋テキストの左右分割レイアウト。LP の交互セクションに最適。
- [FeatureGrid](https://kaze-design-system.vercel.app/docs/components/feature-grid): 機能紹介グリッド
- [Stats](https://kaze-design-system.vercel.app/docs/components/stats): 数値ハイライト
- [Pricing](https://kaze-design-system.vercel.app/docs/components/pricing): 料金プラン
- [Testimonial](https://kaze-design-system.vercel.app/docs/components/testimonial): お客様の声
- [FAQ](https://kaze-design-system.vercel.app/docs/components/faq): よくある質問
- [CTABanner](https://kaze-design-system.vercel.app/docs/components/cta-banner): コール・トゥ・アクション
- [LPFooter](https://kaze-design-system.vercel.app/docs/components/lp-footer): サイトフッター

## Hooks

- `useTheme`: theme context (light/dark toggle), exported from `kaze-design-system`
- `useFocusTrap`: focus-trap helper for modal/dialog components, exported from `kaze-design-system/hooks`
- `useLegendToggle`: Recharts `<Legend>` show/hide series toggle, exported from `kaze-design-system/hooks`