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.