ksk-design-system 1.38.0 → 1.40.0

package/NATIVE_RECIPES.md

@@ -0,0 +1,141 @@
+# KSK Design System Native Recipes
+
+Native / Expo consumer は、新規 UI を作る前に `ksk-design-system/native/ui` の既存コンポーネントを確認してください。ローカル `ds/` に独自 wrapper を増やす前に、このファイルの recipe を使います。
+
+## Expo Router / React Navigation bottom tabs
+
+Expo Router の `<Tabs>` では `createExpoRouterTabBar` を渡します。アイコンは各 screen の `tabBarIcon` をそのまま使えるため、consumer 側で floating tab bar を組み直す必要はありません。
+
+```tsx
+import { Tabs } from "expo-router"
+import { createExpoRouterTabBar } from "ksk-design-system/native/ui"
+
+const tabBar = createExpoRouterTabBar({
+  glass: true,
+  floating: true,
+  keyboardBehavior: "hide",
+  hiddenRouteNames: ["modal"],
+})
+
+export default function Layout() {
+  return (
+    <Tabs tabBar={tabBar}>
+      <Tabs.Screen name="index" options={{ title: "ホーム" }} />
+      <Tabs.Screen name="settings" options={{ title: "設定" }} />
+      <Tabs.Screen name="modal" options={{ href: null }} />
+    </Tabs>
+  )
+}
+```
+
+個別画面で tab bar を隠す場合は `options={{ tabBarStyle: { display: "none" } }}` を使います。画面をルーティング対象から隠す場合は Expo Router の `href: null` を使います。
+
+React Navigation でも同じ factory を `tabBar` に渡せます。
+
+```tsx
+<Tab.Navigator tabBar={createExpoRouterTabBar({ glass: true, floating: true })}>
+  {/* screens */}
+</Tab.Navigator>
+```
+
+## iOS 26 Liquid Glass
+
+`GlassView` は `expo-glass-effect` が使える iOS 26 環境では native Liquid Glass を使い、未導入または非対応環境では `expo-blur`、最後に tokenized surface へフォールバックします。
+
+```bash
+npx expo install expo-glass-effect expo-blur
+```
+
+```tsx
+import { GlassView } from "ksk-design-system/native/ui"
+
+<GlassView
+  nativeGlass
+  fallback="blur"
+  glassEffectStyle="regular"
+  tint="system"
+  intensity="regular"
+  borderRadius={28}
+  interactive
+>
+  {/* tab bar, composer, floating action surface */}
+</GlassView>
+```
+
+`nativeGlass` を有効にしても Android / web / 非対応 iOS では自動で fallback します。feature check が必要な場合は `isNativeLiquidGlassAvailable()` を使います。
+
+## Button loading and icon slots
+
+Native `Button` は `loading`、`loadingLabel`、`leadingIcon`、`trailingIcon` を持ちます。loading 中は disabled 扱いになり、`ActivityIndicator` は `Text` に包まれません。
+
+```tsx
+<Button
+  variant="primary"
+  loading={saving}
+  loadingLabel="保存中"
+  leadingIcon={<SaveIcon />}
+  onPress={save}
+>
+  保存する
+</Button>
+```
+
+## Mobile app shell
+
+`MobileAppShell` は header / main / bottom nav / global FAB / desktop sidebar の基本 geometry を DS 側に寄せる recipe です。consumer 側で main padding や fixed nav の重なりを毎回計算しません。
+
+```tsx
+import {
+  BottomTabBar,
+  MobileAppShell,
+  MobileFloatingActionButton,
+} from "ksk-design-system/native/ui"
+
+<MobileAppShell
+  header={<AppHeader title="Belle" />}
+  bottomNav={<BottomTabBar items={items} glass />}
+  fab={<MobileFloatingActionButton label="追加" onPress={openCreate} />}
+>
+  <HomeScreen />
+</MobileAppShell>
+```
+
+Web/PWA consumer は `ksk-design-system` の `MobileAppShell` と `BottomTabBar variant="pill"` / `MobileFloatingActionButton` を組み合わせます。`bottomNavMode="fixed"` では shell が fixed wrapper と safe-area padding を持ちます。既に fixed な nav を渡す場合は `bottomNavMode="external"` を指定します。
+
+## Settings screens
+
+設定画面は `SettingsSection` と `SettingsListRow` を使います。`Card + SectionHeader + ListItem` のローカル wrapper を consumer 側で複製しないでください。
+
+```tsx
+<SettingsSection title="通知" variant="card">
+  <SettingsListRow title="プッシュ通知" rightSlot={<Switch value={enabled} />} />
+  <SettingsListRow title="通知時間" description="毎日 9:00" rightSlot={<Badge>ON</Badge>} />
+</SettingsSection>
+```
+
+## Attachments
+
+Web では `CompactFilePicker` / `ImageAttachmentPicker` が hidden file input、trigger、preview、remove affordance を持ちます。Native では DocumentPicker / ImagePicker の起動だけ consumer が渡し、trigger と preview は DS が持ちます。
+
+```tsx
+<ImageAttachmentPicker
+  multiple
+  images={images}
+  onFilesChange={setFiles}
+  onRemove={removeImage}
+/>
+```
+
+## Bottom sheet frames
+
+`BottomSheetFrame` は `SheetContent` の外枠 preset です。中身は `DetailSheetScaffold` と `KeyboardAwareSheetFooter` をそのまま組み合わせます。
+
+```tsx
+<Sheet open={open} onOpenChange={setOpen}>
+  <BottomSheetFrame preset="mobile-form">
+    <DetailSheetScaffold header={<DetailSheetHeader title="編集" />} footer={<KeyboardAwareSheetFooter />}>
+      {/* fields */}
+    </DetailSheetScaffold>
+  </BottomSheetFrame>
+</Sheet>
+```

