Naming Conventions

This page explains the naming conventions for class names and CSS variables in Lism CSS.

CSS Variable Naming Conventions

Each block of a variable name is written in camelCase, following the basic form --{varName}.

Token Variables

| Type | Form | Example | |------|------|-----| | Basic | --{prop}--{token} | --fz--l, --bdrs--20, --bxsh--10, --sz--s | | Color | --{color} | --brand, --text, --text-2, --red | | Spacing | --s{Token} | --s10, --s40 |

Token Variation Notation

| Notation | Condition | Example | |------|------|-----| | s, m, l, xl… | When representing graduated steps above and below a base value | --fz--s, --fz--l | | base | Values set as the initial value of :root / body | --fz--base, --lh--base | | 10, 20, 30… | When values increase stepwise from 0 (none) | --bdrs--20, --bxsh--30 | | Semantic names | When none of the above fit, use a semantic name | --ar--og |

Variables for Property Classes

Rules for variable names used in Property Classes (-{prop}:{value}).

| Form | Description | Example | |------|------|-----| | --{prop} | The same abbreviation as the class’s {prop} portion | --p, --bgc, --bdrs, --m | | --{prop}_{bp} | Breakpoint value | --p_sm, --mx_md |

Other Variables

| Form | Use | Example | |------|------|-----| | --{target}-{prop} | Property applied to an element or class (can be overridden on :root) | --link-td, --headings-ff | | --{propName} | Variables controlling a class’s own main feature. Initialized on the element itself and cannot be given an initial value on :root | --sideW, --mainW | | --_{item}-{propName} | Properties for child elements of a component class (c--) | --_icon-size | | --_{varName} | Internal variables for state management | --_isHov, --_notHov |

Class Naming Conventions

Prefixes are chosen to match each class category and joined with two hyphens (--).

• Component: c--
• Atomic Primitives: a--
• Layout Primitives: l--
• Trait (role declaration): is--
• Trait (feature attachment): has--
• Set Class: set--
• Utility Class: u--

The name that follows the prefix is written in camelCase.

• Not allowed: c--my-component
• Allowed: c--myComponent

Property Class naming follows these conventions:

• Class paired with a specific value: -{prop}:{value}
• Class that accepts a --{prop} variable: -{prop}
• Class that accepts a breakpoint value (--{prop}_{bp}): -{prop}_{bp}

Responsibility of each class prefix

The responsibility and layer assignment of each prefix is summarized below.

| Prefix | Responsibility | Layer | Example | |---|---|---|---| | set-- | Base styling of HTML elements / variable setup | lism-base | set--plain, set--hov, set--bxsh, set--bdrsInner | | l-- | Layout Primitives (composition units) | lism-primitive | l--box, l--flex, l--grid | | a-- | Atomic Primitives (smallest units) | lism-primitive | a--icon, a--divider, a--spacer | | c-- | UI components with BEM-like structure | lism-component | c--card, c--button | | is-- | “is a …” (role / existence declaration) | lism-trait | is--container, is--wrapper, is--layer, is--boxLink | | has-- | “has a …” (single-feature trait attachment) | lism-trait | has--transition, has--gutter, has--snap | | u-- | Decorative effects (including child-element decoration) | lism-utility | u--trim, u--cbox, u--divide, u--enclose, u--clipText |

When to use is-- / has-- / set-- / u--

All of set--, is--, has--, and u-- attach some meaning to an element, but they differ in responsibility. Use the criteria below when in doubt.

| | Purpose | CSS variables | |---|---|---| | set-- | Base styling of HTML elements / variable setup | Not required | | is-- | “is a …” (role / existence declaration) | Not required | | has-- | “has a …” (feature attachment) | Required (customization points) | | u-- | Decorative effect (including child-element styling) | Not required |

Abbreviation Rules for {prop}

The basic approach is to abbreviate based on Emmet.

One-character Properties

The main properties that can be abbreviated to a single character are defined as follows.

Among these, the only one that differs from Emmet is opacity.

Property Groups

The following explains abbreviation rules for groups of related properties.

• Shorthand / longhand groups such as font/font-*, background/background-*, padding/padding-*
• Groups that share a common prefix, such as text-* (e.g. text-align, text-decoration)

Basic form: “group abbreviation” + “abbreviation of the sub-property name”

Some examples:

Directional form: “group abbreviation” + - + “direction”

• Side properties that indicate a direction specify it with a hyphenated (-) suffix.
• inline / block become x / y.
• inline-start / inline-end use s / e rather than is / ie, following conventions already common in CSS frameworks.

Directional exception: for p and m only, the hyphen is omitted

For padding and margin, notations like pt, px, my are widely adopted across CSS frameworks, so the hyphen is omitted.

No collisions between group abbreviations

An abbreviation used by one group must not be reused by another group.

Incorrect example: abbreviating flex to fx, then flex-shrink to fsh. (This breaks the consistency of the fx group.)

max- / min- Properties

max- and min- prefixes retain their hyphen.

Other Properties

For the remaining properties, abbreviation follows the criteria below.

1. Single word: use as-is or abbreviate
2. Hyphenated, or 6 characters or more: abbreviate using Emmet style or to a degree still easily recognizable

Reusing one-character abbreviations

For one-character properties that do not form a group, the character can be reused as the first part of another hyphenated abbreviation. It can also be reused when the property has only directional sub-properties, as long as it does not collide with directional suffixes.

Here are some examples.

Abbreviation Rules for {value}

This section describes the abbreviation rules for the {value} portion of a Property Class -{prop}:{value}.

Basic rule: use the actual CSS value as-is

The {value} portion is not abbreviated in principle. Since {prop} is already abbreviated, keeping {value} intact allows the combination to hint at the original property.

.-d:none          → display: none;
.-d:inline-flex   → display: inline-flex;
.-pos:relative    → position: relative;
.-ta:center       → text-align: center;
.-fx:1            → flex: 1;
.-fxd:column      → flex-direction: column;

When using a token value

If a matching token exists, use the token value (the {value} portion of --{token}--{value}).

.-c:text-2        → color: var(--text-2);
.-fz:l            → font-size: var(--fz--l);
.-p:10            → padding: var(--s10);
.-fw:bold         → font-weight: var(--fw--bold);
.-bdrs:20         → border-radius: var(--bdrs--20);
.-bxsh:10         → box-shadow: var(--bxsh--10);

The opacity tokens are an exception that use naming derived from musical dynamic markings, and the token values are used as-is for the class.

.-o:mp            → opacity: var(--o--mp);
.-o:p             → opacity: var(--o--p);
.-o:pp            → opacity: var(--o--pp);
.-o:ppp           → opacity: var(--o--ppp);

Value notation rules

Units, minus signs, and decimal points are generally preserved as-is when used in a class name.

.-w:100%        → width: 100%;
.-h:100%        → height: 100%;
.-z:-1          → z-index: -1;
.-ar:16/9       → aspect-ratio: 16/9;

Decimal Property Classes are not included in the core, but if you want to turn a fixed value like opacity: 0.75 into a class, you can add CSS like the following.

.-o\:0\.75{opacity: 0.75;}

/* → used as <div class="-o:0.75"> */

Long keyword values can be abbreviated if still understandable

As an exception, values that are 6 characters or more and whose abbreviation is still obviously meaningful may be abbreviated.

| Actual value | Abbreviation | Class example | |--------|------------|-----| | uppercase | upper | -tt:upper | | lowercase | lower | -tt:lower | | fit-content | fit | -w:fit, -h:fit | | space-between | between | -ac:between, -jc:between | | currentColor | current | -bdc:current |