@lism-css/mcp 0.23.0 → 0.24.0

package/dist/data/guides/antipatterns.md

@@ -2,87 +2,49 @@
 
 AI が Lism CSS のコードを生成する際に間違いやすい記法と、その正しい書き方をカタログ化したもの。コードを書く前に該当カテゴリを確認すること。
 
+値・スタイル宣言系はこのファイル、構造・レイアウト・レスポンシブ系は [antipatterns-layout.md](./antipatterns-layout.md) に分けている。
+
 ## TOC
 
-- [Token typo（存在しない値）](#token-typo存在しない値)
+### 値・スタイル宣言系（このファイル）
+
 - [px / 固定値の直書き](#px--固定値の直書き)
 - [Property Class で書けるのに CSS で書く](#property-class-で書けるのに-css-で書く)
-- [`is--` の誤用（状態・バリエーション）](#is---の誤用状態バリエーション)
-- [カスタムクラスを全て `c--` にしてしまう](#カスタムクラスを何でも-c---にしない)
-- [クラス名の命名ミス（kebab-case）](#クラス名の命名ミスkebab-case)
+- [Token typo（存在しない値）](#token-typo存在しない値)
+- [`c--*` CSS を `@layer lism-component` に入れない](#c---css-を-layer-lism-component-に入れない)
+- [hover を component CSS に書いて負ける](#hover-を-component-css-に書いて負ける)
+- [Reset 済みプロパティの再指定](#reset-済みプロパティの再指定)
 - [`--keycolor` の誤用](#--keycolor-の誤用)
 - [Prop 型ミス](#prop-型ミス)
-- [レイアウト選択ミス](#レイアウト選択ミス)
-- [レスポンシブ抜け](#レスポンシブ抜け)
-
----
-
-## Token typo（存在しない値）
-
-Lism CSS側が用意しているトークン値と異なるものを書かないように注意する。  
-正確な一覧は [tokens.md](./tokens.md) を参照すること。
-
-ただし、ユーザーが独自に追加定義することは可能。あくまでデフォルトで用意されていないもので間違えやすいものを紹介しておく。
-
-### カラー
-
-| NG | OK | 理由 |
-|---|---|---|
-| `bgc="primary"` | `bgc="brand"` | セマンティックカラーに `primary`/`secondary` は無い。ブランド色は `brand`/`accent` |
-| `bgc="secondary"` | `bgc="base-2"` | サブ背景色は `base-2`（`base-3` がユーザーによって追加定義されている可能性もある） |
-| `c="muted"` | `c="text-2"` | 補助テキスト色は `text-2` |
-| `c="danger"` | `c="red"` | パレットカラーから選ぶ（`red` / `orange` 等） |
-
-- セマンティックカラー: `base` / `base-2` / `text` / `text-2` / `divider` / `link` / `brand` / `accent` / `neutral`
-- パレットカラー: `red` / `blue` / `green` / `yellow` / `purple` / `orange` / `pink` / `gray` / `white` / `black`
-
-### スペース（`p` / `m` / `g` 等）
-
-スペーストークンの数値は**離散的**で、`5/10/15/20/25/30/35/40/50/60/70/80` のみが用意されている。`8/12/14/45/65/75` 等を書きそうになったら、必ず最寄りトークンに丸めるか、ユーザーに方針確認すること（→ [SKILL.md のデザイン取り込みフロー](./SKILL.md#デザインデータ取り込み時のフロー)）。
 
-| NG | OK | 理由 |
-|---|---|---|
-| `p="8"` | `p="10"` | スペーストークンは離散値のみ。tailwindのような4の倍数で連続するスケールではない |
-| `g="6"` | `g="5"` | 同上 |
-| `m="45"`, `m="55"` | `m="40"` or `m="50"` | `40` 以降の中間値は用意されていない（前半は `5/15/25/35` まで補完済み） |
-| `m="100"` | `m="80"` | 上限は `80`（ユーザーが追加定義している可能性はある） |
-
-### フォントサイズ（`fz`）
-
-| NG | OK | 理由 |
-|---|---|---|
-| `fz="14"` | `fz="s"` | `fz` は文字列キー（数値は不可） |
-| `fz="large"`, `fz="md"`  | `fz="l"` | 略号は `2xs` / `xs` / `s` / `m` / `l` / `xl` / `2xl` … |
-
-
-### 角丸 / 影
-
-| NG | OK | 理由 |
-|---|---|---|
-| `bdrs="sm"`, `bdrs="round"` | `bdrs="20"`, `bdrs="99"` | 角丸トークンは `10` / `20` / `30` / `40` / `99` / `inner` |
-| `bxsh="xs"`, `bxsh="sm"` | `bxsh="10"`, `bxsh="20"` | shadowトークンは `10` / `20` / `30` / `40` / `50` |
-
-### プリセット外の値を Lism Props に渡している
-
-Lism Props では、props.ts で事前定義されたものが `-{prop}:{value}` クラスとして出力される。それ以外の値はそのまま出力されてCSSとして無効になる。
-
-```JSX
-// NG: 事前定義されたトークン値に合致しないため、-lts:2xl は出力されない
-<Text lts="2xl">...</Text>
-```
-
-独自にProperty Classを拡張したりトークン値を増やしたりする場合は、 [property-class.md の `:value` 記法](./property-class.md)を活用するか、[`lism.config.js`による拡張](./customize.md)が必要。
+### 構造・レイアウト・レスポンシブ系（antipatterns-layout.md）
+
+- [レイアウト選択ミス](./antipatterns-layout.md#レイアウト選択ミス)
+- [Astro/React Primitive を使わず素の HTML で組む](./antipatterns-layout.md#astroreact-primitive-を使わず素の-html-で組む)
+- [ボタン装飾を reset から自作する](./antipatterns-layout.md#ボタン装飾を-reset-から自作する)
+- [`Frame` 未使用のメディア枠手組み](./antipatterns-layout.md#frame-未使用のメディア枠手組み)
+- [全面リンクの手組み（`BoxLink` 未使用）](./antipatterns-layout.md#全面リンクの手組みboxlink-未使用)
+- [primitive 既定値の重複指定](./antipatterns-layout.md#primitive-既定値の重複指定)
+- [サイト最外殻を `Wrapper` に使う](./antipatterns-layout.md#サイト最外殻を-wrapper-に使う)
+- [row 方向の `Flex` / `Cluster` 直下に `Wrapper` を置く](./antipatterns-layout.md#row-方向の-flex--cluster-直下に-wrapper-を置く)
+- [セクション外殻を `Flex` + `min-h` で組む](./antipatterns-layout.md#セクション外殻を-flex--min-h-で組む)
+- [標準 HTML 属性を `exProps` に入れる](./antipatterns-layout.md#標準-html-属性を-exprops-に入れる)
+- [レスポンシブ抜け](./antipatterns-layout.md#レスポンシブ抜け)
+- [レスポンシブ配列の冗長指定](./antipatterns-layout.md#レスポンシブ配列の冗長指定)
+- [`is--` の誤用（状態・バリエーション）](./antipatterns-layout.md#is---の誤用状態バリエーション)
+- [カスタムクラスを全て `c--` にしてしまう](./antipatterns-layout.md#カスタムクラスを全て-c---にしてしまう)
+- [クラス名の命名ミス](./antipatterns-layout.md#クラス名の命名ミス)
 
 ---
 
 ## px / 固定値の直書き
 
-デザインデータ由来の px / rem / em をそのまま書くと、Lism CSS のスケール統一が崩れる。**書く前に [SKILL.md のデザインデータ取り込み時のフロー](./SKILL.md#デザインデータ取り込み時のフロー) に従い、ユーザーに「A: そのまま採用 / B: 最寄りトークンに丸める / C: トークン基準値を上書きする」を確認すること**。確認なしに固定値を採用しない。
+デザインデータ由来の px / rem / em をそのまま書くと、Lism CSS のスケール統一が崩れる。**書く前に [デザインデータ取り込みフロー](./references/authoring.md#デザインデータ取り込みフロー) に従うこと**。入力種別ごとの既定動作と、丸め/カスタムトークン化/直書き例外（A/B/C）の選択肢の定義はフロー側が正本。確認なしに固定値を採用しない。
 
 ### スペース・サイズ
 
 | NG | OK | 理由 |
-|---|---|---|
+| --- | --- | --- |
 | `padding: 3px 10px` | `padding: var(--s5) var(--s10)` または Props で `py="5" px="10"` | `3px` はトークン外。最寄りは `--s5`(4px) |
 | `min-width: 28px; height: 28px` | `min-w` / `h` をトークン値に丸める、または基準値を上書き | `28px` はトークン外 |
 | `gap: var(--s5); padding: var(--s10) var(--s15)` を CSS で直書き | `<Lism g="5" py="10" px="15">` | Property Class / Props で書ける |
@@ -90,17 +52,25 @@ Lism Props では、props.ts で事前定義されたものが `-{prop}:{value}`
 ### 角丸・ボーダー
 
 | NG | OK | 理由 |
-|---|---|---|
+| --- | --- | --- |
 | `border-radius: 2px` | `border-radius: var(--bdrs--10)`（4px） | 角丸トークンの最小は `--bdrs--10`（4px）。`2px` はトークン外 |
 | `border-radius: 6px` | `--bdrs--10`（4px）か `--bdrs--20`（8px）に丸める | 6px はトークン外 |
 
 ### タイポグラフィ
 
 | NG | OK | 理由 |
-|---|---|---|
+| --- | --- | --- |
 | `font-size: 13px` を直書き | `font-size: var(--fz--xs)` または Props で `fz="xs"` | フォントサイズは調和数列スケール。固定値は避ける |
 | `letter-spacing: 0.02 / 0.12 / 0.14 / 0.18 / 0.2 / 0.24em` を散在 | `--lts--s/-l/-xl` を使う、または独自の `--lts--*` を `global.css` で追加 | デフォルトの `lts` トークンは `s/l/xl` のみ。多種混在はデザイントークンとして不健全 |
 
+### 実測pxの包括例外化（例外の自作）
+
+「正確に再現して」等のユーザー指示を根拠に「ページ固有の実測値として採用」のような例外カテゴリを自作し、実測pxを一括採用してはいけない。`✅例外`にできるのは下記「直書きしてよい例外」に該当する場合だけで、ユーザー指示や実測値であることは根拠にならない。
+
+| NG | OK | 理由 |
+| --- | --- | --- |
+| 実装プランに「『正確に再現』に基づくページ固有実測値として採用」と書き、実測pxを一括直書きして自分で✅ | 入力が画像のみなら最寄りトークンへ丸める（丸め先は`tokens.md`で照合）。px固定が必要と判断したら、その方針自体を⏸にする | 例外の許可リストに新カテゴリを自作しない。包括免除は値照合そのものを消す |
+
 ### 直書きしてよい例外
 
 - 1px / -1px の罫線・視覚補正（border / margin の打ち消し）
@@ -114,93 +84,112 @@ Lism Props では、props.ts で事前定義されたものが `-{prop}:{value}`
 `c--*` を定義したくなったら、まず宣言ごとに Property Class へ落とせるか確認する。落とせる宣言を CSS に書くと、CSS が肥大化し、Property Class の利点（差分上書きの容易さ・読みやすさ）が失われる。
 
 | NG（CSS 直書き） | OK（Property Class） |
-|---|---|
+| --- | --- |
 | `.c--tag { font-size: var(--fz--xs); padding: var(--s10); background: var(--base-2); border-radius: var(--bdrs--10); }` | `<span class="c--tag -fz:xs -p:10 -bgc:base-2 -bdrs:10">` |
 | `.c--eyebrow { font-size: var(--fz--2xs); color: var(--text-2); text-transform: uppercase; }` | `<span class="c--eyebrow -fz:2xs -c:text-2 -tt:uppercase">` |
 
-
 CSS に残すのは、基本的には　`::before` / `> li` などの「Primitive / Trait / Property Class で書けないセレクタ」を伴う宣言。単一要素への装飾束は呼び出し側マークアップに移す。
 
-なお、**CSS が空になっても `c--*` クラス名はマークアップに残して構わない**（むしろ推奨）。コンポーネントとしての役割をソースから読み取りやすくする目的で、意味づけ用に付けたままにする。
-
+なお、CSS が空になっても `c--*` クラス名は意味名としてマークアップに残して構わない（→ [css-rules.md の作成例](./css-rules.md#作成例)）。
 
 ---
 
-## `is--` の誤用（状態・バリエーション）
+## Token typo（存在しない値）
+
+Lism CSS側が用意しているトークン値と異なるものを書かないように注意する。  
+正確な一覧は [tokens.md](./tokens.md) を参照すること。
+
+ただし、ユーザーが独自に追加定義することは可能。あくまでデフォルトで用意されていないもので間違えやすいものを紹介しておく。
+
+### カラー
+
+| NG | OK | 理由 |
+| --- | --- | --- |
+| `bgc="primary"` | `bgc="brand"` | セマンティックカラーに `primary`/`secondary` は無い。ブランド色は `brand`/`accent` |
+| `bgc="secondary"` | `bgc="base-2"` | サブ背景色は `base-2`（`base-3` がユーザーによって追加定義されている可能性もある） |
+| `c="muted"` | `c="text-2"` | 補助テキスト色は `text-2` |
+| `c="danger"` | `c="red"` | パレットカラーから選ぶ（`red` / `orange` 等） |
+
+- セマンティックカラー: `base` / `base-2` / `text` / `text-2` / `divider` / `link` / `brand` / `accent` / `neutral`
+- パレットカラー: `red` / `blue` / `green` / `yellow` / `purple` / `orange` / `pink` / `gray` / `white` / `black`
 
-Lism CSS の `is--` プレフィックスは「**〜である**」という**役割・存在の宣言**を表す trait 用（`is--container` / `is--wrapper` / `is--layer` / `is--boxLink` / `is--coverLink` / `is--skipFlow` / `is--side` 等）。ユーザーが独自に `is--*` を追加することは可能だが、**その要素の役割（trait）を宣言するもの**であることが条件で、**状態管理やスタイルバリエーション目的に流用しない**（`is--active` / `is--current` / `is--solid` などは誤用）。
+### スペース（`p` / `m` / `g` 等）
 
-→ 詳細: [trait-class.md](./trait-class.md#is-trait役割宣言)
+スペーストークンの数値は**離散的**で、`5/10/15/20/25/30/35/40/50/60/70/80` のみが用意されている。`8/12/14/45/65/75` 等を書きそうになったら、必ず最寄りトークンに丸めるか、ユーザーに方針確認すること（→ [デザインデータ取り込みフロー](./references/authoring.md#デザインデータ取り込みフロー)）。
 
-`is--` と紛れがちな 2 つの用途は、Lism では別の手段で表現する：
+| NG | OK | 理由 |
+| --- | --- | --- |
+| `p="8"` | `p="10"` | スペーストークンは離散値のみ。tailwindのような4の倍数で連続するスケールではない |
+| `g="6"` | `g="5"` | 同上 |
+| `m="45"`, `m="55"` | `m="40"` or `m="50"` | `40` 以降の中間値は用意されていない（前半は `5/15/25/35` まで補完済み） |
+| `m="100"` | `m="80"` | 上限は `80`（ユーザーが追加定義している可能性はある） |
 
-### 1. 状態管理 → `data-*` 属性を使う
+### フォントサイズ（`fz`）
 
-オン/オフが切り替わる状態（active / current / disabled / open / selected 等）は、`is--*` クラスを増やさず HTML の `data-*` 属性で表現する。CSS は属性セレクタで書く。
+| NG | OK | 理由 |
+| --- | --- | --- |
+| `fz="14"` | `fz="s"` | `fz` は文字列キー（数値は不可） |
+| `fz="large"`, `fz="md"` | `fz="l"` | 略号は `2xs` / `xs` / `s` / `m` / `l` / `xl` / `2xl` … |
 
-| NG | OK |
-|---|---|
-| `<a class="c--catTab is--active">` + `.c--catTab.is--active { ... }` | `<a class="c--catTab" data-is-active>` + `.c--catTab[data-is-active] { ... }` |
-| `<li class="c--pager_num is--current">` + `.c--pager_num.is--current { ... }` | `<li class="c--pager_num" aria-current="page">` + `.c--pager_num[aria-current] { ... }` |
-| `<a class="c--pager_nav is--disabled">` + `.c--pager_nav.is--disabled { ... }` | `<a class="c--pager_nav" data-is-disabled>` + `.c--pager_nav[data-is-disabled] { ... }` |
+### 角丸 / 影
 
-理由：
+| NG | OK | 理由 |
+| --- | --- | --- |
+| `bdrs="sm"`, `bdrs="round"` | `bdrs="20"`, `bdrs="99"` | 角丸トークンは `10` / `20` / `30` / `40` / `99` / `inner` |
+| `bxsh="xs"`, `bxsh="sm"` | `bxsh="10"`, `bxsh="20"` | shadowトークンは `10` / `20` / `30` / `40` / `50` |
+
+### プリセット外の値を Lism Props に渡している
+
+Lism Props では、props.ts で事前定義されたものが `-{prop}:{value}` クラスとして出力される。それ以外の値はそのまま出力されてCSSとして無効になる。
+
+```JSX
+// NG: 事前定義されたトークン値に合致しないため、-lts:2xl は出力されない
+<Text lts="2xl">...</Text>
+```
 
-- `is--*` は「役割宣言」用の trait であり、状態を表すクラスを `is--*` として増やすと意味体系（trait か state か）が混在して読みにくくなる
-- `data-*` は HTML 標準の状態表現で、JS からの切替（`element.dataset.isActive = ''` / `delete element.dataset.isActive`）も自然
-- ARIA 属性で意味が表せる場合（`aria-current` / `aria-disabled` / `aria-selected` 等）は ARIA を優先し、その属性自体を CSS セレクタにする
+独自にProperty Classを拡張したりトークン値を増やしたりする場合は、 [property-class.md の `:value` 記法](./property-class.md)を活用するか、[`lism.config.js`による拡張](./customize.md)が必要。
 
-### 2. スタイルバリエーション → BEM Modifier `c--{name}--{variant}`
+---
 
-「同じコンポーネントの見た目違い」は、Lism CSS 公式の BEM Modifier 記法で表現する（→ [css-rules.md の Component Class](./css-rules.md#component-classc--)）。
+## `c--*` CSS を `@layer lism-component` に入れない
+
+`.c--*`のCSSは基本的に`@layer lism-component`内に置く。Astroの`<style>`内でも同じ。Layer外に置くと、Lism内部レイヤーやProperty Classとの優先順位設計が崩れる。
 
 | NG | OK |
-|---|---|
-| `<span class="c--tag is--solid">` + `.c--tag.is--solid { ... }` | `<span class="c--tag c--tag--solid">` + `.c--tag.c--tag--solid { ... }` |
-| `<button class="c--button is--outline">` | `<button class="c--button c--button--outline">` |
+| --- | --- |
+| `.c--hero { padding: var(--s40); }` | `@layer lism-component { .c--hero::before { ... } }` |
+| `<style>.c--card { ... }</style>` | `<style>@layer lism-component { .c--card { ... } }</style>` |
 
-なお、Modifier であってもまずは [Property Class で表現できないか](#property-class-で書けるのに-css-で書く) を検討すること。「色だけ違う」程度ならマークアップ側で `-bgc:* -c:*` を差し替えるだけで済むことも多い。
+ただし、`padding`/`gap`/`font-size`/`color`などProps/Property Classへ移せる宣言は、Layerへ入れる前にマークアップ側へ移す。  
+また、詳細度の関係で`@layer`の外で書く必要がある場合は外に出してよい。
 
 ---
 
-## カスタムクラスを全て `c--` にしてしまう
-
-`c--` は「**コンポーネント**（再利用可能な UI 部品）」を表すプレフィックス。**カスタムクラスを必ず `c--` で命名する必要はない**。サイトの大まかな領域（header / sidebar / main / footer 等）やページ固有のスタイルなど、再利用が前提でないクラスは、独自プレフィックス（`z--` / `p--` 等）やプレフィックスなしの命名も選択肢として検討すること。
+## hover を component CSS に書いて負ける
 
-→ 詳細: [css-rules.md の独自プレフィックス](./css-rules.md#独自プレフィックス)
+hover効果は`-hov:*`、`hov={{}}`、`set--hov`、`has--transition`を優先する。component CSSの`:hover`へ単純な色・影・transformを直接書くと、Property Classやhover変数の設計と競合しやすい。
 
-| 用途 | 命名の例 | 配置レイヤー |
-|---|---|---|
-| 再利用可能な UI 部品 | `c--button` / `c--card` / `c--tag` | `@layer lism-component` |
-| サイトのゾーニング | `z--header` / `z--sidebar` / `z--articleBody`（または `header` / `sidebar` / `articleBody`） | `@layer lism-custom` |
-| ページ固有のスタイル | `p--front` / `p--post`（または `frontPage` / `postPage`） | `@layer lism-custom` |
+| NG | OK | 理由 |
+| --- | --- | --- |
+| `.c--button:hover { box-shadow: var(--bxsh--20); }` | `<Button hov={{ bxsh: '20' }} hasTransition>` | hover用Property Classを使う |
+| `.c--card:hover { background: var(--base-2); }` | `<Box hov={{ bgc: 'base-2' }} hasTransition>` | hover時の値はPropsで宣言できる |
+| `.c--link:hover { --keycolor: var(--brand); }` | `set--hov`や`hov={{ ... }}`を検討 | hover変数の仕組みに寄せる |
 
-`c--header` のような命名も間違いとまでは言えないが、「カスタムクラス＝必ず `c--`」ではないことに注意する。
+擬似要素や複雑な子孫セレクタが必要なhoverだけCSSに残す。
 
 ---
 
-## クラス名の命名ミス（kebab-case）
-
-Lism CSS では、プレフィックス（`c--` / `is--` / `has--` / `u--` / `set--` 等）に続く名称は **camelCase** で書くのが規約。kebab-case で書くと、BEM の Modifier 区切り（`--`）と視覚的に紛れて読みにくくなる。
+## Reset 済みプロパティの再指定
 
-→ 詳細: [naming.md](./naming.md#クラス名)
+Lism CSSのreset/base styleで既に初期化されている値を、念のために再指定しない。特に`margin:0`系はHTML要素側で処理済みなので、意図的な差分が無い限り追加しない。
 
 | NG | OK | 理由 |
-|---|---|---|
-| `c--my-card` | `c--myCard` | プレフィックス後の名称は camelCase |
-| `c--my-card--primary` | `c--myCard--primary` | Modifier 区切り `--` と単語区切り `-` が混在して読みにくい |
-| `c--card_my-elem` | `c--card_myElem` | Element 名（`_` 後）も camelCase |
-| `is--side-bar` / `has--gutter-x` | `is--sideBar` / `has--gutterX` | `is--` / `has--` / `u--` 等にも同じ規則が適用される |
+| --- | --- | --- |
+| `<p class="-m:0">` | `<p>` | resetで`margin:0`済み。不要なProperty Classがノイズになる |
+| `<Heading m="0">` | `<Heading>` | 見出しmarginもbase側の前提を確認し、同値なら書かない |
+| `.c--body { margin: 0; }` | `.c--body {}`または削除 | reset済みの宣言をcomponent CSSへ再掲しない |
 
-```jsx
-// NG: kebab-case
-<Stack className="c--feature-card" />
-<div className="c--user-profile c--user-profile--compact" />
-
-// OK: camelCase
-<Stack className="c--featureCard" />
-<div className="c--userProfile c--userProfile--compact" />
-```
+例外として、特定の外部CSS配下・埋め込みHTML・resetが効かない隔離領域で打ち消しが必要な場合は、理由を残して指定する。
 
 ---
 
@@ -211,13 +200,13 @@ Lism CSS では、プレフィックス（`c--` / `is--` / `has--` / `u--` / `se
 ### `:root` でのグローバル上書き
 
 | NG | OK | 理由 |
-|---|---|---|
+| --- | --- | --- |
 | `:root { --keycolor: #c8553d; }` | `:root { --brand: #c8553d; }`（または `--accent` / `--link`） | サイト共通の色は `--brand` / `--accent` / `--link` などのセマンティックカラーで定義する |
 
 ### アクセントカラーとしての `keycolor` 参照
 
 | NG | OK | 理由 |
-|---|---|---|
+| --- | --- | --- |
 | `<Link c="keycolor">` | `<Link c="brand">` または `<Link c="link">` | リンク・hover などの恒常的なアクセントは `brand` / `link` を使う |
 | `hov={{ c: 'keycolor' }}` | `hov={{ c: 'brand' }}` | 同上 |
 | `border-inline-start: 3px solid var(--keycolor)`（CSS 直書き） | `border-inline-start: 3px solid var(--brand)` | 同上 |
@@ -239,7 +228,7 @@ Lism CSS では、プレフィックス（`c--` / `is--` / `has--` / `u--` / `se
 </Lism>
 ```
 
-詳細: [tokens.md のキーカラー変数セクション](./tokens.md#キーカラー変数-keycolor)
+詳細: [tokens.md のキーカラー変数セクション](./tokens.md#キーカラー変数---keycolor)
 
 ---
 
@@ -248,88 +237,21 @@ Lism CSS では、プレフィックス（`c--` / `is--` / `has--` / `u--` / `se
 ### Heading の `level` は文字列
 
 | NG | OK | 理由 |
-|---|---|---|
+| --- | --- | --- |
 | `<Heading level={3}>` | `<Heading level="3">` | `level` は `'1'` 〜 `'6'` の文字列 union 型 |
 
 ### レスポンシブ値は配列 or オブジェクト
 
 | NG | OK | 理由 |
-|---|---|---|
+| --- | --- | --- |
 | `<Columns cols="1,2,3">` | `<Columns cols={[1, 2, 3]}>` | レスポンシブは配列 |
 | `<Box p="20 30 40">` | `<Box p={[20, 30, 40]}>` | 同上 |
 
----
-
-## レイアウト選択ミス
-
-詳細な選択基準は [primitive-class.md](./primitive-class.md#カラムレイアウト-primitive-の使い分けガイド) の使い分けガイドを参照。
-
-### Grid 直書き vs Columns
-
-| NG | OK | 理由 |
-|---|---|---|
-| `<Grid gtc="repeat(3, 1fr)">` | `<Columns cols={3}>` | 等幅 N 列は Columns で宣言的に書く |
-| `<Grid gtc={['1fr', '1fr 1fr', '1fr 1fr 1fr']}>` | `<Columns cols={[1, 2, 3]}>` | BP 切替も Columns のほうが簡潔 |
-
-### コンテンツ幅のハードコード
-
-| NG | OK | 理由 |
-|---|---|---|
-| `style={{ maxWidth: '1200px' }}` | `<Box max-sz="l">` | ヘッダーやセクションなど、コンテンツサイズにはトークン値（`xs` / `s` / `m` / `l` / `xl` / `bleed`）をできるだけ活用する |
+### BP 非対応 Prop への配列指定
 
-### サイドバー型レイアウト
+レスポンシブ配列を渡せるのは BP 対応の Prop だけ。BP 対応可否は [all-props.md](./property-class/all-props.md) の BP 列で確認する。
 
 | NG | OK | 理由 |
-|---|---|---|
-| `<Grid gtc="1fr 240px">` で固定 | `<WithSide sideW="240px">` | コンテンツ幅で自動切替したいなら WithSide |
-| `<Flex>` で 2 カラム強制横並び | `<WithSide>` | 縦並びへの切替が必要なら WithSide |
-
----
-
-## レスポンシブ抜け
-
-### `is--container` 祖先なしで BP 値を使用
-
-レスポンシブ値（配列・オブジェクト・`-{prop}_{bp}` クラス）は、デフォルト設定（SCSS 側 `$is_container_query: 1`）では `@container` クエリで発火するため、祖先要素のいずれかに `is--container`（コンポーネントなら `isContainer` prop）が必須。
-
-※ プロジェクトの SCSS 設定で `$is_container_query: 0` にして `@media` クエリ運用に切り替えている場合は、`is--container` 祖先は不要。
+| --- | --- | --- |
+| `<Grid cg={['40', null, '80']}>` | `<Grid g={['40', null, '80']}>` または `<Grid cg="40">` | `cg` / `rg` は BP 非対応。レスポンシブにするなら BP 対応の `g` を使うか、単一値にする |
 
-```jsx
-// NG: container 祖先がないので sm/md 値が発火しない
-<div>
-  <Box p={[20, 30, 40]}>...</Box>
-</div>
-
-// OK: 祖先に isContainer
-<Stack isContainer>
-  <Box p={[20, 30, 40]}>...</Box>
-</Stack>
-```
-
-### BP 専用クラスをベース値なしで使う
-
-BP 専用クラス（`-{prop}_{bp}`）やコンポーネントの BP キー（`{ sm: ... }` 等）だけを指定すると、BP 未満では値が空になり意図しないレイアウト崩れを起こす。必ずベース値とセットで指定する。
-
-```jsx
-// NG: sm 未満で p が未指定になる
-<Box p={{ sm: 30 }}>...</Box>
-
-// OK: ベース値（base / 配列の先頭）を必ず添える
-<Box p={{ base: 20, sm: 30 }}>...</Box>
-<Box p={[20, 30]}>...</Box>
-```
-
-生 HTML / クラス指定で書く場合も同様：
-
-| NG | OK | 理由 |
-|---|---|---|
-| `<div class="-p_sm" style="--p_sm: var(--s30)">` | `<div class="-p:20 -p_sm" style="--p_sm: var(--s30)">` | BP 未満では値が空になるため、ベースクラス `-{prop}:{value}` も必要 |
-
-### ブレイクポイントの誤用
-
-Lism CSS の標準出力で有効な BP は `sm: 480px` / `md: 800px` / `lg: 1120px`。`xs` は BP キーとして存在しない。
-
-| NG | OK | 理由 |
-|---|---|---|
-| `<Box p={{ xs: 10, sm: 20 }}>` | `<Box p={{ base: 10, sm: 20 }}>` | デフォルトは `base`（`xs` キーは無い） |
-| `cols={[1, 2, 3, 4, 5]}` | `cols={[1, 2, 3, 4]}` | 標準出力では `[base, sm, md, lg]` までが有効。`xl` 以降は SCSS 設定が必要 |

package/dist/data/guides/base-styles.md

@@ -38,13 +38,13 @@ Reset CSS に加え、`@layer lism-base` 内で HTML タグに基本スタイル
 ### 全要素の行間
 
 | 変数 | 用途 |
-|------|------|
+| --- | --- |
 | `--hl` | half-leading（行間の上下余白量）。`line-height: calc(1em + var(--hl) * 2)` として全要素に適用 |
 
 ### body
 
 | 変数 | 用途 |
-|------|------|
+| --- | --- |
 | `--fz--base` | ベースフォントサイズ |
 | `--ff--base` | ベースフォントファミリー |
 | `--lts--base` | ベース字間 |
@@ -56,7 +56,7 @@ Reset CSS に加え、`@layer lism-base` 内で HTML タグに基本スタイル
 ### 見出し（h1〜h6）
 
 | 変数 | 用途 |
-|------|------|
+| --- | --- |
 | `--headings-ff` | 全見出し共通のフォントファミリー（デフォルト: `inherit`） |
 | `--headings-fw` | 全見出し共通のフォントウェイト（デフォルト: `var(--fw--bold)`） |
 
@@ -65,22 +65,22 @@ Reset CSS に加え、`@layer lism-base` 内で HTML タグに基本スタイル
 ### リンク（a）
 
 | 変数 | フォールバック | 用途 |
-|------|------------|------|
+| --- | --- | --- |
 | `--link-c` | `var(--link)` | リンクテキスト色 |
 | `--link-td` | `underline` | テキスト装飾の種類 |
 
 ### リスト（ul, ol）
 
-class を持たない `ul` / `ol` のみブラウザ標準スタイルが自動で復活する（`_html.scss`）。Property Class のみが付いた `ul` / `ol` では list-style が消えたままになるため、箇条書き表示を維持したい場合は [`set--revert`](./set-class.md#set--revert) を付与する。
+class を持たない `ul` / `ol` のみブラウザ標準スタイルが自動で復活する（`_html.scss`）。クラス付きで箇条書き表示を維持したい場合は [`set--revert`](./set-class.md#set--revert) を付与する。
 
 | 変数 | フォールバック | 用途 |
-|------|------------|------|
+| --- | --- | --- |
 | `--list-ps` | `1.75em` | リストの `padding-inline-start` |
 
 ### テーブル（td, th）
 
 | 変数 | フォールバック | 用途 |
-|------|------------|------|
+| --- | --- | --- |
 | `--cells-p` | `0.625em 0.875em` | セルのパディング |
 
 `td` と `th` の両方に `--cells-p` が適用される。色や最小幅などのカスタマイズは必要な要素にスタイルを直接当てる。
@@ -88,7 +88,7 @@ class を持たない `ul` / `ol` のみブラウザ標準スタイルが自動
 ### フォーム要素
 
 | 変数 | フォールバック | 用途 |
-|------|------------|------|
+| --- | --- | --- |
 | `--controls-bgc` | `var(--base-2)` | 背景色 |
 | `--controls-bdc` | `var(--divider)` | ボーダー色 |
 | `--controls-p` | `0.25em 0.5em` | パディング |
@@ -98,5 +98,6 @@ class を持たない `ul` / `ol` のみブラウザ標準スタイルが自動
 ### その他
 
 | 変数 | 対象 | 用途 |
-|------|------|------|
+| --- | --- | --- |
 | `--focus-offset` | `:focus-visible` | アウトラインのオフセット（デフォルト: `0px`） |
+| `--o--pp` | `:disabled` | 無効状態の不透明度（デフォルト: `0.5`） |

package/dist/data/guides/components-core.md

@@ -19,6 +19,7 @@ import { Lism, Box, Flex, Stack, Grid, Text, Media } from 'lism-css/astro';
 - [Trait Components](#trait-components)
 - [Layout Primitives](#layout-primitives)
 - [`getLismProps()`](#getlismprops--外部コンポーネントとの連携)
+- [AstroでのラップコンポーネントのProps型](#astroでのラップコンポーネントのprops型)
 
 [詳細](https://lism-css.com/docs/core-components/lism-props.md)
 
@@ -49,7 +50,7 @@ import { Lism, Box, Flex, Stack, Grid, Text, Media } from 'lism-css/astro';
 すべての Lism コンポーネントで使えるpropsです。
 
 | Prop | 説明 | 例 |
-|------|------|-----|
+| --- | --- | --- |
 | `as` | レンダリングする HTML 要素または外部コンポーネントを指定（デフォルト: `"div"`） | `as="section"`, `as={Image}` |
 | `layout` | レイアウトプリミティブ（`l--{layout}`）を指定 | `layout="flow"` |
 | `atomic` | アトミックプリミティブ（`a--{atomic}`）を指定。`'divider'` / `'spacer'` / `'decorator'` が利用可能（`'icon'` は内部用） | `atomic="divider"` |
@@ -109,14 +110,14 @@ import { Lism, Box, Flex, Stack, Grid, Text, Media } from 'lism-css/astro';
 `prop={value}`で指定した値(`value`)によって、基本的な出力は以下のように分類されます。
 
 | 値 | 出力形式 | 例 |
-|------|------|-----|
+| --- | --- | --- |
 | トークン値・プリセット値 | `-{prop}:{value}` クラスのみ | `fz='l'` → `class="-fz:l"` |
 | `true` | `-{prop}` クラスのみ（変数なし） | `bd` / `bd={true}` → `class="-bd"` |
 | `:` で始まる値 | 強制的にクラス化 | `p=':hoge'` → `class="-p:hoge"` |
 | その他の値（レスポンシブ対応プロパティ） | `-{prop}` + `--{prop}` | `fz='20px'` → `class="-fz"` + `style="--fz:20px"` |
 | その他の値（レスポンシブ非対応プロパティ） | `style` 属性に直接出力 | `o='0.7'` → `style="opacity:0.7"` |
 | その他の値（変数プロパティ） | `--{prop}` | `bdw='2px'` → `style="--bdw:2px"` (`border-width`としては出力されない) |
-| レスポンシブ指定値 | 上記いずれかのベース出力 + `-{prop}_{bp}` + `--{prop}_{bp}` | `p={[10,20]}` → `class="-p:10 -p_sm"` + `style="--p_sm:var(--s20)"`|
+| レスポンシブ指定値 | 上記いずれかのベース出力 + `-{prop}_{bp}` + `--{prop}_{bp}` | `p={[10,20]}` → `class="-p:10 -p_sm"` + `style="--p_sm:var(--s20)"` |
 
 補足:
 - **レスポンシブ対応プロパティ**かどうかは、 `props.ts`で`bp: 1`がセットされているかどうかで分かります。
@@ -178,7 +179,7 @@ import { Lism, Box, Flex, Stack, Grid, Text, Media } from 'lism-css/astro';
 Trait クラス（`is--*` / `has--*`）を出力するためのプロパティ群です。
 
 | Prop | 出力クラス |
-|------|-----------|
+| --- | --- |
 | `isWrapper` | `is--wrapper` |
 | `isWrapper="{s\|m\|l\|xl}"` | `is--wrapper` + `-contentSize:{s\|m\|l\|xl}` |
 | `isWrapper="{value}"` | `is--wrapper` + `-contentSize` + `--contentSize:{value}` |
@@ -208,7 +209,7 @@ Trait クラス（`is--*` / `has--*`）を出力するためのプロパティ
 `Lism` の `as` エイリアスとして機能するコンポーネント群です。layout クラスは付与されず、HTML のセマンティクスを表現するために使います。
 
 | コンポーネント | デフォルト要素 | 許容タグ |
-|-------------|-------------|---------|
+| --- | --- | --- |
 | `<Text>` | `<p>` | `p`, `div`, `blockquote`, `address`, `figcaption`, `pre` |
 | `<Heading>` | `<h2>` | `h1`〜`h6`（`level` prop で指定） |
 | `<Inline>` | `<span>` | `span`, `em`, `strong`, `small`, `code`, `time`, `i`, `b`, `mark`, `abbr`, `cite`, `kbd`, `label` |
@@ -232,7 +233,7 @@ Trait クラス（`is--*` / `has--*`）を出力するためのプロパティ
 ## Atomic Primitives
 
 | コンポーネント | 出力クラス | 用途 |
-|-------------|-----------|------|
+| --- | --- | --- |
 | `<Icon>` | `a--icon` | SVG アイコン・アイコンフォント |
 | `<Spacer>` | `a--spacer` | 空白要素 |
 | `<Divider>` | `a--divider` | 区切り線 |
@@ -247,7 +248,7 @@ Trait クラス（`is--*` / `has--*`）を出力するためのプロパティ
 `<Lism isXxx>`のエイリアスコンポーネントです。`is--*` クラスを出力します。
 
 | コンポーネント | 内部処理 | 出力クラス |
-|-------------|------------|-----------|
+| --- | --- | --- |
 | `<Container>` | `isContainer` | `is--container` |
 | `<Wrapper>` | `isWrapper` | `is--wrapper` |
 | `<Layer>` | `isLayer` | `is--layer` |
@@ -261,7 +262,7 @@ Trait クラス（`is--*` / `has--*`）を出力するためのプロパティ
 内部で `layout` prop が固定されており、対応する `l--{layout}` クラスが自動で出力されます。各コンポーネントの専用 Props（`cols`, `rows`, `breakSize`, `sideW`/`mainW`, `flow` など）は、それぞれの詳細ファイルを参照してください。
 
 | コンポーネント | 出力クラス |
-|-------------|-----------|
+| --- | --- |
 | `<Box>` | `l--box` |
 | `<Flex>` | `l--flex` |
 | `<Stack>` | `l--stack` |
@@ -293,3 +294,20 @@ function MyComponent({ children }) {
   return <div {...lismProps}>{children}</div>;
 }
 ```
+
+## AstroでのラップコンポーネントのProps型
+
+Astroで`<Lism>`をラップする独自コンポーネントのProps型は、`interface extends`ではなく交差型（`&`）で合成する。`Lism`のProps型は`layout`による discriminated union を含むため、`interface extends`はTSエラーになる。
+
+```ts
+import { Lism } from 'lism-css/astro';
+import type { ComponentProps } from 'astro/types';
+
+type LismProps = ComponentProps<typeof Lism>;
+
+// NG: interface Props extends LismProps { class?: string } → TSエラー
+// OK: 交差型で合成
+type Props = LismProps & { class?: string };
+```
+
+この制約は`<Lism>`に限らず、`<Text>`や`<Wrapper>`など layout Prop を受け取れるコンポーネント全般に共通する。`<Cluster>`など layout 固定のレイアウトコンポーネントのみ union を含まず`interface extends`も通るが、交差型に統一する。