@lism-css/mcp 0.26.0 → 0.27.0

package/dist/data/guides/tokens.md

@@ -32,12 +32,13 @@ CSSコードを書く場合やコンポーネントのPropsに値を指定する
 | --- | --- | --- | --- |
 | 余白 (space) | `5`, `10`, `15`, `20`, `25`, `30`, `35`, `40`, `50`, `60`, `70`, `80` | `--s{N}` | `--s20` |
 | フォントサイズ (fz) | `base`, `2xs`, `xs`, `s`, `m`, `l`, `xl`, `2xl`, `3xl`, `4xl`, `5xl` | `--fz--{key}` | `--fz--l` |
-| ハーフレディング・行間 (hl/lh) | `base`, `xs`, `s`, `l` | `--hl--{key}` | `--hl--s` |
-| 字間 (lts) | `base`, `s`, `l`, `xl` | `--lts--{key}` | `--lts--s` |
+| ハーフレディング (hl) | `base`, `xs`, `s`, `l`, `xl` | `--hl--{key}` | `--hl--s` |
+| 行間比率 (lh) | `xs`, `s`, `m`, `l`, `xl` | `--lh--{key}` | `--lh--m` |
+| 字間 (lts) | `base`, `xs`, `s`, `l`, `xl` | `--lts--{key}` | `--lts--s` |
 | フォント (ff) | `base`, `accent`, `mono` | `--ff--{key}` | `--ff--mono` |
 | ウェイト (fw) | `light`, `normal`, `bold` | `--fw--{key}` | `--fw--bold` |
 | 透明度 (o) | `mp`, `p`, `pp`, `ppp` | `--o--{key}` | `--o--p` |
-| 角丸 (bdrs) | `10`, `20`, `30`, `40`, `99`, `inner` | `--bdrs--{key}` | `--bdrs--20` |
+| 角丸 (bdrs) | `10`, `20`, `30`, `40`, `50`, `99`, `inner` | `--bdrs--{key}` | `--bdrs--20` |
 | 影 (bxsh) | `10`, `20`, `30`, `40`, `50` | `--bxsh--{N}` | `--bxsh--20` |
 | サイズ (sz) | `xs`, `s`, `m`, `l`, `xl` | `--sz--{key}` | `--sz--l` |
 | アスペクト比 (ar) | `og` | `--ar--{key}` | `--ar--og` |
@@ -51,7 +52,7 @@ CSSコードを書く場合やコンポーネントのPropsに値を指定する
 
 ## 余白 (space)
 
-フィボナッチ数列ベースのスケーリング。`--s-unit`（デフォルト `calc(var(--fz--base) * 0.5)` ＝ ≒ 8px）を基準単位とする。
+フィボナッチ数列ベースのスケーリング。`--s-unit`（デフォルト `0.5rem` ≒ 8px）を基準単位とする。
 
 | CSS変数 | 値 | 実サイズ目安 |
 | --- | --- | --- |
@@ -68,7 +69,7 @@ CSSコードを書く場合やコンポーネントのPropsに値を指定する
 | `--s70` | `calc(var(--s-unit) * 21)` | ≒ 168px |
 | `--s80` | `calc(var(--s-unit) * 34)` | ≒ 272px |
 
-`--s40` 以降の主軸は係数 `1, 2, 3, 5, 8, 13, 21, 34`（フィボナッチ数列）に基づく。`--s5`〜`--s35` の前半部分は、主軸トークン間を補う中間値（4px / 12px / 20px / 32px 相当）として配置している。`--s-unit` を上書きするとスケール全体を比例的に調整できる。
+`--s40` 以降の主軸は係数 `1, 2, 3, 5, 8, 13, 21, 34`（フィボナッチ数列）に基づく。`--s5`〜`--s35` の前半部分は、主軸トークン間を補う中間値（4px / 12px / 20px / 32px 相当）として配置している。`--s-unit` を上書きするとスケール全体を比例的に調整できる。`--fz--base` を流体値にしていて余白も連動させたい場合は、`:root` で `--s-unit: calc(var(--fz--base) * 0.5)` に上書きする。
 
 ### `set--s` ユーティリティ
 
@@ -109,7 +110,9 @@ CSSコードを書く場合やコンポーネントのPropsに値を指定する
 
 ## 行間 (hl/lh)
 
-ハーフレディングの大きさ。Lism CSSでは、`line-height` は `calc(1em + var(--hl) * 2)` で算出される。`--hl-unit`（≒ 2px）を基準単位とする。
+`line-height` は全要素で `var(--lh, calc(1em + var(--hl) * 2))` として算出される。既定は `--hl`（ハーフレディング）で管理し、`--lh` がセットされていればそちらが優先される。
+
+`hl` はハーフレディングの大きさ。`--hl-unit`（≒ 2px）を基準単位とする。
 
 | CSS変数 | 値 | 説明 |
 | --- | --- | --- |
