ksk-design-system 1.61.1 → 1.63.0

package/MIGRATION.md

@@ -53,6 +53,84 @@ npx ksk-ds check-migration ./src
 
 ## v1 系内の minor 変更（参考）
 
+### 次のリリース — `typescript` が必須依存から optional peer dependency になった（issue #409）
+
+CLI の1ルール（P046）のためだけに typescript（24MB）が全 consumer の
+node_modules に入っていたのを解消した。install サイズが減り、`ksk-ds lint` の
+起動も速くなる（実測 655ms → 407ms）。
+
+- **通常の TypeScript プロジェクト**: 自前で typescript を持っているので影響なし
+- **typescript を持たないプロジェクト**: P046（card-child-spacing）だけが
+  「typescript が無いため skip」の1行案内つきでスキップされる。他の全ルールは動く
+- DS の typescript に transitive 依存していた場合のみ、自分の devDependencies に
+  typescript を追加すること
+
+
+### 次のリリース — `ksk-ds lint` の severity 語彙が `warn` → `warning` に統一（要確認）
+
+`--format json` の `results[].severity` と text 出力の severity 表記が、これまで
+`"warn"` と `"warning"` で不統一だった（contract の `contracts/rules.json` は
+`"warning"`、CLI 出力は `"warn"`）。**CLI 出力側を `"warning"` に揃えた**（issue #406）。
+
+CI で JSON をフィルタしている場合は置き換えが必要:
+
+```bash
+# before
+jq '[.results[] | select(.severity == "warn")] | length'
+# after
+jq '[.results[] | select(.severity == "warning")] | length'
+```
+
+text 出力の要約行も `0 error / 3 warn` → `0 error / 3 warning` に変わる。
+
+あわせて `ksk-ds lint` に次を追加した:
+
+- `--strict` … warning があれば exit 1
+- `--max-warnings N` … warning が N 件を超えたら exit 1
+- **未知のオプションはエラー終了**（従来は黙って捨てられ、CI に書いた
+  `--strict` が無言で効かないまま緑になっていた）
+
+### 次のリリース — `ksk-ds lint` の escape がルール単位・行単位で書けるようになった
+
+ファイル全体・全ルールを無期限に外す `// ksk-ds-allow-custom-ui: 理由` は
+後方互換で残るが**非推奨**。新規はルール単位を使う（issue #405）:
+
+```tsx
+// ksk-ds-lint-ignore P008 -- ブランドロゴの規定色のため     ← 直下 2 行以内に効く
+// ksk-ds-lint-ignore-file P008 -- ブランド定数ファイル      ← そのファイル全体・P008 のみ
+```
+
+理由は **5 文字以上が必須**。空虚な理由は `ESCAPE001` / `ESCAPE002` として報告され、
+ignore は効かない。あわせて escape マーカーは**文字列リテラルの中では発火しなくなった**
+（ドキュメント URL に `ksk-ds-allow-custom-ui` が含まれるだけで lint 全体が黙って
+無効化されていた）。既に short な理由を書いていたファイルは lint が復活するので、
+理由を書き足すか違反を直すこと。
+
+### 次のリリース — 自動生成物と DS 自身のトークン CSS を lint 対象外にした
+
+- 先頭 12 行に自動生成マーカー（`AUTO-GENERATED` / `DO NOT EDIT` / `自動生成` 等）を
+  持つファイルは全ルールを skip する（issue #408）。直す先は生成物ではなく生成元。
+- P049（product theme の無許可上書き）は、DS 自身 / ベンダリングされた DS の
+  トークン定義 CSS を対象外にする（issue #407）。`vendor/ksk-design-system/**` のように
+  DS を再梱包しているリポで P049 が大量に出ていたのが解消する。
+
+### 次のリリース — `Footer` の `paymentIcons` 既定値が空になった（挙動変更）
+
+`Footer` は `paymentIcons` を省略すると `["VISA", "Master", "JCB", "AmEx", "PayPay", "LINE Pay"]`
+の決済バッジを既定で描画していた。EC 以外のプロダクトでも「取り扱っていない決済手段」が
+出てしまうため、**既定値を `[]`（非表示）に変更**した。
+
+従来の表示を維持したい場合は明示的に渡す:
+
+```tsx
+<Footer
+  paymentIcons={["VISA", "Master", "JCB", "AmEx", "PayPay", "LINE Pay"]}
+  copyright="© 2026 KSK Inc."
+/>
+```
+
+`paymentIcons` を明示的に渡していた箇所は影響なし。
+
 ### 次のリリース — `postinstall` による AI ルールファイル自動設置を廃止（要確認）
 
 これまで `npm install ksk-design-system` の `postinstall` フックが、消費側の

