lism-css-guide

Lism CSS Implementation Guide

The starting point for decisions when implementing UIs, pages, and components with Lism CSS. Determine the execution level from the scale of change, and go through pre-implementation checks → implementation → pre-submission self-check.

Official documentation: https://lism-css.com/docs/overview.md

Version: lism-css@1.0.1/@lism-css/ui@0.40.1Information as of this point in time. If the project's version differs, inform the user and guide them to update the package or update this skill.

Implementation flow (strictly adhere)

Verify materials immediately before the corresponding operation in the code. Which materials to read before which operation follows the "Material Verification Triggers".

1. Execution level determination: Decide unnecessary/lightweight/normal/with value verification using the "Pre-check execution level".
2. Initial confirmation: Do not implement based on SKILL.md alone. First open the minimum necessary detail files that are clearly related to the implementation target, and list the "materials confirmed initially" in the implementation plan. Merely glancing at the link table does not count as confirmed.
3. Select Primitive/component candidates using the "Purpose-specific implementation guide".
4. Perform pre-implementation checks (C0–C8), and produce anImplementation planlisting the initially confirmed materials, Primitives to use, components, tokens, and responsive policy. Attach 🔁 to any decision that cannot be adopted while unread, and link the "materials to read" to the decision line.
5. Following the "Material Verification Triggers", read the corresponding materials before writing each operation in the code, and resolve 🔁 to ✅ or ⏸.
6. For items where ⏸ remains (px rounding, arbitrary colors, behavior changes, public class changes, etc.), confirm with the user before implementing that part. If confirmation cannot be obtained, follow the ⏸ section of "Judgment symbols".
7. Implement.
8. (Normal and with value verification only) Cross-check the implementation plan against the implementation using the "Pre-submission self-check".

For details on C0–C8 and the format of the implementation plan, seereferences/authoring.md。

Judgment symbols

Attach to each line of the implementation plan. Only the following 3 symbols and notes to ✅✅新規・✅例外・✅前提may be used. Do not create combinations of notes (✅例外/前提, etc.) or new symbols/notes. Treat applicable lines as 🔁.

