ksk-design-system 1.35.0

package/scripts/codemod/template.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/**
+ * Codemod テンプレート — ksk-design-system 破壊変更時に複製して使う
+ *
+ * 使い方:
+ *   cp scripts/codemod/template.mjs scripts/codemod/v1-to-v2.mjs
+ *   # RENAMES と PACKAGE_PATTERN を編集
+ *   node scripts/codemod/v1-to-v2.mjs --dry ../my-app/src   # 事前確認
+ *   node scripts/codemod/v1-to-v2.mjs       ../my-app/src   # 実行
+ *
+ * 利用側プロジェクトへの公開:
+ *   npx ksk-design-system codemod v1-to-v2 ./src
+ *   または
+ *   node node_modules/ksk-design-system/scripts/codemod/v1-to-v2.mjs ./src
+ *
+ * 注意:
+ *   - 正規表現ベースなので 100% 正確ではない（複雑なケースは手動確認推奨）
+ *   - --dry オプションで事前確認可能
+ *   - 必ずコミット済みの状態で実行すること（git diff で変更確認）
+ */
+
+import fs from "node:fs"
+import path from "node:path"
+
+// ============================================================
+// このテンプレートを複製した後、ここを編集してください
+// ============================================================
+
+/** 対象パッケージの import 文を含むファイルだけを処理 */
+const PACKAGE_PATTERN = /@ksk\/design-system/
+
+/** 単純な識別子 rename: [oldName, newName] */
+const RENAMES = [
+  // 例:
+  // ["OldComponent", "NewComponent"],
+  // ["OldComponentProps", "NewComponentProps"],
+]
+
+/** prop 名 rename: [componentName, oldProp, newProp] */
+const PROP_RENAMES = [
+  // 例:
+  // ["Button", "kind", "variant"],
+]
+
+/** 手動移行が必要な箇所の警告 */
+const WARNINGS = [
+  // { pattern: /\bOldThing\b/, message: "OldThing は廃止されました。NewThing への移行ガイドは MIGRATION.md を参照。" },
+]
+
+// ============================================================
+// CLI 引数
+// ============================================================
+
+const args = process.argv.slice(2)
+const dry = args.includes("--dry")
+const targetDir = args.find((a) => !a.startsWith("--")) || "./src"
+
+if (!fs.existsSync(targetDir)) {
+  console.error(`✗ Directory not found: ${targetDir}`)
+  process.exit(1)
+}
+
+console.log(`\n🔧 ksk-design-system codemod`)
+console.log(`   Target: ${path.resolve(targetDir)}`)
+console.log(`   Mode:   ${dry ? "DRY RUN (no changes written)" : "APPLY"}`)
+console.log("")
+
+// 長い名前から順にマッチさせる（部分マッチ防止）
+const sortedRenames = [...RENAMES].sort((a, b) => b[0].length - a[0].length)
+
+// ============================================================
+// ファイル探索
+// ============================================================
+
+function findFiles(dir) {
+  const results = []
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name === "dist" || entry.name.startsWith(".")) continue
+      results.push(...findFiles(full))
+    } else if (/\.(ts|tsx|js|jsx|mjs|cjs)$/.test(entry.name)) {
+      results.push(full)
+    }
+  }
+  return results
+}
+
+// ============================================================
+// 変換
+// ============================================================
+
+let totalFiles = 0
+let totalChanges = 0
+const fileChanges = []
+
+for (const file of findFiles(targetDir)) {
+  const original = fs.readFileSync(file, "utf-8")
+  let updated = original
+  let fileChangeCount = 0
+
+  // 対象パッケージを使っていないファイルはスキップ
+  if (!PACKAGE_PATTERN.test(original)) continue
+
+  // 識別子 rename
+  for (const [oldName, newName] of sortedRenames) {
+    const re = new RegExp(`\\b${oldName}\\b`, "g")
+    const matches = updated.match(re)
+    if (matches) {
+      updated = updated.replace(re, newName)
+      fileChangeCount += matches.length
+    }
+  }
+
+  // prop rename
+  for (const [componentName, oldProp, newProp] of PROP_RENAMES) {
+    // <Component oldProp= → <Component newProp=
+    const re = new RegExp(`(<${componentName}[^>]*\\s)${oldProp}=`, "g")
+    const matches = updated.match(re)
+    if (matches) {
+      updated = updated.replace(re, `$1${newProp}=`)
+      fileChangeCount += matches.length
+    }
+  }
+
+  // 警告のみ
+  for (const { pattern, message } of WARNINGS) {
+    if (pattern.test(original)) {
+      console.log(`  ⚠ ${file}`)
+      console.log(`     ${message}`)
+    }
+  }
+
+  if (fileChangeCount > 0) {
+    totalFiles++
+    totalChanges += fileChangeCount
+    fileChanges.push({ file, count: fileChangeCount })
+    if (!dry) {
+      fs.writeFileSync(file, updated, "utf-8")
+    }
+  }
+}
+
+// ============================================================
+// 結果
+// ============================================================
+
+console.log(`\n📊 結果`)
+console.log(`   ファイル: ${totalFiles}`)
+console.log(`   置換数:   ${totalChanges}`)
+console.log("")
+
+if (totalFiles > 0) {
+  for (const { file, count } of fileChanges) {
+    console.log(`  ${dry ? "[dry]" : "✓"}  ${count.toString().padStart(3)} 件: ${path.relative(process.cwd(), file)}`)
+  }
+  if (dry) {
+    console.log(`\n💡 --dry を外すと実際に書き込みます。`)
+  } else {
+    console.log(`\n✅ 完了。git diff で変更を確認してください。`)
+  }
+} else {
+  console.log(`変更対象なし。`)
+}

