.user_cardIdentity, in snake_case..user_card-titleA part, joined by one hyphen.[data-state]State, as data.UserCard.cssOne block, one file.Devographics asked 4,902 developers what hurts. Here's the freshest data:
“Supporting light/dark mode is difficult; developers struggle to work with system preferences, manual theme selection, and duplicated theme definitions.”
“Managing color palettes, tokens, variables and design-system scales is hard.”
Nobody is waiting on a browser anymore. The named causes are duplicated theme definitions, palettes that are hard to manage, cognitive overload, and maintenance.
That is an architecture problem. That's what we solve.
Almost every idea here is borrowed. A convention nobody has seen before is a convention nobody will follow.
Separate structure from skin.
Became Mass vs Void: object shape and page rhythm are different budgets.
Namespace every component.
Kept the idea, dropped the typing tax of __ and --.
Categorize rules before you write them.
Became the prefix taxonomy: l_, u_, g_, and the block itself.
Scoping is not optional.
Kept co-location, refused the runtime and the generated class names.
Order the cascade deliberately.
Handed the job to :where() and a flat file layout instead.
Constraints beat freedom.
Kept the constrained scale, put it in tokens instead of the class attribute.
Compose layout, do not enumerate it.
Became the l_* primitives and the Binary Rule.
A rule you have to look up is a rule you will break.
.snake_caseNamed for what it is. .user_card, not .bg-white.rounded-xl.p-4. When the fill changes, bg-white is a lie in forty files. A card is still a card.
snake_case because user_card is one double-click. id is a document hook, not a styling API – specificity 1,0,0, not reusable.
.user_card {
padding: var(--space-5);
border: 1px solid var(--border-base);
background: var(--bg-surface);
}.block-part_nameOne hyphen joins a block to its part. Underscores inside each half. The hyphen means belongs to, and nothing else. Names stay flat – they do not encode today's DOM.
/* Correct: flat, one hyphen, searchable */
.nav_bar-list_item { }
.nav_bar-action_button { }
/* Wrong: the hyphen now means two different things */
.nav_bar-list-item { }
/* Wrong: encodes today's DOM into tomorrow's selector */
.nav_bar .list_item { }[data-state]State is data, not a class. is-active, --active, .button--loading, .js-open – five codebases, five dialects. Attributes have been around since 2008, and they are the best tool for the job. You also stop concatenating class strings in JavaScript.
<button class="button" data-variant="primary" data-state="loading">
Save
</button>UserCard.cssOne block, one file, next to the component. UserCard.tsx and UserCard.css live and die together. No orphans. No four-thousand-line components.css. The exceptions are big components, implementing full pages, like index.astro
src/components/
UserCard.tsx -> renders .user_card
UserCard.css -> styles .user_card and nothing else
PromoBanner.tsx
PromoBanner.cssTo make it work – never use the ampersand to build a class name.
.user_card {
&-title {
font-size: var(--text-2xl);
}
}.user_card-title {
font-size: var(--text-2xl);
}In the first version, user_card-title exists nowhere – not in search, not in rg, not in the language server, not in a model's context window. You saved eleven characters.
In the second, one string is the markup and the style. ⌘D or * cgn . can grab it because it is actually in the file. &-title gives those keystrokes nothing. BEM's &__element has the same hole.
A quarter of developers named theming as a top color pain point, and the survey recorded the specific cause: duplicated theme definitions. So let's remove the duplication instead of managing it.
/* 1. Foundations. Raw materials. Never used in a component. */
:root {
--palette-white: oklch(1 0 0);
--palette-stone-900: oklch(21.6% 0.006 56.043);
}
/* 2. Themes. What "light" and "dark" physically mean.
Components must never touch these either. */
:root {
--theme-light-bg-surface: var(--palette-white);
--theme-dark-bg-surface: var(--palette-stone-900);
}/* 3. Semantics. The only layer a component may read. */
[data-theme='light'],
[data-theme='dark'] [data-theme='inverse'] {
--bg-surface: var(--theme-light-bg-surface);
}
[data-theme='dark'],
[data-theme='light'] [data-theme='inverse'] {
--bg-surface: var(--theme-dark-bg-surface);
}A semantic is declared twice: light block, dark block. Components read var(--bg-surface) and stop.
A third theme is one more block. Inverse is one attribute on a subtree. No component has ever heard the word “dark.”
Same markup. Same stylesheet. Not one conditional color in the component.
data-theme="light"Same markup. Same stylesheet. Not one conditional color in the component.
data-theme="dark"Same markup. Same stylesheet. Not one conditional color in the component.
data-theme="inverse"Flip the theme in the header. The first two columns hold their ground; the third flips with you, because inverse resolves against whatever context it lands in.
padding: 1rem and width: 1rem are not the same kind of 1rem.
Void is margin, padding, gap. Shared rhythm. Always --space-*.
Mass is width, height, inset, translate. The avatar is 3rem because the avatar is 3rem, not because --space-12 happens to equal that. If you tighten the scale – the avatar should not become an oval.
.profile_card {
/* Void: shared rhythm, always a token */
padding: var(--space-5);
gap: var(--space-3);
}
.profile_card-avatar {
/* Mass: this object's own shape */
width: 3rem;
height: 3rem;
border-radius: var(--radius-full);
}<article class="l_stack user_card" data-gap="4">
...
</article><article class="user_card">
...
</article>The State of CSS missing-features list asked for “simpler fluid typography primitives.” It turns out to be about forty lines of PostCSS.
font-size: clamp(
2.25rem,
calc(2.25rem + (8 - 2.25) * ((100vw - 40rem) / (80 - 40))),
8rem
);font-size: fluid(var(--text-4xl), var(--text-9xl));Nobody audits the first one. The two 2.25rems drift. fluid() , on the other hand, resolves both tokens at build and emits a clamp() with the slope already computed.
Refraction
Same component, same design, four philosophies. Read each one and ask the only question that matters: what happens to this in eighteen months, when the person working on it has never met you?
Right instinct, four extra characters per name. Nest &__title and card__title exists nowhere in the repo.
<article class="promo-card promo-card--featured">
<h2 class="promo-card__title">Refraction</h2>
<button class="promo-card__action promo-card__action--loading">
Read
</button>
</article>.promo-card {
&__title { font-size: 1.5rem; }
&__action {
&--loading { opacity: 0.5; }
}
&--featured { border-color: #e11d48; }
}Fast to write. The markup describes pixels. The same card in three places drifts three ways.
<article class="flex flex-col gap-3 rounded-xl border
border-stone-200 bg-white p-6 shadow-sm
dark:border-stone-800 dark:bg-stone-900">
<h2 class="text-2xl font-semibold tracking-tight
text-stone-900 dark:text-stone-100">Refraction</h2>
</article>Every color is declared twice: once light, once dark.
Every card repeats all fourteen classes.
Renaming the component renames nothing.
"Which of these 40 divs is the card?" – you, in MarchSolved scoping, then billed a runtime for it. Styles in the JS bundle, class names hashed, CSS needs JavaScript to exist.
const Card = styled.article`
padding: 1.5rem;
border: 1px solid ${(p) => p.theme.border};
background: ${(p) => p.theme.surface};
`
const Title = styled.h2`
font-size: 1.5rem;
color: ${(p) => p.theme.ink};
`
// Renders: <article class="sc-bdVaJa hXlkjP">Devtools shows you hXlkjP.
Search cannot find a style by name.
Theme values arrive through a React context.
Your CSS is now a JavaScript dependency.Identity in the class, state in the attribute, color in the token, geometry in the wrapper.
<article class="promo_card" data-featured="true">
<div class="l_stack" data-gap="3">
<h2 class="promo_card-title">Refraction</h2>
<button class="u_reset_button promo_card-action" data-state="loading">
Read
</button>
</div>
</article>.promo_card {
padding: fluid(var(--space-4), var(--space-6));
border: 1px solid var(--border-base);
background: var(--bg-surface);
}
.promo_card[data-featured='true'] {
border-color: var(--border-focus);
}
.promo_card-title {
font-size: var(--text-2xl);
color: var(--ink-main);
}
.promo_card-action[data-state='loading'] {
opacity: var(--opacity-disabled);
}The 2026 survey puts AI-generated CSS at roughly 28 percent – the lowest share anywhere in the stack. Here is my theory.
There is no ground truth to generate against. A model writing Go has a compiler. Writing SQL, a schema. Writing TypeScript, types. Writing CSS, it has vibes.
Ask five senior engineers to name and structure a card component and you will get five answers, all defensible. A model trained on all five produces a sixth. Then it produces a seventh in the next file, because nothing told it what the sixth was.
BEAM's rules are the kind machines are actually good at, because they are mechanical, strict and deterministic rather than tasteful.
Block snake_case, from the filename
Element .block-part_name, always flat
Attribute data-*, never a state class
Module one block, one co-located file
Color Layer 3 semantics only
Void --space-* for margin/padding/gap
Mass raw rem for width/height/inset
Layout l_* on a wrapper, never the block
Selectors classes only, never an ID
Queries min-width only, never max-width
Nesting one level, conditions only
Ampersand banned for name buildingEvery architecture doc ends with a triumphant list of benefits. Here is the other list, because you are going to find it anyway and I would rather you heard it from me.
Correct. A block plus a CSS file is slower than fourteen utilities – the first time. It is faster the third time you touch that component, and dramatically faster the first time you rename it. If your component is genuinely one-off, utilities win. Most components are not one-off.
For about a day. Then double-clicking a class name and getting the whole class name stops feeling like a trick and starts feeling like the baseline. Nobody has ever asked to go back.
So does everyone – mixins have been in the survey's top missing features for years, and the platform is finally building them. Until then, custom properties cover most of it and honest duplication covers the rest. That is a real cost, and it is smaller than a preprocessor.
That part is load-bearing. A convention with exceptions is a convention that gets quietly abandoned in month three. The rules are absolute so that nobody has to relitigate them in a pull request at 6pm.
No. Nothing will. What it does is make bad CSS visible – a raw hex code, a state class, an l_ class riding a block. You stop arguing about taste and start pointing at rules.
It is BEM with fewer steps, plus the two things BEM never had: state that lives in attributes, and a theme engine that stops color from being copy-pasted. If you already run disciplined BEM, migration is mostly a find-and-replace.
Six stylesheets, one PostCSS plugin, and a set of rules short enough to memorize. You can convert one component this afternoon and keep the rest of your codebase exactly as it is.
Then open the inspector on this page. Every class you find is a Block, an Element, an l_, a u_, or a g_. That is the whole vocabulary.