Symbol	Meaning
✅	Confirmed. Note new definitions (components/tokens/classes) or agreed direct-writing exceptions in the line (e.g.: ✅新規、✅例外（1px罫線））
🔁	Unpassed items that fall under the Material Verification Triggers. Read the specified materials before writing the corresponding operation in the code, and resolve to ✅ or ⏸. Do not implement while still 🔁
⏸	User confirmation required. Do not implement until confirmed

✅例外conditions of: antipatterns.mdOnly when it falls under the "exceptions that may be written directly" in. For lines, attach a quote of that item; lines for which a quote cannot be written are ⏸. Other exceptions, rounding, and new tokens are ⏸. Do not create your own exception categories in the allowlist. User instructions such as "reproduce exactly" or the fact that a value is a measured value do not serve as grounds. The default handling of design values followsreferences/authoring.md's "design data import flow".

When confirmation of ⏸ cannot be obtained(such as autonomous execution): Choose the option on the compliance side in principle (if there is an already-aligned policy, use that; otherwise, the default behavior for each input type. Example: rounding to the nearest token), update that line as in✅前提（p="30"へ丸め）and proceed, and list the issues and alternatives in the completion report. Deviating options such as writing px directly, creating new exception categories, changing public classes, or breaking changes cannot be chosen, and implementation must not proceed while ⏸ remains.

lism-css-refactorThe skill uses the same symbols with different meanings (✅ = do not touch, ⬜ = intentionally leave, etc.). During refactoring, follow the refactor side's definitions and clarify which meaning applies in table headings, etc.

Pre-implementation checklist items (C0–C8)

C	What to look at	Main references
C0	Input organization: target/granularity/framework/existing constraints/unknowns	Existing code/requirements
C1	Structure/semantics selection	primitive-class.md、components-core.md
C2	Reuse/component boundaries	components-core.md、components-ui.md
C3	Naming design	naming.md、css-rules.md
C4	State/variation design	trait-class.md、antipatterns-layout.md
C5	Value/token verification	tokens.md、property-class.md
C6	Responsive policy	responsive.md、trait-class/is--container.md
C7	What to write in CSS / what to move to Props	property-class.md、css-rules.md
C8	Confirmation of default values	primitives/l--*.md

Pre-check execution level

Level	Condition	C to confirm	Output	Pre-submission self-check
Not required	Explanation only / no code changes / changes that merely follow existing conventions (criteria below)	—	None. Perform only step 6 (implementation), and.lism/also do not create	Do not perform
Lightweight	Small changes of a few lines / changes within existing patterns / addition of small parts completed only with Props/Property Class	Mainly C1 and C5	Bullet list of 3–5 lines	Do not perform
Normal	New section, or new part accompanied by new CSS (b--*/c--*style declarations)	Required = materials confirmed initially, C0, C1, C5, C6. C2/C3/C4/C7/C8 only when applicable	Table by item	Perform, and.lism/review.mdsave to
With value verification	Design reproduction from Figma/screenshots, etc.	Confirm Normal + C5/C7 in detail	Table by item + token diff table (diff column required). Not in chat but.lism/plan.mdsave to	Perform, and.lism/review.mdsave to

.lism/The conventions ofreferences/verification.md。

Criteria for judging "unnecessary": If none of the following are included, it is "unnecessary". If even one is included, it is "lightweight" or above.

• Newc--*/b--*Class
• New CSS declarations (file,<style>）
• Introduction of Primitive/Trait/components not used in existing code
• New responsive switching
• Numbers/colors outside tokens

Even if you are unsure between unnecessary/lightweight/normal, do not raise it to a higher level. Only when you are unsure whether it is design reproduction, make it "with value verification". Even for normal, omit C items that do not apply, and do not fill in the table just for form—list only the items that affect implementation.

Document check trigger

Before writing the operation on the left into code, read the document on the right. If unread, mark that judgment as 🔁, and either read it and make it ✅, or if it cannot be judged, make it ⏸.Do not reflect it in code while it remains 🔁.Do not substitute with "refer if necessary".

Before doing this operation	Read this document
Use a Primitive not yet read	The correspondingprimitives/l--*.md
Use a Trait Class not yet read	The correspondingtrait-class/*.mdortrait-class.md
Write a style declaration in CSS (file,<style>), or move it to Property Class/Lism Props	property-class.md
Write state styles such as hover/focus	property-class/hov.md(as necessarytrait-class/has--transition.md）
Write numbers/colors outside tokens into code (including when rounding. Regardless of CSS/Props)	tokens.md、antipatterns.mdthe "px / direct writing of fixed values" section of
Decide responsive switching	responsive.md
Create/name a custom class (b--*/c--*)	naming.md、css-rules.mdの独自クラスの選び方（2分類）section
b--*/c--*Write the CSS of	css-rules.mdのBlock Class（b--）/Custom Class（c--）section
Design states/variations	trait-class.md

Minimum gate

Always follow. If you are unsure, make an exception, or it conflicts with existing implementation, read the relevant document and resolve 🔁 to ✅ or ⏸.

• For structure,<div>Prioritize Primitive over + plain CSS. Choose candidates from the "Purpose-specific implementation guide".
• c--*/b--*makes Block camelCase and Element_one, and Modifier--Name with the two.c--feature-cardや__Do not use.
• Name custom classes in 2 categories: common foundational parts whose base styles are managed on the CSS side →b--, otherwise →c--。
• Always place custom CSS inside@layer lism-custom(b--only the base styles@layer lism-block）。
• Do not arbitrarily round or directly write px/rem/em values outside tokens. Rounding, new tokens, and direct-writing exceptions are ⏸ (✅例外the condition is "judgment symbol").
• c--*In, do not write declarations that affect only a single element in CSS; first check whether they can be expressed with Lism Props/Property Class. What remains in CSS is only declarations that cannot be written with Property Class, such as pseudo-elements, descendant selectors, and state switching. What remains as a name is only the main classc--name, and do not attach Elements that are not referenced in CSS (c--name_elem).b--*The base style is out of scope; use tokens to@layer lism-blockmay be written in (BP switching, hover, and exceptional adjustments are Property Classes).
• For responsive values, if using container queries, check the necessaryisContainerancestor.
• States are expressed withdata-*/ARIA; visual variations are expressed with a Modifier using the same prefix as the Block (c--name--variant/b--name--variant).is--activeDo not reuse a Trait Class as a state name, as in

Purpose-Specific Implementation Guide

Look up candidates starting from what you want to do. For rows with multiple candidates, choose between them based on the criteria in parentheses.

What you want to do	Candidate to use	Details
Vertical arrangement	Stack/Flow	primitives/l--stack.md、primitives/l--flow.md
Horizontal arrangement	Cluster(wraps)/Flex(fine-grained control)	primitives/l--cluster.md、primitives/l--flex.md
Column	Columns(equal-width N columns)/AutoColumns(auto-flow based on minimum width)/WithSide(automatic 2-column switching)	primitive-class.md#カラムレイアウト-primitive-の使い分けガイド
Width control	Container(container query based)/Wrapper(width restriction of the direct child area)/max-sz(width of a single element)	trait-class/is--container.md、trait-class/is--wrapper.md、property-class/max-sz.md
Placing images, videos, iframes	Frame(aspect ratio frame / fit for direct-child media / let overflow be handled)	primitives/l--frame.md
Button	@lism-css/uiのButton. If you are styling a plain<button>use the reset-appliedset--plain	components-ui.md、set-class.md
Tooltip/Popover	@lism-css/uiのTooltip(supplementary text for hover/focus)/Popover(panel that opens on click. If it contains links or forms, use this one)	components-ui.md
hover effect	-hov:*/hov={{}}/set--hov/has--transition（component CSSの:hoverconsider before)	property-class/hov.md、trait-class/has--transition.md
Whole-box/card link	BoxLink/is--boxLink(leave the click area and stacking order to it)	trait-class/is--boxLink.md
Small UI parts	c--*＋Property Class（c--*should remain a name indicating what part it is, and the appearance of a single element goes to Property Class/Lism Props). If it is a shared component whose base style is managed on the CSS side, useb--*	property-class.md、css-rules.md#custom-classc--、css-rules.md#block-classb--
Standard page sections (hero, site header, footer, etc.)	Group＋Wrapper/Stack/Clusterstandard composition of	references/page-sections.md

