CSS Methodology

This page explains the CSS design principles behind Lism.

Lism CSS Layer Structure

To address the common problem of CSS specificity becoming overly complex, Lism defines a clear layer structure.

Design Tokens

CSS custom properties are defined for major CSS properties — typography, spacing, color, shadows, and more — using stepped preset values and semantic keywords.

Using tokens brings consistency to the design, makes the intent behind property usage more readable, and improves maintainability by allowing site-wide adjustments to be made simply by updating token values.

See the Tokens reference page for details.

CSS Class Design

This section explains the design philosophy behind the core class groups in Lism CSS.

Set Class

Set Classes are utility classes defined within the @lism-base layer. They are used for HTML element base styling or for setting variables.

Primitive Class

Primitive Classes are small building blocks for composing layouts.

These are further categorized into several types:

Primitive classes are standalone — they have no variations or child element classes. Only the c-- Component Classes described next follow a BEM-like structure.

Combining Primitives follows these rules:

Trait Class

Trait Classes declare a role on an element or attach a feature to it.

The decision criteria between is-- and has-- are:

See the naming guide for the detailed decision criteria and usage guidelines.

Component Class

Component Classes prefixed with c-- are concrete UI components composed from Primitives.
They are not included in the core lism-css and are partially provided via the @lism-css/ui package.

Users can also freely define their own c-- classes inside @layer lism-component.

@layer lism-component {
  .c--card { /* ... */ }
  .c--pricing { /* ... */ }
}

c-- classes can follow a BEM-like structure (Block / Modifier / Element), each expressed in the following format:

Combining Blocks (.c--xxx.c--yyy) is generally NG, but the following combinations are allowed:

• Block with its own Modifier: .c--xxx.c--xxx--variant
• Block with another Block’s Element: .c--xxx.c--yyy_elem

Utility Class

Utility classes with a clear decorative or functional purpose are defined as follows:

Property Class

In Lism CSS, utility classes that correspond to a single CSS property are defined as Property Classes.

Utility classes are provided for major properties, covering commonly used values and dedicated token values, with responsive support built in.

Property Classes come in three formats:

See the Property Class reference page for the full list.

Responsive Property Classes

The .-{prop}_{bp} class format combined with the --{prop}_{bp} variable format enables responsive styling.

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

<Box p={[20, 40, 50]} bd>
  BOX
</Box>

See the Responsive styling guide for details.

Naming and placing custom classes

When you add your own classes that match one of Lism CSS’s existing class categories (set--, is--, has--, l--, a--, u--, -{prop}:{value}), use the same prefix and add them to the corresponding definition layer.

If you need to override an existing Lism class, do so within that same layer.

For example, set-- class redefinitions belong in @layer lism-base. In that case, define them after the Lism main.css is loaded, or boost the specificity by repeating the class name (e.g. .set--xxx.set--xxx) to ensure the override takes effect.

@layer lism-base {
  /* New addition */
  .set--hoge { /* ... */ }

  /* Override */
  .set--plain.set--plain { /* ... */ }
}

Adding custom classifications

You may also define your own prefixes that don’t match any of the built-in Lism class categories.

Place these in @layer lism-custom.

@layer lism-custom {
  .z--header { /* ... */ }
  .p--front { /* ... */ }
}

Using data attributes for dynamic state

For state management that is dynamically toggled by JavaScript, use data attributes.

Example: [data-opened], [data-active]