Tired of Overthinking CSS Architecture? Meet Lism CSS

Ryo — Mon, 06 Apr 2026 16:34:14 +0000

CSS architecture is an eternal challenge in web development.

Modern CSS features evolve every day. But how far do you adopt them, how do you combine them, and how do you translate all of that into a cohesive CSS design for your entire site? Naming conventions? Token design? Layer structure? Do you find yourself facing the same questions every project?

Tailwind CSS is a powerful option — but its No-CSS approach of handling everything through utility classes feels too extreme for many developers. There are times when you simply want to write CSS freely.

A framework that takes full ownership of CSS architecture while still embracing the act of writing CSS — that's what Lism CSS offers as a new alternative.

What is Lism CSS?

Lism CSS is a lightweight CSS design framework for building the skeleton of websites at a comfortable, beautiful pace.

Typography design that naturally creates a pleasant rhythm throughout your site.
A layout-first module design that makes wireframing quick and easy.
A flexible utility design leveraging CSS variables with responsive support built in.

https://lism-css.com/en/

It's not just a collection of utility classes.

It comprehensively defines design token architecture, naming conventions, and @layer hierarchy — taking full ownership of your site's entire CSS design.

It blends the layout primitives of Every Layout, the utility-first approach of Tailwind CSS, and the layer design of ITCSS into a unique CSS architecture of its own.

Why Lism CSS?

No need to design your own CSS architecture. — From base styling and @layer hierarchy to tokens and naming conventions, it handles your entire site's CSS design end-to-end.
Just load the CSS and you're ready. — No build step or configuration required. Simply import a single lightweight stylesheet.
Even better with React & Astro. — Dedicated components let you handle responsive layouts and layout composition intuitively via props.

Installation

For HTML Sites

To use Lism CSS in a plain HTML site, simply load the CSS file from a CDN:

<!-- Load the stylesheet from CDN -->
<link href="https://cdn.jsdelivr.net/npm/lism-css@0.11.0/dist/css/main.css" rel="stylesheet" />

For React or Astro Projects

In modern environments like React, Astro, or Next.js, installing the npm package (lism-css) is the recommended approach.

# Install the package
npm install lism-css

// Import the CSS globally
import "lism-css/main.css";

Just like the HTML option, importing the CSS file alone is enough to get started.

But for the best experience, you can also import Lism's dedicated JSX components:

// Import components where needed (React)
import { Box, Stack, Flex, Grid, ... } from "lism-css/react";

// For Astro
import { Box, Stack, Flex, Grid, ... } from "lism-css/astro";

The Lism CSS Ecosystem

Lism CSS provides not only a core CSS library, but also a suite of supporting packages — all open source:

Package	Description
`lism-css`	Core CSS + React / Astro layout components
`@lism-css/ui`	UI component library (accordion, tabs, buttons, etc.)
`@lism-css/cli`	CLI for copying and customizing UI components into your project
`@lism-css/mcp`	MCP server for AI coding tools

All packages are free and open source (MIT).

How Lism CSS Differs from Tailwind CSS

Let's compare it with Tailwind CSS, the current dominant standard:

	Lism CSS	Tailwind CSS
Build	Not required. Works by loading a CSS file	Requires a build tool for production (CDN uses JS execution, for development only)
Class names	Shorthand notation aligned to CSS properties	Property names as-is or custom naming (inconsistent)
Design philosophy	Separates layout structure from decoration (`l--stack -g:20 -p:30`)	Describe everything with utility classes
Responsive	Combination of base class + CSS variables	Individual responsive classes for each breakpoint
Breakpoint basis	Container queries (based on parent element size)	Media queries (based on viewport)
CSS size	~30KB	Only used classes are generated at build time

Utility Class Comparison

Lism CSS includes utility classes targeting individual CSS properties, but unlike Tailwind, it does not cover every CSS property.

It provides a curated selection of the most essential ones — which is how it achieves a lightweight ~30KB without any build or purge step.

For responsive support, rather than generating a large number of classes per breakpoint, it keeps the total class count low by combining with CSS variables (details below).

Here's a rough comparison of class differences:

	Lism CSS	Tailwind CSS
