@lism-css/mcp 0.12.0 → 0.13.0

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

@@ -20,11 +20,11 @@ Lism CSS は CSS Layers による詳細度管理を採用しています。
 Settings（トークン定義）
   → @layer lism-base（Reset CSS・トークン・.set--クラス）
       → @layer reset（リセットCSS）
-  → @layer lism-modules
-      → @layer state（.is-- ステートモジュール）
-      → @layer layout（.l-- レイアウトモジュール）
-      → @layer atomic（.a-- アトミックモジュール）
-      → .c-- は sublayer なし（lism-modules 直下、または lism-custom で定義）
+  → @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 部品）
   → @layer lism-custom（ユーザーカスタマイズ用）
   → @layer lism-utility（.u-- ユーティリティクラス）
   → Property Class（レイヤー外 — 最も詳細度が高い）
@@ -33,46 +33,66 @@ Settings（トークン定義）
 
 ## 命名規則とプレフィックス
 
-[詳細](https://lism-css.com/docs/module-class/)
+[詳細](https://lism-css.com/docs/primitives/)
 
 クラス名のプレフィックスによって、役割とレイヤーの所属が決まります。
 
 | プレフィックス | レイヤー | 役割 | 例 |
 |--------------|---------|------|-----|
 | `.set--` | lism-base | ベーススタイル上書き・トークン再定義 | `.set--plain`, `.set--transition` |
-| `.is--` | lism-modules | 付け外し可能な状態モジュール | `.is--container`, `.is--wrapper` |
-| `.l--` | lism-modules | レイアウト構成モジュール | `.l--grid`, `.l--flex`, `.l--stack` |
-| `.a--` | lism-modules | レイアウト最小単位モジュール | `.a--icon`, `.a--divider` |
-| `.c--` | lism-modules | 具体的な役割のコンポーネント | `.c--button`, `.c--accordion` |
+| `.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` |
 
 **併用ルール:**
 - `.l--` と `.c--` は併用OK（例: `<div class="l--flex c--nav">`）
-- 同カテゴリ内の併用は不可（例: `.l--flex` と `.l--grid` は同要素に付けない）
-- バリエーション: `.c--button.c--button--outline`
-- 子要素: `.c--card_header`, `.c--card_body`
+- 同カテゴリ内の Primitive 併用は不可（例: `.l--flex` と `.l--grid`、`.a--icon` と `.a--divider` は同要素に付けない）
+- `.l--` × `.a--` は非推奨（役割的に同居しない想定）
+- `.is--` 同士は併用OK（Trait は複数併用できる）
+- `.is--` × `.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 を持つ。`_` 一つ区切り）
 
 **記述順序:**
-class 属性にクラスを直接記述する場合、Property Class（`-` プレフィックス）はモジュールクラスやユーティリティクラスの**後ろ**に書いてください。
+class 属性にクラスを直接記述する場合は、以下の順序で並べてください。粒度の大きい（塊としての役割を持つ）クラスから、粒度の小さい（単一プロパティ制御）クラスの順です。
+
+```
+[customClass] [c--/a--] [l--] [is--*] [set--*] [u--*] [Property Class...]
+```
+
+| # | 区分 | 例 |
+|---|---|---|
+| 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` |
 
 ```html
-<!-- OK: モジュールクラス → Property Class -->
-<div class="l--flex c--nav -p:20 -g:20">...</div>
-<div class="l--box u--cbox -bd -p:20">...</div>
+<!-- OK -->
+<div class="c--nav l--flex -p:20 -g:20">...</div>
 
 <!-- NG: Property Class が先 -->
 <div class="-p:20 -g:20 l--flex c--nav">...</div>
 ```
 
+なお、`class` 属性内の並び順は CSS の適用結果（詳細度・カスケード順）には影響しません。この順序はあくまで可読性と一貫性のための整理です。
+
 
 ## カスタムCSS を追加する場合
 
 独自のスタイルを追加する場合は、対象に合った Lism の CSS Layer 内に記述してください。
 
 ```css
-/* カスタムコンポーネント → lism-modules に追加 */
-@layer lism-modules {
+/* カスタムコンポーネント → lism-component に追加 */
+@layer lism-component {
   .c--my-card {
     border: 1px solid var(--brand);
     border-radius: var(--bdrs--20);
@@ -137,8 +157,8 @@ Lism のトークン変数のカスタマイズやベーススタイルの上書
 - `.astro` ファイル: `import` するか、コンポーネントファイル内の `<style>` タグに記述
 
 ```css
-/* コンポーネント用CSS は lism-modules 内に定義する */
-@layer lism-modules {
+/* コンポーネント用CSS は lism-component 内に定義する */
+@layer lism-component {
   .c--yourComponent {
     ...
   }

package/dist/data/guides/primitive-class.md

@@ -0,0 +1,148 @@
+# Primitive クラス
+
+Lism CSS では、レイアウトを組み立てる小さな積み木として **Primitive クラス**（`is--` / `l--` / `a--`）を提供します。これらはすべて `@layer lism-primitive` に属します（サブレイヤーは `trait` / `layout` / `atomic`）。
+
+具体的な UI 部品は **Component クラス**（`c--`）として `@layer lism-component` に配置されますが、コアの `lism-css` には含まれず、`@lism-css/ui` パッケージやユーザー定義として提供されます。
+
+## TOC
+
+- [プレフィックス一覧](#プレフィックス一覧)
+- [Trait Primitive（`is--`）](#trait-primitiveis--)
+- [Layout Primitive（`l--`）](#layout-primitivel--)
+- [Atomic Primitive（`a--`）](#atomic-primitivea--)
+- [Component（`c--`）](#componentc--)
+
+[詳細](https://lism-css.com/docs/primitives/)
+
+---
+
+## プレフィックス一覧
+
+| プレフィックス | 種類 | サブレイヤー | 役割 |
+|--------------|------|------------|------|
+| `is--` | Trait Primitive | `lism-primitive.trait` | 要素に静的な構造的特性を付与する汎用クラス |
+| `l--` | Layout Primitive | `lism-primitive.layout` | レイアウトの構成単位となる Primitive |
+| `a--` | Atomic Primitive | `lism-primitive.atomic` | レイアウトの最小単位（アイコン・区切り線等） |
+| `c--` | Component | `lism-component` | BEM 構造を持つ具体的な UI 部品 |
+
+**併用ルール:**
+- `is--` は他のすべての Primitive / Component と併用可能（複数の `is--` 同士もOK）
+- `l--` と `c--` は併用可能（例: `class="l--flex c--nav"`）
+- 同カテゴリ内の併用は不可（例: `l--flex` と `l--grid` は同要素に付けない）
+- `c--` のみ Modifier との併記が可能（`.c--button.c--button--outline`）
+
+
+## Trait Primitive（`is--`）
+
+[詳細](https://lism-css.com/docs/primitives/#trait-primitives)
+
+要素に**静的な構造的特性 (trait)** を付与するクラスです。他の Primitive / Component と自由に組み合わせられます。
+
+| クラス | 用途 |
+|--------|------|
+| `is--container` | コンテナクエリの基準要素を定義する（`container-type: inline-size`を付与する）。Lism のレスポンシブ機能の判定基準となるラッパーに付与する |
+| `is--wrapper` | 直下の子要素のコンテンツ幅を一括で制限する。`-contentSize:s` / `-contentSize:l` で事前定義したプリセットサイズを指定可能（デフォルト: `--sz--m`）。セクション・ヘッダー・フッター・記事コンテンツなどで、共通したコンテンツ幅を使用する |
+| `is--layer` | 親要素全体に被さる絶対配置レイヤー（`position: absolute; inset: 0;`）。背景画像・カラーオーバーレイ・フィルターレイヤー・コンテンツ等を重ねて表示する |
+| `is--boxLink` | ボックス全体をクリッカブルなリンク領域にする。自身を`a`タグにして利用するか、もしくは自身を`div`にして内部の`a`タグに`is--coverLink`を付与して使う |
+| `is--coverLink` | 親要素全体に被さるクリック領域を持つリンク（`::before` を `inset: 0` で広げる）。`is--boxLink` と併用する |
+| `is--vertical` | 縦書きモードを定義する（`writing-mode: var(--vertical-mode)`） |
+| `is--skipFlow` | `l--flow` 直下で使用し、次の兄弟要素のフロー余白をゼロにする。`l--flow`の中にあるが`position:absolute`にしたい要素などに使用する |
+| `is--side` | `l--sideMain` 直下で使用し、サイド側の要素であることを示す |
+
+Lism コンポーネントでは `isContainer`, `isLayer` 等の Props として利用できます。
+
+
+## Layout Primitive（`l--`）
+
+レイアウト構造を定義するメインの Primitive 群です。
+
+| クラス | 用途 |
+|--------|-------------|
+| `l--box` | 汎用ボックス |
+| `l--flex` | 横方向の基本的なFlexboxレイアウト |
+| `l--stack` | 縦方向の縦積みFlexboxレイアウト（`flex-direction: column`）。 |
+| `l--cluster` | タグの表示UIなど、複数要素を水平に並べて配置し、数が多ければ折り返すようなレイアウト。（`flex-wrap: wrap; align-items: center`） |
+| `l--grid` | 基本的なGridレイアウト。 |
+| `l--center` | 要素を縦横中央に配置するレイアウト（`place-content: center; place-items: center`） |
+| `l--flow` | 記事コンテンツなどのフローレイアウト。子要素間の余白を `margin-block-start` で管理する。 |
+| `l--frame` | アスペクト比や高さが固定されたメディア要素を配置する。直下のメディア要素に `object-fit: cover` を付与する。 |
+| `l--columns` | `repeat`と`minmax(0, 1fr))`を使ったカラムレイアウト。レスポンシブ対応の`--cols`用のProperty Classでカラム数の切り替え可能。 |
+| `l--tileGrid` | `--cols`だけではなく`--rows`も組み合わせた均等タイルグリッド（`grid-template: repeat(var(--rows,1), minmax(0, 1fr)) / repeat(var(--cols,1), minmax(0, 1fr))`） |
+| `l--fluidCols` | ブレイクポイントに依存せず、自動段組のできる流動カラムレイアウト。`--cols: 16em`のようにして最小維持幅を指定できる。 |
+| `l--sideMain` | 画像とコンテンツ、メインエリアとサイドバーなどの「"Side" + "Main"」に分かれ、横並びと縦並びが切り替わるレイアウト。"Main"が`--mainW`で指定したサイズ以上の横幅を維持できる範囲内で横並びを維持し、下回る場合は縦並びへ自動で切り替わる。横並びの間の"Side"の横幅は`--sideW`で指定する。 |
+| `l--switchCols` | 任意のサイズで一括カラム切り替えができるカラムレイアウト。`--breakSize` で制御 |
+
+それぞれ対応するLismコンポーネント（`<Flex>`, `<Stack>`, `<Cluster>` 等）があります。
+
+
+## Atomic Primitive（`a--`）
+
+レイアウト構成物の最小単位となる Primitive です。
+
+| クラス | 用途 |
+|--------|------|
+| `a--icon` | SVG アイコン。`flex-shrink: 0`, デフォルトサイズ `1em` |
+| `a--divider` | 区切り線。`--bdc`, `--bds`, `--bdw` 変数でカスタマイズ |
+| `a--spacer` | 空白要素（`min-height: 1px; min-width: 1px`） |
+| `a--decorator` | 装飾用要素（SCSS定義なし、クラス名のみ出力） |
+
+それぞれ対応するコンポーネント（`<Icon>`, `<Divider>`, `<Spacer>`, `<Decorator>`）があります。
+
+
+## Component（`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`
+
+`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 で書く */
+  }
+}
+```

package/dist/data/guides/primitives/a--decorator.md

@@ -0,0 +1,45 @@
+# a--decorator / `<Decorator>`
+
+コンテンツを装飾するための空要素として使うクラス。`<Decorator>` はデフォルトで `aria-hidden="true"` が付与されます。
+
+## 基本情報
+
+- クラス名: `a--decorator`
+- コンポーネント: `<Decorator>`
+- ドキュメント（人間向け）: https://lism-css.com/docs/primitives/a--decorator/
+
+## 専用Props
+
+| Prop | 説明 |
+|------|------|
+| `size` | デコレーターのサイズを一括指定。この指定があると `w`（`width`）に値が渡され、自動で `ar="1/1"`（`aspect-ratio:1/1`）が付与される |
+| `clipPath` | `style.clipPath` に渡す |
+| `boxSizing` | `style.boxSizing` に渡す |
+
+## Usage
+
+### 使用例（コーナー装飾）
+
+`pos="absolute"` と組み合わせて、親の四隅にコーナー枠を配置する例です。`bdc="current"` で文字色に追随します。
+
+```jsx
+<Box p="30" pos="relative">
+  <p>本文テキスト...</p>
+  <Decorator size="1.25em" pos="absolute" t="0" l="0" bd-x-s bd-y-s bdc="current" />
+  <Decorator size="1.25em" pos="absolute" r="0" b="0" bd-x-e bd-y-e bdc="current" />
+</Box>
+```
+
+```html
+<div class="l--box -p:30 -pos:relative">
+  <p>本文テキスト...</p>
+  <div class="a--decorator -pos:absolute -t:0 -l:0 -bd-x-s -bd-y-s -bdc:current -ar:1/1 -w" style="--w:1.25em" aria-hidden="true"></div>
+  <div class="a--decorator -pos:absolute -r:0 -b:0 -bd-x-e -bd-y-e -bdc:current -ar:1/1 -w" style="--w:1.25em" aria-hidden="true"></div>
+</div>
+```
+
+## 関連プリミティブ
+
+- [a--spacer](./a--spacer.md) — 要素間スペース
+- [a--divider](./a--divider.md) — 区切り線
+- [is--layer](./is--layer.md) — `position: absolute` のオーバーレイ

package/dist/data/guides/primitives/a--divider.md

@@ -0,0 +1,69 @@
+# a--divider / `<Divider>`
+
+コンテンツ間に区切り線を描画するクラス。`--bdc` は `var(--divider)` が初期セットされます。`<Divider>` はデフォルトで `aria-hidden="true"` が付与されます。
+
+## 基本情報
+
+- クラス名: `a--divider`
+- コンポーネント: `<Divider>`
+- SCSSソース: https://raw.githubusercontent.com/lism-css/lism-css/main/packages/lism-css/src/scss/primitives/atomic/_divider.scss
+- ドキュメント（人間向け）: https://lism-css.com/docs/primitives/a--divider/
+
+## 専用Props
+
+| Prop | 説明 |
+|------|------|
+| `bdw` / `bds` / `bdc` | 区切り線のボーダー幅 / スタイル / 色 |
+| `isVertical` | 縦方向の区切り線にする（`is--vertical` クラス付与） |
+
+## Usage
+
+### 基本的な使い方
+
+```jsx
+<Box bgc="base-2" py="40" ta="center">...Contents...</Box>
+<Divider />
+<Box bgc="base-2" py="40" ta="center">...Contents...</Box>
+```
+
+```html
+<div class="l--box -bgc:base-2 -py:40 -ta:center">...Contents...</div>
+<div class="a--divider" aria-hidden="true"></div>
+<div class="l--box -bgc:base-2 -py:40 -ta:center">...Contents...</div>
+```
+
+### スタイルの変更
+
+```jsx
+<Divider bds="dotted" bdw="4px" bdc="blue" />
+```
+
+```html
+<div class="a--divider" aria-hidden="true" style="--bds: dotted; --bdw: 4px; --bdc: var(--blue)"></div>
+```
+
+### 縦方向の区切り線
+
+`isVertical` を指定すると縦方向の区切り線になります。Flex 子要素として使うなら `aslf="stretch"` で高さいっぱいに伸ばせます。
+
+```jsx
+<Flex ai="center" g="20">
+  <Box fx="1" bgc="base-2" py="40">...Contents...</Box>
+  <Divider isVertical bds="dashed" bdw="2px" aslf="stretch" />
+  <Box fx="1" bgc="base-2" py="40">...Contents...</Box>
+</Flex>
+```
+
+```html
+<div class="l--flex -g:20 -ai:center">
+  <div class="-fx:1 -bgc:base-2 -py:40">...Contents...</div>
+  <div class="a--divider is--vertical -aslf:stretch" style="--bds: dashed; --bdw: 2px" aria-hidden="true"></div>
+  <div class="-fx:1 -bgc:base-2 -py:40">...Contents...</div>
+</div>
+```
+
+## 関連プリミティブ
+
+- [a--spacer](./a--spacer.md) — 要素間のスペース確保
+- [a--decorator](./a--decorator.md) — 装飾用空要素
+- [a--icon](./a--icon.md) — アイコン要素

package/dist/data/guides/primitives/a--icon.md

@@ -0,0 +1,105 @@
+# a--icon / `<Icon>`
+
+アイコン要素を表示するためのクラス。`flex-shrink: 0`、デフォルトサイズ `1em`。
+
+## 基本情報
+
+- クラス名: `a--icon`
+- コンポーネント: `<Icon>`
+- SCSSソース: https://raw.githubusercontent.com/lism-css/lism-css/main/packages/lism-css/src/scss/primitives/atomic/_icon.scss
+- ドキュメント（人間向け）: https://lism-css.com/docs/primitives/a--icon/
+
+## 出力されるHTML構造
+
+`<Icon>` は `label` の有無でアクセシビリティ属性を自動切り替えします。
+
+```html
+<!-- label なし -->
+<svg class="a--icon" aria-hidden="true">...</svg>
+
+<!-- label あり -->
+<svg class="a--icon" aria-label="..." role="img">...</svg>
+```
+
+## 専用Props
+
+| Prop | 説明 |
+|------|------|
+| `icon` | アイコンを指定。文字列（プリセット名）・オブジェクト（`{as, ...exProps}`）のどちらでも可 |
+| `size` | プリセットアイコン使用時の `width` / `height`（通常は `fz` で指定するほうが推奨） |
+| `label` | `aria-label` として出力。指定があれば `role="img"`、なければ `aria-hidden="true"` |
+
+## Usage
+
+`<Icon>` には**4つの使い方**があります。
+
+### 1. 外部パッケージのアイコンを使う（`as` + `exProps`）
+
+`react-icons`, `@phosphor-icons/react`, `lucide-react` などのサードパーティアイコンコンポーネントを `as` で渡すと、Lism が未処理の props は自動的にそのコンポーネントに転送されます。外部コンポーネント専用の props を明示的に分離したい場合は `exProps` を使います。
+
+```jsx
+import { SmileyIcon } from '@phosphor-icons/react';
+import { Icon } from 'lism-css/react';
+
+// 基本形
+<Icon as={SmileyIcon} fz="2rem" />
+
+// exProps で外部 props を明示的に分離
+<Icon as={SmileyIcon} exProps={{ weight: 'fill', size: '3em' }} c="blue" />
+
+// 上と同じ結果（Lism が "weight" を処理しないため最終的に SmileyIcon に渡る）
+<Icon as={SmileyIcon} weight="fill" c="blue" />
+```
+
+### 2. `as` と `exProps` を `icon` prop に一括指定
+
+`icon={{as: Component, ...exProps}}` の形式で、`as` と `exProps` を1つのオブジェクトとしてまとめて渡せます。アイコンを選択制にする親コンポーネントを作るときに便利です。
+
+```jsx
+import { Home } from 'lucide-react';
+
+<Icon icon={{ as: Home, strokeWidth: 1, size: 64 }} />
+
+// 同じ結果（分割形式）
+<Icon as={Home} exProps={{ strokeWidth: 1, size: 64 }} />
+```
+
+### 3. プリセットアイコンを使う
+
+`lism-css` パッケージ内に [Phosphor Icons](https://phosphoricons.com/) ベースのプリセットアイコンが同梱されています。`icon="アイコン名"` の文字列で呼び出せます。
+
+```jsx
+<Icon icon="menu" />
+<Icon icon="lightbulb" fz="2xl" c="blue" />
+<Icon icon="warning" size="40px" />
+```
+
+プリセット一覧のエクスポート元:
+
+```jsx
+import { phIcons, logoIcons } from 'lism-css/react/atomic/Icon/presets';
+```
+
+### 4. SVG の `path` を直接記述する
+
+`viewBox` を指定すると `<svg>` 要素として出力されるため、子要素に `<path>` 等をそのまま書けます。
+
+```jsx
+<Icon viewBox="0 0 256 256" label="Smiley icon" fz="4xl" c="blue">
+  <path d="M128,24A104,104,0,1,0,232,128..." />
+</Icon>
+```
+
+### 5. `src` で画像をアイコンとして使う
+
+`src` を指定すると `<img>` として出力されます（厳密には4パターンに加えて画像指定も可能）。
+
+```jsx
+<Icon fz="4xl" src="/img/avatar01.jpg" alt="avatar" />
+```
+
+## 関連プリミティブ
+
+- [a--divider](./a--divider.md) — 区切り線
+- [a--spacer](./a--spacer.md) — 空白要素
+- [a--decorator](./a--decorator.md) — 装飾用要素

package/dist/data/guides/primitives/a--spacer.md

@@ -0,0 +1,63 @@
+# a--spacer / `<Spacer>`
+
+要素間のスペースを確保するクラス。`<Spacer>` はデフォルトで `aria-hidden="true"` が付与されます。
+
+## 基本情報
+
+- クラス名: `a--spacer`
+- コンポーネント: `<Spacer>`
+- SCSSソース: https://raw.githubusercontent.com/lism-css/lism-css/main/packages/lism-css/src/scss/primitives/atomic/_spacer.scss
+- ドキュメント（人間向け）: https://lism-css.com/docs/primitives/a--spacer/
+
+## 専用Props
+
+`<Spacer>` では **`w` / `h` に対して SPACE トークンの値**が使えます（他のコンポーネントでは SIZE トークンが優先されるため、スペースサイズを直感的に指定できる特殊対応）。
+
+## Usage
+
+### 縦方向のスペース
+
+```jsx
+<p>Content...</p>
+<Spacer h="100px" />
+<p>Content...</p>
+```
+
+```html
+<p>Content...</p>
+<div class="a--spacer -h" style="--h:100px" aria-hidden="true"></div>
+<p>Content...</p>
+```
+
+### SPACE トークンを使う
+
+```jsx
+<p>Content...</p>
+<Spacer h="60" />
+<p>Content...</p>
+```
+
+```html
+<p>Content...</p>
+<div class="a--spacer -h" style="--h:var(--s60)" aria-hidden="true"></div>
+<p>Content...</p>
+```
+
+### 横方向のスペーサー
+
+Flex コンテナ内で `w` を指定すれば横方向のスペーサーとしても使えます。
+
+```jsx
+<Flex g="10">
+  <Box p="20" bd>Box</Box>
+  <Spacer w="40" />
+  <Box p="20" bd>Box</Box>
+  <Box p="20" bd>Box</Box>
+</Flex>
+```
+
+## 関連プリミティブ
+
+- [a--divider](./a--divider.md) — 区切り線
+- [a--decorator](./a--decorator.md) — 装飾用空要素
+- [l--stack](./l--stack.md) — `gap` で余白を管理する縦積み

package/dist/data/guides/primitives/is--boxLink.md

@@ -0,0 +1,97 @@
+# is--boxLink / `<BoxLink>`
+
+ボックス全体をクリック可能なリンク領域にするクラス。
+
+## 基本情報
+
+- クラス名: `is--boxLink`
+- コンポーネント: `<BoxLink>`
+- SCSSソース: https://raw.githubusercontent.com/lism-css/lism-css/main/packages/lism-css/src/scss/primitives/trait/_boxLink.scss
+- ドキュメント（人間向け）: https://lism-css.com/docs/primitives/is--boxLink/
+
+## 専用Props
+
+| Prop | 説明 |
+|------|------|
+| `href` | リンク先を指定。`href` があれば `<BoxLink>` 自体が `<a>` タグに、なければ `<div>` として出力される（**特殊挙動**） |
+
+通常の `<Lism>` エイリアスコンポーネントと異なり、`<BoxLink>` だけは `href` 指定の有無で出力タグが動的に切り替わります。
+
+## Usage
+
+BoxLink には主に2通りの使い方があります。
+
+### パターン1: `<BoxLink>` 自身を `<a>` にする
+
+`href` を指定すると `<BoxLink>` 自体が `<a>` タグとして出力されます。シンプルなカード全体リンクに最適。
+
+```jsx
+<BoxLink href="/article/1" p="30" bgc="base" bd bdrs="30" hov="o">
+  <Group fz="xl" fw="bold">Heading text</Group>
+  <Text lh="s" my-s="15">記事の抜粋テキスト...</Text>
+  <Group fz="s" c="text-2" ta="right" lh="1" my-s="10">
+    MORE →
+  </Group>
+</BoxLink>
+```
+
+```html
+<a class="is--boxLink -hov:o -p:30 -bgc:base -bd -bdrs:30" href="/article/1">
+  <p class="-fz:xl -fw:bold">Heading text</p>
+  <p class="-c:text-2 -lh:s -my-s:15">記事の抜粋テキスト...</p>
+  <p class="-fz:s -c:text-2 -ta:right -lh:1 -my-s:10">MORE →</p>
+</a>
+```
+
+### パターン2: `<div>` + 内部に `is--coverLink`
+
+`<BoxLink>` は `<div>` にしたまま、内部のアンカー要素に `is--coverLink` クラスを付けてボックス全体をクリック可能にします。**BoxLink 内部にさらに別のリンクを配置したい場合はこちらを選ぶこと**。
+
+```jsx
+<BoxLink as="section" p="30" bgc="base" bd bdrs="30" set="transition" hov="bxsh">
+  <Group fz="xl" fw="bold">
+    <Link isCoverLink href="/article/1">
+      Heading link text
+    </Link>
+  </Group>
+  <Text c="text-2" lh="s" my-s="15">記事の抜粋テキスト...</Text>
+  <Group my-s="10">
+    <a href="/tag/foo" className="-hov:o">Inner Link</a>
+  </Group>
+</BoxLink>
+```
+
+```html
+<div class="is--boxLink -hov:bxsh -p:30 -bgc:base -bd -bdrs:30 set--transition">
+  <div class="-fz:xl -fw:bold">
+    <a class="is--coverLink" href="/article/1">Heading link text</a>
+  </div>
+  <p class="-c:text-2 -lh:s -my-s:15">記事の抜粋テキスト...</p>
+  <div class="-my-s:10">
+    <a href="/tag/foo" class="-hov:o">Inner Link</a>
+  </div>
+</div>
+```
+
+## Opt-in スタイル
+
+### Tabキーフォーカス時のアウトラインをボックス全体に広げる
+
+パターン2 の場合、デフォルトでは Tab フォーカス時のアウトラインがリンクテキスト部分のみに表示されます。ボックス全体に広げたい場合は以下のCSSを追記してください。
+
+```css
+@supports selector(:has(*)) {
+  .is--boxLink:has(.is--coverLink:focus-visible) {
+    outline: auto 1px;
+    outline: auto 1px -webkit-focus-ring-color;
+  }
+  .is--coverLink:focus {
+    outline: 0;
+  }
+}
+```
+
+## 関連プリミティブ
+
+- [is--container](./is--container.md) — コンテナクエリの基準要素
+- [is--wrapper](./is--wrapper.md) — コンテンツ幅ラッパー