Installation

This guide walks you through setting up and using Lism CSS.

CSS-only setup

For simple HTML sites or other cases where you only need the CSS file, you can use it via CDN.

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

You can also download the CSS file and load it locally.

Quick start

The fastest way to start from scratch is using create lism. The template and output directory can be chosen through interactive prompts.

pnpm create lism@latest

npm create lism@latest

yarn create lism

This is equivalent to lism create from lism-cli.

Specify a template

Pass --template to skip the interactive prompt and choose a template directly.

pnpm create lism@latest --template minimal-astro

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

yarn create lism --template minimal-astro

Available templates

Use React/Astro components

React (.jsx) and Astro (.astro) components are distributed as an npm package.

1. Install the package

npm i lism-css

pnpm add lism-css

yarn add lism-css

2. Import the CSS

import 'lism-css/main.css';

In Next.js (16 or later), import it in your root layout (app/layout.tsx for App Router). If you also want to apply lism.config.js settings and generate types, set up @lism-css/plugin as described in Setting up with Next.js below.

3. Import components

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

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

Setting up with Next.js

In Next.js, wrapping your config with withLism() from @lism-css/plugin lets you set up CSS generation, type generation, and CSS loading — all reflecting your lism.config.js — in one step.

1. Install the packages

In addition to lism-css itself, install @lism-css/plugin for the build integration.

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. Wrap next.config.mjs with withLism()

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

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

export default withLism(nextConfig);

withLism() reads lism.config.js and pre-generates CSS reflecting your settings under .lism-css/css/. It then replaces (aliases) imports such as lism-css/main.css with the pre-generated CSS. This approach is necessary because Next.js does not have a mechanism to transform imports on the fly like Vite or Astro. Your existing nextConfig is merged without modification.

3. Load the CSS and components

Import main.css globally in your root layout (app/layout.tsx for App Router).

import 'lism-css/main.css';

Import components from lism-css/react.

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

4. Customize with lism.config.js (optional)

Placing a lism.config.js at the root of your project lets you add or override props and tokens. Saving this file while next dev is running automatically regenerates the CSS and types, so no server restart is needed.

export default {
  tokens: {
    color: {
      // Example: outputs `--success` and makes it available as `-c:success` / `-bgc:success`, etc.
      success: 'oklch(0.6 0.15 150)',
    },
  },
};

See the Customize page for the full list of available options.

5. Handling generated files

withLism() automatically generates lism-env.d.ts at the project root, reflecting enabled breakpoints and any added props/traits. Add it to the include array in tsconfig.json and commit it to git so type completion works correctly.

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

On the other hand, .lism-css/ (the generated CSS) is build output and should be added to .gitignore.

# .gitignore
.lism-css/

Installing Lism UI

UI components such as accordions, tabs, and modals are provided as a separate package, @lism-css/ui.

Use as a package

npm i @lism-css/ui

pnpm add @lism-css/ui

// Example: importing React components
import { Accordion } from '@lism-css/ui/react/Accordion';
import { Tabs } from '@lism-css/ui/react/Tabs';
import { Button } from '@lism-css/ui/react/Button';

// Example: importing in .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';

// Bulk import works, but is not recommended
import { Accordion, Tabs, Button } from '@lism-css/ui/react';

Copy to your project with the CLI

With lism-cli’s lism ui add, you can copy UI component source code directly into your project and customize it freely. Specify component names in PascalCase — the same form you use when importing.

# Add a component (interactive setup on first run)
npx lism-cli ui add Accordion

# Add multiple components at once
npx lism-cli ui add Accordion Modal Tabs NavMenu

# Add all components
npx lism-cli ui add --all

Name resolution is case-insensitive and ignores hyphens and underscores, so NavMenu / navmenu / nav-menu / nav_menu all resolve to the same component.

Strip unused CSS (purge)

The purge feature that removes unused Lism CSS classes from your production build is provided by @lism-css/plugin. For Vite / Astro projects, install @lism-css/plugin and pass purge: true to lismCss() from the matching entry (@lism-css/plugin/vite or @lism-css/plugin/astro).

pnpm add -D @lism-css/plugin

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

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

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

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

You can also pass an object like purge: { report: true } to configure additional purge plugin options.

See CSS Purge for the full setup, options, and safelist usage.

AI Tool Integration

Set up AI coding tools (Claude Code, Cursor, Codex, etc.) to work effectively with Lism CSS.

• Skills — Place a file in your project to communicate design rules to AI agents
• MCP Server — AI tools can reference component, Props, and token information in real time