padding	`-p:10`, `-p:20`,...	`p-4`, `p-8`,...
font-size	`-fz:l`, `-fz:xl`,...	`text-lg`, `text-xl`,...
font-weight	`-fw:bold`, `-fw:thin`,...	`font-bold`, `font-thin`,...
color	`-c:text`, `-c:text-2`, `-c` + `--c:var(--red)`...	`text-gray-900`, `text-gray-700`, `text-red-500`,...
background-color	`-bgc:base`, `-bgc:base-2`,...	`bg-gray-50`, `bg-gray-100`,...
Arbitrary values	`-p` + `--p:10px`	`p-[10px]`
Responsive	`-p:10 -p_md` + `--p_md:var(--s20)`	`py-4 md:py-8`

Lism class names follow a consistent -{prop}:{value} format. CSS property abbreviations are used, but the abbreviation rules are consistent — so once you learn a few exceptions, the rest becomes easy to infer.

Layout Approach Comparison

Lism provides layout classes like l--center and l--columns that make the layout structure immediately readable at a glance.

Lism CSS	Tailwind CSS
`l--flex -jc:center`	`flex justify-center`
`l--cluster`	`flex items-center flex-wrap`
`l--center`	`grid place-content-center place-items-center`
`l--columns -cols_sm` + `--cols:2;--cols_sm:4`	`grid grid-cols-2 sm:grid-cols-4`
`l--fluidCols` + `--cols:16rem;`	`grid [grid-template-columns:repeat(auto-fit,minmax(min(16rem,100%),1fr))]`

...and more.

Lism Also Has Conventional Utility Classes

While Lism includes Tailwind-style classes, it also accepts what you might call conventional utility classes — like u--cbox, u--trim, and u--srOnly — and even includes some in the core CSS.

Users are free to define their own utility classes under @layer lism-utility as needed.

Key Features of Lism CSS

Let's explore the distinguishing characteristics of Lism CSS in more detail.

1. Layout-First Module Design

Lism CSS draws heavy inspiration from the layout primitive concept of "Every Layout."

As a result, while Lism has several types of utility classes, its overall design philosophy is layout-first.

The approach is to first build the broad layout structure, then fill in the decorative details with fine-grained utility classes.

<!-- Layout module + Prop Classes -->
<div class="l--stack -g:20 -p:30 -bgc:base-2">
  <h2>Heading</h2>
  <p>Content...</p>
</div>

2. Clear CSS Architecture via Layer Hierarchy

Lism CSS adopts CSS Layers (@layer) for specificity management, with a clearly defined hierarchy that prevents specificity complexity.

Layer	Role	`@layer`
Base	Reset CSS, token definitions, and Set Class layer.	`@lism-base`
Modules	Defines module classes (`.is--`, `.l--`, `.a--`, `.c--`).	`@lism-modules`
Utility Class	Defines utility classes (`.u--`) for clear-purpose decorations and features.	`@lism-utility`
Custom	Layer for user customizations.	`@lism-custom`
Prop Class	Classes tied to individual CSS properties, defined outside any layer. Highest specificity.	—

This hierarchy improves CSS design readability and makes long-term maintenance easier.

3. Consistency via Design Tokens

Preset values for key properties — including color, spacing, typography, and shadows — are defined as CSS variables, offering both stepped and semantic options:

/* Space tokens (Fibonacci-based, relative to --s-unit) */
--s5:  calc(0.5 * var(--s-unit));  /* ≒ 4px */
--s10: var(--s-unit);              /* ≒ 8px */
--s15: calc(1.5 * var(--s-unit));  /* ≒ 12px */
--s20: calc(2 * var(--s-unit));    /* ≒ 16px */
--s30: calc(3 * var(--s-unit));    /* ≒ 24px */
--s40: calc(5 * var(--s-unit));    /* ≒ 40px */
--s50: calc(8 * var(--s-unit));    /* ≒ 64px */
/* ... */

/* Semantic color tokens */
--base: hsl(224 4% 99%);     /* Base background color */
--base-2: hsl(224 8% 95%);   /* Secondary background color */
--text: hsl(224 4% 8%);      /* Text color */
--text-2: hsl(224 6% 32%);   /* Secondary text color */
--brand: #1e5f8c;            /* Brand color */
--accent: #d94a6a;           /* Accent color */