package/src/components/COMPONENT_LOOKUP.md

@@ -0,0 +1,190 @@
+# Component Lookup（AI必読）
+
+> **このファイルは `node scripts/generate-component-lookup.mjs` で自動生成されています。手動編集しないでください。**
+
+コンポーネントを使う前に必ずこのファイルを確認し、既存コンポーネントを再利用すること。
+独自でコンポーネントを定義する前に、ここに同等品がないか確認すること。
+
+---
+
+## UI Components（src/components/ui/）
+
+| Component | Import | Variants | Stories |
+|-----------|--------|----------|---------|
+| Accordion, AccordionItem, AccordionTrigger, AccordionContent | `@/components/ui/accordion` | — | ThreeItems, MultipleOpen |
+| AlertDialog, AlertDialogTrigger, AlertDialogPortal, AlertDialogOverlay, AlertDialogContent, AlertDialogHeader, AlertDialogFooter, AlertDialogTitle, AlertDialogDescription, AlertDialogAction, AlertDialogCancel | `@/components/ui/alert-dialog` | — | Default, Small |
+| Alert, AlertTitle, AlertDescription | `@/components/ui/alert` | **variant**: `success`, `info`, `error`, `warning`, `inline-info`, `inline-caution`, `inline-warning` | Info, Success, Error, Warning, InlineInfo, InlineCaution, InlineWarning, AllVariants, Prop-based API (auto icon), Prop-based + action |
+| AutoGrowTextarea | `@/components/ui/auto-grow-textarea` | — | — |
+| Avatar, AvatarImage, AvatarFallback | `@/components/ui/avatar` | — | WithImage, Fallback, Sizes, Group |
+| Badge | `@/components/ui/badge` | **variant**: `default`, `secondary`, `outline`, `destructive`, `success`, `warning`, `info`, `subtle`, `ghost` | Default, Secondary, Outline, Destructive, Success, Warning, Info, Subtle, Ghost, AllVariants |
+| Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis | `@/components/ui/breadcrumb` | — | ThreeLevel, WithEllipsis |
+| Button | `@/components/ui/button` | **variant**: `default`, `secondary`, `secondary-switch`, `tertiary`, `ghost`, `destructive`, `link`, `glass`, `accent`, `inverse`, `ghost-inverse`<br>**size**: `xs`, `sm`, `default`, `lg`, `xl`, `hero`, `icon`, `icon-sm`, `icon-lg`, `icon-xl`, `match`<br>**layout**: `horizontal`, `vertical` | Default, Secondary, SecondarySwitch, Tertiary, Ghost, Destructive, Link, AllVariants, AllSizes, Hero, Inverse on Dark Background, Real UI — Hero Section CTAs, Disabled, DisabledAllVariants, IconButton, Glass — Liquid Glass (iOS 26), WithIcon |
+| Calendar | `@/components/ui/calendar` | — | Single, Range |
+| Card, CardHeader, CardTitle, CardDescription, CardAction, CardContent, CardFooter | `@/components/ui/card` | **variant**: `default`, `media` | FullCard, MinimalCard, HeaderOnly |
+| CheckboxCardGroup, CheckboxCardItem | `@/components/ui/checkbox-card` | — | Default, WithDescription, WithExpandedContent, Disabled |
+| CheckboxField | `@/components/ui/checkbox-field` | — | Default, WithDescription, WithError, LongLabelWrap, Disabled |
+| CheckboxGroup, CheckboxGroupItem | `@/components/ui/checkbox-group` | — | Default, Required, WithError, SingleColumn |
+| Checkbox | `@/components/ui/checkbox` | — | Default, Checked, Disabled, DisabledChecked, WithLabel, MultipleOptions, Row Layout (label/description/count), Real UI — Filter Sidebar |
+| CoachMark | `@/components/ui/coach-mark` | — | Default, Brand, Placements, Onboarding, Hover |
+| Collapsible, CollapsibleTrigger, CollapsibleContent | `@/components/ui/collapsible` | — | Default, FAQ |
+| Combobox | `@/components/ui/combobox` | — | Default, WithDisabledOption |
+| CountdownTimer | `@/components/ui/countdown-timer` | — | Filled, Ghost, Compact, Ended, AllVariants |
+| DatePicker, DateRangePicker | `@/components/ui/date-picker` | — | Default, WithInitialValue, Disabled, RangePicker, CalendarOnly, CalendarRange |
+| Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger | `@/components/ui/dialog` | — | WithTrigger, WithForm, ReportShop, StackedFooter |
+| DropdownFilter | `@/components/ui/dropdown-filter` | — | Default, ActiveFilter, WithIcons（ビュー切替・アイコン付き）, MultipleFilters |
+| DropdownMenu, DropdownMenuPortal, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuGroup, DropdownMenuLabel, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent | `@/components/ui/dropdown-menu` | — | Default, WithCheckbox, WithRadio, WithSubmenu |
+| ErrorBoundary | `@/components/ui/error-boundary` | — | — |
+| Form, FormItem, FormLabel, FormControl, FormDescription, FormMessage, FormField | `@/components/ui/form` | — | BasicForm, WithSelect |
+| HoverCard, HoverCardTrigger, HoverCardContent | `@/components/ui/hover-card` | — | Default |
+| ImageGallery | `@/components/ui/image-gallery` | — | Thumbnail, Dot, Square, Single |
+| Input | `@/components/ui/input` | — | Default, WithPlaceholder, Disabled, Error, WithLabel, FileInput |
+| Label | `@/components/ui/label` | — | Default, WithRequiredMarker, DisabledState |
+| MultiSelect | `@/components/ui/multi-select` | — | Default |
+| NavigationBar | `@/components/ui/navigation-bar` | — | Default, WithCloseButton, TitleOnly, CustomRightSlot, Liquid Glass — over gradient, Liquid Glass — over photo tone |
+| NumberInput | `@/components/ui/number-input` | — | Default, WithMinMax, WithStep, CurrencyFormat, Disabled |
+| Pagination, PaginationContent, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, PaginationEllipsis | `@/components/ui/pagination` | — | FivePages, WithEllipsis |
+| PillToggle | `@/components/ui/pill-toggle` | — | Default, TwoState, Small |
+| Popover, PopoverTrigger, PopoverContent, PopoverAnchor | `@/components/ui/popover` | — | ClickToShow, SimpleContent |
+| ProgressRing | `@/components/ui/progress-ring` | — | Default, Empty, Full, AllSizes, CustomLabel, Animated |
+| Progress | `@/components/ui/progress` | — | Default, Empty, Half, Full, AllStates |
+| RadioGroup, RadioGroupItem | `@/components/ui/radio-group` | — | ThreeOptions, WithDisabled, WithDescription, HoverState |
+| ResponsiveDialog, ResponsiveDialogTrigger, ResponsiveDialogContent, ResponsiveDialogHeader, ResponsiveDialogTitle, ResponsiveDialogDescription, ResponsiveDialogFooter, ResponsiveDialogClose | `@/components/ui/responsive-dialog` | — | Default |
+| ScrollArea, ScrollBar | `@/components/ui/scroll-area` | — | VerticalScroll, LongText |
+| Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, SelectValue | `@/components/ui/select` | **size**: `sm`, `default`, `lg` | WithPlaceholder, WithGroups, WithDisabledItem, DisabledSelect |
+| Separator | `@/components/ui/separator` | — | Horizontal, Vertical |
+| Sheet, SheetTrigger, SheetClose, SheetContent, SheetHeader, SheetFooter, SheetTitle, SheetDescription, SheetDragIndicator | `@/components/ui/sheet` | **side**: `top`, `bottom`, `left`, `right`, `float`, `float-glass`, `bottom-glass` | BottomSheet, FloatSheet, RightSheet, Float Glass (Liquid Glass), Bottom Glass (Liquid Glass), BottomSheet — swipeToClose, BottomSheet — swipeToClose (full height / scrollable), BottomSheet — Snap 0.4/0.9, BottomSheet — Snap (push-up layout) |
+| Skeleton | `@/components/ui/skeleton` | — | CardSkeleton, TextSkeleton, AvatarWithText |
+| Slider | `@/components/ui/slider` | — | Default, Range, WithLabel, Disabled |
+| SOCIAL_ICON_LABELS, SOCIAL_ICON_DATA, SOCIAL_ICON_PLATFORMS | `@/components/ui/social-icon-data` | — | — |
+| SocialIcon, SOCIAL_ICON_PLATFORMS, SOCIAL_ICON_LABELS | `@/components/ui/social-icon` | — | Default, AllPlatforms, AllMono, Tones |
+| SocialLoginButton | `@/components/ui/social-login-button` | — | Line, Google, Apple, Amazon, AllProviders, Loading |
+| Spinner | `@/components/ui/spinner` | — | Default, AllSizes |
+| StarRating | `@/components/ui/star-rating` | — | Interactive, ReadOnly, Sizes |
+| SubNav | `@/components/ui/sub-nav` | — | Underline, Chip, WithBadge |
+| Switch | `@/components/ui/switch` | — | Default, Checked, Disabled, DisabledChecked, WithLabel, SettingsList |
+| SyncStatusBadge | `@/components/ui/sync-status-badge` | — | Syncing, Success, Error, Offline, AllStates |
+| Tabs, TabsList, TabsTrigger, TabsContent | `@/components/ui/tabs` | — | ThreeTabs, WithDisabledTab |
+| Textarea | `@/components/ui/textarea` | — | Default, WithPlaceholder, Disabled, Error, AutoGrow |
+| TimePicker | `@/components/ui/time-picker` | — | Default, 15分刻み |
+| Toaster | `@/components/ui/toast` | **variant**: `default`, `success`, `caution`, `warning`, `info` | Default, Success, Caution, Warning, Info, AllVariants, Fire-and-forget (no <Toaster />) |
+| Tooltip, TooltipTrigger, TooltipContent, TooltipProvider | `@/components/ui/tooltip` | — | HoverToShow, OnIconButton |
+
+---
+
+## Pattern Components（src/components/patterns/）
+
+### patterns/admin/
+
+| Component | Import | Variants | Stories |
+|-----------|--------|----------|---------|
+| BulkActions | `@/components/patterns/admin/bulk-actions` | — | Default, ManySelected |
+| ChartControls | `@/components/patterns/admin/chart-controls` | — | Default, PeriodOnly |
+| DataTable, DataTableTable, DataTableHeader, DataTableBody, DataTableRow, DataTableHead, DataTableCell, DataTableAvatarCell, DataTableImageCell, DataTableCheckboxCell, DataTableActionCell, DataTableInputCell, DataTableSelectCell, DataTableNumberCell, DataTableDragHandleCell, DataTableLinkCell, DataTableBulkActions, DataTableSectionRow, DataTableAddRow, DataTableEmptyState | `@/components/patterns/admin/data-table` | **align**: `left`, `center`, `right`<br>**width**: `auto`, `narrow`, `checkbox`, `action`, `sm`, `md`, `lg`, `xl` | Default, Empty, WithSections, CellVariants, Sticky Columns (左端固定), Drag & Drop (行の並べ替え) |
+| ImageUploader | `@/components/patterns/admin/image-uploader` | — | Default, Empty |
+| KebabMenu | `@/components/patterns/admin/kebab-menu` | — | Default |
+| NotificationList | `@/components/patterns/admin/notification-list` | — | Vertical, Horizontal, Empty |
+| SearchPanel | `@/components/patterns/admin/search-panel` | — | Default |
+| StatusTabs | `@/components/patterns/admin/status-tabs` | — | Default |
+
+### patterns/（汎用）
+
+| Component | Import | Variants | Stories |
+|-----------|--------|----------|---------|
+| AppHeader | `@/components/patterns/app-header` | — | Default, WithBack, WithSubtitle, WithMenu, Sticky, Glass — Liquid Glass (over gradient), Transparent — scrollable reveal |
+| BannerCarousel | `@/components/patterns/banner-carousel` | — | Default, NoHeader, Tall |
+| Banner | `@/components/patterns/banner` | **variant**: `info`, `success`, `warning`, `caution` | Info, Success, Warning, Caution, WithAction, AllVariants |
+| BottomSheetForm | `@/components/patterns/bottom-sheet-form` | — | Default, WithLoading |
+| CategoryNav | `@/components/patterns/category-nav` | — | Default, WithSelection |
+| CategoryScroll | `@/components/patterns/category-scroll` | — | Default, CircleShape, GridLayout |
+| ChipSelector | `@/components/patterns/chip-selector` | — | MultiSelect, SingleSelect, WithMax |
+| Chip | `@/components/patterns/chip` | **variant**: `filled`, `accent`, `outline`<br>**size**: `sm`, `md`, `lg`, `tile`<br>**shape**: `pill`, `square` | Filled, Accent, Outline, AllVariants, AllSizes, Selected, Removable, SquareShape, WithCount, TileAndSoldOut, AsLink, Real UI — Filters & Status |
+| CoachMarkOverlay | `@/components/patterns/coach-mark-overlay` | — | — |
+| ConfirmDialog | `@/components/patterns/confirm-dialog` | — | Default, Destructive, WithLoading |
+| CookieConsent | `@/components/patterns/cookie-consent` | — | — |
+| EmptyState | `@/components/patterns/empty-state` | — | WithAction, Minimal, WithIconOnly, With dual action (recommended layout) |
+| ErrorState | `@/components/patterns/error-state` | — | DefaultWithRetry, CustomMessages, WithoutRetry |
+| FileUpload | `@/components/patterns/file-upload` | — | Default, Multiple |
+| FilterChip | `@/components/patterns/filter-chip` | — | — |
+| Footer | `@/components/patterns/footer` | — | Default, Minimal |
+| FormField | `@/components/patterns/form-field` | — | WithInput, Required, WithError, WithDescription, WithTextarea, WithSelect, CompleteForm |
+| FormRoot, FormSection, FormActions | `@/components/patterns/form` | — | Default |
+| ListItem | `@/components/patterns/list-item` | — | WithSlots, Interactive, WithBottomSlot |
+| ListSkeleton, GridSkeleton | `@/components/patterns/list-skeletons` | — | — |
+| MenuDrawer | `@/components/patterns/menu-drawer` | — | Default, NoBanner |
+| NotificationBadge | `@/components/patterns/notification-badge` | — | SingleDigit, DoubleDigit, MaxOverflow, CustomMax, Zero, VariousCounts, WithIcon |
+| ProgressSteps | `@/components/patterns/progress-steps` | — | Step2Active, FirstStep, ThirdStep, AllComplete, ThreeSteps |
+| ReviewOverlay | `@/components/patterns/review-overlay` | — | Default, WithPins |
+| SearchBar | `@/components/patterns/search-bar` | — | Default, WithValue, Disabled, WithOnSearch |
+| SectionHeader | `@/components/patterns/section-header` | — | WithAction, WithoutAction, TitleOnly, WithGhostButton |
+| ShareButtons | `@/components/patterns/share-buttons` | — | Circle, Inline, SelectiveProviders |
+| SimplePagination | `@/components/patterns/simple-pagination` | — | アイテム数指定 (items), ページ数指定 (pages), compact (モバイル省略表示), 境界での disabled, 0 件 |
+| StatCard | `@/components/patterns/stat-card` | — | TrendUp, TrendDown, NoTrend, Variants, MultipleCards |
+| StickyActionBar | `@/components/patterns/sticky-action-bar` | — | Default, TwoButtons, NoBorder |
+| SwipeRow | `@/components/patterns/swipe-row` | — | Default, SingleAction |
+| TagInput | `@/components/patterns/tag-input` | — | Default, WithInitialTags, WithMax, Disabled |
+| Tag | `@/components/patterns/tag` | **variant**: `default`, `brand`, `caution`, `success`, `warning`, `info` | Default, Brand, Caution, Success, Warning, Info, AllVariants |
+
+### patterns/commerce/
+
+| Component | Import | Variants | Stories |
+|-----------|--------|----------|---------|
+| BottomTabBar | `@/components/patterns/commerce/bottom-tab-bar` | — | Default, Pill — iOS 26 Liquid Glass, Pill — on light background |
+| FilterBar | `@/components/patterns/commerce/filter-bar` | — | Default, Interactive |
+| ImageCarousel | `@/components/patterns/commerce/image-carousel` | — | Banner, Square, Video, AutoPlay |
+| OrderSummary | `@/components/patterns/commerce/order-summary` | — | Default, Simple |
+| PriceDisplay | `@/components/patterns/commerce/price-display` | **size**: `sm`, `md`, `lg`, `xl` | Default, Sale, Range, AllSizes |
+| ProductCard | `@/components/patterns/commerce/product-card` | — | Vertical, VerticalWithDiscount, VerticalWithCart, VerticalWithRanking, Horizontal, Grid |
+| ProductCarousel | `@/components/patterns/commerce/product-carousel` | — | Default, WithRanking, WithCartButton, LargeCards |
+| QuantitySelector | `@/components/patterns/commerce/quantity-selector` | — | Medium, Small, WithTrash, Disabled |
+| RatingDisplay | `@/components/patterns/commerce/rating-display` | — | Default, AllSizes, ValueOnly |
+| ReviewCard, StarRow | `@/components/patterns/commerce/review-card` | — | Default, LowRating, WithSummary |
+| ReviewSummary | `@/components/patterns/commerce/review-summary` | — | Default, HighRating |
+
+### patterns/shells/
+
+| Component | Import | Variants | Stories |
+|-----------|--------|----------|---------|
+| AdminShell | `@/components/patterns/shells/admin-shell` | — | Default |
+| AppShell | `@/components/patterns/shells/app-shell` | — | Default |
+| MarketingShell | `@/components/patterns/shells/marketing-shell` | — | Default |
+
+---
+
+## よくある間違い
+
+| 禁止（手書き） | 正しい書き方 |
+|---|---|
+| `<button className="...">` | `<Button variant="..." size="...">` |
+| `<input className="...">` | `<Input>` |
+| `<textarea className="...">` | `<Textarea>` |
+| `<select>...</select>` | `<Select><SelectItem>` |
+| `function SectionHeader()` をページ内で定義 | `import { SectionHeader }` |
+| `function FormField()` をページ内で定義 | `import { FormField }` |
+| `<div className="rounded-xl border p-4">` | `<Card><CardContent>` |
+| `text-blue-500` 等 Tailwind 標準色 | `text-[var(--Brand-Primary)]` 等セマンティックトークン |
+| `font-bold` 直書き | `typo-body-md-bold` 等 typo-* クラス |
+
+---
+
+## 「DSにない」と誤解されやすいコンポーネント対応表
+
+> **新規コンポーネントを提案・実装する前に必ずこの表を確認すること。**
+
+| やりたいこと | 正しい使い方 | インポート |
+|---|---|---|
+| アイコンだけのボタン | `<Button size="icon">` / `"icon-sm"` / `"icon-lg"` | `Button` |
+| リンク見た目のボタン | `<Button variant="link">` | `Button` |
+| チェックボックス | `<Checkbox>` | `Checkbox` |
+| ラジオボタン | `<RadioGroup><RadioGroupItem>` | `RadioGroup, RadioGroupItem` |
+| Badge の色違い | `<Badge variant="success">` / `"destructive"` / `"warning"` / `"info"` | `Badge` |
+| 空状態の表示 | `<EmptyState>` | `EmptyState` |
+| 数値カード | `<StatCard>` | `StatCard` |
+| トースト通知 | `<Toaster>` + `useToast()` | `Toaster, useToast` |
+| スケルトン | `<Skeleton>` | `Skeleton` |
+| 下部ナビゲーション | `<BottomTabBar>` | `BottomTabBar` |
+| プログレスバー | `<Progress>` | `Progress` |
+| フォームフィールド | `<FormField>` | `FormField` |
+| ケバブメニュー | `<KebabMenu>` | `KebabMenu` |
+| モーダル（PC） | `<Dialog>` | `Dialog, DialogContent, ...` |
+| ドロワー（モバイル） | `<Sheet side="bottom">` | `Sheet, SheetContent, ...` |
+| PC/モバイル自動切替モーダル | `<ResponsiveDialog>` | `ResponsiveDialog, ...` |

