How to contribute to LSCSS projects

Ask this first

Ask first: Are you improving the system, or only solving today's ticket?

Good contributions reduce future work. Poorly scoped ones increase future maintenance.

Shipping quickly matters. Shipping confusion faster does not. Contributions should leave the system easier to work with.

Core contribution rules

• Choose ownership before writing selectors.
• Prefer layers over specificity escalation.
• Use tokens before inventing new values.
• Name components semantically, not visually.
• Use utilities rarely and deliberately.
• Move urgent fixes into hacks, then remove them.

Pull request review questions

• Does this belong in settings, base, utilities, layout, components, theme, legacy, or hacks?
• Is this state or a reusable modifier?
• Why is specificity increasing here?
• Why is this a utility instead of a component?
• Will someone understand this safely in six months?

Review the pattern, not the person. Architecture survives better that way.

Definition of done

A change counts as done when all of the following are true:

• Correct layer chosen
• Tokens used instead of random values
• State and modifiers are clear
• No accidental utility architecture
• Hacks are documented and temporary
• Overrides stay predictable

Done means maintainable, not merely passing visual inspection today.

Things rejected immediately

• New !important without strong justification
• Deep selectors solving ownership problems
• Utility stacks replacing obvious components
• Magic numbers with no token reason
• State disguised as permanent modifiers
• Legacy CSS copied into new files without challenge

Fast rejection is kinder than slow technical debt.

What good looks like

A good contribution often looks boring.

• small, predictable selectors
• clear ownership
• obvious state naming
• token consistency
• less explanation needed in review comments

Calm CSS is usually good CSS.

Next useful pages