Lism Mockup Guide

Lism Mockup 実装ガイド（@lism-css/mockup）

Lism Mockupを使って画面モックアップを作成するための実装ガイドです。画面モックアップは@lism-css/mockupのデータディレクトリ（1画面=1ファイルのpages/＋小さな設定ファイル）として組みます。プレビューアプリ（ビューア）はCLIに同梱されており、モックアップ側にビルド設定やpackage.jsonは不要です。このスキルが扱うのは「モックアップとしてどんなファイルを置けるか（データ契約）」と「initからcheckまでのワークフロー」だけです。

前提（必須）: lism-css-guideを併用する。 このスキルはlism-css-guideが同じ階層に導入されていることを前提にします。マークアップ自体の書き方 — Primitive選定・トークン照合・Property Class・レスポンシブ設計 — はすべてlism-css-guideの実装フローに従ってください。無い場合は、lism-cli skill add（引数なしで全スキル一括導入）での追加をユーザーに案内してください。guideなしで、推測だけでモックアップを書かないでください。

バージョン情報: このガイドは@lism-css/mockup@0.1.0時点の情報に基づきます。

役割分担

• このスキル: データ契約（ファイル構成・スキーマ・import規則）と、init→実装→check→devのワークフロー
• lism-css-guide: マークアップの書き方すべて。実行レベル判定・実装前チェック・提出前セルフチェックはguideの手順をそのまま実行する（../lism-css-guide/SKILL.md）
• 契約の正本: lism-mockup initが生成するREADME.md（契約説明書）。このスキルの要約と食い違う場合は生成物側を優先する

コマンド

[dir]省略時はカレントディレクトリ。ローカルにインストール済みならbin名lism-mockupでも実行できる。Node要件は^20.19.0 || >=22.12.0。

ワークフロー（厳守）

1. init: データディレクトリがまだ無ければ、必ずnpx @lism-css/mockup init <dir>から始める。既にデータディレクトリがある場合はinitを実行せず、既存の生成物を読む
   • initは生成予定のファイルと衝突すると無変更で非0終了する（生成対象と無関係な既存ファイルは妨げにならない）。--forceは衝突ファイルを上書きするオプションなので、ユーザーの明示的な指示なしに使わない