Pre-submission self-check

Perform only Normal and Value-Verification levels. For Unnecessary/Lightweight, do neither a simple in-chat check nor delegation to an evaluation subagent.

In environments where subagent/task delegation is available, delegate the verification in this section to a read-only evaluation subagent rather than the implementer themselves (instruction template, reporting format, and re-evaluation loop arereferences/verification.md). Save the report to.lism/review.md, repeat fix → re-evaluation until there are zero violations, then submit, and reference.lism/review.mdin the completion report. In environments where delegation is not possible, the implementer performs the same verification in the order of this section.

First, compare the implementation plan and the implementation line by line, and classify differences into "plan change (intentional) / implementation omission (fix) / needs re-confirmation (requires checking again)". After that, check the following.

Process verification

• Whether the 🔁 items in the implementation plan have been resolved to ✅ or ⏸. Whether any judgment marked 🔁 was reflected in the code as-is.
• Whether each line of the material review log corresponds to a decision item in the implementation plan. Whether any Primitive/token/naming/responsive decision was adopted while still unread.

Rule verification

• Whether any item of the "minimum gate" is violated.
• antipatterns.mdとantipatterns-layout.mdOpen the TOC of and verify one by one the items that could apply to the implementation code. Do not mark as confirmed just by glancing at the link table.

Plan re-review(Deviations marked ✅ at the plan stage cannot be detected by diff verification, so this is done separately)

• ✅例外Re-verify the ✅ judgments including against the minimum gate,antipatterns.md's "exceptions that may be written directly" and the agreed value mapping policy. Any✅例外outside the allowlist should be returned to ⏸.
• For value-verification-enabled,.lism/plan.mdcheck whether there is a token diff table (with a diff column). If there is none, the implementation plan is invalid. Create the diff table and redo the verification. Also check whether the scale assumptions (such as image export magnification) have been verified by actual measurement/consistency checks (if unverified, the entire diff table is invalid).
• Review whether the execution level determination was appropriate (whether, despite being design reproduction, it avoided the diff table by not raising it to "value-verification-enabled").

Individual confirmation

• @lism-css/uiWhether it cannot be replaced by an existing component of.
• If the same Property Class combination appears in 3 or more places, was componentization considered?
• Whether it matches the existing naming, layers, and file placement.
• For value-verification-enabled, make confirmation of the rendering result a prerequisite for the completion report. In environments where it cannot be confirmed, include a request for the user to visually confirm in the completion report. Do not treat HTTP status or build success alone as completion.

Detailed reference

File	Content / when to read
primitive-class.md	l--/a-- Primitive list and how to use them properly. Layout selection (if necessary,primitives/l--*.mdも）
trait-class.md	is--/has-- Trait list and roles. State/variation design
property-class.md	-{prop}:{value}format Property Class. Whether CSS can be moved to Property Class/Props
utility-class.md	u--*Utility
set-class.md	set--plain/set--hovset classes such as. Reset-applied buttons, etc.
tokens.md	Design tokens and CSS variables. Verification of spacing, color, corner radius, shadow, fz
naming.md	Naming conventions and Property Class omission rules
css-rules.md	CSS design, Layer structure,b--*/c--*, classification of custom classes. Custom CSS
responsive.md	BP, container queries, responsive Props
base-styles.md	Reset CSS and basic styles for HTML elements. Confirm the defaults of plain HTML elements
components-core.md	lism-cssReact/Astro core components
components-ui.md	@lism-css/uiUI components. UI component replacement
customize.md	SCSS variables,lism.config.jscustomization via
antipatterns.md	NG→OK that AI tends to generate (value/style declaration type). Check typical mistakes
antipatterns-layout.md	Separate volume of NG→OK (structure/layout/responsive type)
references/authoring.md	How to create an implementation plan (C0–C8 details, output format)
references/verification.md	.lism/Delegation to conventions/evaluation subagents
references/page-sections.md	Standard composition examples such as hero, header, footer, etc.

Detailed reference by class

The file name is the class name as-is (primitives/l--stack.mdetc.). The corresponding component names arecomponents-core.md。

• primitives/: l--box l--flex l--stack l--cluster l--grid l--flow l--center l--frame l--columns l--tileGrid l--autoColumns l--switchColumns l--withSide a--icon a--divider a--spacer a--decorator
• trait-class/: is--container is--wrapper is--layer is--boxLink has--transition has--gutter has--snap has--mask
• property-class/: all-props.md(full Prop table),bd.md（-bd/-bd-{side}series),hov.md（-hov:*series),max-sz.md（-max-sz:full/bleed）

How to update this skill file itself

For skill update requests,lism-cli skill addorlism-cli skill updateguide them to. Check the latest in the GitHub repository'sskills/lism-css-guide.