インストール

Lism CSSを利用するための手順を解説します。

CSS設計のみを導入する

シンプルなHTMLサイトの場合など、CSSファイルのみを読み込む場合はCDN経由で利用できます。

<link href="https://cdn.jsdelivr.net/npm/lism-css@0.22.2/dist/css/main.css" rel="stylesheet" />

もちろん、CSSファイルをダウンロードして読み込んでもOKです。

クイックスタート

ゼロからセットアップする場合は create lism を使うのが最短です。テンプレートと出力先は対話プロンプトで選択できます。

pnpm create lism@latest

npm create lism@latest

yarn create lism

lism-cli の lism create と等価です。

テンプレートを指定して実行する

--template オプションを付けると、対話プロンプトをスキップしてテンプレートを直接指定できます。

pnpm create lism@latest --template minimal-astro

npm create lism@latest -- --template minimal-astro

yarn create lism --template minimal-astro

利用可能なテンプレート

React/Astro コンポーネントを使用する

React(.tsx)、Astro(.astro)形式のコンポーネントを lism-cssとしてnpmパッケージで配布しています。

1. パッケージ(lism-css)のインストール

npm i lism-css

pnpm add lism-css

yarn add lism-css

2. CSS(main.css)の読み込み

import 'lism-css/main.css';

Next.js（16 以降）では、ルートレイアウト（App Router なら app/layout.tsx）で読み込みます。lism.config.js の反映や型生成も行う場合は、後述の Next.js での導入で @lism-css/plugin をセットアップしてください。

3. コンポーネントの読み込み

import { Box, Flex, ... } from 'lism-css/react';

import { Box, Flex, ... } from 'lism-css/astro';

Next.js での導入

Next.js では、@lism-css/plugin の withLism() で設定ファイルをラップすることで、lism.config.js を反映した CSS の生成・型生成・読み込みをまとめてセットアップできます。

1. パッケージのインストール

lism-css 本体に加えて、ビルド用の @lism-css/plugin を導入します。

pnpm add lism-css
pnpm add -D @lism-css/plugin

npm i lism-css
npm i -D @lism-css/plugin

yarn add lism-css
yarn add -D @lism-css/plugin

2. next.config.mjs を withLism() でラップする

import { withLism } from '@lism-css/plugin/next';

/** @type {import('next').NextConfig} */
const nextConfig = {};

export default withLism(nextConfig);

withLism() は lism.config.js を読み込み、設定を反映した CSS を .lism-css/css/ 以下へ事前生成します。そのうえで lism-css/main.css などの import を生成済み CSS へ差し替え（alias）ます。Next.js には Vite / Astro のような「import をその場で変換する仕組み」が無いため、この方式を取っています。既存の nextConfig は壊さずにマージされます。

3. CSS とコンポーネントの読み込み

ルートレイアウト（App Router なら app/layout.tsx）で main.css をグローバルに読み込みます。

import 'lism-css/main.css';

コンポーネントは lism-css/react から import します。

import { Box, Flex } from 'lism-css/react';

4. lism.config.js でカスタマイズする（任意）

プロジェクトのルートに lism.config.js を置くと、props やトークンを追加・上書きできます。next dev の実行中にこのファイルを保存すると CSS と型が自動で再生成されるため、開発サーバーの再起動は不要です。

export default {
  tokens: {
    color: {
      // 例: `--success` を出力し、`-c:success` / `-bgc:success` などで使えるようにする
      success: 'oklch(0.6 0.15 150)',
    },
  },
};

設定できる項目の詳細はカスタマイズページを参照してください。

5. 生成ファイルの扱い

withLism() は、有効化したブレイクポイントや追加した props / traits を反映した lism-env.d.ts をプロジェクト直下に自動生成します。型補完を効かせるため、tsconfig.json の include に追加し、git にコミットしてください。

{
  "include": ["next-env.d.ts", "lism-env.d.ts", "**/*.ts", "**/*.tsx"]
}

一方、.lism-css/（生成された CSS）はビルド出力なので .gitignore に追加します。

# .gitignore
.lism-css/

Lism UI の導入

アコーディオンやタブ、モーダルなどのUIコンポーネントは、別パッケージ @lism-css/ui として提供しています。

パッケージとして利用する

npm i @lism-css/ui

pnpm add @lism-css/ui

// Reactコンポーネントをインポートする例
import { Accordion } from '@lism-css/ui/react/Accordion';
import { Tabs } from '@lism-css/ui/react/Tabs';
import { Button } from '@lism-css/ui/react/Button';

// .astro でインポートする例
import { Accordion } from '@lism-css/ui/astro/Accordion';
import { Tabs } from '@lism-css/ui/astro/Tabs';
import { Button } from '@lism-css/ui/astro/Button';

// 一括 import も動作はしますが、推奨はしません
import { Accordion, Tabs, Button } from '@lism-css/ui/react';

CLI でプロジェクトにコピーする

lism-cli の lism ui add を使うと、UIコンポーネントのソースコードを自分のプロジェクトにコピーし、自由にカスタマイズできます。コンポーネント名は import するときと同じ PascalCase で指定します。

# コンポーネントを追加（初回は対話形式でセットアップ）
npx lism-cli ui add Accordion

# 複数コンポーネントをまとめて追加
npx lism-cli ui add Accordion Modal Tabs NavMenu

# 全コンポーネントを追加
npx lism-cli ui add --all

名前は大文字小文字・ハイフン・アンダースコアを無視して解決するため、NavMenu / navmenu / nav-menu / nav_menu のいずれでも同じコンポーネントに解決されます。

未使用CSSの削除（パージ）

本番ビルド時に未使用の Lism CSS クラスを取り除き、CSS ファイルを軽量化するパージ機能は @lism-css/plugin で提供しています。Vite / Astro で使う場合は @lism-css/plugin を追加し、対象エントリ（@lism-css/plugin/vite または @lism-css/plugin/astro）の lismCss() に purge: true オプションを渡します。

pnpm add -D @lism-css/plugin

// astro.config.mjs の例
import { defineConfig } from 'astro/config';
import { lismCss } from '@lism-css/plugin/astro';

export default defineConfig({
  integrations: [lismCss({ purge: true })],
});

// vite.config.js の例
import { defineConfig } from 'vite';
import { lismCss } from '@lism-css/plugin/vite';

export default defineConfig({
  plugins: [lismCss({ purge: true })],
});

purge: { report: true } のようにオブジェクトで渡すと、purge プラグインの各オプションも指定できます。

詳しいセットアップ・オプション・safelist の指定方法は CSS Purge を参照してください。

AIツール連携

AIコーディングツール（Claude Code, Cursor, Codex など）で Lism CSS を効率よく扱うためのセットアップも用意しています。

• Skills — プロジェクトにファイルを配置し、AIに設計ルールを伝える
• MCP Server — AIツールがコンポーネント・Props・トークンの情報をリアルタイムに参照できる