package/README.md

@@ -4,7 +4,7 @@
 
 **🔗 ライブ Storybook → https://ksk-design-system.vercel.app**
 
-115 コンポーネントを実際に操作・確認できます。
+125 コンポーネントを実際に操作・確認できます。
 
 ---
 
@@ -14,7 +14,7 @@
 - **アクセシブル** — shadcn/ui（Radix UI ベース）+ `@storybook/addon-a11y` で a11y を担保
 - **Tailwind CSS v4 ネイティブ** — `@theme` ベースのトークン設計
 - **型安全** — React 19 + TypeScript、CVA によるバリアント管理
-- **115 + 91 コンポーネント** — Web 115（UI 56 / EC 11 / 管理 8 / シェル 3 / パターン 37）+ React Native 91
+- **125 + 96 コンポーネント** — Web 125（UI 57 / EC 11 / 管理 8 / シェル 3 / パターン 46）+ React Native 96
 - **iOS 26 Liquid Glass 対応** — RN 側 `GlassView` + `Button variant="glass"`、Web 側 `.glass` CSS マテリアル
 
 ## 🎨 テーマ
@@ -54,6 +54,22 @@ import { Button, Card, Input, FormField } from "ksk-design-system"
 
 新規クライアント案件では、テーマファイルで `--Primitive-Brand-500` などブランドカラーの 10 行を定義するだけで、全コンポーネントがそのブランドカラーで動作します。
 
+### Consumer lint
+
+consumer 側のローカル grep script が古くならないよう、DS 本体から `contracts/rules.json` を読む lint CLI を同梱しています。
+
+```bash
+npx ksk-ds lint src
+npx ksk-ds lint src --format json
+npx ksk-ds lint --changed
+```
+
+出力は `file:line rule severity fix` を含みます。どうしても DS で表現できない domain-specific UI は、理由付きの escape コメントを置きます。
+
+```tsx
+// ksk-ds-allow-custom-ui: medical chart requires bespoke interaction
+```
+
 ### Media overlay utilities
 
 動画・写真の上に文字や操作を置く場合は、`--Text-on-Media` と `.text-on-media` / `.text-on-media-secondary`、上下の `.media-scrim-top` / `.media-scrim-bottom` を使います。TikTok / Reels 型の操作群は `MediaActionCluster` が glass ボタン、ラベル、safe-area anchor、idle auto-hide をまとめて扱います。
