Layer-based component architecture
CSS cascade layers give us explicit control over the order in which the browser evaluates styles, which makes them a natural fit for organizing component code. They scale from top-level architecture down to nested interiors, letting us author increasingly precise rules based on position in the cascade. The risk, of course, is over-engineering — but the approach below tries to stay simple while keeping concerns separated.
Starting from a .button base
Buttons make a good test case: they perform actions, navigate between UI sections, and carry state like hover and focus. Their markup varies too — <button>, input[type="button"], and <a class="button">. Thinking roughly along BEM lines inside cascade layers, a generic class is the most reusable way to target any of them.
.button {}
.button-primary {}
.button-secondary {}
.button-warning {}
/* etc. */
.button {
/* Styles common to all buttons */
}
Enter the components layer
The first layer can be deliberately generic, named components, so other design system parts can join it later and stay distinct from non-component styles.
/* Components top-level layer */
@layer components {
.button {
/* Styles common to all buttons */
}
}
Layers can nest inside classes
A layer can be declared inside a class selector — including one already sitting in a layer. Nested styles carry their own caveats, so use the technique judiciously.
/* Components top-level layer */
@layer components {
.button {
/* Component elements layer */
@layer elements {
/* Styles */
}
}
}
The browser flattens that nesting into an effective layer order:
@layer components {
@layer elements {
.button {
/* button styles... */
}
}
}
Splitting the sub-layers
One sub-layer per element type
Inside .button, a sub-layer handles the different markup flavors individually. The :is() function reads as “if this .button is an <a> element, apply these styles.”
/* Components top-level layer */
@layer components {
.button {
/* Component elements layer */
@layer elements {
/* styles common to all buttons */
&:is(a) {
/* <a> specific styles */
}
&:is(button) {
/* <button> specific styles */
}
/* etc. */
}
}
}
Defaults in the elements layer
Shared styles for every button, regardless of markup, sit at the top of the elements layer as the baseline.
/* Components top-level layer */
@layer components {
.button {
/* Component elements layer */
@layer elements {
background-color: darkslateblue;
border: 0;
color: white;
cursor: pointer;
display: grid;
font-size: 1rem;
font-family: inherit;
line-height: 1;
margin: 0;
padding-block: 0.65rem;
padding-inline: 1rem;
place-content: center;
width: fit-content;
}
}
}
States and modifiers
The states sub-layer
Adding a states sub-layer directly beneath elements covers hover, click and focus behavior:
/* Components top-level layer */
@layer components {
.button {
/* Component elements layer */
@layer elements {
/* Styles common to all buttons */
}
/* Component states layer */
@layer states {
/* Styles for specific button states */
}
}
}
Where two states share a property change — :hover and :focus with the same background, say — :where() groups them. That choice matters: :where() carries zero specificity, while :is() takes on the specificity of its highest-scoring argument. Low specificity is easier to override and easier to maintain.
/* Component states layer */
@layer states {
&:where(:hover, :focus-visible) {
/* button hover and focus state styles */
}
}
A state change should still relate to the base background-color rather than replacing it wholesale. That means promoting the original value into a custom property, --button-background-color, initially darkslateblue, set at the default button level:
/* Component elements layer */
@layer elements {
--button-background-color: darkslateblue;
background-color: var(--button-background-color);
border: 0;
color: white;
cursor: pointer;
display: grid;
font-size: 1rem;
font-family: inherit;
line-height: 1;
margin: 0;
padding-block: 0.65rem;
padding-inline: 1rem;
place-content: center;
width: fit-content;
}
The states layer can then define --state-background-color by passing that variable through color-mix() to lighten it:
/* Component states layer */
@layer states {
&:where(:hover, :focus-visible) {
/* custom property only used in state */
--state-background-color: color-mix(
in srgb,
var(--button-background-color),
white 10%
);
}
}
…and apply the result:
/* Component states layer */
@layer states {
&:where(:hover, :focus-visible) {
/* custom property only used in state */
--state-background-color: color-mix(
in srgb,
var(--button-background-color),
white 10%
);
/* applying the state background-color */
background-color: var(--state-background-color);
}
}
The modifiers sub-layer
Variants — a green button confirming a decision, a red one signaling danger — take the defaults and alter them for specific cases. Because the cascade flows top to bottom, modified styles must not leak into states, so a modifiers layer slots in between elements and states:
/* Components top-level layer */
@layer components {
.button {
/* Component elements layer */
@layer elements {
/* etc. */
}
/* Component modifiers layer */
@layer modifiers {
/* new layer! */
}
/* Component states layer */
@layer states {
/* etc. */
}
}
Modifiers work by reassigning --button-background-color. The .success class is fed to :is() — here the extra specificity is wanted, so it overrides the default:
/* Component modifiers layer */
@layer modifiers {
&:is(.success) {
--button-background-color: darkgreen;
}
}
Applied to a button, .success swaps darkslateblue for darkgreen, and the existing color-mix() handling in states automatically lightens that new color on hover and focus.
/* Components top-level layer */
@layer components {
.button {
/* Component elements layer */
@layer elements {
--button-background-color: darkslateblue;
background-color: var(--button-background-color);
/* etc. */
/* Component modifiers layer */
@layer modifiers {
&:is(.success) {
--button-background-color: darkgreen;
}
}
/* Component states layer */
@layer states {
&:where(:hover, :focus) {
--state-background-color: color-mix(
in srgb,
var(--button-background-color),
white 10%
);
background-color: var(--state-background-color);
}
}
}
}
Where this leads
Any property that needs to change can be refactored into a custom property, which opens up considerable customization room:
/* Components top-level layer */
@layer components {
.button {
/* Component elements layer */
@layer elements {
--button-background-color: darkslateblue;
--button-border-width: 1px;
--button-border-style: solid;
--button-border-color: transparent;
--button-border-radius: 0.65rem;
--button-text-color: white;
--button-padding-inline: 1rem;
--button-padding-block: 0.65rem;
background-color: var(--button-background-color);
border:
var(--button-border-width)
var(--button-border-style)
var(--button-border-color);
border-radius: var(--button-border-radius);
color: var(--button-text-color);
cursor: pointer;
display: grid;
font-size: 1rem;
font-family: inherit;
line-height: 1;
margin: 0;
padding-block: var(--button-padding-block);
padding-inline: var(--button-padding-inline);
place-content: center;
width: fit-content;
}
/* Component modifiers layer */
@layer modifiers {
&:is(.success) {
--button-background-color: darkgreen;
}
&:is(.ghost) {
--button-background-color: transparent;
--button-text-color: black;
--button-border-color: darkslategray;
--button-border-width: 3px;
}
}
/* Component states layer */
@layer states {
&:where(:hover, :focus) {
--state-background-color: color-mix(
in srgb,
var(--button-background-color),
white 10%
);
background-color: var(--state-background-color);
}
}
}
}
For a small project with only a handful of components, this layering can be more architecture than necessary. But even limited use shows how much control the cascade offers over a deceptively complex element — defaults, states and modifiers all handled with a modest amount of CSS.