package/README.md

@@ -87,6 +87,50 @@ import { Button, Card, Input, FormField } from "ksk-design-system"
 
 新規クライアント案件では、テーマファイルで `--Primitive-Brand-500` などブランドカラーの 10 行を定義するだけで、全コンポーネントがそのブランドカラーで動作します。
 
+### 段階移行レシピ（既存 CSS を保ったまま DS 化する）
+
+既存の手書き CSS で作られた画面を DS へ移すときは、**見た目を後回しにして挙動と
+アクセシビリティだけ先に統一する**のが最も安全です。生タグ（`<button>` / `<input>` /
+`<textarea>`）を DS コンポーネントへ置き換え、既存クラスを `className` へ渡し、
+`unstyled` を付けます。
+
+```tsx
+// before — 生タグ + 手書き CSS
+<button className="btn btn-primary" onClick={submit}>ログイン</button>
+<textarea className="composer-input" value={text} onChange={onChange} />
+
+// after — 挙動と a11y は DS、見た目は既存 CSS のまま
+<Button unstyled className="btn btn-primary" onClick={submit}>ログイン</Button>
+<Textarea unstyled className="composer-input" value={text} onChange={onChange} />
+```
+
+**なぜ `unstyled` が要るのか。** 手書き CSS は非レイヤー、DS のユーティリティは
+`@layer utilities` なので、宣言が衝突すれば手書き側が勝ちます。しかし手書きクラスの
+大半は height / white-space / font-weight / border-radius / background を宣言して
+おらず、**衝突しないプロパティは DS の base + variant がそのまま効きます**。
+`className` を渡すだけでは見た目は保てません。aikoibito web の実測では、
+チャット入力欄が `--Field-Min-Height: 5rem` の流入で **43px → 80px** に、
+ログイン CTA が **52px → 40px** に変わりました（issue #420）。
+
+`unstyled` を付けたときに DS が出すのは次だけです。
+
+| コンポーネント | 維持されるもの | 出さないもの |
+|---|---|---|
+| `Button` | `type` 既定 `"button"` / disabled・aria-disabled クリックの抑止 / `haptic` / `asChild` | `inline-flex` `items-center` `justify-center` `gap-*` `whitespace-nowrap` `typo-*` `cursor-pointer` と variant・size・layout の全クラス |
+| `Input` | `showCount`（IME 追従）/ adornment の配置土台 | `h-*` `w-full` `border-*` `bg-*` `px-*` `typo-*` `placeholder:*` |
+| `Textarea` | `autoGrow` / `showCount` | `min-h-*` `w-full` `border-*` `bg-*` `px-*` `py-*` `typo-*` `placeholder:*` |
+
+キーボード操作時の `focus-visible` リングだけは a11y のため既定で残ります。手書き CSS が
+自前のフォーカス表現を持つ場合は `className="focus-visible:ring-0"` で消せます。
+
+移行の順番は次のとおりです。
+
+1. 生タグを DS コンポーネント + `unstyled` + 既存クラスへ置き換える（見た目は 1px も変わらない）
+2. この状態で `npx ksk-ds lint src` の P001〜P006 を通す
+3. 画面ごとに、既存クラスを DS のトークン・variant へ置き換えて `unstyled` を外す
+
+`unstyled` は移行の足場であって最終形ではありません。3 が済んだ画面から順に外してください。
+
 ### Consumer lint
 
 consumer 側のローカル grep script が古くならないよう、DS 本体から `contracts/rules.json` を読む lint CLI を同梱しています。
@@ -95,14 +139,68 @@ consumer 側のローカル grep script が古くならないよう、DS 本体
 npx ksk-ds lint src
 npx ksk-ds lint src --format json
 npx ksk-ds lint --changed