@@ -92,6 +108,27 @@ import { Screen, PhotoHero, Button } from "ksk-design-system"
 </Screen>
 ```
 
+### Liquid Glass bottom navigation
+
+Web のグローバルナビで iOS 26 風の Liquid Glass を使う場合は、`BottomTabBar variant="pill"` を使います。実アプリの中央 CTA は `centerAction`、ラベル付き構成は `showLabels`、暗い写真・動画・gradient 上では `tone="inverse"` を指定します。
+
+```tsx
+import { BottomTabBar } from "ksk-design-system"
+
+<BottomTabBar
+  variant="pill"
+  items={[
+    { label: "トーク", icon: <TalkIcon />, href: "/talk", isActive: true },
+    { label: "ギャラリー", icon: <GalleryIcon />, href: "/gallery" },
+  ]}
+  centerAction={{ label: "作成", icon: <PlusIcon />, href: "/create" }}
+  tone="inverse"
+  maxWidth={430}
+/>
+```
+
+`pillPosition` は実アプリでは既定の `fixed`、Storybook や mobile shell 内のデモでは `absolute` を使います。safe-area は内部で `env(safe-area-inset-bottom)` を見ます。入力フォーム画面では keyboard 表示時に被らないよう、画面側で nav を隠すか bottom action に切り替えてください。
+
 ### React Native / Expo
 
 `ksk-design-system/native/ui` から直接 RN 用コンポーネント（91 個）を import できます。iOS 26 の **Liquid Glass** にも対応:
@@ -102,11 +139,13 @@ import { ThemeProvider, Button, Card, GlassView } from "ksk-design-system/native
 
 ```bash
 # Liquid Glass を本物の UIVisualEffectView で出したい場合
-npx expo install expo-blur
+npx expo install expo-glass-effect expo-blur
 ```
 
 Web は backdrop-filter で擬似、Android は半透明 surface でフォールバックします。
 
+Expo Router / React Navigation の tab bar、native `GlassView`、Button loading、settings/attachment/mobile shell recipes は `NATIVE_RECIPES.md` を参照してください。
+
 ## 🧪 試してみる（1コマンドお試し）
 
 ```bash

package/bin/init.js

@@ -10,6 +10,7 @@
 //   npx ksk-design-system init          # AGENTS.md + CLAUDE.md を設置
 //   npx ksk-design-system init --force  # 既存ファイルを上書き
 //   npx ksk-design-system demo [dir]    # DS リポを clone + setup（お試し用）
+//   npx ksk-ds lint src                 # contracts/rules.json に基づき consumer UI を検査
 //   npx ksk-design-system postinstall   # npm postinstall から呼ばれる silent モード
 
 import { copyFileSync, existsSync } from "node:fs"