@@ -117,6 +120,19 @@ CSSコードを書く場合やコンポーネントのPropsに値を指定する
 | `--hl--s` | `calc(var(--hl-unit) * 2)` | 小さめの行間（≒ 4px） |
 | `--hl--base` | `calc(var(--hl-unit) * 3)` | 基本の行間（≒ 6px） |
 | `--hl--l` | `calc(var(--hl-unit) * 4)` | 大きめの行間（≒ 8px） |
+| `--hl--xl` | `calc(var(--hl-unit) * 5)` | より大きな行間（≒ 10px） |
+
+`--fz--base` を流体値にしていて行間も連動させたい場合は、`:root` で `--hl-unit: calc(var(--fz--base) * 0.125)` に上書きする。
+
+`lh` は `line-height` を倍率で指定するトークン。`hl` が fz 非依存の固定量なのに対し、fz に比例した行送りを保ちたい場合に使う。
+
+| CSS変数 | 値 |
+| --- | --- |
+| `--lh--xs` | `1.25` |
+| `--lh--s` | `1.5` |
+| `--lh--m` | `1.75` |
+| `--lh--l` | `2` |
+| `--lh--xl` | `2.25` |
 
 
 ## 字間 (lts)
@@ -124,6 +140,7 @@ CSSコードを書く場合やコンポーネントのPropsに値を指定する
 | CSS変数 | 値 | 説明 |
 | --- | --- | --- |
 | `--lts--base` | `normal` | 基本の文字間隔 |
+| `--lts--xs` | `-0.05em` | より狭い文字間隔 |
 | `--lts--s` | `-0.025em` | 狭めの文字間隔 |
 | `--lts--l` | `0.05em` | 広めの文字間隔 |
 | `--lts--xl` | `0.1em` | より広い文字間隔 |
@@ -163,32 +180,37 @@ CSSコードを書く場合やコンポーネントのPropsに値を指定する
 
 ## 角丸 (bdrs)
 
+増分が0.125remずつ大きくなる二階等差数列のスケール。
+
 | CSS変数 | 値 | 説明 |
 | --- | --- | --- |
 | `--bdrs--10` | `0.25rem` | ≒ 4px |
-| `--bdrs--20` | `0.5rem` | ≒ 8px |
-| `--bdrs--30` | `1rem` | ≒ 16px |
-| `--bdrs--40` | `1.5rem` | ≒ 24px |
+| `--bdrs--20` | `0.375rem` | ≒ 6px |
+| `--bdrs--30` | `0.625rem` | ≒ 10px |
+| `--bdrs--40` | `1rem` | ≒ 16px |
+| `--bdrs--50` | `1.5rem` | ≒ 24px |
 | `--bdrs--99` | `99rem` | 完全な丸（pill） |
-| `--bdrs--inner` | `calc(var(--bdrs, 0px) - var(--p, 0px))` | 内側の角丸（親要素に合わせる） |
+| `--bdrs--inner` | `calc(var(--bdrs, 0px) - var(--p, 0px) + 1px)` | 内側の角丸（親要素に合わせる） |
 
 
 ## 影 (bxsh)
 
-`--shc`（シャドウカラー）と `--shsz--{N}`（シャドウサイズ）を組み合わせて構成される。要素ごとに `--shc` を上書きして再計算したい場合は、`set--bxsh` クラスを併用する。
+要素に近い薄い影と主となる影の2層で構成される。近い側の影は、1段小さいシャドウサイズ `--shsz--{N}` と、`--shc`（シャドウカラー）を50%薄めた `--shc--near` を使う。要素ごとに `--shc` を上書きして再計算したい場合は、`set--bxsh` クラスを併用する（`--shc--near` も `--shc` から再計算される）。
 
 | CSS変数 | 値 |
 | --- | --- |
-| `--bxsh--10` | `var(--shsz--10) var(--shc)` |
-| `--bxsh--20` | `var(--shsz--20) var(--shc)` |
-| `--bxsh--30` | `var(--shsz--30) var(--shc)` |
-| `--bxsh--40` | `var(--shsz--40) var(--shc)` |
-| `--bxsh--50` | `var(--shsz--50) var(--shc)` |
+| `--bxsh--10` | `var(--shsz--5) var(--shc--near), var(--shsz--10) var(--shc)` |
+| `--bxsh--20` | `var(--shsz--10) var(--shc--near), var(--shsz--20) var(--shc)` |
+| `--bxsh--30` | `var(--shsz--20) var(--shc--near), var(--shsz--30) var(--shc)` |
+| `--bxsh--40` | `var(--shsz--30) var(--shc--near), var(--shsz--40) var(--shc)` |
+| `--bxsh--50` | `var(--shsz--40) var(--shc--near), var(--shsz--50) var(--shc)` |
 
 | CSS変数 | 初期値 |
 | --- | --- |