package/src/preset.css

@@ -0,0 +1,168 @@
+/* =============================================================
+   KSK Design System — Preset CSS
+
+   外部プロジェクト向けプリセット。
+   1行の @import で全トークン + shadcn互換 + アニメーションが有効になる。
+
+   使い方:
+   @import "ksk-design-system/preset";
+
+   ─── Tailwind CSS v4 の @source 設定（重要） ───────────────────
+   Tailwind v4 はデフォルトで node_modules を走査しません。
+   コンポーネントの Tailwind クラスを検出するため、CSS ファイルに
+   @source ディレクティブで dist フォルダを指定してください。
+   詳細は CLAUDE.md / README を参照。
+   ============================================================= */
+
+@import "./styles/primitive.css";
+@import "./styles/semantic.css";
+@import "./styles/categorical.css";
+@import "./styles/typography.css";
+@import "./styles/glass.css";
+
+/* ─── Bridge Layer: shadcn/ui 互換マッピング ─── */
+:root {
+  --radius: 0.5rem;
+
+  --background: var(--Surface-Primary);
+  --foreground: var(--Text-High-Emphasis);
+
+  --card: var(--Surface-Primary);
+  --card-foreground: var(--Text-High-Emphasis);
+
+  --popover: var(--Surface-Primary);
+  --popover-foreground: var(--Text-High-Emphasis);
+
+  --primary: var(--Brand-Primary);
+  --primary-foreground: var(--Text-on-Inverse);
+
+  --secondary: var(--Surface-Secondary);
+  --secondary-foreground: var(--Text-High-Emphasis);
+
+  --muted: var(--Surface-Tertiary);
+  --muted-foreground: var(--Text-Low-Emphasis);
+
+  --accent: var(--Surface-Secondary);
+  --accent-foreground: var(--Text-High-Emphasis);
+
+  --destructive: var(--Caution-Base);
+  --destructive-foreground: var(--Text-on-Inverse);
+
+  --border: var(--Border-Medium-Emphasis);
+  --input: var(--Border-Medium-Emphasis);
+  --ring: var(--Focus-High-Emphasis);
+
+  --sidebar-background: var(--Surface-Primary);
+  --sidebar-foreground: var(--Text-High-Emphasis);
+  --sidebar-primary: var(--Brand-Primary);
+  --sidebar-primary-foreground: var(--Text-on-Inverse);
+  --sidebar-accent: var(--Surface-Accent-Primary-Light);
+  --sidebar-accent-foreground: var(--Text-Accent-Primary);
+  --sidebar-border: var(--Border-Low-Emphasis);
+  --sidebar-ring: var(--Focus-High-Emphasis);
+}
+
+.dark {
+  --background: var(--Surface-Primary);
+  --foreground: var(--Text-High-Emphasis);
+  --card: var(--Surface-Secondary);
+  --card-foreground: var(--Text-High-Emphasis);
+  --popover: var(--Surface-Secondary);
+  --popover-foreground: var(--Text-High-Emphasis);
+  --primary: var(--Brand-Primary);
+  --primary-foreground: var(--Text-on-Inverse);
+  --secondary: var(--Surface-Tertiary);
+  --secondary-foreground: var(--Text-High-Emphasis);
+  --muted: var(--Surface-Tertiary);
+  --muted-foreground: var(--Text-Low-Emphasis);
+  --accent: var(--Surface-Tertiary);
+  --accent-foreground: var(--Text-High-Emphasis);
+  --destructive: var(--Caution-Base);
+  --destructive-foreground: var(--Text-on-Inverse);
+  --border: var(--Border-Medium-Emphasis);
+  --input: var(--Border-Medium-Emphasis);
+  --ring: var(--Focus-High-Emphasis);
+}
+
+/* ─── Radius Tokens ───
+   角丸の意味別トークン。コンポーネントは rounded-[var(--Radius-*)] で参照し、
+   rounded-lg / rounded-[32px] のベタ書き（＝ドリフトの元）を避ける。
+   テーマ非依存（Brand / Light-Dark で変わらない固定値）。
+   面 < モーダル < シート の順に丸くなる階層。 */
+:root {
+  --Radius-Surface: 0.5rem;  /* 8px  — Card / Popover パネル / 面の既定。丸くしたいならここを上げる */
+  --Radius-Modal:   1.5rem;  /* 24px — 中央モーダル（Dialog / AlertDialog）。ピル/シートの丸い言語に合わせる */
+  --Radius-Sheet:   2rem;    /* 32px — 端寄せ Sheet（bottom / float） */
+}
+
+/* ─── Shadow Tokens ───
+   影色はテーマ非依存の neutral（Gray-900 ベース rgba(17,24,39,…)）。
+   旧来の青寄り rgba(24,39,75) は default=Blue 前提で、violet/orange/green
+   テーマや地の色とわずかにケンカするため neutral に統一。
+   ダークモードでは黒影が機能しない（glow 方向が必要）ため、.dark 側は別途調整する。 */
+:root {
+  --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
+  --shadow-md: 0 0 8px rgba(20, 20, 20, 0.08);
+  --shadow-lg: 0px 12px 32px -4px rgba(17, 24, 39, 0.12), 0px 8px 16px -6px rgba(17, 24, 39, 0.12);
+  --shadow-dialog: 0px 12px 32px -4px rgba(17, 24, 39, 0.12), 0px 8px 16px -6px rgba(17, 24, 39, 0.12), 0px 1px 4px 1px rgba(0, 0, 0, 0.2);
+  --shadow-tooltip: 0px 8px 8px -4px rgba(17, 24, 39, 0.08), 0px 4px 6px -4px rgba(17, 24, 39, 0.12);
+}
+
+/* ─── Animation ─── */
+@keyframes slide-in-right {
+  from { transform: translateX(100%); opacity: 0; }
+  to   { transform: translateX(0);    opacity: 1; }
+}
+@keyframes slide-in-left {
+  from { transform: translateX(-100%); opacity: 0; }
+  to   { transform: translateX(0);     opacity: 1; }
+}
+@keyframes fade-in {
+  from { opacity: 0; }
+  to   { opacity: 1; }
+}
+@keyframes fade-in-up {
+  from { opacity: 0; transform: translateY(8px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+@keyframes scale-in {
+  from { opacity: 0; transform: scale(0.95); }
+  to   { opacity: 1; transform: scale(1); }
+}
+
+@theme inline {
+  --animate-slide-in-right: slide-in-right 200ms ease-out;
+  --animate-slide-in-left:  slide-in-left 200ms ease-out;
+  --animate-fade-in:        fade-in 150ms ease-out;
+  --animate-fade-in-up:     fade-in-up 200ms ease-out;
+  --animate-scale-in:       scale-in 150ms ease-out;
+}
+
+/* ─── Scrollbar Hide Utility ─── */
+@utility scrollbar-hide {
+  -ms-overflow-style: none;
+  scrollbar-width: none;
+  &::-webkit-scrollbar {
+    display: none;
+  }
+}
+
+/* ─── Base Layer: ボーダー / アウトライン色のセーフティネット ───
+   Tailwind CSS v4 の破壊的変更で、border / outline の既定色は
+   gray-200 ではなく `currentColor`（＝要素の文字色）になった。
+   そのため `border` `border-b` のように「幅だけで色を指定しない」
+   クラスは、消費側が親に濃い文字色（例: --Text-High-Emphasis = #1C1A1A）
+   を敷くと枠線が黒ずむ。これを防ぐため、shadcn / 多くの DS と同じく
+   全要素のフォールバック色をテーマ追従の --border / --ring に固定する。
+
+   ※ これは「保険」。コンポーネント側は引き続き
+     border-[var(--Border-Low-Emphasis)] のように明示色を指定すること
+     （明示色を持つ要素は utilities レイヤが base を上書きするため不変）。 */
+@layer base {
+  *,
+  ::after,
+  ::before {
+    border-color: var(--border);
+    outline-color: var(--ring);
+  }
+}