/* Palette colors (OKLCH-based, adjustable via --L and --C) */
--red: oklch(var(--L) var(--C) 20);
--blue: oklch(calc(var(--L) - 2%) calc(var(--C) + 0.01) 260);
--green: oklch(calc(var(--L) + 4%) calc(var(--C) - 0.02) 152);
/* ... */

/* Font sizes based on the harmonic series (numerator 8, relative to --REM) */
--fz-mol: 8;
--fz--5xl: calc(1em * var(--fz-mol) / (var(--fz-mol) - 6));
--fz--4xl: calc(1em * var(--fz-mol) / (var(--fz-mol) - 5));
--fz--3xl: calc(1em * var(--fz-mol) / (var(--fz-mol) - 4));
--fz--2xl: calc(1em * var(--fz-mol) / (var(--fz-mol) - 3));
--fz--xl: calc(1em * var(--fz-mol) / (var(--fz-mol) - 2));
--fz--l: calc(1em * var(--fz-mol) / (var(--fz-mol) - 1));
--fz--m: 1em;
--fz--s: calc(1em * var(--fz-mol) / (var(--fz-mol) + 1));
--fz--xs: calc(1em * var(--fz-mol) / (var(--fz-mol) + 2));
--fz--2xs: calc(1em * var(--fz-mol) / (var(--fz-mol) + 3));

Space tokens use the Fibonacci sequence, and font sizes use harmonic series — ratios found in nature and music. This makes it hard to create a bad-looking design no matter which token values you combine, since they naturally harmonize.

Reference: Scaling Design for Typography and Whitespace

View the full token reference here

4. Utility Classes for Individual CSS Properties

For specific combinations of a CSS property and value, Lism CSS defines classes in the format -{prop}:{value}.

These are called Prop Classes in Lism CSS. (Utility classes are a separate category.)

/* Examples */
.-p\:10 { padding: var(--s10) }
.-px\:20 { padding-inline: var(--s20) }
.-fz\:l { font-size: var(--fz--l) }
.-bxsh\:20 { box-shadow: var(--bxsh--20) }
.-d\:none { display: none }
.-ta\:center { text-align: center }

Unlike Tailwind CSS, these are not provided for every CSS property — only the most essential ones are included.

Users can add their own definitions in the same format as needed.

View the full Prop Class reference here

5. A Unique Responsive Design Approach

One of the most distinctive features of Lism CSS is its responsive design using a combination of CSS variables and classes.

As a derivative of the Prop Classes introduced earlier, responsive classes are defined in the format -{prop}_{bp}:

/* Base */
.-p{ padding: var(--p); }

/* @sm ~ */
@container (min-width: 480px) {
  .-p_sm{ padding: var(--p_sm); }
}

/* @md ~ */
@container (min-width: 800px) {
  .-p_md{ padding: var(--p_md); }
}

These responsive classes are not available for every CSS property either — only a subset of Prop Classes have responsive variants.

(When using SCSS, you can expand this through customization.)

For example, to switch padding from 20 → 30 → 50:

<div class="-p:20 -p_sm -p_md -bd" style="--p_sm:var(--s30);--p_md:var(--s50)">
  <p>Example</p>
</div>

Using dedicated components, this can be written even more concisely:

<Lism p={[20, 30, 50]} bd>
  <p>Example</p>
</Lism>

6. Container Queries by Default

Lism CSS adopts container queries as the default for responsive behavior.

Traditional media queries are based on the viewport (the entire screen width), which often means a component in a main column and one in a sidebar need to be handled separately. Container queries switch based on the parent element's width, so the same component lays out appropriately no matter where it is placed.

Note: Container queries require a container definition on an ancestor element in order to trigger responsive behavior. In Lism, this means setting the is--container class on an ancestor element.

7. Designed with Writing CSS in Mind

Lism CSS is different from Tailwind CSS's approach of doing everything through classes, and also different from CSS-in-JS's approach of encapsulating styles inside JSX.

Major layout and light decoration → Quickly assemble with classes and CSS variables
Detailed styling and fine-tuning → Polish carefully with native CSS

This balance is central to Lism's philosophy: there are places where writing CSS is the right call, and the framework is designed around that assumption.

Use Lism's design as your foundation, add any missing classes you need, and write CSS directly for the details.

Key Layout Modules

Here are some of the layout modules defined in Lism CSS.

Stack (`l--stack`)

Provides a flexbox layout that stacks children vertically (flex-direction: column).