@@ -32,10 +33,19 @@ if (cmd === "help" || cmd === "--help" || cmd === "-h") {
   npx ksk-design-system init --force  既存ファイルを上書き
   npx ksk-design-system demo [dir]    DS リポを clone + npm install（お試し）
                                       dir 省略時は ./ksk-ds-demo
+  npx ksk-ds lint src                 DS-first ルール違反を検査
+  npx ksk-ds lint src --format json   CI 向け JSON 出力
+  npx ksk-ds lint --changed           Git 差分のみ検査
 `)
   process.exit(0)
 }
 
+if (cmd === "lint") {
+  const { runLintCli } = await import("./lint.js")
+  const status = await runLintCli(args.slice(1), { cwd: process.cwd(), pkgRoot })
+  process.exit(status)
+}
+
 if (cmd === "demo") {
   runDemo(args.slice(1))
   process.exit(0)

package/bin/lint.js

@@ -0,0 +1,266 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs"
+import { extname, join, relative, resolve } from "node:path"
+import { spawnSync } from "node:child_process"
+
+const DEFAULT_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx"])
+const DEFAULT_IGNORES = [
+  ".git",
+  ".next",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "storybook-static",
+]
+
+export async function runLintCli(argv, { cwd = process.cwd(), pkgRoot = resolve(".") } = {}) {
+  const options = parseArgs(argv)
+  const rulesPath = resolve(pkgRoot, "contracts/rules.json")
+  if (!existsSync(rulesPath)) {
+    console.error(`contracts/rules.json が見つかりません: ${rulesPath}`)
+    return 1
+  }
+
+  const rules = loadRules(rulesPath)
+  const files = options.changed
+    ? getChangedFiles(cwd, options)
+    : collectTargetFiles(cwd, options.targets, options)
+  const findings = []
+
+  for (const file of files) {
+    findings.push(...lintFile(file, cwd, rules, options))
+  }
+
+  const summary = summarize(findings)
+  if (options.format === "json") {
+    console.log(JSON.stringify({ results: findings, summary }, null, 2))
+  } else {
+    printText(findings, summary)
+  }
+
+  return summary.errors > 0 ? 1 : 0
+}
+
+function parseArgs(argv) {
+  const targets = []
+  const excludes = []
+  let format = "text"
+  let changed = false
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === "--format") {
+      format = argv[++i] ?? "text"
+      continue
+    }
+    if (arg.startsWith("--format=")) {
+      format = arg.slice("--format=".length)
+      continue
+    }
+    if (arg === "--changed") {
+      changed = true
+      continue
+    }
+    if (arg === "--exclude") {
+      excludes.push(argv[++i])
+      continue
+    }
+    if (arg.startsWith("--exclude=")) {
+      excludes.push(arg.slice("--exclude=".length))
+      continue
+    }
+    if (arg === "--help" || arg === "-h") {
+      console.log(`ksk-ds lint
+
+使い方:
+  ksk-ds lint [path ...]
+  ksk-ds lint src --changed
+  ksk-ds lint src --format json
+
+オプション:
+  --changed       Git の変更ファイルのみ検査
+  --format json   JSON 出力
+  --exclude TEXT  パスに TEXT を含むファイルを除外
+
+例外:
+  // ksk-ds-allow-custom-ui: domain-specific reason
+`)
+      process.exit(0)
+    }
+    if (!arg.startsWith("-")) targets.push(arg)
+  }
+
+  return {
+    changed,
+    excludes: excludes.filter(Boolean),
+    format: format === "json" ? "json" : "text",
+    targets: targets.length > 0 ? targets : ["."],
+  }
+}
+
+function loadRules(rulesPath) {
+  const contract = JSON.parse(readFileSync(rulesPath, "utf8"))
+  const prohibited = Array.isArray(contract)
+    ? contract
+    : Array.isArray(contract.prohibited)
+      ? contract.prohibited
+      : []
+  const aiPatterns = Array.isArray(contract?.aiPatterns?.patterns)
+    ? contract.aiPatterns.patterns.map((rule) => ({ ...rule, category: "ai-pattern", severity: "warn" }))
+    : []
+
+  return [...prohibited, ...aiPatterns].filter((rule) => typeof rule.pattern === "string" && rule.pattern.length > 0)
+}
+
+function collectTargetFiles(cwd, targets, options) {
+  const files = []
+  for (const target of targets) {
+    const abs = resolve(cwd, target)
+    if (!existsSync(abs)) continue
+    collect(abs, cwd, options, files)
+  }
+  return files
+}
+
+function collect(abs, cwd, options, out) {
+  const rel = normalize(relative(cwd, abs))
+  if (shouldIgnorePath(rel, options)) return
+  const stat = statSync(abs)
+  if (stat.isDirectory()) {
+    for (const entry of readdirSync(abs)) {
+      collect(join(abs, entry), cwd, options, out)
+    }
+    return
+  }
+  if (stat.isFile() && DEFAULT_EXTENSIONS.has(extname(abs))) out.push(abs)
+}
+
+function getChangedFiles(cwd, options) {
+  const names = new Set()
+  for (const args of [
+    ["diff", "--name-only", "--diff-filter=ACMR", "origin/main...HEAD"],
+    ["diff", "--name-only", "--diff-filter=ACMR"],
+    ["diff", "--name-only", "--diff-filter=ACMR", "--cached"],
+  ]) {
+    const result = spawnSync("git", args, { cwd, encoding: "utf8" })
+    if (result.status !== 0) continue
+    for (const line of result.stdout.split(/\r?\n/)) {
+      if (line.trim()) names.add(line.trim())
+    }
+  }
+  return [...names]
+    .map((name) => resolve(cwd, name))
+    .filter((abs) => existsSync(abs))
+    .filter((abs) => !shouldIgnorePath(normalize(relative(cwd, abs)), options))
+    .filter((abs) => DEFAULT_EXTENSIONS.has(extname(abs)))
+}
+
+function lintFile(file, cwd, rules) {
+  const rel = normalize(relative(cwd, file))
+  const source = readFileSync(file, "utf8")
+  const escape = findEscape(source, rel)
+  if (escape.valid) return []
+
+  const findings = []
+  if (escape.invalid) findings.push(escape.invalid)
+  const lines = source.split(/\r?\n/)
+
+  for (const rule of rules) {
+    let regex
+    try {
+      regex = new RegExp(rule.pattern)
+    } catch {
+      continue
+    }
+    if (rule.pattern.includes("[\\s\\S]")) {
+      const match = source.match(regex)
+      if (match && match.index != null) {
+        const lineNumber = lineForIndex(source, match.index)
+        const line = lines[lineNumber - 1] ?? ""
+        if (!matchesRuleExclude(rule, rel, line)) {
+          findings.push(toFinding(rule, rel, lineNumber))
+        }
+      }
+      continue
+    }
+    for (let index = 0; index < lines.length; index++) {
+      const line = lines[index]
+      if (matchesRuleExclude(rule, rel, line)) continue
+      if (!regex.test(line)) continue
+      findings.push(toFinding(rule, rel, index + 1))
+    }
+  }
+
+  return findings
+}
+
+function toFinding(rule, file, line) {
+  return {
+    file,
+    line,
+    ruleId: rule.id ?? "UNKNOWN",
+    severity: rule.severity === "error" ? "error" : "warn",
+    category: rule.category ?? "pattern",
+    message: rule.message ?? rule.name ?? "DS rule violation",
+    fix: rule.fix ?? "",
+  }
+}
+
+function findEscape(source, file) {
+  const match = source.match(/ksk-ds-allow-custom-ui(?::\s*(.+))?/)
+  if (!match) return { valid: false }
+  const reason = match[1]?.trim()
+  if (reason) return { valid: true }
+  return {
+    valid: false,
+    invalid: {
+      file,
+      line: lineForIndex(source, match.index ?? 0),
+      ruleId: "ESCAPE001",
+      severity: "error",
+      category: "escape",
+      message: "ksk-ds-allow-custom-ui には理由が必要です",
+      fix: "例: // ksk-ds-allow-custom-ui: domain-specific reason",
+    },
+  }
+}
+
+function lineForIndex(source, index) {
+  return source.slice(0, index).split(/\r?\n/).length
+}
+
+function matchesRuleExclude(rule, file, line) {
+  const excludes = Array.isArray(rule.excludes) ? rule.excludes : []
+  return excludes.some((exclude) => file.includes(exclude) || line.includes(exclude))
+}
+
+function shouldIgnorePath(relPath, options) {
+  if (!relPath || relPath === ".") return false
+  const parts = relPath.split("/")
+  if (parts.some((part) => DEFAULT_IGNORES.includes(part))) return true
+  return options.excludes.some((exclude) => relPath.includes(exclude))
+}
+
+function summarize(findings) {
+  return {
+    files: new Set(findings.map((finding) => finding.file)).size,
+    errors: findings.filter((finding) => finding.severity === "error").length,
+    warnings: findings.filter((finding) => finding.severity !== "error").length,
+  }
+}
+
+function printText(findings, summary) {
+  if (findings.length === 0) {
+    console.log("ksk-ds lint: 違反は見つかりませんでした")
+    return
+  }
+  for (const finding of findings) {
+    console.log(`${finding.file}:${finding.line} ${finding.severity} ${finding.ruleId} ${finding.message}`)
+    if (finding.fix) console.log(`  fix: ${finding.fix}`)
+  }
+  console.log(`\nksk-ds lint: ${summary.errors} error / ${summary.warnings} warn in ${summary.files} files`)
+}
+
+function normalize(path) {
+  return path.replaceAll("\\", "/")
+}