-| `--shadow` | `hsl(220 4% 8% / 12%)` |
+| `--shadow` | `hsl(220 2% 4% / 8%)` |
 | `--shc` | `var(--shadow)` |
+| `--shc--near` | `color-mix(in srgb, var(--shc), transparent 50%)` |
+| `--shsz--5` | `0px 0px 1px` |
 | `--shsz--10` | `0px 1px 3px` |
 | `--shsz--20` | `0px 2px 6px` |
 | `--shsz--30` | `0px 4px 12px` |

package/dist/data/guides/trait-class/has--transition.md

@@ -3,9 +3,24 @@
 `transition` 系のプロパティを CSS 変数経由でセットする Trait クラス。主に `-hov:*` クラスと組み合わせて、ホバー時のスムーズな変化に使う。
 
 - Lism props: `hasTransition`（`<Lism hasTransition>` / `<Box hasTransition>` 等）
+- 文字列を渡すと `--transitionProps` として出力される: `<Box hasTransition="color, opacity">` → `class="has--transition" style="--transitionProps: color, opacity"`
 
 公式ドキュメント（使い方・コード例）: https://lism-css.com/docs/trait-class.md#has--transition
 
+## 対象プロパティは明示指定する
+
+`--transitionProps` の初期値は `all` ではなく、色・影・透明度・transform 系・filter 系に限定したリスト。`all` はページ読み込み時やレイアウト変化時に意図しないアニメーション（ちらつき）を起こすため使わない。
+
+実際に変化させるプロパティだけを `--transitionProps`（Lism props では `hasTransition="..."`）で明示指定する。初期値のリストに無いプロパティ（`padding`, `width`, `border-width` 等）を変化させる場合は必ず指定が要る。
+
+```html
+<a class="is--boxLink has--transition -hov:-bxsh" style="--transitionProps: box-shadow; --hov-bxsh: var(--bxsh--40)">...</a>
+```
+
+```jsx
+<BoxLink hasTransition="box-shadow" hov={{ bxsh: '40' }}>...</BoxLink>
+```
+
 ## SCSS 定義
 
 ```scss
@@ -13,7 +28,7 @@
   --duration: var(--transition-duration, 0.25s);
   --ease: ease;
   --delay: 0s;
-  --transitionProps: all;
+  --transitionProps: color, background-color, border-color, box-shadow, scale, rotate, translate, transform, opacity, filter, backdrop-filter;
   transition: var(--duration) var(--ease) var(--delay);
   transition-property: var(--transitionProps);
 }
@@ -23,7 +38,7 @@
 
 | 変数 | 役割 | デフォルト |
 | --- | --- | --- |
-| `--transitionProps` | transition 対象プロパティ | `all` |
+| `--transitionProps` | transition 対象プロパティ | `color, background-color, border-color, box-shadow, scale, rotate, translate, transform, opacity, filter, backdrop-filter` |
 | `--duration` | トランジションの長さ | `var(--transition-duration, 0.25s)` |
 | `--ease` | イージング関数 | `ease` |
 | `--delay` | ディレイ | `0s` |

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

@@ -52,26 +52,15 @@ Lism コンポーネントでは `isContainer`, `isLayer` 等の Props として
 
 | クラス | 用途 | 主な CSS 変数 |
 | --- | --- | --- |
-| `has--transition` | transition プロパティをまとめてセット。主に hoverクラス（`-hov:*`）と組み合わせて使用 | `--transitionProps`, `--duration`, `--ease`, `--delay`（グローバル上書きは `--transition-duration`） |
+| `has--transition` | transition プロパティをまとめてセット。主に hoverクラス（`-hov:*`）と組み合わせて使用。対象プロパティは `--transitionProps` で明示指定する（初期値は `all` ではなく色・影・透明度・transform 系・filter 系に限定） | `--transitionProps`, `--duration`, `--ease`, `--delay`（グローバル上書きは `--transition-duration`） |
 | `has--gutter` | コンテンツの左右に統一した余白（gutter）を設定する | `--gutter`（基準値: `--gutter--base`、初期値 `var(--s30)`） |
 | `has--snap` | `scroll-snap-` 系プロパティを CSS 変数経由でセットできるようにする | `--snapType`, `--snapAlign` 等 |
 | `has--mask` | `--maskImg` 変数と組み合わせて、要素自身にマスクを適用する | `--maskImg`, `--maskPos`（`50%`）, `--maskSize`（`contain`）, `--maskRepeat`（`no-repeat`） |
 
-Lism コンポーネントでは `hasTransition`, `hasGutter`, `hasSnap`, `hasMask` という Props として利用できます（例: `<Lism hasTransition>`）。
+Lism コンポーネントでは `hasTransition`, `hasGutter`, `hasSnap`, `hasMask` という Props として利用できます（例: `<Lism hasTransition>`）。`hasTransition` は文字列も受け付け、`--transitionProps` として出力されます（例: `<Lism hasTransition="color, opacity">`）。
 
 詳細は以下の個別ドキュメントを参照してください:
 - [has--transition](./trait-class/has--transition.md)
 - [has--gutter](./trait-class/has--gutter.md)
 - [has--snap](./trait-class/has--snap.md)
 - [has--mask](./trait-class/has--mask.md)
-
-
-## `is--` と `has--` の判断軸
-
-|  | `is--` | `has--` |
-| --- | --- | --- |
-| 意味 | 〜である（役割・存在の宣言） | 〜を持つ（機能の付与） |
-| CSS 変数 | 必須ではない | 必須（カスタマイズポイント） |
-
-- その要素が **何であるか**（役割）を表すなら → `is--`
-- その要素に **どんな機能を持たせるか**（カスタマイズポイント付き）なら → `has--`

package/dist/data/meta.js

@@ -1,6 +1,6 @@
 import { packageVersion } from '../lib/version.js';
 export const meta = {
-    generatedAt: '2026-08-16',
-    sourceCommit: '06107666',
+    generatedAt: '2026-09-02',
+    sourceCommit: 'efc6ab9a',
     docsVersion: packageVersion,
 };

package/dist/lib/markdown-utils.d.ts

@@ -1,38 +1,19 @@
-/**
- * Markdown から指定した見出しのセクションを抽出する。
- * 同レベル以上の次の見出しが来るまでの内容を返す。
- * @param md - Markdown 全文
- * @param heading - 見出しテキスト（`#` プレフィックスあり・なし両可）
- */
+/** 指定見出しから同レベル以上の次の見出しまでを抽出する。headingは#の有無を問わない。 */
 export declare function extractSection(md: string, heading: string): string;
