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:
reset: what the app changes about every page, such asbox-sizing.tokens: the custom properties in:root.base: a rule that starts with a bare tag or an attribute, such asa,label, orinput[type="text"].components: a rule that starts with a class, for a repeated element with state, such as a button, a card, or a drawer.utilities: one property per class, for layout, spacing, and type.print: a rule for paper..print-hidehides an element there.
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:
componentsandprint: a kebab-case name with an optional--modifierand no__.utilities: a short name with no__and no--, such asmt-1.- Every other layer: no class.
It also fails on these:
- A top-level rule in
componentsthat does not start with a class. A rule for a tag or an attribute goes inbase. - An ID selector, in any layer. An ID outranks every class rule in its layer, so a component class cannot override it. A template keeps an ID that JavaScript reads, and the sheet styles a class on the same element.
- A rule outside every layer. An unlayered rule beats every layered rule, so one added at the end of the file would override the utilities.
- A class with
__anywhere it reads one: a template, the TypeScript, or Go. This holds even when the sheet does not define the class. - A media query that tests
min-widthormax-width. The query writes the width as a range, such as(width < 70em).max-width: 70emandmin-width: 70emboth match at 70em, so a screen that wide gets both layouts. !importantoutside thebaselayer and the.hiddenutility. Inbaseit beats a style that a browser extension writes inline. Everywhere else a later layer wins without it.
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.