@lism-css/mcp 0.22.0 → 0.24.0

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

@@ -48,8 +48,9 @@ import { Button } from '@lism-css/ui/astro/Button';
 **構造:** `Accordion.Root > Accordion.Item > (Accordion.Heading > Accordion.Button) + Accordion.Panel`（`Accordion.Icon` は自動で含まれる）
 
 | Prop | 対象 | 型 | デフォルト | 説明 |
-|------|------|-----|----------|------|
+| --- | --- | --- | --- | --- |
 | `allowMultiple` | Root | `boolean` | — | 複数アイテムの同時展開を許可 |
+| `isOpen` | Item / Button / Panel | `boolean` | `false` | アイテムを初期展開。Item・Button・Panel の3つ揃えて指定（Item=`data-opened` 付与、Button=`aria-expanded`、Panel=`hidden` 解除） |
 | `as` | Heading | `string` | `div` | 見出しのHTMLタグ。`div` 時は `role='heading'` が自動付与。`h2`〜`h6` 指定時は role なし |
 | `flow` | Panel | `string` | — | パネル内コンテンツ領域（`c--accordion_content`）のフロー余白 |
 
@@ -70,10 +71,11 @@ import { Button } from '@lism-css/ui/astro/Button';
 ソース: [Alert/](https://github.com/lism-css/lism-css/tree/main/packages/lism-ui/src/components/Alert)
 
 短めの文言を目立たせて強調表示するアラートボックス。`type` プリセットによりアイコンとカラーが自動設定される。
+プリセット: `alert`=alert/red, `point`=lightbulb/orange（`tip`も同じ）, `warning`=warning/yellow, `check`=check-circle/green, `help`=question/purple, `info`=info/blue, `note`=note/gray。
 
 | Prop | 型 | デフォルト | 説明 |
-|------|-----|----------|------|
-| `type` | `'alert' \| 'point' \| 'warning' \| 'check' \| 'help' \| 'info'` | `'alert'` | アラートタイプ。keycolor と icon の組み合わせプリセット |
+| --- | --- | --- | --- |
+| `type` | `'alert' \| 'point' \| 'tip' \| 'warning' \| 'check' \| 'help' \| 'info' \| 'note'` | `'alert'` | アラートタイプ。keycolor と icon の組み合わせプリセット |
 | `keycolor` | `string` | — | キーカラー |
 | `icon` | `ReactNode \| string` | — | カスタムアイコン |
 | `layout` | `'flex' \| 'withSide'` | `'flex'` | レイアウトプリミティブ |
@@ -91,7 +93,7 @@ import { Button } from '@lism-css/ui/astro/Button';
 アバター（プロフィール画像）コンポーネント。Frame ベースの円形画像表示。`c--avatar` クラスが付与される。
 
 | Prop | 型 | デフォルト | 説明 |
-|------|-----|----------|------|
+| --- | --- | --- | --- |
 | `src` | `string` | — | 画像URL |
 | `alt` | `string` | — | 代替テキスト |
 | `size` | `string` | `'1.5em'` | アバターのサイズ |
@@ -108,7 +110,7 @@ import { Button } from '@lism-css/ui/astro/Button';
 バッジ（ラベル）コンポーネント。`span` 要素としてインライン表示。`c--badge` クラスが付与される。
 
 | Prop | 型 | デフォルト | 説明 |
-|------|-----|----------|------|
+| --- | --- | --- | --- |
 | `variant` | `string` | — | バリエーション（`'outline'` 等）。`c--badge--{variant}` クラスが出力 |
 | `keycolor` | `string` | — | キーカラー |
 
@@ -124,7 +126,7 @@ import { Button } from '@lism-css/ui/astro/Button';
 ボタン型リンクコンポーネント。デフォルトで `a` 要素として出力。`c--button` クラスが付与される。
 
 | Prop | 型 | デフォルト | 説明 |
-|------|-----|----------|------|
+| --- | --- | --- | --- |
 | `variant` | `string` | — | バリエーション（`'fill'`, `'outline'` 等）。`c--button--{variant}` クラスが出力 |
 | `keycolor` | `string` | — | キーカラー |
 | `href` | `string` | — | リンク先URL |
@@ -138,18 +140,18 @@ import { Button } from '@lism-css/ui/astro/Button';
 
 ソース: [Callout/](https://github.com/lism-css/lism-css/tree/main/packages/lism-ui/src/components/Callout)
 
-記事中の重要ポイントを示すコンポーネント。タイトルとアイコン付きの強調ボックス。`type` プリセットによりアイコンとカラーが自動設定される。
+記事中の重要ポイントを示すコンポーネント。タイトルとアイコン付きの強調ボックス。`type` プリセットによりアイコンとカラーが自動設定される（プリセット内容は [Alert](#alert) と同一）。
 
 | Prop | 型 | デフォルト | 説明 |
-|------|-----|----------|------|
-| `type` | `'note' \| 'alert' \| 'point' \| 'warning' \| 'check' \| 'help'` | `'note'` | コールアウトタイプ |
+| --- | --- | --- | --- |
+| `type` | `'alert' \| 'point' \| 'tip' \| 'warning' \| 'check' \| 'help' \| 'info' \| 'note'` | `'note'` | コールアウトタイプ |
 | `keycolor` | `string` | — | キーカラー |
 | `icon` | `ReactNode \| string` | — | カスタムアイコン |
 | `title` | `string` | — | タイトルテキスト |
 | `flow` | `string` | `'s'` | コンテンツ部分のフロー余白 |
 
 ```jsx
-<Callout type='note' title='Important' keycolor='blue'>Important note</Callout>
+<Callout type='note' title='Note'>Supplemental note</Callout>
 ```
 
 
@@ -160,7 +162,7 @@ import { Button } from '@lism-css/ui/astro/Button';
 チャット風の吹き出しコンポーネント。Grid ベースの会話形式 UI。`c--chat` クラスが付与される。
 
 | Prop | 型 | デフォルト | 説明 |
-|------|-----|----------|------|
+| --- | --- | --- | --- |
 | `name` | `string` | — | 発言者の名前 |
 | `avatar` | `string` | — | アバター画像の src |
 | `variant` | `'speak' \| 'think'` | `'speak'` | チャットタイプ |
@@ -182,8 +184,9 @@ HTML の `details/summary` 要素をラップしたコンポーネント。Accor
 **構造:** `Details.Root > Details.Summary > (Details.Title + Details.Icon) + Details.Content`
 
 | Prop | 対象 | 型 | デフォルト | 説明 |
-|------|------|-----|----------|------|
+| --- | --- | --- | --- | --- |
 | `as` | Title | `string` | `'span'` | Title の HTML タグ |
+| `open` | Root | `boolean` | — | 初期展開状態（`details` 要素の `open` 属性） |
 | `--duration` | Root | `string` | — | 展開アニメーションの秒数（style 経由で指定） |
 
 ```jsx
@@ -206,7 +209,7 @@ HTML の `details/summary` 要素をラップしたコンポーネント。Accor
 **構造:** `Modal.OpenBtn + Modal.Root > Modal.Inner > Modal.Body + Modal.CloseBtn`
 
 | Prop | 対象 | 型 | デフォルト | 説明 |
-|------|------|-----|----------|------|
+| --- | --- | --- | --- | --- |
 | `id` | Root | `string` | — | モーダルの ID（必須） |
 | `modalId` | OpenBtn / CloseBtn | `string` | — | 対象モーダルの ID |
 | `duration` | Root | `string` | — | アニメーション持続時間。`--duration` 変数として出力 |
@@ -233,11 +236,12 @@ HTML の `details/summary` 要素をラップしたコンポーネント。Accor
 **構造:** `NavMenu.Root > NavMenu.Item > NavMenu.Link`（`NavMenu.Nest` でネスト可能）
 
 | Prop | 対象 | 型 | デフォルト | 説明 |
-|------|------|-----|----------|------|
+| --- | --- | --- | --- | --- |
 | `hovBgc` | Root | `string` | — | ホバー時の背景カラー。`--hov-bgc` 変数として出力 |
 | `hovC` | Root | `string` | — | ホバー時のテキストカラー。`--hov-c` 変数として出力 |
 | `itemP` | Root | `string` | — | 各アイテムのパディング。`--_item-p` 変数として出力 |
-| `href` | Link | `string` | — | リンク先URL。指定ありで `a` 要素、なしで `span` 要素 |
+| `href` | Link | `string` | — | リンク先URL（Link は常に `a` 要素として出力） |
+| `hov` | Link | `string` | `-bgc` | ホバー時のスタイル。デフォルトで背景色が変化 |
 
 ```jsx
 <NavMenu.Root>
@@ -260,10 +264,11 @@ HTML の `details/summary` 要素をラップしたコンポーネント。Accor
 **構造:** `Tabs.Root > Tabs.Item > (Tabs.Tab + Tabs.Panel)`（`Tabs.List` も利用可能）
 
 | Prop | 対象 | 型 | デフォルト | 説明 |
-|------|------|-----|----------|------|
+| --- | --- | --- | --- | --- |
 | `tabId` | Root | `string` | — | タブを特定するための ID 文字列 |
 | `defaultIndex` | Root | `number` | `1` | 初期アクティブタブ（1始まり） |
 | `listProps` | Root | `object` | — | タブボタンリスト要素へ渡す props |
+| `variant` | Root | `string` | — | バリエーション。`c--tabs--{variant}` クラスが出力 |
 
 ```jsx
 <Tabs.Root>
@@ -286,7 +291,7 @@ HTML の `details/summary` 要素をラップしたコンポーネント。Accor
 セクション間の波型などの装飾的な区切り要素。SVG ベースの形状で区切りを表現。
 
 | Prop | 型 | デフォルト | 説明 |
-|------|-----|----------|------|
+| --- | --- | --- | --- |
 | `viewBox` | `string` | — | SVG の viewBox |
 | `level` | `number` | `5` | シェイプの高さレベル。`0` で非表示 |
 | `flip` | `'X' \| 'Y' \| 'XY'` | — | 反転方向。`data-flip` 属性として出力 |
@@ -309,7 +314,7 @@ HTML の `details/summary` 要素をラップしたコンポーネント。Accor
 ダミーテキストを生成するコンポーネント。プレビューやテスト用。複数の言語とテキスト長に対応。
 
 | Prop | 型 | デフォルト | 説明 |
-|------|-----|----------|------|
+| --- | --- | --- | --- |
 | `lang` | `'ja' \| 'en' \| 'ar'` | `'en'` | テキストの言語 |
 | `length` | `'xs' \| 's' \| 'm' \| 'l' \| 'xl' \| 'codes'` | `'m'` | テキストの長さ。`'codes'` は `b`, `i`, `a`, `code` 要素を含むテキスト |
 | `pre` | `string` | — | テキストの前に表示する文字列 |
@@ -327,8 +332,8 @@ HTML の `details/summary` 要素をラップしたコンポーネント。Accor
 コンポーネント名は `import` するときと同じ PascalCase で指定します。
 
 ```bash
-# 初期設定（framework、出力先ディレクトリを対話的に設定）
-npx lism-cli ui init
+# 初期設定（lism.config.js が無い場合に新規生成。framework 等を対話的に設定）
+npx lism-cli init
 
 # コンポーネントを追加
 npx lism-cli ui add Button Modal
@@ -339,14 +344,13 @@ npx lism-cli ui add --all        # 全コンポーネントを追加
 npx lism-cli ui list
 ```
 
-`ui init` で生成される `lism.config.js` の `cli` セクション:
+`init` で生成される `lism.config.js` の `ui` セクション:
 
 ```js
 export default {
-  cli: {
+  ui: {
     framework: 'react',
-    componentsDir: 'src/components/ui',
-    helperDir: 'src/components/ui/_helper',
+    dir: 'src/components/ui', // helper は常に {dir}/_helper に配置される
   },
 };
 ```

package/dist/data/guides/css-rules.md

@@ -3,7 +3,7 @@
 ## TOC
 
 - [CSS Layer 構造](#css-layer-構造)
-- [プレフィックスとクラス分類](#プレフィックスとクラス分類)
+- [クラス分類とプレフィックス](#クラス分類とプレフィックス)
 - [Component Class（`c--`）](#component-classc--)
 - [カスタムCSS を追加する場合](#カスタムcss-を追加する場合)
 - [独自プレフィックス](#独自プレフィックス)
@@ -34,7 +34,6 @@ Settings（トークン定義）
   → Property Class（レイヤー外 — 最も詳細度が高い）
 ```
 
-
 ## クラス分類とプレフィックス
 
 [詳細](https://lism-css.com/docs/naming.md)
@@ -42,7 +41,7 @@ Settings（トークン定義）
 Lism CSSで定義されるクラスは、その役割とレイヤーの所属が決まっており、その分類によってプレフィックスが定められています。
 
 | 分類 | 役割 | プレフィックス | 例 |
-|---|---|---|---|
+| --- | --- | --- | --- |
 | Set Class | ベーススタイル上書き・変数提供 | `set--` | `set--plain`, `set--revert`, `set--hov`, `set--bxsh` |
 | Layout Primitive | レイアウトの構成単位となる Primitive | `l--` | `l--grid`, `l--flex`, `l--stack` |
 | Atomic Primitive | レイアウトの最小単位となる Primitive | `a--` | `a--icon`, `a--divider` |
@@ -53,20 +52,18 @@ Lism CSSで定義されるクラスは、その役割とレイヤーの所属が
 | Property Class | 単一プロパティの制御 | `-` | `-fz:l`, `-p:20`, `-d:none` |
 
 **併用ルール:**
+
 - `l--` と `c--` は併用OK（例: `<div class="l--flex c--nav">`）
 - 同カテゴリ内の Primitive 併用は不可（例: `l--flex` と `l--grid`、`a--icon` と `a--divider` は同要素に付けない）
 - `l--` × `a--` は非推奨（役割的に同居しない想定）
 - `is--` / `has--` 同士は併用OK（Trait は複数併用できる）
 - `is--` / `has--` × `l--` / `a--` も併用OK
-- `c--` の Block 同士の併用（`.c--xxx.c--yyy`）は基本 NG。ただし以下は許容:
-  - Block と自身の Modifier: `.c--button.c--button--outline`
-  - Block と他 Block の Element: `.c--xxx.c--yyy_elem`
-- 子要素: `c--card_header`, `c--card_body`（`c--` のみ Element を持つ。`_` 一つ区切り）
+- `c--` 同士の併用ルールとBEM構造は[Component Class（`c--`）](#component-classc--)を参照
 
 **`is--` と `has--` の判定軸:**
 
 |  | `is--` | `has--` |
-|---|---|---|
+| --- | --- | --- |
 | 意味 | 〜である（役割・存在の宣言） | 〜を持つ（機能の付与） |
 | CSS 変数 | 必須ではない | 必須（カスタマイズポイントを提供） |
 
@@ -78,7 +75,7 @@ class 属性にクラスを直接記述する場合は、以下の順序で並
 ```
 
 | # | 区分 | 例 |
-|---|---|---|
+| --- | --- | --- |
 | 1 | 独自クラス（`customClass`） | `z--header`, `hoge` |
 | 2 | Component（`c--`） | `c--box`, `c--box--primary` |
 | 3 | Atomic Primitive（`a--`） | `a--icon`, `a--divider` |
@@ -99,7 +96,6 @@ class 属性にクラスを直接記述する場合は、以下の順序で並
 
 なお、`class` 属性内の並び順は CSS の適用結果（詳細度・カスケード順）には影響しません。この順序はあくまで可読性と一貫性のための整理です。
 
-
 ## Component Class（`c--`）
 
 `c--` プレフィックスで定義する **Component クラス** は、Primitive を組み合わせて作られた具体的な UI 部品です。`@layer lism-component` に配置され、コアの `lism-css` には含まれず、`@lism-css/ui` パッケージやユーザー定義として提供されます。
@@ -107,7 +103,7 @@ class 属性にクラスを直接記述する場合は、以下の順序で並
 `c--` クラスは BEM 構造（Block / Modifier / Element）を持つことができ、それぞれ次の形式で定義します。
 
 | 分類 | 形式 | 例 |
-|---|---|---|
+| --- | --- | --- |
 | Block | `c--{name}` | `c--button`, `c--card` |
 | Modifier | `c--{name}--{modifier}` | `c--button--outline` |
 | Element | `c--{name}_{element}` | `c--card_header`, `c--card_body` |
@@ -121,33 +117,17 @@ class 属性にクラスを直接記述する場合は、以下の順序で並
 
 `c--` を使った独自コンポーネントを使う場合でも、他の Primitive クラス（`l--`, `is--`）や Property Class（`-{prop}:{value}`）との組み合わせを前提とした設計にすることで CSS の記述量を削減できます。`c--` クラスにスタイルが全くなく、HTML 側での可視性を高める名前付けのためだけに利用しても構いません。
 
-
 ### 作成例
 
-`l--stack` と併用する前提でのカスタムクラス例:
-
-```css
-@layer lism-component {
-  .c--myCard {
-    gap: var(--s20);
-    padding: var(--s30);
-    border-radius: var(--bdrs--20);
-    box-shadow: var(--bxsh--20);
-    border: 1px solid currentColor;
-    /* ... */
-  }
-}
-```
+`c--*`は意味名として残し、レイアウトと単一プロパティ値はPrimitive/Property Classへ寄せます。CSSへ残すのは、擬似要素・子孫セレクタ・状態セレクタなど、Props/Property Classで表現できないものだけです。
 
 ```html
-<div class="c--myCard l--stack">
-  ...
-</div>
+<!-- HTMLで書く場合も、意味名 + Primitive + Property Class を優先 -->
+<div class="c--myCard l--stack -g:20 -p:30 -bdrs:20 -bxsh:20 -bd">...</div>
 ```
 
-素の HTML サイトではこのように `c--` クラスに CSS を書いてスタイリングしても問題ありませんが、React などでコンポーネントを作成できる場合は、特別な理由がない限り Property Class を活用してください。
-
 ```jsx
+// React/AstroコンポーネントではPropsを優先
 export default function MyCard(props) {
   return <Stack className="c--myCard" g="20" p="30" bdrs="20" bxsh="20" bd {...props} />;
 }
@@ -155,12 +135,13 @@ export default function MyCard(props) {
 
 ```css
 @layer lism-component {
-  .c--myCard {
-    /* 複雑なスタイルがあれば css で書く */
+  .c--myCard::before {
+    /* 擬似要素など、Props/Property Classで表せないものだけを書く */
   }
 }
 ```
 
+CSSが空になる場合は、CSSファイル側に`.c--myCard {}`を書かず、マークアップ上の意味名として`c--myCard`だけ残して構いません。
 
 ## カスタムCSS を追加する場合
 
@@ -169,53 +150,39 @@ export default function MyCard(props) {
 ```css
 /* カスタムコンポーネント → lism-component に追加 */
 @layer lism-component {
-  .c--my-card {
-    border: 1px solid var(--brand);
-    border-radius: var(--bdrs--20);
-    padding: var(--s30);
+  .c--myCard[data-is-active]::before {
+    border-color: var(--brand);
   }
 }
 
 /* ベーススタイルの拡張 → lism-base に追加 */
 @layer lism-base {
-  .set--my-theme {
+  .set--myTheme {
     --brand: #c00;
   }
 }
 ```
 
-カスタムCSS内でも、できる限り Lism のCSS変数（トークン）を使ってください。
+カスタムCSS内でも、できる限り Lism のCSS変数（トークン）を使ってください。ただし、`padding`/`border-radius`/`font-size`/`color`などProperty Class/Propsへ移せる宣言は、CSSに書く前にマークアップ側へ移します（NG→OK例は[antipatterns.md](./antipatterns.md#property-class-で書けるのに-css-で書く)を参照）。
 
-```css
-/* NG */
-.c--my-card { padding: 24px; border-radius: 8px; }
-
-/* OK */
-.c--my-card { padding: var(--s30); border-radius: var(--bdrs--20); }
-```
-
-ただし、明確にその数値に意図がある場合は、生のCSS値を使用しても構いません。
+明確にその数値に意図があり、トークン化・丸め・Property Class化ができない場合だけ、生のCSS値を例外として使用できます。その場合は実装プランに理由を残します。
 
 **レイヤー外に書く場合:**
 `@layer` の外（レイヤーなし）でカスタムCSSを書くのは、**Property Class（`-{prop}:{value}`）を拡張する場合のみ**としてください。それ以外のカスタムスタイルは必ずいずれかの `@layer` 内に記述します。
 
 ```css
-/* OK: Property Class の拡張はレイヤー外 */
+/* Property Class の拡張のみレイヤー外に書ける */
 .-myProp\:myValue { ... }
-
-/* NG: コンポーネントやユーティリティをレイヤー外に書かない */
-.c--my-card { ... }
 ```
 
-
-### 独自プレフィックス
+## 独自プレフィックス
 
 Lism CSS の既存プレフィックス（`set--` / `is--` / `has--` / `l--` / `a--` / `c--` / `u--` / `-`）のどれにも該当しないクラスは、独自プレフィックスを付けても、プレフィックスなしで命名しても構いません。
 
 代表的な例：
 
 | 分類 | 形式 | 例 |
-|---|---|---|
+| --- | --- | --- |
 | ゾーニング（サイトの大まかな領域） | `z--{zoneName}` または `{zoneName}` | `z--header`, `z--main`, `z--sidebar`, `z--footer` |
 | ページ分類 | `p--{type}-{id\|slug}` または `{slug}Page` | `p--front`, `p--page--{slug}` |
 
@@ -223,11 +190,27 @@ Lism CSS の既存プレフィックス（`set--` / `is--` / `has--` / `l--` / `
 
 ```css
 @layer lism-custom {
-  .z--header { /* ... */ }
-  .p--front { /* ... */ }
+  .z--header {
+    /* ... */
+  }
+  .p--front {
+    /* ... */
+  }
 }
 ```
 
+### `z--`/`p--`/`c--`の使い分け
+
+| 用途 | 推奨 | 理由 |
+| --- | --- | --- |
+| 再利用可能なUI部品 | `c--featureCard` | componentとして再利用され、Block/Element/Modifier構造を持てる |
+| サイトの大まかな領域 | `z--header`/`z--main`/`z--footer` | 再利用UIではなくゾーニングなので`c--`にしない |
+| ページ固有の領域 | `p--frontHero`/`p--postBody` | ページ依存の見た目をcomponent命名から分離する |
+| 外部JS・CMS・E2Eが参照するclass | 既存名を維持、または⏸ | 外部契約なのでrenameはユーザー確認が必要 |
+
+`c--header`や`c--sidebar`のような命名は、UI部品として再利用する意図がある場合だけ使います。サイト構造の領域名なら`z--header`、ページ限定なら`p--*`を優先してください。
+
+公開API、CMS出力、外部JS、E2Eセレクタ、ドキュメントで案内済みのclass名を変える場合は、内部参照を全更新できる場合でも⏸としてユーザー確認します。CSSだけrenameしてJS/テスト/HTML生成側を漏らさないでください。
 
 ## CSS の配置場所