-/**
- * Markdown から全ての見出しとその開始行を抽出する。
- */
 export declare function listHeadings(md: string): {
     level: number;
     text: string;
     line: number;
 }[];
 export interface PropRow {
-    /** Lism Prop 名（例: "fz"） */
     prop: string;
-    /** CSS プロパティ名（例: "font-size"）。変数形式（"--hl"）も含む */
     cssProperty: string;
-    /** 所属する ### セクション名 */
     sectionName: string;
-    /** プリセット値クラス列の生テキスト（例: "-fz:base, -fz:5xl, ..."） */
     presetColumn: string;
 }
-/**
- * property-class.md のテーブルを全て解析して PropRow[] を返す。
- * `| Prop | CSS プロパティ | ...` 形式のテーブルのみ対象とする。
- */
+/** Property Classの対象テーブルを解析してPropRowへ変換する。 */
 export declare function parsePropRows(md: string): PropRow[];
-/**
- * Markdown からコンポーネント名に一致するセクションを探して返す。
- *
- * components-ui.md のように各コンポーネントが `## ComponentName` で始まる場合に有効。
- */
+/** 各コンポーネントが`## ComponentName`で始まる文書向け。 */
 export declare function findComponentByHeading(md: string, name: string): string;
 /**
  * Markdown 内のテーブルセル（`` `<ComponentName>` ``）からコンポーネントを含む

package/dist/lib/markdown-utils.js

@@ -1,14 +1,8 @@
-/** 見出しの `#` レベルを返す（見出しでなければ 0） */
 function headingLevel(line) {
     const m = line.match(/^(#{1,6})\s/);
     return m ? m[1].length : 0;
 }
-/**
- * Markdown から指定した見出しのセクションを抽出する。
- * 同レベル以上の次の見出しが来るまでの内容を返す。
- * @param md - Markdown 全文
- * @param heading - 見出しテキスト（`#` プレフィックスあり・なし両可）
- */
+/** 指定見出しから同レベル以上の次の見出しまでを抽出する。headingは#の有無を問わない。 */
 export function extractSection(md, heading) {
     const headingText = heading.replace(/^#+\s*/, '').trim();
     const lines = md.split('\n');
@@ -34,9 +28,6 @@ export function extractSection(md, heading) {
     }
     return lines.slice(startIdx, endIdx).join('\n').trimEnd();
 }
-/**
- * Markdown から全ての見出しとその開始行を抽出する。
- */
 export function listHeadings(md) {
     return md.split('\n').flatMap((line, i) => {
         const lv = headingLevel(line);
@@ -45,38 +36,32 @@ export function listHeadings(md) {
         return [{ level: lv, text: line.replace(/^#+\s*/, '').trim(), line: i }];
     });
 }
-/**
- * property-class.md のテーブルを全て解析して PropRow[] を返す。
- * `| Prop | CSS プロパティ | ...` 形式のテーブルのみ対象とする。
- */
+/** Property Classの対象テーブルを解析してPropRowへ変換する。 */
 export function parsePropRows(md) {
     const lines = md.split('\n');
     const rows = [];
     let currentSection = '';
     let inPropTable = false;
+    // 見出しと対象テーブルの範囲を追跡する。
     for (const line of lines) {
         const lv = headingLevel(line);
-        // セクション見出しを追跡（### レベル）
         if (lv >= 2) {
             currentSection = line.replace(/^#+\s*/, '').trim();
             inPropTable = false;
             continue;
         }
-        // Property Class テーブルのヘッダー行を検出
         if (line.includes('Prop') && line.includes('CSS プロパティ')) {
             inPropTable = true;
             continue;
         }
-        // 区切り行はスキップ
         if (inPropTable && /^\|[-\s|:]+\|/.test(line)) {
             continue;
         }
-        // テーブルの終了を検出
         if (inPropTable && !line.startsWith('|')) {
             inPropTable = false;
             continue;
         }
-        // データ行を解析
+        // 対象テーブルの各行をPropRowへ変換する。
         if (inPropTable && line.startsWith('|')) {
             const cells = line
                 .split('|')
@@ -84,9 +69,7 @@ export function parsePropRows(md) {
                 .filter(Boolean);
             if (cells.length >= 2) {
                 const prop = cells[0].replace(/`/g, '').trim();
-                // CSS プロパティ: バッククォート除去、括弧内の注釈は保持しない
                 const cssPropertyRaw = cells[1].replace(/`/g, '').trim();
-                // `line-height`（`--hl` 経由） のような括弧注釈を除去
                 const cssProperty = cssPropertyRaw
                     .replace(/（[^）]*）$/, '')
                     .replace(/\([^)]*\)$/, '')
@@ -103,11 +86,7 @@ export function parsePropRows(md) {
 // ----------------------------------------------------------------
 // コンポーネント検索
 // ----------------------------------------------------------------
-/**
- * Markdown からコンポーネント名に一致するセクションを探して返す。
- *
- * components-ui.md のように各コンポーネントが `## ComponentName` で始まる場合に有効。
- */
+/** 各コンポーネントが`## ComponentName`で始まる文書向け。 */
 export function findComponentByHeading(md, name) {
     return extractSection(md, name);
 }
@@ -119,10 +98,9 @@ export function findComponentByHeading(md, name) {
 export function findComponentInTables(md, name) {
     const nameLower = name.toLowerCase();
     const lines = md.split('\n');
-    // コンポーネント名のパターン: `<Flex>`, `<flex>`, または単純に "flex" がテーブル行に含まれるか
     const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     const pattern = new RegExp(`\`?<${escaped}>?\`?`, 'i');
-    // まず対象行を探す
+    // コンポーネントを含むテーブル行を探す。
     let targetLineIdx = -1;
     for (let i = 0; i < lines.length; i++) {
         if (lines[i].startsWith('|') && (pattern.test(lines[i]) || lines[i].toLowerCase().includes(`\`${nameLower}\``))) {
@@ -132,7 +110,7 @@ export function findComponentInTables(md, name) {
     }
     if (targetLineIdx === -1)
         return '';
-    // 対象行を含む ## セクションの開始を遡って探す
+    // 対象行を含む##節の範囲を決める。
     let sectionStart = -1;
     let sectionLevel = 0;
     for (let i = targetLineIdx; i >= 0; i--) {
@@ -145,7 +123,6 @@ export function findComponentInTables(md, name) {
     }
     if (sectionStart === -1)
         return lines.slice(0, targetLineIdx + 20).join('\n');
-    // セクションの終端を探す
     let sectionEnd = lines.length;
     for (let i = sectionStart + 1; i < lines.length; i++) {
         const lv = headingLevel(lines[i]);

package/dist/lib/search.d.ts

@@ -1,8 +1,5 @@
 import type { DocsEntry, SearchResult } from './types.js';
-/**
- * Property Class 記法（例: "-g:5", ".-p:20", "-fz"）から prop 名を抽出する。
- * get-props-system.ts からも利用される共通ユーティリティ。
- */
+/** Property Class記法からprop名を取り出す。get-props-system.tsからも利用する。 */
 export declare function parsePropClassName(input: string): string | null;
 export interface SearchDocsOptions {
     category?: string;

package/dist/lib/search.js

@@ -4,32 +4,22 @@ function tokenize(text) {
         .split(/[\s\-_./]+/)
         .filter((t) => t.length > 0);
 }
-// ".-g:5" or "-g:5" → prop="g", value="5" / "-p" → prop="p"
 const PROP_CLASS_RE = /^\.?-([a-z][a-z0-9-]*)(:.+)?$/i;
-/**
- * Property Class 記法（例: "-g:5", ".-p:20", "-fz"）から prop 名を抽出する。
- * get-props-system.ts からも利用される共通ユーティリティ。
- */
+/** Property Class記法からprop名を取り出す。get-props-system.tsからも利用する。 */
 export function parsePropClassName(input) {
     const m = input.match(PROP_CLASS_RE);
     return m ? m[1].toLowerCase() : null;
 }
-/**
- * 検索クエリをCSSプロパティ名やProperty Class記法で展開する。
- * 例: "font-size" → "font-size fz"
- * 例: "-g:5" → "-g:5 g gap property class"
- */
+/** CSSプロパティとProperty Classを相互展開して検索語を補う。 */
 function expandQuery(query, cssPropertyMap) {
     const additions = [];
     const queryLower = query.toLowerCase();
     const parsedProp = parsePropClassName(queryLower.trim());
     if (cssPropertyMap) {
         for (const [cssProp, lismProps] of cssPropertyMap) {
-            // Property Class 記法の逆引き（例: "-g:5" の "g" → "gap"）
             if (parsedProp && lismProps.includes(parsedProp)) {
                 additions.push(cssProp);
             }
-            // CSSプロパティ名の展開（例: "font-size" → "fz"）
             if (queryLower.includes(cssProp)) {
                 additions.push(...lismProps);
             }
@@ -47,20 +37,16 @@ function scoreEntry(entry, queryTokens) {
     const headingsLower = entry.headings.join(' ').toLowerCase();
     const keywordsLower = entry.keywords.join(' ').toLowerCase();
     const snippetLower = entry.snippet.toLowerCase();
+    // titleからsnippetへ順に重みを下げる。
     for (const token of queryTokens) {
-        // title matches are weighted highest
         if (titleLower.includes(token))
             score += 10;
-        // keywords
         if (keywordsLower.includes(token))
             score += 5;
-        // headings
         if (headingsLower.includes(token))
             score += 3;
-        // description
         if (descLower.includes(token))
             score += 2;
-        // snippet
         if (snippetLower.includes(token))
             score += 1;
     }
@@ -68,7 +54,7 @@ function scoreEntry(entry, queryTokens) {
 }
 export function searchDocs(entries, query, options) {
     const { category, limit = 10, cssPropertyMap, guideTopics } = options ?? {};
-    // CSSプロパティ名・Property Class記法をLism prop名に展開してからトークナイズ
+    // CSSプロパティ名とProperty Class記法も同じ検索対象へ展開する。
     const expandedQuery = expandQuery(query, cssPropertyMap);
     const queryTokens = tokenize(expandedQuery);
     if (queryTokens.length === 0)
@@ -103,19 +89,14 @@ const SITE_BASE_URL = 'https://lism-css.com';
 function slugToPageUrl(slug) {
     return slug.startsWith('ui/') ? `${SITE_BASE_URL}/${slug}/` : `${SITE_BASE_URL}/docs/${slug}/`;
 }
-/** `sourcePath`（拡張子なし）の末尾セグメントを返す（例: `primitives/l--flex` → `l--flex`） */
 function getBasename(withoutExt) {
     const parts = withoutExt.split('/');
     return parts[parts.length - 1];
 }
-/**
- * 検索結果のページを詳しく見るための推奨フォローアップツール呼び出しを返す。
- * sourcePath による判定をカテゴリによる判定より優先する。
- */
+/** 検索結果を掘り下げる推奨ツールを返す。カテゴリよりsourcePathの規則を優先する。 */
 function getNextTool(entry, guideTopics) {
     const withoutExt = entry.sourcePath.replace(/\.mdx$/, '');
     const basename = getBasename(withoutExt);
-    // sourcePath ベースの判定（category より優先）
     if (withoutExt === 'core-components/lism-props') {
         return 'get_props_system()';
     }
@@ -128,13 +109,10 @@ function getNextTool(entry, guideTopics) {
     if (withoutExt.startsWith('property-class/')) {
         return `get_props_system(prop: "${basename}")`;
     }
-    // ui/block-examples/（Chat, Timeline 等）と ui/components/（Card, Hero 等）は、
-    // パッケージが提供するコンポーネントではなく Lism CSS での実装例ページなので get_component では解決できない。
-    // 詳細が必要な場合は検索結果の url を参照してもらう。
+    // 実装例ページはパッケージ提供コンポーネントではないためget_componentでは解決できない。
     if (withoutExt.startsWith('ui/block-examples/') || withoutExt.startsWith('ui/components/')) {
         return null;
     }
-    // category ベースの判定
     switch (entry.category) {
         case 'core-components':
             return `get_component(name: "${basename}")`;
@@ -156,12 +134,6 @@ function getNextTool(entry, guideTopics) {
  * IMPORTANT: `apps/docs/src/lib/contentSlug.ts` の `toContentSlug` と必ず同じロジックに保つこと。
  * 別ワークスペース（apps/docs）なので直接 import できず、ローカル実装で複製している。
  * apps/docs 側を変更した場合は必ずここも合わせて更新する。
- *
- * 例:
- *   `primitives/l--tileGrid.mdx`    → `primitives/l--tileGrid`
- *   `trait-class/is--boxLink.mdx`   → `trait-class/is--boxLink`
- *   `core-components/Group.mdx`     → `core-components/group`
- *   `ui/DummyText.mdx`              → `ui/dummytext`
  */
 const PRESERVE_CASE_PREFIXES = ['primitives/', 'trait-class/'];
 export function sourcePathToUrlSlug(sourcePath) {

package/dist/tools/convert-css.js

@@ -3,7 +3,6 @@ import { loadPropsMarkdown } from '../lib/load-markdown.js';
 import { parsePropRows } from '../lib/markdown-utils.js';
 import { MetaInfoSchema } from '../lib/schemas.js';
 import { success, error, READ_ONLY_ANNOTATIONS } from '../lib/response.js';
-/** 変換結果の1行 */
 const ConversionEntrySchema = z.object({
     css: z.string(),
     lismProp: z.string().nullable(),
@@ -12,7 +11,6 @@ const ConversionEntrySchema = z.object({
     confidence: z.enum(['exact', 'approximate', 'unmapped']),
     note: z.string(),
 });
-/** コンポーネント提案 */
 const ComponentSuggestionSchema = z.object({
     name: z.string(),
     reason: z.string(),
@@ -21,7 +19,6 @@ const ComponentSuggestionSchema = z.object({
 // ----------------------------------------------------------------
 // CSS パース
 // ----------------------------------------------------------------
-/** @ルール（@media 等）が含まれていないか検査する */
 function detectAtRules(cssText) {
     const atRuleMatch = cssText.match(/^@(\w[\w-]*)/m);
     if (atRuleMatch) {
@@ -29,16 +26,12 @@ function detectAtRules(cssText) {
     }
     return null;
 }
-/**
- * CSS テキストから宣言を抽出する。
- * `;` で分割する際に `url()` 等の括弧内の `;` を無視する。
- */
+/** CSSテキストから宣言を抽出する。url()などの括弧内にある`;`は区切りとみなさない。 */
 function parseCssDeclarations(cssText) {
-    // コメント除去
+    // コメントとセレクタの外枠を取り除く。
     let cleaned = cssText.replace(/\/\*[\s\S]*?\*\//g, '');
-    // セレクタ + ブレースを除去（裸の宣言リストも受け付ける）
     cleaned = cleaned.replace(/[^{}]*\{/g, '').replace(/\}/g, '');
-    // 括弧のネストを考慮して `;` で分割
+    // 括弧の深さを追いながら宣言単位に分ける。
     const segments = [];
     let current = '';
     let parenDepth = 0;
@@ -72,12 +65,10 @@ function parseCssDeclarations(cssText) {
     }
     return declarations;
 }
-/** プリセット値列から値を抽出する（例: "-fz:base, -fz:5xl" → ["base", "5xl"]） */
 function extractPresetValues(presetColumn, propName) {
     if (!presetColumn || presetColumn === '—' || presetColumn === '-')
         return [];
     const values = [];
-    // -{prop}:{value} パターンを全て抽出
     const escaped = propName.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
     const regex = new RegExp(`-${escaped}:([^,\\s\`〜]+)`, 'g');
     let match;
@@ -98,7 +89,6 @@ function buildCssPropertyMap(mappings) {
     const map = new Map();
     for (const mapping of mappings) {
         const normalized = mapping.cssProperty.toLowerCase();
-        // CSS カスタムプロパティ形式はスキップ（"--hl" 等）
         if (!normalized.startsWith('(class:')) {
             map.set(normalized, mapping);
         }
@@ -108,7 +98,6 @@ function buildCssPropertyMap(mappings) {
 // ----------------------------------------------------------------
 // 値のマッピング
 // ----------------------------------------------------------------
-/** よくある CSS 値 → Lism トークン値の変換テーブル */
 const VALUE_ALIASES = {
     'space-between': 'between',
     currentcolor: 'current',
@@ -119,10 +108,8 @@ function suggestValue(mapping, cssValue) {
     const tokens = mapping.presetValues;
     if (tokens.length === 0)
         return null;
-    // 直接一致
     if (tokens.includes(cssValue))
         return cssValue;
-    // エイリアス変換後に一致
     const aliased = VALUE_ALIASES[cssValue.toLowerCase()];
     if (aliased && tokens.includes(aliased))
         return aliased;
@@ -131,12 +118,12 @@ function suggestValue(mapping, cssValue) {
 // ----------------------------------------------------------------
 // コンポーネント検出
 // ----------------------------------------------------------------
+/** display関連の宣言から利用できるLismレイアウトコンポーネントを提案する。 */
 function detectComponent(declarations) {
     const propMap = new Map(declarations.map((d) => [d.property, d.value.toLowerCase()]));
     const display = propMap.get('display');
     const flexDirection = propMap.get('flex-direction');
     const placeItems = propMap.get('place-items');
-    // Stack: flex + column
     if (display === 'flex' && (flexDirection === 'column' || flexDirection === 'column-reverse')) {
         return {
             name: 'Stack',
@@ -144,7 +131,6 @@ function detectComponent(declarations) {
             implicitCss: ['display: flex', 'flex-direction: column'],
         };
     }
-    // Center: grid + place-items: center
     if (display === 'grid' && placeItems === 'center') {
         return {
             name: 'Center',
@@ -152,7 +138,6 @@ function detectComponent(declarations) {
             implicitCss: ['display: grid', 'place-items: center'],
         };
     }
-    // Flex
     if (display === 'flex') {
         return {
             name: 'Flex',
@@ -160,7 +145,6 @@ function detectComponent(declarations) {
             implicitCss: ['display: flex'],
         };
     }
-    // Grid
     if (display === 'grid') {
         return {
             name: 'Grid',
@@ -177,6 +161,7 @@ function findCategory(mappings, propName) {
     const found = mappings.find((m) => m.prop === propName);
     return found?.sectionName ?? 'unknown';
 }
+/** 変換結果からJSX使用例を組み立てる。 */
 function buildExample(conversions, component) {
     const tagName = component?.name ?? 'Lism';
     const implicitCssSet = new Set(component?.implicitCss.map((c) => c.split(':')[0].trim()) ?? []);
@@ -188,7 +173,7 @@ function buildExample(conversions, component) {
             styles.push(conv.css);
             continue;
         }
-        // コンポーネントが暗黙的に付与する CSS はスキップ
+        // コンポーネントが暗黙に持つCSSは重複出力しない。
         if (implicitCssSet.has(cssProp))
             continue;
         if (conv.suggestedValue != null) {
@@ -232,7 +217,6 @@ export function registerConvertCss(server) {
         annotations: READ_ONLY_ANNOTATIONS,
     }, ({ css }) => {
         try {
-            // @ ルール検出
             const atRuleError = detectAtRules(css);
             if (atRuleError) {
                 return error(atRuleError);
@@ -244,7 +228,7 @@ export function registerConvertCss(server) {
             if (declarations.length === 0) {
                 return error('No CSS declarations found. Provide CSS in "property: value;" format.');
             }
-            // 各宣言を変換
+            // 各宣言をLism Propと候補値へ変換する。
             const conversions = declarations.map((decl) => {
                 const mapping = cssPropertyMap.get(decl.property);
                 if (!mapping) {
@@ -272,9 +256,8 @@ export function registerConvertCss(server) {
                             : `Use as a custom value (category: ${category})`,
                 };
             });
-            // コンポーネント検出
+            // 変換結果からコンポーネント候補と使用例を組み立てる。
             const suggestedComponent = detectComponent(declarations);
-            // 使用例
             const example = buildExample(conversions, suggestedComponent);
             return success({
                 conversions,