<div class="l--stack -g:20">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</div>

Used everywhere — section skeletons, forms, card content layouts, and more.

Flow (`l--flow`)

A component for automatically managing spacing in flow content such as article body text. Manages whitespace using margin-block-start between child elements.

Spacing is automatically increased before headings (h1–h6), making it ideal for managing content area spacing.

<div class="l--flow">
  <p>Text...</p>
  <p>Text...</p>
  <h2>Heading</h2>
  <p>Text...</p>
</div>

Flex (`l--flex`)

Achieves a horizontal layout with Flexbox.

<div class="l--flex -fxw:wrap -g:20 -jc:center">
  <div>Flex Content</div>
  <div>Flex Content</div>
  <div>Flex Content</div>
</div>

Grid (`l--grid`)

A component for building Grid layouts.

<div class="l--grid -g:20 -gtc_sm" style="--gtc:1fr 1fr;--gtc_sm:1fr 2fr">
  <div class="l--box -p:30 -bgc:base-2">A</div>
  <div class="l--box -p:30 -bgc:base-2">B</div>
</div>

<Grid gtc={['1fr 1fr', '1fr 2fr']} g='20'>
  <Box p='30' bgc='base-2'>A</Box>
  <Box p='30' bgc='base-2'>B</Box>
</Grid>

Center (`l--center`)

Centers its inner content both horizontally and vertically.

<div class="l--center -g:10 -ar:3/2">
  <p class="-fz:l">TEXT</p>
  <p class="-fz:s">Lorem ipsum dolor sit amet.</p>
</div>

<Center g='10' ar='3/2'>
  <Text fz='l'>TEXT</Text>
  <Text fz='s'>Lorem ipsum dolor sit amet.</Text>
</Center>

Columns (`l--columns`)

Creates a column layout with a specified number of columns.

<div class="l--columns -g:30" style="--cols:1;--cols_sm:2;--cols_md:3">
  <div class="-bgc:base-2 -p:30">Box1</div>
  <div class="-bgc:base-2 -p:30">Box2</div>
  <div class="-bgc:base-2 -p:30">Box3</div>
  ...
</div>

<Columns cols={[1, 2, 3]} g='30'>
  <Lism bgc='base-2' p='30'>Box1</Lism>
  <Lism bgc='base-2' p='30'>Box2</Lism>
  <Lism bgc='base-2' p='30'>Box3</Lism>
  ...
</Columns>

SideMain (`l--sideMain`)

Creates a two-column layout that automatically switches between side-by-side and stacked based on the main content width — without relying on media queries or container queries.

<div class='l--sideMain -g:30' style='--sideW:12rem;--mainW:20rem'>
  <div class='l--box -p:20 -bd' style='--bdc:var(--blue)'>
    <p>Main Content</p>
    <p>Lorem ipsum dolor sit, amet consectetur adipisicing elit, sed do eiusmod tempor. Non facere laudantium ex eos doloribus aut dolore nisi.</p>
  </div>
  <div class='l--box is--side -p:20 -bd' style='--bdc:var(--red)'>
    <p>Side Content</p>
  </div>
</div>

<SideMain sideW='12rem' mainW='20rem' g='30'>
  <Box p='20' bd bdc='blue'>
    <p>Main Content</p>
    <Dummy />
  </Box>
  <Box isSide p='20' bd bdc='red'>
    <p>Side Content</p>
  </Box>
</SideMain>

Utility Class Examples

Features serving clear decorative design purposes are defined and used as utility classes prefixed with u--.

View the full Utility Class reference here

Example: u--cbox

A utility class that colors a box based on a key color specified via --keycolor.

<div class='u--cbox -p:30' style='--keycolor:var(--blue)'>...</div>
<div class='u--cbox -bd -p:30' style='--keycolor:var(--red)'>...</div>
<div class='u--cbox -bd -p:30' style='--keycolor:var(--purple)'>...</div>
<div class='u--cbox -bd-x-s -p:30' style='--keycolor:#688f04;--bdw:4px;'>...</div>

<Lism className='u--cbox' keycolor='blue' p='30'>...</Lism>
<Lism className='u--cbox' keycolor='red' bd p='30'>...</Lism>
<Lism className='u--cbox' keycolor='purple' bd p='30'>...</Lism>
<Lism className='u--cbox' keycolor='#688f04' bd-x-s bdw='4px' p='30'>...</Lism>

