lism.config.js で設定する

lism.config.js は、Lism CSS の設定を書いておくファイルです。新しいクラスの値を足したり、トークン（決まった値）を増やしたり、xs・xl のブレイクポイントを使えるようにしたりできます。ほかの方法との選び方は カスタマイズの選び方 にまとめています。

使う前に知っておくこと#

• lism.config.js を読むのは @lism-css/plugin というパッケージです。これが無いと、ファイルを置いても何も起きません
• ファイルは、プロジェクトのいちばん上のフォルダ（ルート）に置きます。lism.config.ts・lism.config.mjs という名前でもかまいません
• 統合プラグイン lismCss() は Vite・Astro 用です。Next.js 用には withLism() があります。どちらも使わない構成なら、CLI（コマンドで動かす道具）で CSS だけを作ります

セットアップ#

1. パッケージを入れる#

pnpm add -D @lism-css/plugin

2. 統合プラグインを足す#

Astro なら astro.config.mjs、Vite なら vite.config.js に、lismCss() を足します。

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

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

import { defineConfig } from 'vite';
import { lismCss } from '@lism-css/plugin/vite';

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

これだけで、次の3つがまとめて動きます。

• lism.config.js を読み込む
• 設定を CSS に自動で反映する
• 型定義のファイル lism-env.d.ts を自動で作る

3. 設定ファイルの場所#

プラグインは、ルートから lism.config.ts → lism.config.mjs → lism.config.js の順に探します。別の場所に置くときは、configPath で場所を教えます。

integrations: [lismCss({ configPath: './config/lism.config.js' })],

設定ファイルの書き方#

書ける項目#

export default {
  props: {
    // Property Class の設定
  },
  tokens: {
    // トークンの値
  },
  traits: {
    isHoge: 'is--hoge',
  },
  // breakpoints と isFullMode もここに書く
};

props に書ける設定#

props には、1つの Property Class ごとに、次のような設定を書きます。今の設定は lism-css/default-config から読み込めます。最初から入っているトークンの値は デザイントークン・文字のトークン・色のトークン に、Trait の一覧（isContainer → is--container など11個）は Trait Class ってなに？ にあります。

例：値やクラスを足す#

import DEFAULT_CONFIG from 'lism-css/default-config';
const { props } = DEFAULT_CONFIG;

export default {
  props: {
    // 今ある ta に justify を足す
    ta: { presets: [...(props.ta.presets || []), 'justify'] },
    // 今ある p に box（2em）を足す
    p: { utils: { box: '2em' } },
    // 新しく filter を作る（最初からは入っていない）
    filter: { prop: 'filter', utils: { blur: 'blur(3px)' } },
  },
  tokens: {
    // 今のトークンに足される（--lts--2xl と -lts:2xl ができる）
    lts: { '2xl': '.5em' },
  },
  traits: {
    isHoge: 'is--hoge',
  },
};

この設定で、コンポーネントは次のクラスを出すようになります。

<Box p="box" ta="justify" filter="blur" lts="2xl" isHoge>Box</Box>
// → <div class="l--box is--hoge -p:box -ta:justify -filter:blur -lts:2xl">Box</div>

クラスの CSS と型は、統合プラグインがあれば自動で用意されます。

トークンを足す#

tokens は { 名前: 値 } の形で書きます。今のトークンに足し合わされます。トークンに値を書くと、そのクラスと、:root の CSS 変数の両方ができます。

• 値に '-' を書くと、名前だけを登録して、値は出しません（palette.keycolor や bdrs.inner のように、値をほかで決めているもの）
• vars の中の --L・--C・--fz-mol・--hl-unit・--s-unit は、ほかのトークンの計算に使う値です。今ある値を書きかえるために使います

export default {
  tokens: {
    color: {
      // --success ができて、c="success" などで使える
      success: 'oklch(0.6 0.15 150)',
    },
  },
};

ブレイクポイント（xs・xl）を使えるようにする#

main.css のブレイクポイントは、最初は次のとおりです。0 は「使わない（CSS を出さない）」という意味です。

xs・xl を使うには、breakpoints に、使いたいものの幅だけを書きます。

export default {
  breakpoints: {
    xs: '360px',
    xl: '1400px',
  },
};

これで、ブレイクポイントに対応する（bp: 1 の）すべての Property Class に、-p_xs・-p_xl のようなクラスが増えます。コンポーネントでも xs・xl を書けるようになります。

<Box p={{ base: 20, xs: 10, sm: 30 }} />