+npx ksk-ds lint src --platform native
+npx ksk-ds lint src --strict            # warning も exit 1
+npx ksk-ds lint src --max-warnings=0    # warning が N 件を超えたら exit 1
 ```
 
-出力は `file:line rule severity fix` を含みます。どうしても DS で表現できない domain-specific UI は、理由付きの escape コメントを置きます。
+既定では `severity: "error"` のルールだけが exit code に影響します。a11y 系を含む
+`warning` ルールも CI で締めたい場合は `--strict` か `--max-warnings N` を使ってください。
+**未知のオプションはエラー終了**します（黙って捨てないので、CI に書いたフラグが
+無言で効かないことはありません）。
+
+ルールはファイルごとに **capability（そのファイルがどの記法を持ちうるか）** を判定して
+出し分けます（`contracts/rules.json` の `appliesTo`）。
+
+| ファイル | capability | 当たるルール |
+|---|---|---|
+| web（native シグナルなし） | `dom` `tailwind` `web` | 全部 |
+| React Native ＋ `className` あり（**NativeWind**） | `native` `tailwind` | Tailwind 系は当たる／DOM 生タグ系と CSS 変数系は外れる |
+| React Native ＋ `className` なし（**StyleSheet**） | `native` | Tailwind 系も外れる |
+
+native の判定シグナルは `*.native.tsx` というファイル名、`react-native` /
+`ksk-design-system/native` の **import 文**、`StyleSheet.create` の使用です。
+自動判定が合わない場合は `--platform web` / `--platform native` で上書きできます
+（ファイル判定より優先）。ただし `--platform native` を付けても Tailwind を持つかどうかは
+ソースの `className` の有無で決まるので、NativeWind の consumer が Tailwind 系ルールを
+失うことはありません。
+
+`appliesTo` を持たないルール（`#hex` 直書きの P008 等）は従来どおり全ファイルに適用され、
+native では RN 向けの fix 文言を表示します。
+
+出力は `file:line rule severity fix` を含みます。severity の語彙は `error` / `warning` で、
+`contracts/rules.json` と JSON 出力・text 出力すべてで一致しています。
+
+#### 例外（escape）
+
+どうしても DS で表現できない箇所は、**ルール単位・理由付き**の escape コメントを置きます
+（理由は 5 文字以上が必須。空虚な理由は `ESCAPE002` として報告され、ignore は効きません）。
 
 ```tsx
-// ksk-ds-allow-custom-ui: medical chart requires bespoke interaction
+// ksk-ds-lint-ignore P008 -- ブランドロゴの規定色のため
+const BRAND = "#06C755"
 ```
 
+| 書き方 | スコープ |
+|---|---|
+| `// ksk-ds-lint-ignore P008 -- 理由` | そのコメント行から**下 2 行以内**・指定ルールのみ |
+| `// ksk-ds-lint-ignore-file P008 -- 理由` | **そのファイル全体**・指定ルールのみ |
+| `// ksk-ds-allow-custom-ui: 理由` | そのファイル全体・**全ルール**（非推奨・後方互換） |
+
+`ksk-ds-allow-custom-ui` はスコープが広すぎて将来の違反まで隠すため、新規では使わず
+ルール単位の `ksk-ds-lint-ignore` を使ってください。escape マーカーは**コメントの中でのみ**
+有効で、文字列リテラル（ドキュメント URL 等）の中では発火しません。
+理由は 5 文字以上が必須です。また理由文字列に `*` は使えません
+（`*/` を誤って飲み込まないための制約で、`*` 以降は理由として認識されません）。
+
+#### lint されないファイル
+
+- 先頭 12 行に自動生成マーカー（`AUTO-GENERATED` / `DO NOT EDIT` / `自動生成` 等）を持つ
+  ファイルは全ルールを skip します。直す先は生成物ではなく生成元です。
+- DS 自身のトークン定義 CSS（`src/styles/*.css` / `src/themes/*.css` / `src/preset.css` と、
+  それを再梱包したベンダリングコピー）は P049 の対象外です。トークンを**定義**している側で
+  あって、consumer による上書きではないためです。
+
 ### Jest（CommonJS）でコンポーネントをテストする
 
 このパッケージは **ESM-only** です。CJS との dual build は配布せず、Jest

package/bin/check-duplicates.js

@@ -36,11 +36,15 @@ export function runCheckDuplicatesCli(
 
   const registry = loadComponentRegistry(contractsPath)
   const files = collectSourceFiles(target)
-  const findings = files
-    .flatMap((file) => findDuplicateExports(file, cwd, registry))
+  const results = files.map((file) => findDuplicateExports(file, cwd, registry))
+  const findings = results
+    .flatMap((result) => result.findings)
     .sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.name.localeCompare(b.name))
+  const wrapperExclusions = results
+    .flatMap((result) => result.wrapperExclusions)
+    .sort((a, b) => a.file.localeCompare(b.file) || a.name.localeCompare(b.name))
 
-  printFindings(findings, files.length, options.strict)
+  printFindings(findings, wrapperExclusions, files.length, options.strict)
   return options.strict && findings.length > 0 ? 1 : 0
 }
 