Lism UI Components (`@lism-css/ui`)

Beyond layout, interactive UI components are also in active development under the @lism-css/ui package.

Components frequently needed on websites — Accordion, Modal, Tabs, Button, Badge, and more — are available (with many more planned). They are all built following Lism CSS's class design (.c-- prefix).

// React
import { Accordion } from '@lism-css/ui/react';

<Accordion.Root>
  <Accordion.Item>
    <Accordion.Heading as='h3'>
      <Accordion.Button p='20'>FAQ Question</Accordion.Button>
    </Accordion.Heading>
    <Accordion.Panel p='20'>
      Answer content goes here...
    </Accordion.Panel>
  </Accordion.Item>
</Accordion.Root>

// React
import { Button } from '@lism-css/ui/react';

<Button href='/contact' variant='fill'>Contact Us</Button>
<Button href='/about' variant='outline'>Learn More</Button>

Each component accepts Lism props directly, so you can freely adjust styles using p, g, bgc, bdrs, and others. They are provided as "one implementation example" — feel free to customize them to fit your project's requirements.

Copy to Your Project with the CLI

Using @lism-css/cli, you can copy UI component source code directly into your own project for full customization:

# Add a component (first run walks you through setup interactively)
npx @lism-css/cli add accordion

# Add multiple components at once
npx @lism-css/cli add accordion modal tabs

# Add all components
npx @lism-css/cli add --all

View the full UI Component reference here

Copy-and-Paste Astro Templates

The official documentation site provides a large collection of Astro templates ready to copy and use.

Sections commonly found on websites — CTA, Feature, Navigation, News, Price Table, Member, Section, and more — are organized across 13 categories. You can preview each one and copy the source code directly.

All templates are built with Lism CSS Astro components, so they also serve as practical examples of Lism-style markup.

View the full template collection here

AI Coding Support

llms.txt

LLM-oriented documentation is published as llms.txt:

https://lism-css.com/llms.txt

MCP Server

Lism CSS officially provides an MCP server (@lism-css/mcp).

It integrates with AI coding tools such as Claude Code, Cursor, and VS Code (GitHub Copilot), enabling AI to directly reference the latest Lism CSS documentation and API details when generating code.

# Setup for Claude Code
claude mcp add lism-css -- npx -y @lism-css/mcp

// For Cursor / Windsurf (.cursor/mcp.json)
{
  "mcpServers": {
    "lism-css": {
      "command": "npx",
      "args": ["-y", "@lism-css/mcp"]
    }
  }
}

The MCP server provides the following 6 tools, and we are continuously fine-tuning them so AI calls them automatically to generate accurate code:

Tool	Description
`get_overview`	Retrieve an overview of the framework
`get_tokens`	Reference design tokens (colors, spacing, font sizes, etc.)
`get_props_system`	Reference the Props → CSS class / style conversion rules
`get_component`	Get component details (props, usage, structure)
`search_docs`	Full-text search of the documentation
`convert_css`	Convert existing CSS code to Lism CSS notation

Even if Lism's custom naming conventions initially feel unfamiliar, the MCP server allows AI to guide you to the correct class names and prop values, significantly lowering the learning curve.

Summary

Lism CSS is designed to embrace modern CSS features — @layer, container queries, CSS variables, color-mix(), and more — while taking full ownership of a site's entire CSS architecture.

Lightweight: Starting from ~30KB (gzip: ~8KB) with only what you need.
Zero build: Just import the CSS. No build tools or configuration required.
Full CSS architecture ownership: Comprehensively covers tokens, layer hierarchy, and naming conventions.
Designed for writing CSS: Rather than doing everything through classes, the design assumes you'll write CSS where appropriate.
Rich ecosystem: Officially provides UI components, CLI, MCP server, and more.
AI integration: Official MCP server and llms.txt allow AI coding tools to reference the latest information when generating code.

The custom naming conventions might take a little getting used to at first — but the MCP server has AI to guide you, and once familiar, it becomes highly intuitive.

We'll keep developing Lism CSS as a powerful ally for those who want both efficiency and quality in their web development.

If any part of this caught your attention, please check out the official documentation and give it a try.

A GitHub star also means a lot to us!

Repository: https://github.com/lism-css/lism-css

DEV Community: Ryo