SCSS で組み立てる構成では、$breakpoints でも同じことができます（SCSS で設定する）。

isFullMode#

full.css（全部入りの CSS）を読み込んでも、それだけではコンポーネントが出すクラスは変わりません。たとえば t="20" は、style 属性で出たままです。コンポーネントの出力も full.css に合わせたいときに、isFullMode を true にします。

export default {
  isFullMode: true,
};

true にすると、次のように変わります。

• t="20" のような値が、-t クラスと --t 変数で出るようになります
• ta={['start', 'center']} のようなブレイクポイントの指定が、full.css に対応するクラスがあれば警告なしで使えます
• 変数だけを出す Props（isVar のもの）は、bds・bdc を除いて、ブレイクポイントに対応しません。contentSize などの isVar のもの、lh、border をまとめて書く Props は、true にしてもブレイクポイントを書くと警告が出ます
• 設定は「最初の設定 → full 用の設定 → lism.config.js の props」の順に重ねられ、後ろのものが勝ちます

型（TypeScript）#

型には2種類あります。

設定ファイルの型（LismConfig）#

lism-css/config-types から LismConfig を読み込むと、エディタが項目の名前や形を補ってくれたり、まちがいを教えてくれたりします。props を porps と打ちまちがえても、すぐ分かります。

lism.config.ts では、satisfies LismConfig を付けるのがおすすめです。

import type { LismConfig } from 'lism-css/config-types';

export default {
  props: {
    filter: { prop: 'filter', utils: { blur: 'blur(3px)' } },
  },
  breakpoints: {
    xs: '360px',
  },
} satisfies LismConfig;

JavaScript の lism.config.js では、JSDoc の @type を付けます。

/** @type {import('lism-css/config-types').LismConfig} */
export default {
  props: {
    filter: { prop: 'filter', utils: { blur: 'blur(3px)' } },
  },
};

コンポーネントの型（lism-env.d.ts）#

設定の中身から、統合プラグインが lism-env.d.ts を自動で作ります。自分で型を書く必要はありません。このファイルは git にコミットします。

• 足した Props や Trait は、CustomPropRegistry・CustomTraitRegistry を広げる形で型に入ります。<Box filter="blur" isHoge> も型のエラーになりません
• breakpoints で使えるようにした xs・xl も、型と補完に入ります
• isFullMode: true のときは、ta などのブレイクポイントの書き方も型のエラーになりません
• 今ある Props に足した値（ta="justify" など）は、CustomPropValueRegistry に入り、補完の候補に増えます。もともと今ある Props はどんな文字でも受け取るので、値を足さなくても型のエラーにはなりません

統合プラグインを使わない構成で、isFullMode の型だけを切り替えるときは、型定義のファイルに次のように書きます。キーの名前は何でもよく、1つあれば full 用の型になります。

// src/lism-env.d.ts
import 'lism-css';

declare module 'lism-css' {
  interface FullModeRegistry {
    enabled: true;
  }
}

統合プラグインを使わないとき#

統合プラグインが無いと、lism.config.js は自動では使われません。CSS は CLI で作ります。

コンポーネントも lism.config.js を読まないので、p="box" と書いてもクラスになりません。コンポーネントからは : を付けて p=":box" と書きます（Lism Props（コンポーネントの指定））。ブラウザで描くコンポーネントなら、window._LISM_CSS_CONFIG_ に同じ設定を入れて使うこともできます（isFullMode はできません）。

CLI で CSS を作る#

npx lism-css build

lism.config.js を読み込んで、設定を入れた CSS を作ります。上の「例：値やクラスを足す」の設定なら、lism-css/main.css に次の CSS が足されます。

.-ta\:justify {
  text-align: justify;
}
.-p\:box {
  --p: 2em;
}
.-filter\:blur {
  filter: blur(3px);
}
.-lts\:2xl {
  letter-spacing: var(--lts--2xl);
}

-p:box が padding ではなく --p になっているのは、p が alwaysVar の Props だからです。padding: var(--p) のほうは、main.css に最初から入っています。

is-- のクラスの見た目は自動では作られません。自分で CSS を書いて読み込みます。

@layer lism-trait {
  .is--hoge {
    /* ... */
  }
}

npx lism-css build --full

関連するページ#

• カスタマイズの選び方
• SCSS で設定する
• 使わない CSS を消す（CSS Purge）
• 画面の幅で切り替える（レスポンシブ）
• CSS ファイルの種類