@@ -117,10 +121,83 @@ function collectSourceFiles(target) {
   return files.sort()
 }
 
+// ksk-design-system 本体（サブパス含む）からの named import/re-export かどうか。
+// 例: "ksk-design-system", "ksk-design-system/native", "ksk-design-system/native/ui"
+function isDsModuleSpecifier(moduleSpecifier) {
+  return moduleSpecifier === "ksk-design-system" || moduleSpecifier.startsWith("ksk-design-system/")
+}
+
+// `{ A, B as C, type D }` のような specifier リストを
+// [{ sourceName: "A", localName: "A" }, { sourceName: "B", localName: "C" }, ...] に分解する。
+// エイリアス判定は「import 指定子の imported 名（sourceName）」を用いる。ローカル名（localName）は問わない。
+function parseSpecifierList(specifierList) {
+  return specifierList
+    .split(",")
+    .map((spec) => spec.trim())
+    .filter((spec) => spec.length > 0)
+    .map((spec) => {
+      const withoutTypeModifier = spec.replace(/^type\s+/, "")
+      const [sourceName, localName] = withoutTypeModifier.split(/\s+as\s+/).map((part) => part.trim())
+      return { sourceName, localName: localName ?? sourceName }
+    })
+    .filter((entry) => entry.sourceName)
+}
+
+// import/re-export 検出はコメントを除外してから行う（JSDoc の使用例コメント
+// `* import { X } from "ksk-design-system"` を実コードの import と誤認しないため）。
+// 文字列リテラル内の `/* `等までは考慮しないが、このファイル全体の regex ベース方針と
+// 整合する範囲の簡易対応とする。
+function stripComments(source) {
+  return source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "")
+}
+
+// このファイルが ksk-design-system から named import している「imported 名（sourceName）」の集合。
+// `import { EmptyState as DSEmptyState } from 'ksk-design-system/native/ui'` なら "EmptyState"。
+// ローカルの alias 名（DSEmptyState）ではなく、パッケージ側の元の名前で判定する。
+function collectDsImportSourceNames(source) {
+  const names = new Set()
+  const importPattern = /import\s*\{([^}]*)\}\s*from\s*["']([^"']+)["']/g
+
+  for (const match of source.matchAll(importPattern)) {
+    const [, specifierList, moduleSpecifier] = match
+    if (!isDsModuleSpecifier(moduleSpecifier)) continue
+    for (const { sourceName } of parseSpecifierList(specifierList)) {
+      names.add(sourceName)
+    }
+  }
+
+  return names
+}
+
+// `export { X as Y } from 'ksk-design-system/...'` のような re-export 形式。
+// これは常に DS の実装をそのまま右から左へ渡すだけなので、localName が
+// registry と一致する場合は無条件でラッパー（除外対象）として扱う。
+function collectDsReExports(source) {
+  const reExports = []
+  const reExportPattern = /export\s*\{([^}]*)\}\s*from\s*["']([^"']+)["']/g
+
+  for (const match of source.matchAll(reExportPattern)) {
+    const [, specifierList, moduleSpecifier] = match
+    if (!isDsModuleSpecifier(moduleSpecifier)) continue
+    for (const { localName } of parseSpecifierList(specifierList)) {
+      reExports.push(localName)
+    }
+  }
+
+  return reExports
+}
+
 function findDuplicateExports(file, cwd, registry) {
   const source = readFileSync(file, "utf8")
   const lines = source.split(/\r?\n/)
   const findings = []
+  const wrapperExclusions = []
+  const relFile = normalize(relative(cwd, file))
+
+  const codeForImportScan = stripComments(source)
+  const dsImportSourceNames = collectDsImportSourceNames(codeForImportScan)
+  const dsReExportLocalNames = collectDsReExports(codeForImportScan)
+
   const declarationPattern =
     /^\s*export\s+(?:default\s+)?(?:(?:async|declare)\s+)?(?:function|const)\s+([A-Z][A-Za-z0-9]*)\b/
 
@@ -130,37 +207,59 @@ function findDuplicateExports(file, cwd, registry) {
     const name = match[1]
     const components = registry.get(name)
     if (!components) continue
+
+    // 同名のローカル宣言があっても、同ファイルが ksk-design-system から同名（元の
+    // export 名基準。ローカル alias は問わない）を import して使っているなら、
+    // DS 委譲ラッパーとして重複報告から除外する（DS が推奨する段階移行の型のため）。
+    if (dsImportSourceNames.has(name)) {
+      wrapperExclusions.push({ file: relFile, name })
+      continue
+    }
+
     findings.push({
       components,
-      file: normalize(relative(cwd, file)),
+      file: relFile,
       line: index + 1,
       name,
     })
   }
 
-  return findings
+  // `export { X as Y } from 'ksk-design-system/...'` 形式の re-export。
+  // registry と一致する localName だけを対象にする（DS に無い名前の re-export は無関係）。
+  for (const localName of dsReExportLocalNames) {
+    if (!registry.get(localName)) continue
+    wrapperExclusions.push({ file: relFile, name: localName })
+  }
+
+  return { findings, wrapperExclusions }
 }
 