2. 契約確認: 生成されたREADME.md（契約説明書）を必ず読む。サンプルページ（pages/）の構成を踏襲し、新しい構造を発明しない
3. 実装: pages/*.jsx|tsxを書く。ここからはlism-css-guideの実装フロー（実行レベル判定→実装前チェック→実装→提出前セルフチェック）に従う
4. 自己検証: npx @lism-css/mockup check <dir>を実行する。checkが非0で終了する間は、完成と報告してはいけない。 エラーには対象ファイルと原因が表示されるので、修正して再実行する
5. ブラウザ確認: devサーバーは終了しない常駐プロセス。フォアグラウンドで起動して終了を待ってはいけない。 バックグラウンドで起動するか、ユーザーに起動してもらう。見た目・render結果の確認はユーザーの役割
6. 完了報告: checkが通ったことを報告する。checkはrender時エラー（後述）を検出しないため、devでのブラウザ目視確認の依頼を報告に含める

データ契約（要約）

データディレクトリの構成:

mockup/
├── mockup.config.json      # 必須 — schemaVersion＋追加import＋表示メタデータ
├── tokens.json             # 任意 — デザイントークンの上書き
├── tokens.dark.json        # 任意 — ダーク時の値（initでは生成されない）
└── pages/                  # 必須 — 1ファイル=1画面（最低1ページ）
    ├── landing.jsx
    ├── components.jsx      # 予約ID — 共通部品の一覧（手で維持するページ）
    └── admin/
        ├── settings.jsx
        └── settings.css  # ページ付随CSS（settings.jsxが相対importする）

pages/

• 1ファイル=1画面。propsを取らないReactコンポーネントをdefault exportする
• ページID = pages/からの相対パスから拡張子を除いたもの（pages/admin/settings.jsx → admin/settings）。サブディレクトリ可
• 画面はファイルシステムから自動発見される。ファイルを置くだけでよく、configへの登録は不要
• .jsx / .tsxの両方が使えるが、型チェックは行われない（型は剥がされるだけ）。同名の.jsxと.tsxの併存はID衝突エラー
• useState等のローカルUI状態とイベントハンドラは書いてよい。API通信・認証・永続化・業務ロジックは書かない（モックアップは画面の絵であり、アプリではない）
• ページ付随のCSS・画像は相対importで置ける。CSSに書くのは擬似要素・子孫セレクタ・属性状態などProperty Class / Propsで表せない宣言だけ（判断はlism-css-guideのproperty-class.md）。c--*のCSSは@layer lism-custom内に置く

mockup.config.json（必須）

{
  "schemaVersion": 2,
  "title": "Lism Mockup",
  "imports": ["lucide-react"],
  "pages": {
    "landing": { "label": "Landing", "category": "Marketing", "order": 10 }
  }
}

• schemaVersionは必須で2
• titleは任意。importsは追加でimportを許可するパッケージ（後述）。pagesは表示メタデータ（label / category / order）の上書きのみで、並び順の既定はページIDの辞書順
• componentsは予約ページID（後述）。ビューアが「UI Parts」という名前でサイドバーの「Viewer」グループに固定表示するため、ここにエントリを書く必要はない（label / category / orderはいずれも無視される）
• 実在しないページIDの参照はエラー（消し忘れ・タイポのシグナル）。未知のトップレベルキーもエラー

tokens.json（任意）

lism.config互換のtokensオブジェクト（lism.config.jsのtokensに書く形と同じ）:

{
  "color": { "brand": "#2f6f5e", "success": "oklch(62% 0.14 152)" },
  "space": { "60": "calc(var(--s-unit) * 12)" }
}

• トップレベルはLism CSSに実在するトークングループ（color / space / fz / bdrs / bxshなど）のみ
• 新キーを追加できるのはcolorだけ。 他のグループは既存キーの値上書きのみ
• 違反は警告にならない。checkとdevの起動時は非0終了し、dev起動後の監視中に違反へ変わった場合はサーバー継続のままターミナルとブラウザへエラーが表示される
• どのトークンを使う・上書きするかの判断はlism-css-guideのtokens.mdに従う

colorの新キーにはProperty Classが生成されない。 例えばcanvasを追加しても-bgc:canvasというクラスは存在しない（書いてもCSSが無い）。新キーの色は次のどちらかで使う:

<Group bgc="canvas">…</Group>   {/* props経由 → var(--canvas)に変換される */}

@layer lism-custom {
  .c--saveStatus::before { background-color: var(--success); }  /* CSS内はvar()直書き */
}

tokens.dark.json（任意）

ダーク時の値だけを書くファイル。形式はtokens.jsonと同じで、ファイルの有無＝ダーク対応の有無（initでは生成されないので、必要になったら自分で作る）。

• 書けるのはライト側がCSS変数として実際に持っているトークンの上書きだけ。基準はマージ後のライト（Lismデフォルト＋tokens.jsonが追加したキー）なので、tokens.jsonに書いていないcolor.base / color.textもダークだけで指定できる
• 新キーの追加は不可（colorの例外はダークには適用されない）。ライト側が実値を持たないキー（bdrs.inner / flow.s / palette.keycolorなど）もエラー。ただしtokens.jsonで実値を与えていれば上書きできる
• グループの制限は無い（color / palette / space / fz / bxsh / varsなど全て）。違反はtokens.jsonと同じくエラー
• 値は.set--darkクラスの中に出力される（:root.set--darkではない）。ページ全体でも一部でも、className="set--dark"を付けた箱の中だけダークになる
• @media (prefers-color-scheme: dark)は出力されない。OS設定への追従やモード切替UIが要る場合はページ側で用意する
• vars（--L等）を上書きすると、それを参照しているライト側トークン（palette.* / space.* / fz.*など）も同じ.set--darkブロックへ自動で再宣言される（var()は宣言した要素で解決されるため）

import規則

bare importは許可リストのパッケージのみ。次の標準パッケージは設定不要で常に使え、CLI側のnode_modulesで解決される（ユーザープロジェクトへ依存を追加する必要はない）。

それ以外のパッケージはmockup.config.jsonのimportsにパッケージ名だけを書いて許可する（"lucide-react"は可、"lucide-react/icons"は不可）。

