web / css

My largest web app has one stylesheet of plain CSS, about 5,000 lines. It has no preprocessor, no Tailwind, and no CSS Modules. Each rule has one place it can go and one way its class can be named, and a lint in CI enforces both. A reader can tell from a class name where its rule lives.

Layers

The first line of the sheet names the layers in order:

@layer reset, tokens, base, components, utilities, print;

@layer reset {
  *,
  *::after,
  *::before {
    box-sizing: border-box;
  }
}

@layer tokens {
  :root {
    --spacing--medium: 1rem;
    --font-size--small: 0.8rem;
    --color--link: #002667;
  }
}

@layer base {
  a {
    color: var(--color--link);
  }
}

@layer components {
  .card {
    border-radius: var(--border-radius--base);
  }
}

@layer utilities {
  .mt-1 {
    margin-top: var(--spacing--medium);
  }
}

Each layer holds one kind of rule:

A later layer beats an earlier one, whatever the specificity. So a utility beats every component rule, and it needs no !important. A print rule beats every utility, and it needs no !important either.

.hidden is the one utility that keeps !important. It must beat every display utility, wherever that utility sits in the layer.

What the order costs

A utility also beats a component's :hover rule and its state rules, such as .tab-link.active. A gray link with .text-gray loses the hover color that a:hover gives it, because a:hover is in base. So a link that keeps its hover wears a small component that sets both colors:

@layer components {
  .link-muted {
    color: var(--color--text-light);

    &:hover {
      color: var(--color--link-hover);
    }
  }
}

For the same reason, every component that sets color on a link sets its own hover color.

Names

A component class is kebab-case, with an optional --modifier. An element inside a block is a nested selector under the block, not a new name:

@layer components {
  .card {
    padding: var(--spacing--medium);

    .title {
      font-size: var(--font-size--medium);
    }
  }
}

A modifier on an element is worn with it, as in .label.label--bold. There is no &--suffix concatenation and no @extend. A widget that shares a base wears both classes in the markup.

An element's short name belongs to one block. .card .title reaches every .title in the card, so no other block uses .title. If the short name is already a class elsewhere, the element keeps its block in its name, as in .select { .select-input {} }. Review checks this, not the lint.

The script toggles a few state classes, such as active, hidden, and resizing. Each one means the same thing on every element.

The lint

The lint is a public Go command, github.com/croaky/cssunused. I pin it as a tool in the go.mod of each app, and CI runs go tool cssunused -sheet <sheet>. It reports each class that nothing renders, and it checks a naming rule for each layer:

It also fails on these:

A class counts as rendered only where it reads as a class: a template's class attribute, a classList call, or a Go value named for a class. The command has no allowlist. Where Go builds a class name at run time, I replace the build with a lookup that returns whole literals. A Go package that writes classes, such as the syntax highlighter of this site, names each class in a const. The app then passes -module with the package path.

The lint parses the sheet and resolves the nesting, so it does not check a nested rule as top-level. The rule of each layer is a regular expression:

// componentRE matches a kebab-case name and an optional --modifier.
var componentRE = regexp.MustCompile(`^[a-z][a-z0-9]*(?:-[a-z0-9]+)*(?:--[a-z0-9-]+)?$`)

One scale

Every utility spends a token:

@layer utilities {
  .mt-1 {
    margin-top: var(--spacing--medium);
  }
  .gap-2 {
    gap: var(--spacing--x-large);
  }
  .font-medium {
    font-weight: var(--font-weight--medium);
  }
}

A new step goes in :root first, and then a utility spends it. A value off the scale keeps a literal and says why in a comment. A size such as w-* or h-* keeps a literal too, because a size is not a step of spacing.

@media cannot read a custom property. So the two breakpoints, 70em and 50em, are literals.

Inline styles

An inline style on a page sets only a custom property, and a rule in the sheet reads it with var():

Style: hml.SafeCSS(fmt.Sprintf("--chart-pct: %.1f%%", pct)),
.chart-bars-bar {
  height: var(--chart-pct);
}

The rule holds for a template's style, the Go value it renders, and a .style write in the script. A state is a class, even inside a measuring pass, because the next layout read sees the class change. So every property the page sets is in the sheet, under its layer, and a media query can change how the sheet spends the value (see web / charts).

A shared sheet

My charts come from a Go package, github.com/croaky/chart, with its own sheet, chart.CSS (see web / charts). An app serves it beside its own sheet, and the shared sheet follows the rules above.

It cannot see the app's classes. So every class starts with chart-, and an element keeps its block in its name even where the short name is free in the sheet: .chart-tip { .chart-tip-title {} }, not .chart-tip { .title {} }. The blocks are chart-lines, chart-bars, chart-tip, chart-legend, chart-plot, chart-sparkline, and one for each other chart. The modifiers follow the same form: chart-series--1 to chart-series--10, and chart-tip--left.

Every rule sits in one @layer components block. The app's @layer order line places that block, so a utility in the app still beats a chart rule.

Each rule spends one of the app's tokens, with a fallback:

.chart-tip {
  background-color: var(--color--bg-secondary, Canvas);
  border-radius: var(--border-radius--base, 3px);
  padding: var(--spacing--x-small, 0.25rem) var(--spacing--small, 0.5rem);
}

The sheet uses the token names my apps already share, such as --color--text, --spacing--small, and --font-size--small. It adds no theme name of its own where an app token says the same thing. Each app sets its tokens in :root, and a chart then matches the page around it. An app that sets no token still gets a chart that draws. The header of the sheet lists each token it reads.

Nesting

The sheet uses native CSS nesting. esbuild flattens it at build time for a list of browser targets. So the browser floor is that list, not the engines that shipped native nesting.

How I check a change

CI cannot see what a page looks like. For a change to the sheet, an agent takes screenshots with browse at phone, laptop, and desktop widths, and compares them with the same pages from main.

← All articles