-function printFindings(findings, scannedFiles, strict) {
+function printFindings(findings, wrapperExclusions, scannedFiles, strict) {
   if (findings.length === 0) {
     console.log(`ksk-ds check-duplicates: 重複候補はありません（${scannedFiles} files）`)
-    return
+  } else {
+    console.log(`ksk-ds check-duplicates: DS と同名のローカル実装を ${findings.length} 件検出しました`)
+    for (const finding of findings) {
+      console.log(`\n${finding.file}:${finding.line} ${finding.name}`)
+      for (const component of finding.components) {
+        console.log(`  DS: ${component.tier} / ${component.path}`)
+      }
+    }
+    console.log("\nローカル実装を削除して ksk-design-system から import できないか確認してください。")
+    console.log("DS に必要な機能が不足する場合は、ローカル台帳を作らず DS 側に Issue を登録してください。")
+    console.log(
+      strict
+        ? "strict mode: 重複候補があるため終了コード 1"
+        : "advice mode: 終了コード 0（CI で失敗させる場合は --strict）",
+    )
   }
 
-  console.log(`ksk-ds check-duplicates: DS と同名のローカル実装を ${findings.length} 件検出しました`)
-  for (const finding of findings) {
-    console.log(`\n${finding.file}:${finding.line} ${finding.name}`)
-    for (const component of finding.components) {
-      console.log(`  DS: ${component.tier} / ${component.path}`)
+  if (wrapperExclusions.length > 0) {
+    console.log(`\nℹ ラッパー（DS 委譲済み）として除外: ${wrapperExclusions.length} 件`)
+    for (const wrapper of wrapperExclusions) {
+      console.log(`  ℹ ラッパー（DS 委譲済み）として除外: ${wrapper.name} (${wrapper.file})`)
     }
   }
-  console.log("\nローカル実装を削除して ksk-design-system から import できないか確認してください。")
-  console.log("DS に必要な機能が不足する場合は、ローカル台帳を作らず DS 側に Issue を登録してください。")
-  console.log(
-    strict
-      ? "strict mode: 重複候補があるため終了コード 1"
-      : "advice mode: 終了コード 0（CI で失敗させる場合は --strict）",
-  )
 }
 
 function printHelp() {
@@ -176,6 +275,8 @@ DIR の既定値:
 動作:
   export function / export const の PascalCase 宣言を
   contracts/components.json と名前の完全一致で照合します。
+  ただし、同ファイルが ksk-design-system から同名（alias 可）を import/re-export して
+  使っているものは DS 委譲ラッパーとみなし、重複報告から除外します（info 行で件数報告）。
   既定は助言モード（常に exit 0）、--strict は検出時 exit 1 です。
 `)
 }

package/bin/init.js

@@ -82,8 +82,23 @@ if (cmd === "lint") {
 }
 
 if (cmd === "check-migration") {
-  const { runCheckMigrationCli } = await import("./check-migration.js")
-  const status = runCheckMigrationCli(args.slice(1), { cwd: process.cwd(), pkgRoot })
+  // check-migration.js は TypeScript の AST 解析そのものが本体なので、
+  // typescript 不在なら raw な ERR_MODULE_NOT_FOUND ではなく案内を出して
+  // skip する（exit 0。lint 同様に「無言で落ちる」を避ける／issue #409）。
+  let mod
+  try {
+    mod = await import("./check-migration.js")
+  } catch (error) {
+    if (error?.code === "ERR_MODULE_NOT_FOUND" && String(error.message ?? "").includes("typescript")) {
+      console.log(
+        `[ksk-ds check-migration] typescript が見つからないため skip します。` +
+          `devDependencies に typescript を追加すると検査できます。`,
+      )
+      await exitWith(0)
+    }
+    throw error
+  }
+  const status = mod.runCheckMigrationCli(args.slice(1), { cwd: process.cwd(), pkgRoot })
   await exitWith(status)
 }