• 宣言したパッケージは、データディレクトリを含むプロジェクト側にインストールする。未インストールならbundle前に停止する
• lucide-reactはCLIが提供するためインストール不要。importsへの記載は必要（initが生成する設定には最初から入っている）。使えるのはルートからの名前付きimportで、アイコン（Bell / BellIcon / Sidebarなど）とIcon / createLucideIconのみ。icons（全アイコンのレコード）とlucide-react/icons/bellのようなサブパスは提供していない（どちらもcheckがエラーにする）
• 標準パッケージをimportsに書くとエラーになる（常時許可されているため）
• devは起動時に一度だけ許可リストを作る。importsを編集したらdevを再起動する
• @lism-css/uiにルートexportは無い。 必ず@lism-css/ui/react/<Component>から個別importする
• 許可リスト内でも、パッケージが実際にexportしているパスのみ許可（存在しないサブパスは拒否される）
• 相対importはデータディレクトリ内で完結させ、対象は.jsx / .tsx / .css / 画像（.png / .jpg / .jpeg / .gif / .svg / .webp）のみ
• 絶対パス・/@fs/パス・../によるデータディレクトリ外への脱出・許可外のbare importは契約違反としてエラーになる

checkの保証範囲

checkはdevと同じ発見・検証・import規則を通るため、両者の結果は食い違わない。保証するのは次の3点。

1. mockup.config.json / tokens.json / tokens.dark.jsonのスキーマ（schemaVersion含む）
2. import境界（上記の規則）
3. 全ページのbundle成功（構文エラー・未解決import・変換エラーを対象ファイルと原因つきで報告）

renderは実行しない。 次はcheckでは検出できず、devでの人間のブラウザ確認に委ねる:

• default exportがReactコンポーネントでない
• 初回render中の例外・ブラウザAPI依存のエラー
• 画面の見た目が意図通りか

「check成功」は「モックアップが整形式でビルドできる」であり「画面が正しい」ではない。逆に、checkが失敗しているモックアップを完成と報告することは禁止。

モックアップ特有の注意

• Astroプロジェクト向けのモックアップでもReact（.jsx / .tsx）で書く。 モックアップの目的は「デザインと、それを実装するクラス・コンポーネントが把握できること」であり、import文を実プロジェクトと厳密に揃える必要はない
• ビューアにカラーモードの切替UIは無い。 ダーク確認はtokens.dark.json＋className="set--dark"で行い、切替UIが要る場合はモックのページ側に作る。色をトークンで書いていればそのまま両モードを確認できる（直書き色を避けるのはlism-css-guideの通常ルール通り）
• ビューアの既定表示はギャラリー。 予約IDcomponentsを除く各ページがiframeカードでカテゴリごとに並び、カードをクリックするとそのページの単体表示になる。サイドバーは「Viewer」グループ（Design tokens → UI Parts → All pages）から始まり、その下にカテゴリ別のページが並ぶ。「All pages」でギャラリーへ戻れる。「Design tokens」はtokens.jsonとLismデフォルトをマージしたトークン一覧をビューアが自動生成する。tokens.dark.jsonがある場合は、ダークで値が変わるグループの直後にcolor (dark)のようなセクションが増え、.set--darkスコープの中で描画される。サイドバーのページ名は、ギャラリー表示中でも常に単体表示で開く
• モック内で定義した共通部品の一覧は自動生成できない。 そのためinitのひな形にはpages/components.jsx（ボタン・フォーム部品・バッジ・カードなど、そのモックで使う部品を並べたページ）が含まれる。共通部品を追加したらこのページの一覧にも載せる。componentsは予約IDで、ビューアはこれを「UI Parts」という固定の名前で「Viewer」グループに表示し、カテゴリ別の一覧とギャラリーからは除外する。一覧が不要ならファイルごと削除してよい（別の名前にすると普通の画面として扱われる）
• ページはただのJSX（任意コード実行）でサンドボックスは無い。信頼できるモックアップだけを実行する

このスキルファイル自身のアップデート方法

ユーザーがスキル更新を依頼した場合は、lism-cli skill addまたはlism-cli skill updateを案内してください。最新を確認したい場合は、GitHubリポジトリのskills/lism-mockup-guideを確認してください。