@lism-css/mcp 0.13.0 → 0.15.0

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

@@ -16,11 +16,11 @@ import { Lism, Box, Flex, Stack, Grid, Text, Media } from 'lism-css/astro';
 - [Lism Props](#lism-props)
 - [セマンティックコンポーネント](#セマンティックコンポーネント)
 - [Atomic Primitives](#atomic-primitives)
-- [Trait Primitives](#trait-primitives)
+- [Trait Components](#trait-components)
 - [Layout Primitives](#layout-primitives)
 - [`getLismProps()`](#getlismprops--外部コンポーネントとの連携)
 
-[詳細](https://lism-css.com/docs/core-components/Lism/)
+[詳細](https://lism-css.com/docs/core-components/lism-props/)
 
 ---
 
@@ -41,7 +41,7 @@ import { Lism, Box, Flex, Stack, Grid, Text, Media } from 'lism-css/astro';
 
 ソース: [props.ts](https://raw.githubusercontent.com/lism-css/lism-css/main/packages/lism-css/config/defaults/props.ts)
 
-`<Lism>` で受け取れる Lism CSS 専用プロパティを **Lism Props** と呼びます。
+`<Lism>`系コンポーネントで受け取れる Lism CSS 専用プロパティを **Lism Props** と呼びます。
 
 
 ### 共通 Props
@@ -51,10 +51,11 @@ import { Lism, Box, Flex, Stack, Grid, Text, Media } from 'lism-css/astro';
 | Prop | 説明 | 例 |
 |------|------|-----|
 | `as` | レンダリングする HTML 要素または外部コンポーネントを指定（デフォルト: `"div"`） | `as="section"`, `as={Image}` |
-| `lismClass` | コンポーネントの主要クラス名を指定。（`c--{lismClass}`） | `lismClass="c--myComponent"` |
-| `variant` | `lismClass` に対するバリエーションクラスを指定。（`c--{lismClass}--{variant}`） | `variant="secondary"` |
-| `layout` | レイアウトプリミティブ（`l--{layout}`）を指定。 | `layout="flow"` |
-| `set` | セットクラス（`set--{value}`）を指定。スペース区切りで複数指定可。値の先頭に `-` を付けると除外 | `set="gutter"`, `set="transition plain"`, `set="-plain"` |
+| `lismClass` | コンポーネント基底となる `c--*` クラスを指定。`variant` による BEM 展開の対象 | `lismClass="c--myComponent"` |
+| `variant` | `lismClass` 先頭クラスに対する BEM Modifier を付与（`c--` 専用。`a--` / `l--` には展開されない） | `variant="secondary"` |
+| `layout` | レイアウトプリミティブ（`l--{layout}`）を指定 | `layout="flow"` |
+| `atomic` | アトミックプリミティブ（`a--{atomic}`）を指定。`'divider'` / `'spacer'` / `'decorator'` が利用可能（`'icon'` は内部用） | `atomic="divider"` |
+| `set` | セットクラス（`set--{value}`）を指定。スペース区切りで複数指定可。値の先頭に `-` を付けると除外 | `set="plain"`, `set="var:hov var:bxsh"`, `set="-plain"` |
 | `util` | ユーティリティクラス（`u--{value}`）を指定。`set` と同様に複数指定・`-` prefix 除外が可能 | `util="cbox"`, `util="cbox trim"`, `util="-trim"` |
 | `exProps` | Lism Propsの処理をスキップして外部コンポーネントに直接渡すpropsオブジェクト | `exProps={{ size: '1em' }}` |
 
@@ -80,12 +81,12 @@ import { Lism, Box, Flex, Stack, Grid, Text, Media } from 'lism-css/astro';
 // → p, fz は Lism が処理、size は HogeIcon に直接渡される
 
 // set でセットクラスを付与（layout と同じ要領）
-<Box set="shadow" p="30">...</Box>
-// → <div class="l--box set--shadow -p:30">...</div>
+<Box set="var:bxsh" p="30">...</Box>
+// → <div class="l--box set--var:bxsh -p:30">...</div>
 
 // set を複数指定（スペース区切り）
-<Stack set="shadow hov" p="30">...</Stack>
-// → <div class="l--stack set--shadow set--hov -p:30">...</div>
+<Stack set="var:bxsh var:hov" p="30">...</Stack>
+// → <div class="l--stack set--var:bxsh set--var:hov -p:30">...</div>
 
 // `-` prefix で除外（コンポーネント内部で適用済みの set を打ち消す用途）
 <AccordionButton set="-plain">...</AccordionButton>
@@ -112,8 +113,8 @@ import { Lism, Box, Flex, Stack, Grid, Text, Media } from 'lism-css/astro';
 | 値 | 出力形式 | 例 |
 |------|------|-----|
 | トークン値・プリセット値 | `-{prop}:{value}` クラスのみ | `fz='l'` → `class="-fz:l"` |
-| `true` または `"-"` | `-{prop}` クラスのみ（変数なし） | `bd` / `bd='-'` → `class="-bd"` |
-| `:` で始まる値 | 強制的にユーティリティクラス化 | `p=':hoge'` → `class="-p:hoge"` |
+| `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`としては出力されない) |
@@ -138,8 +139,8 @@ import { Lism, Box, Flex, Stack, Grid, Text, Media } from 'lism-css/astro';
 <Lism bd bdc="#000" bdw="2px">...</Lism>
 // 出力 → <div class="-bd" style="--bdc:#000;--bdw:2px">...</div>
 
-// `-` でクラスだけ出力（変数は親から継承したい場合などに使う）
-<Lism p='-' bdrs>...</Lism>
+// `true` でクラスだけ出力（変数は親から継承したい場合などに使う）
+<Lism p bdrs>...</Lism>
 // 出力 → <div class="-p -bdrs">...</div>
 
 // `:` で強制ユーティリティクラス化
@@ -176,7 +177,7 @@ import { Lism, Box, Flex, Stack, Grid, Text, Media } from 'lism-css/astro';
 
 ### Trait Props
 
-Trait Primitives クラス（`is--*`）を出力するためのプロパティ群です。
+Trait クラス（`is--*` / `has--*`）を出力するためのプロパティ群です。
 
 | Prop | 出力クラス |
 |------|-----------|
@@ -189,7 +190,10 @@ Trait Primitives クラス（`is--*`）を出力するためのプロパティ
 | `isContainer` | `is--container` |
 | `isSide` | `is--side` |
 | `isSkipFlow` | `is--skipFlow` |
-| `isVertical` | `is--vertical` |
+| `hasTransition` | `has--transition` |
+| `hasGutter` | `has--gutter` |
+| `hasSnap` | `has--snap` |
+| `hasMask` | `has--mask` |
 
 ```jsx
 // Trait Props の使用例
@@ -236,12 +240,13 @@ Trait Primitives クラス（`is--*`）を出力するためのプロパティ
 | `<Divider>` | `a--divider` | 区切り線 |
 | `<Decorator>` | `a--decorator` | 装飾要素（SCSS定義なし、クラス名のみ出力） |
 
+
 各プリミティブの詳細は SKILL.md の「プリミティブ単位の詳細リファレンス」、または `primitives/` 配下の各ファイルを参照。
 
 
-## Trait Primitives
+## Trait Components
 
-`<Lism isXxx>`のエイリアスコンポーネントです。
+`<Lism isXxx>`のエイリアスコンポーネントです。`is--*` クラスを出力します。
 
 | コンポーネント | 内部処理 | 出力クラス |
 |-------------|------------|-----------|
@@ -250,7 +255,7 @@ Trait Primitives クラス（`is--*`）を出力するためのプロパティ
 | `<Layer>` | `isLayer` | `is--layer` |
 | `<BoxLink>` | `isBoxLink` | `is--boxLink` |
 
-各プリミティブの詳細は SKILL.md の「プリミティブ単位の詳細リファレンス」、または `primitives/` 配下の各ファイルを参照。
+各 Trait クラスの詳細は SKILL.md の「プリミティブ単位の詳細リファレンス」、または `trait-class/` 配下の各ファイルを参照。`has--*` については [trait-class.md](./trait-class.md) を参照。
 
 
 ## Layout Primitives

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

@@ -25,7 +25,6 @@ import { Accordion, Tabs, Modal, Button } from '@lism-css/ui/astro';
 - [Tabs](#tabs)
 - [ShapeDivider](#shapedivider)
 - [DummyText](#dummytext)
-- [DummyImage](#dummyimage)
 - [CLI でプロジェクトにコピーして使う](#cli-でプロジェクトにコピーして使う)
 
 [詳細](https://lism-css.com/ui/)
@@ -313,39 +312,33 @@ HTML の `details/summary` 要素をラップしたコンポーネント。Accor
 ```
 
 
-## DummyImage
-
-ソース: [DummyImage/](https://github.com/lism-css/lism-css/tree/main/packages/lism-ui/src/components/DummyImage)
-
-ダミーのプレースホルダー画像を出力するコンポーネント。`cdn.lism-css.com` からダミー画像を取得。
-
-```jsx
-<DummyImage />
-```
-
-
 ## CLI でプロジェクトにコピーして使う
 
 `@lism-css/ui` の UI コンポーネントは、CLI コマンドで自分のプロジェクトにソースコードをコピーして使うこともできます。コピーしたファイルは自由にカスタマイズ可能です。
 
+コンポーネント名は `import` するときと同じ PascalCase で指定します。
+
 ```bash
 # 初期設定（framework、出力先ディレクトリを対話的に設定）
-npx lism-ui init
+npx lism-cli ui init
 
 # コンポーネントを追加
-npx lism-ui add Button Modal
-npx lism-ui add -a          # 全コンポーネントを追加
+npx lism-cli ui add Button Modal
+npx lism-cli ui add NavMenu
+npx lism-cli ui add --all        # 全コンポーネントを追加
 
 # 利用可能なコンポーネント一覧を表示
-npx lism-ui list
+npx lism-cli ui list
 ```
 
-`init` で生成される `lism-ui.json`:
+`ui init` で生成される `lism.config.js` の `cli` セクション:
 
-```json
-{
-  "framework": "react",
-  "componentsDir": "src/components/ui",
-  "helperDir": "src/components/ui/_helper"
-}
+```js
+export default {
+  cli: {
+    framework: 'react',
+    componentsDir: 'src/components/ui',
+    helperDir: 'src/components/ui/_helper',
+  },
+};
 ```

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

@@ -3,12 +3,15 @@
 ## TOC
 
 - [CSS Layer 構造](#css-layer-構造)
-- [命名規則とプレフィックス](#命名規則とプレフィックス)
+- [プレフィックスとクラス分類](#プレフィックスとクラス分類)
+- [Component Class（`c--`）](#component-classc--)
 - [カスタムCSS を追加する場合](#カスタムcss-を追加する場合)
 - [CSS の配置場所](#css-の配置場所)
 
 [詳細](https://lism-css.com/docs/css-methodology/)
 
+> **命名規則の詳細**: CSS変数名・クラス名・Property Class の `{prop}` / `{value}` の省略ルールについては [naming.md](./naming.md) を参照してください。
+
 ---
 
 ## CSS Layer 構造
@@ -20,8 +23,8 @@ Lism CSS は CSS Layers による詳細度管理を採用しています。
 Settings（トークン定義）
   → @layer lism-base（Reset CSS・トークン・.set--クラス）
       → @layer reset（リセットCSS）
+  → @layer lism-trait（.is-- / .has-- Trait Class）
   → @layer lism-primitive
-      → @layer trait（.is-- Trait Primitive）
       → @layer layout（.l-- Layout Primitive）
       → @layer atomic（.a-- Atomic Primitive）
   → @layer lism-component（.c-- Component Class — BEM 構造を持つ UI 部品）
@@ -31,61 +34,133 @@ Settings（トークン定義）
 ```
 
 
-## 命名規則とプレフィックス
+## クラス分類とプレフィックス
 
-[詳細](https://lism-css.com/docs/primitives/)
+[詳細](https://lism-css.com/docs/naming/)
 
-クラス名のプレフィックスによって、役割とレイヤーの所属が決まります。
+Lism CSSで定義されるクラスは、その役割とレイヤーの所属が決まっており、その分類によってプレフィックスが定められています。
 
-| プレフィックス | レイヤー | 役割 | 例 |
-|--------------|---------|------|-----|
-| `.set--` | lism-base | ベーススタイル上書き・トークン再定義 | `.set--plain`, `.set--transition` |
-| `.is--` | lism-primitive.trait | Trait Primitive（要素の静的特性） | `.is--container`, `.is--wrapper` |
-| `.l--` | lism-primitive.layout | Layout Primitive | `.l--grid`, `.l--flex`, `.l--stack` |
-| `.a--` | lism-primitive.atomic | Atomic Primitive | `.a--icon`, `.a--divider` |
-| `.c--` | lism-component | Component Class（BEM 構造を持つ UI 部品） | `.c--button`, `.c--accordion` |
-| `.u--` | lism-utility | 用途が明確なユーティリティ | `.u--cbox`, `.u--trim` |
-| `.-` | レイヤー外 | 単一プロパティ制御（Property Class） | `.-fz:l`, `.-p:20`, `.-d:none` |
+| 分類 | 役割 | プレフィックス | 例 |
+|---|---|---|---|
+| Set Class | ベーススタイル上書き・変数提供 | `set--` | `.set--plain`, `.set--revert`, `.set--var:hov`, `.set--var:bxsh` |
+| Layout Primitive | レイアウトの構成単位となる Primitive | `l--` | `.l--grid`, `.l--flex`, `.l--stack` |
+| Atomic Primitive | レイアウトの最小単位となる Primitive | `a--` | `.a--icon`, `.a--divider` |
+| Component Class | BEM 構造を持つ UI 部品 | `c--` | `.c--button`, `.c--accordion` |
+| `is--` Trait | 要素に役割（〜である）を宣言 | `is--` | `.is--container`, `.is--wrapper`, `.is--layer`, `.is--boxLink` |
+| `has--` Trait | 要素に機能（〜を持つ）を付与 | `has--` | `.has--transition`, `.has--gutter`, `.has--snap`, `.has--mask` |
+| Utility Class | 用途が明確な装飾系ユーティリティ | `u--` | `.u--cbox`, `.u--trim`, `.u--collapseGrid` |
+| 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--` 同士は併用OK（Trait は複数併用できる）
-- `.is--` × `.l--` / `.a--` も併用OK
+- `.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 を持つ。`_` 一つ区切り）
 
+**`is--` と `has--` の判定軸:**
+
+|  | `is--` | `has--` |
+|---|---|---|
+| 意味 | 〜である（役割・存在の宣言） | 〜を持つ（機能の付与） |
+| CSS 変数 | 必須ではない | 必須（カスタマイズポイントを提供） |
+
 **記述順序:**
-class 属性にクラスを直接記述する場合は、以下の順序で並べてください。粒度の大きい（塊としての役割を持つ）クラスから、粒度の小さい（単一プロパティ制御）クラスの順です。
+class 属性にクラスを直接記述する場合は、以下の順序で並べてください。
 
 ```
-[customClass] [c--/a--] [l--] [is--*] [set--*] [u--*] [Property Class...]
+[customClass] [c--] [a--] [l--] [set--] [is--] [has--] [u--] [-]
 ```
 
 | # | 区分 | 例 |
 |---|---|---|
-| 1 | 独自クラス（`customClass`） | `my-card`, `hoge` |
-| 2 | Component / Atomic Primitive（`c--` / `a--`） | `c--box`, `a--icon`, `c--box c--box--primary` |
-| 3 | Layout Primitive（`l--`） | `l--flex`, `l--grid` |
-| 4 | Trait Primitives（`is--`） | `is--wrapper`, `is--layer` |
-| 5 | Set Class（`set--`） | `set--hov`, `set--card` |
-| 6 | ユーティリティ（`u--`） | `u--cbox`, `u--trim` |
-| 7 | Property Class（`-`） | `-p:20`, `-bgc:base-2` |
+| 1 | 独自クラス（`customClass`） | `z--header`, `hoge` |
+| 2 | Component（`c--`） | `c--box`, `c--box--primary` |
+| 3 | Atomic Primitive（`a--`） | `a--icon`, `a--divider` |
+| 4 | Layout Primitive（`l--`） | `l--flex`, `l--columns` |
+| 5 | Set Class（`set--`） | `set--var:hov`, `set--var:bxsh` |
+| 6 | Trait Class 役割宣言（`is--`） | `is--wrapper`, `is--layer` |
+| 7 | Trait Class 機能付与（`has--`） | `has--transition`, `has--gutter` |
+| 8 | Utility Class（`u--`） | `u--cbox`, `u--trim` |
+| 9 | Property Class（`-`） | `-p:20`, `-bgc:base-2`, `-hov:-c` |
 
 ```html
 <!-- OK -->
 <div class="c--nav l--flex -p:20 -g:20">...</div>
 
-<!-- NG: Property Class が先 -->
+<!-- NG: Property Class が先 になっている -->
 <div class="-p:20 -g:20 l--flex c--nav">...</div>
 ```
 
 なお、`class` 属性内の並び順は CSS の適用結果（詳細度・カスケード順）には影響しません。この順序はあくまで可読性と一貫性のための整理です。
 
 
+## Component Class（`c--`）
+
+`c--` プレフィックスで定義する **Component クラス** は、Primitive を組み合わせて作られた具体的な UI 部品です。`@layer lism-component` に配置され、コアの `lism-css` には含まれず、`@lism-css/ui` パッケージやユーザー定義として提供されます。
+
+`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` |
+
+- Modifier は Block と併記して使用: `.c--button.c--button--outline`
+- Element は `_`（アンダースコア）一つ区切り
+- Block 同士の併用（`.c--xxx.c--yyy`）は基本 NG。ただし次は許容される:
+  - Block と自身の Modifier: `.c--xxx.c--xxx--variant`
+  - Block と他 Block の Element: `.c--xxx.c--yyy_elem`
+- `a--` / `l--` には `variant` の BEM 展開は適用されない**
+
+`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;
+    /* ... */
+  }
+}
+```
+
+```html
+<div class="c--myCard l--stack">
+  ...
+</div>
+```
+
+素の HTML サイトではこのように `c--` クラスに CSS を書いてスタイリングしても問題ありませんが、React などでコンポーネントを作成できる場合は、特別な理由がない限り Property Class を活用してください。
+
+```jsx
+export default function MyCard(props) {
+  return <Stack lismClass="c--myCard" g="20" p="30" bdrs="20" bxsh="20" bd {...props} />;
+}
+```
+
+```css
+@layer lism-component {
+  .c--myCard {
+    /* 複雑なスタイルがあれば css で書く */
+  }
+}
+```
+
+
 ## カスタムCSS を追加する場合
 
 独自のスタイルを追加する場合は、対象に合った Lism の CSS Layer 内に記述してください。

package/dist/data/guides/customize.md

@@ -0,0 +1,220 @@
+# カスタマイズ
+
+`lism-css` パッケージから読み込む CSS や、コンポーネントが受け付ける Props の挙動を上書きしてカスタマイズする方法をまとめます。
+
+## TOC
+
+- [`@layer` をオフにする](#layer-をオフにする)
+- [SCSS でのカスタマイズ](#scss-でのカスタマイズ)
+- [`lism.config.js` でのカスタマイズ](#lismconfigjs-でのカスタマイズ)
+- [追加スタイルを読み込ませる方法](#追加スタイルを読み込ませる方法)
+
+[詳細](https://lism-css.com/docs/customize/)
+
+---
+
+## `@layer` をオフにする
+
+`lism-css/main.css` の代わりに `lism-css/main_no_layer.css` を読み込むだけで、`@layer` を使わない CSS に切り替えられます。
+
+```js
+// 通常
+import 'lism-css/main.css';
+
+// @layer なしのCSSを読み込む場合はこちら
+import 'lism-css/main_no_layer.css';
+```
+
+`@layer` のオン・オフは SCSS 変数では管理されません。**読み込むファイル自体を切り替える**点に注意してください。
+
+
+## SCSS でのカスタマイズ
+
+`lism-css/scss/_setting.scss` で定義された変数を `@use ... with (...)` で上書きできます。
+上書き定義をしてから `lism-css/scss/main.scss` を読み込むことでカスタマイズが反映されます。
+
+ソース: [`_setting.scss`](https://raw.githubusercontent.com/lism-css/lism-css/main/packages/lism-css/src/scss/_setting.scss)
+
+### 上書き可能な変数
+
+| 変数 | 用途 | デフォルト |
+|------|------|-----------|
+| `$breakpoints` | ブレイクポイント数値の定義 | `('sm': '480px', 'md': '800px', 'lg': '1120px')` |
+| `$common_support_bp` | 主要な Property Class が共通サポートするブレイクポイント上限 | `'md'` |
+| `$is_container_query` | コンテナクエリで出力するか（`1` = container query, `0` = media query） | `1` |
+| `$default_important` | Property Class にデフォルトで `!important` を付与するか | `0` |
+| `$props` | Property Class ごとの個別出力設定 | `prop-config` のデフォルト |
+
+### 基本フォーマット
+
+```scss
+// 1. 設定変数を上書き
+@use '../path-to/node_modules/lism-css/scss/setting' with (
+  $breakpoints: (
+    'sm': '400px',  // 個別キーの上書き可
+  ),
+  $common_support_bp: 'lg',
+  $is_container_query: 0,
+  $default_important: 1,
+  $props: (
+    // 個別 Prop の設定（後述）
+  )
+);
+
+// 2. main.scss を読み込む（@layer なしにする場合は main_no_layer）
+@use '../path-to/node_modules/lism-css/scss/main';
+```
+
+> Astro の場合、`../path-to/node_modules/` 部分は不要で `lism-css/scss/setting` のように書けます。
+
+### `$props` の個別カスタマイズ
+
+各 Property Class について、出力範囲やユーティリティクラスを追加できます。
+
+```scss
+@use '../path-to/node_modules/lism-css/scss/setting' with (
+  $props: (
+    'fz': (
+      important: 1,        // .-fz:* に !important を付与
+    ),
+    'h': (
+      bp: 0,               // .-h_sm 等のブレイクポイント版を出力しない
+    ),
+    'p': (
+      bp: 'lg',            // .-p_sm / .-p_md / .-p_lg まで出力
+      utilities: (
+        'box': '2em',      // .-p:box { --p: 2em } を追加
+      ),
+    ),
+  )
+);
+@use '../path-to/node_modules/lism-css/scss/main';
+```
+
+### 注意点
+
+SCSS を直接読み込む構成では、コンパイル時に `lism-css` 本体 CSS と読み込み順がずれる可能性があります。意図しない上書きが起きないよう、レイヤー順を確認してください。
+
+
+## `lism.config.js` でのカスタマイズ
+
+プロジェクトのルート直下に `lism.config.js` を置くことで、**コンポーネントの挙動**（受け付ける props の値や、出力されるクラス名）をカスタマイズできます。
+
+> **注意**: `lism.config.js` は HTML 出力（クラス名）を変えるだけで、追加されたクラスに対する CSS は別途読み込ませる必要があります（[追加スタイルを読み込ませる方法](#追加スタイルを読み込ませる方法) を参照）。
+
+### フォーマット
+
+```js
+// lism.config.js
+export default {
+  props: {
+    // Property Class の出力をカスタマイズ
+  },
+  tokens: {
+    // トークン値を追加
+  },
+  traits: {
+    // Trait（is--* / has--*）用の props を追加
+  },
+};
+```
+
+デフォルト値は以下を参照：
+
+- props: [`config/defaults/props.ts`](https://raw.githubusercontent.com/lism-css/lism-css/main/packages/lism-css/config/defaults/props.ts)
+- tokens: [`config/defaults/tokens.ts`](https://raw.githubusercontent.com/lism-css/lism-css/main/packages/lism-css/config/defaults/tokens.ts)
+- traits: [`config/defaults/traits.ts`](https://raw.githubusercontent.com/lism-css/lism-css/main/packages/lism-css/config/defaults/traits.ts)
+
+### カスタマイズ例
+
+```js
+// lism.config.js
+import DEFAULT_CONFIG from 'lism-css/default-config';
+const { props, tokens } = DEFAULT_CONFIG;
+
+export default {
+  props: {
+    d: { presets: [...(props.d.presets || []), 'flex', 'grid'] },
+    p: { utils: { box: '2em' } },
+  },
+  tokens: {
+    bdrs: [...(tokens.bdrs || []), '5'],
+  },
+  traits: {
+    isHoge: 'is--hoge',
+  },
+};
+```
+
+これによってコンポーネント側で次のような挙動が追加されます：
+
+| 入力 | 出力されるクラス |
+|------|----------------|
+| `d="flex"` | `-d:flex` |
+| `d="grid"` | `-d:grid` |
+| `p="box"` | `-p:box` |
+| `bdrs="5"` | `-bdrs:5` |
+| `isHoge` | `is--hoge` |
+
+```jsx
+<Box p="box" d="flex" bdrs="5" isHoge>Box</Box>
+// → <div class="l--box is--hoge -p:box -d:flex -bdrs:5">Box</div>
+```
+
+
+## 追加スタイルを読み込ませる方法
+
+`lism.config.js` で props を増やしただけでは、対応するユーティリティクラスのスタイルは存在しません。次のいずれかでスタイルを追加してください。
+
+### 1. CLI コマンドで CSS を再ビルド
+
+```bash
+npx lism-css build
+```
+
+`lism.config.js` の内容に基づいて `lism-css/main.css` を再生成します。上記カスタマイズ例だと、以下のスタイルが自動生成されます：
+
+```css
+.-d\:flex { display: flex; }
+.-d\:grid { display: grid; }
+.-p\:box { padding: 2em; }
+.-bdrs\:5 { border-radius: var(--bdrs--5); }
+```
+
+> **注意**:
+> - トークン CSS 変数（例: `--bdrs--5`）と `is--*` クラスのスタイルは自動生成されないため、手動で追加してください。
+> - `lism-css` パッケージ自体を上書きする処理のため、**パッケージ更新ごとに再実行**が必要です。
+
+### 2. 手動で CSS を追記
+
+CLI を使わず、追加クラス分の CSS をプロジェクト側で書いて読み込ませる方法でも問題ありません。
+
+```css
+:root { --bdrs--5: 0.125rem; }
+.is--hoge { /* ... */ }
+```
+
+### 3. SCSS で `lism.config.js` と整合させる
+
+SCSS 経由で読み込む構成なら、`lism.config.js` と同じ追加分を `$props` の `utilities` 設定として書いておけば、ビルドコマンドなしで反映できます。
+
+```scss
+@use '../path-to/node_modules/lism-css/scss/setting' with (
+  $props: (
+    'd': (
+      utilities: (
+        'flex': 'flex',
+        'grid': 'grid',
+      ),
+    ),
+    'p': ( utilities: ( 'box': '2em' ) ),
+    'bdrs': ( utilities: ( '5': 'var(--bdrs--5)' ) ),
+  )
+);
+@use '../path-to/node_modules/lism-css/scss/main';
+
+// トークン追記
+@layer lism-base {
+  :root { --bdrs--5: 0.125rem; }
+}
+```