An Overview of Lism CSS

Lism CSS is a CSS design framework that combines utility classes, components, design tokens, and @layer-based cascade control. The lism-css package ships the core CSS along with layout components for React and Astro, while the @lism-css/ui package adds UI components such as Accordion, Modal, Tabs, and Button.

This post walks through the main layers that make up Lism CSS, one by one.

CSS Layers

Lism CSS styles are organized across several @layers, and the order in which the layers are declared determines their priority. They stack in the order lism-base → lism-component → lism-utility, so you can override styles with Property Classes without worrying about specificity.

When you add custom CSS, place it on whichever layer fits its purpose.

@layer lism-base {
  :root {
    --base: #fbfaf7;
    --text: #1a1a1a;
    --brand: #c8553d;
  }
}

@layer lism-component {
  .c--postList > li {
    border-block-end: 1px solid var(--divider);
  }
}

Design Tokens

Almost every visual detail — colors, spacing, font sizes, line heights, letter spacing, border radii, shadows — is exposed as a CSS variable. Spacing tokens range from --s5 to --s80 (based on the Fibonacci sequence), font sizes from --fz--2xs to --fz--5xl (based on a harmonic sequence), border radii follow the --bdrs--10 family, and colors are exposed under semantic names such as --base / --base-2 / --text / --text-2 / --divider / --link / --brand / --accent.

To adjust your site’s tone, you only need to override these variables in :root.

Note that --keycolor plays a different role from the regular color tokens: it sets the “anchor color” on a per-box basis (used together with utilities like u--cbox).

Property Class

Lism provides a class for each single CSS property, in the form -{prop}:{value}. The value is a token key (p="20" references --s20, and fz="s" references --fz--s).

<div class="-p:20 -bgc:base-2 -bdrs:10 -fz:s">…</div>

To switch values per breakpoint, add a _{bp} suffix. Because this is container-query based, an ancestor element needs is--container.

<div class="-d:none -d:flex_md">…</div>

Layout Primitives

Lism provides l--{name} classes for layout, each with a matching React/Astro component. The most common ones:

---
import { Stack, Flex, Heading, Text } from 'lism-css/astro';
---

<Stack g="20">
  <Flex g="10" ai="center">
    <Heading level="2" fz="l">{title}</Heading>
    <Text fz="xs" c="text-2">{date}</Text>
  </Flex>
  <Text c="text-2">{excerpt}</Text>
</Stack>

Trait Classes

Lism provides classes with the is--{name} prefix to declare a “role.”

• is--container — the reference point for container queries
• is--wrapper — controls max width and inner padding
• is--layer — a base that stacks children with position: absolute
• is--boxLink — extends a child <a> into a link covering the whole block

Don’t use them for state switching (such as active) or variations. Express state with data-* attributes, and variations with the c--{name}--{variant} BEM modifier.

Component Classes (c—)

Define project-specific components with classes that use the c--{name} prefix. Move any declarations that can be written as Property Classes into the markup, and leave in the CSS only what CSS alone can express — pseudo-classes, state switching, descendant selectors, and the like.

<span class="c--tag -fz:xs -px:10 -py:5 -bgc:base-2 -bdrs:10">React</span>

@layer lism-component {
  .c--tag:hover {
    background-color: var(--divider);
  }
}

Installation

You can either load only the CSS via CDN or install it as an npm package.

pnpm add lism-css @lism-css/ui

import 'lism-css/main.css';

// React
import { Stack, Flex, Grid } from 'lism-css/react';
import { Accordion } from '@lism-css/ui/react/Accordion';
import { Modal } from '@lism-css/ui/react/Modal';
import { Tabs } from '@lism-css/ui/react/Tabs';

// Astro
import { Stack, Flex, Grid } from 'lism-css/astro';
import { Accordion } from '@lism-css/ui/astro/Accordion';
import { Modal } from '@lism-css/ui/astro/Modal';
import { Tabs } from '@lism-css/ui/astro/Tabs';

For details, see the official documentation.