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.

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 to override base styles, redefine tokens, or set up functional properties as initial defaults.

Module Class

Layout building blocks are broken down and defined as Module Classes.

These are further categorized into several types:

Defining style variations

When defining variants of a module, create a class by appending a BEM-style Modifier to the base class name. Always include the base module class alongside the modifier class to avoid duplicating CSS.

• Format: .{pre}--{name}--{variant}
• Example: .c--button.c--button--outline

Class names for child elements

For modules that function as a unit including child elements, append a BEM-style Element string to the class name.

• Format: .{pre}--{componentName}_{elementName}
• Example: .c--hoge_item

Utility Class

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

Prop Class

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

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

Prop Classes come in three formats:

.-ta\:c { text-align: center; }
.-ta\:l { text-align: left; }
.-fz\:l { font-size: var(--fz--l); }
.-fz\:3xl { font-size: var(--fz--3xl); }

.-p{ padding: var(--p); }
@container (min-width: 480px) {
  .-p_sm{ padding: var(--p_sm); }
}
@container (min-width: 720px) {
  .-p_md{ padding: var(--p_md); }
}

(The actual implementation may differ slightly, but this gives you the general idea.)

Responsive Prop Classes

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

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

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

Other Recommended Conventions

Dynamic Attributes

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

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

Naming custom classes

There are no strict rules for classes that are not part of the built-in Lism package.

The recommended approach is either to use a Lism-like prefix for visual consistency, or to use no prefix at all to make it clear that the class is custom. (Custom component classes are recommended to be defined as c-- within @lism-modules.)

Naming Conventions

CSS Variable Naming

Each block of a variable name uses camelCase, expressed as --{varName}.

Token values

• Color: --{color}. Examples: --brand, --text, --link, --red
• Spacing: Uses the format --s{Token}. Examples: --s10, --s40
• Other variations for specific properties or categories use the format --{prop}--{token}:
  • font-size: --fz--s, --fz--base, --fz--l
  • --hl: --hl--s, --hl--base, --hl--l
  • border-radius: --bdrs--10, --bdrs--20
  • box-shadow: --bxsh--10, --bxsh--20
  • Size tokens: --sz--{size}. Examples: --sz--s, --sz--m, --sz--l

Rules for expressing token variations

1. Size notation using s, l, xl, etc.
   • This notation is used for tokens that represent whether a value is smaller or larger relative to a defined base value (base) or center value (m).
   • base is used for values that reset to the value set on :root (html) or body; m is used for a primary center value that is not necessarily the base.
2. Stepped numeric notation using 10, 20, 30, …
   • This notation is used for tokens where 0 (none) is the baseline and values increase in steps.
3. Other
   • Semantic token names are defined to match the semantics of each property.
   • Example: --ar--og

Variable names for Prop Classes

• Custom properties corresponding to Prop Classes use --{prop}, expressed with the same abbreviation as the class name.
  • Examples: --p, --mx, --c, --bgc, --bdrs
• Breakpoint values for Prop Classes use --{prop}_{bp}.
  • Examples: --p_sm, --mx_md

Variable names for elements

• Properties that are overridable from :root and are specific to a particular element or class use the format --{target}-{prop}.
  • Examples: --link-td, --heading-ff, --gutter-size, --under-offset, --hl-unit, --ov-bgc
• Variables for the primary functionality of a component or module class are expressed as a single block, like --{propName}.
  • Examples: --sideW, --mainW for .l--sideMain
  • Note: When the property is also defined as a Prop Class, the same variable name can be used to allow overriding.
    • Example: --c, --bgc on .c--button
• Properties for child elements of specific components or modules (e.g., c--hoge_item) use the format --_{item}-{propName}.
  • Example: --_icon-size
• Variables used for special state management start with _ and are written as a single camelCase block: --_{varName}.
  • Examples: --_isHov, --_notHov

Class Naming Conventions

About prefixes:

• Prefixes connected with double hyphens (--), such as l-- and a--, indicate that only one class from the same layer can be applied to the same element.
• Prefixes starting with a single hyphen, such as set-, is-, and u-, indicate that multiple classes from the same layer can be applied to the same element.

For the {value} part of -{prop}:{value}:

• Decimal values — use . as-is. (The CSS side requires escaping with \.)
  • Example: .-prop:1.5
• Negative values — use the minus sign as-is.
  • Example: .-prop:-1

Abbreviation Rules

This section explains the abbreviation rules for both the {prop} and {value} parts of Prop Classes (-{prop}:{value}), as well as the corresponding CSS variable names and component prop keys.

The {prop} part

For layout-, typography-, and color-related major properties, extreme abbreviations of 1–3 characters are used, similar to Emmet.

• font-size → fz
• background-color → bgc
• padding → p
• flex → fx
• grid-template-columns → gtc

Other properties are either left as-is or abbreviated to a degree where the original property is still easily inferred. However, hyphens (-) in the original property name are generally omitted entirely, with a few exceptions.

• clear → clear
• white-space → whspace
• writing-mode → writing

max- and min- properties retain their hyphens:

• max-width → max-w
• min-width → min-w
• max-height → max-h
• min-height → min-h

Directional properties

Directional properties follow the {prop}-{side} naming convention, connected with a hyphen -. However, p and m omit the first hyphen (e.g., pt, px) since those forms are already widely used.

The {value} part

The {value} part is generally not abbreviated excessively. Even when the {prop} part is heavily abbreviated, the combination of the two should make it easy to infer which CSS property is being referenced.

Only long keyword values are shortened to the extent their meaning remains clear:

• Class for display:none → .-d:none
• Class for display:inline-flex → .-d:in-flex
• Class for position:relative → .-pos:rel
• Class for text-align:center → .-ta:center