Designing with CSS, not around it 🎨

[vnys]

Designing with CSS, not around it 🎨

EDS 2.0 — Architecture Direction

How modern CSS features replace the workarounds that design system methodologies were built to provide — and what that means for EDS.

---

🧱 Every major CSS methodology was in essence a polyfill

BEM, CUBE CSS, utility-first, CSS-in-JS — these weren't best practices. They were workarounds for a language that couldn't yet do what we needed. The language has caught up.

Important

The core argument: methodologies existed because CSS wasn't expressive enough. Now that it is, we have an opportunity to build a design system that works with CSS rather than around it.

The three pillars that drove every methodology

🔒 Scoping
CSS is global — everything leaks. BEM naming and CSS Modules existed to prevent collisions. Now we have @layer, nesting, and Shadow DOM.

🧮 Logic
CSS couldn't compute. Sass mixins and JS-in-CSS filled the gap. Now we have @function, calc(), clamp(), and if().

🎨 Theming
There was no native way to switch visual contexts. Theme classes and CSS-in-JS providers emerged. Now custom property inheritance does the job natively — the browser's own cascade handles propagation that JavaScript frameworks have been doing unnecessarily for years.

---

🗺️ The full replacement map

Problem	Old workaround	Native CSS today
Scoping / collisions	BEM, CSS Modules	@layer, nesting, Shadow DOM
Logic & calculation	Sass functions, Less mixins	@function, calc(), clamp(), if()
Variants / conditions	BEM modifiers, utility classes	if(), :has(), data attributes
Typed design tokens	Sass variables, build-time gen	@property with typed syntax
Theming	Theme classes, CSS-in-JS providers	Custom property inheritance
Responsive components	JS ResizeObserver	Container queries
Fluid type & spacing	Modular scale libs, Utopia	clamp(), @function for steps
Relational styling	JS class toggling	:has()
Baseline alignment	JS measurement, magic numbers	text-box: trim-both ex alphabetic

Tip

:has() is arguably the single most transformative CSS addition in years — it lets a parent style itself based on its children, replacing a whole category of JavaScript workarounds.

---

✨ The opportunity

EDS 2.0 can be one of the first design systems designed with CSS rather than around it.

This is not a rewrite. It's a rethink of where the logic lives.

Designsystemet is on a similar path — their button component is a useful reference point.

---

🏗️ EDS 2.0 Architecture

Two distinct worlds, one shared token contract.

🪙 Design Tokens

Token Studio → Style Dictionary → CSS custom properties. The shared contract between all layers. Typed selectively via @property where animation or type safety matters.

🌊 Page layer (Inspired by CUBE CSS)

Native elements, layout, base typography. CUBE CSS inspired methodology embraces the cascade here — it's exactly the right tool for this context. l- prefix for layout, global element styles, token inheritance. ¹

Note

CUBE CSS's "embrace the cascade" philosophy applies to the page layer only. Inside web components, Shadow DOM provides encapsulation — CUBE CSS and the Shadow DOM are philosophically opposite, and that's fine. They serve different contexts.

🧩 Web Components

Shadow DOM encapsulation. Single class per component (eds-button). Tokens pierce the shadow boundary via custom properties. Adopted stylesheets for zero style duplication across instances.

⚛️ React (Phase 1)

Same CSS, light DOM. React becomes a thin wrapper around web components in Phase 2. Product teams never notice the transition.

---

🧩 Component conventions

One class. Data attributes for consumer decisions only.

The rule of thumb: if removing the attribute would require the consumer to make a new decision — keep it. If removing it means the component handles it internally — remove it.

<!-- ❌ Current — exposes Figma's internal structure -->
<button
  class="eds-button"
  data-variant="primary"
  data-selectable-space="md"
  data-space-proportions="squished"
  data-font-family="ui"
  data-font-size="md"
  data-line-height="squished"
  data-color-appearance="neutral"
>

<!-- ✅ EDS 2.0 — consumer API only -->
<button
  class="eds-button"
  data-variant="primary"
  data-size="md"
  data-color="accent"
>

Caution

The current button exposes the typography system's internal configuration as HTML attributes. This leaks Figma's variable collection structure into the DOM and makes the component hard to reason about for both developers and AI agents. Typography decisions belong inside the component CSS.

Inspired by Designsystemet, whose button in production looks like this:

<button class="ds-button" data-variant="primary" data-color="accent" type="button">

---

💅 CSS conventions

One root selector. Nesting for everything else.

@layer eds-tokens, eds-base, eds-components, eds-utilities, eds-overrides;

@layer eds-components {
  .eds-button {
    /* Local variable contract — the component's "API" */
    --btn-bg: var(--eds-color-bg-emphasis);
    --btn-color: var(--eds-color-text-on-emphasis);

    background: var(--btn-bg);
    color: var(--btn-color);
    min-height: var(--eds-size-11);

    /* Variants reassign local vars only */
    &[data-variant="secondary"] {
      --btn-bg: transparent;
      --btn-color: var(--eds-color-text-subtle);
    }

    /* Hover only on pointer devices.
       :where() keeps specificity at zero */
    @media (hover: hover) and (pointer: fine) {
      &:where(:not(:disabled)):hover {
        --btn-bg: var(--eds-color-bg-emphasis-hover);
      }
    }

    /* Disabled via both native and aria */
    &:is(:disabled, [aria-disabled="true"]) {
      cursor: not-allowed;
      opacity: var(--eds-opacity-disabled);
    }
  }
}

Tip

The eds-overrides layer at the top of the stack is a sanctioned place for product teams to put customisations. Without it, teams reach for !important or increasingly specific selectors. With it, overrides become visible feedback — if a product is heavily using eds-overrides, that's a signal the component or token contract needs attention.

Web component factory function

// Factory function — not a class
function EdsButton(element) {
  const shadow = element.attachShadow({ mode: 'open' });

  // Shared CSS via adopted stylesheets — zero duplication across instances
  shadow.adoptedStyleSheets = [buttonStyles];

  // No innerHTML — real DOM nodes
  const btn = document.createElement('button');
  btn.className = 'eds-button';
  btn.append(document.createElement('slot'));
  shadow.append(btn);
}

// Thin registration wrapper only
customElements.define('eds-button',
  class extends HTMLElement {
    connectedCallback() {
      Object.assign(this, EdsButton(this));
    }
  }
);

---

🚀 Migration strategy — same CSS, three phases

Phase 1 — Now: React components

Ship React components using the new CSS conventions. Teams get components immediately. The CSS is the stable contract.

<button
  className="eds-button"
  data-variant={variant}
  data-size={size}
>

Phase 2 — Autumn: Web components

Same CSS file, adopted into Shadow DOM. React wraps the web component. Consumer API unchanged. Zero visual regression.

<eds-button data-variant={variant} data-size={size}>

Phase 3 — Ongoing: Framework-agnostic adoption

Teams choose their adoption level:

• 🧩 Web component only — drop in anywhere, works immediately
• 💅 CSS only — import the stylesheet, build your own implementation
• 🎯 Both — full EDS experience

This means teams using Vue, Angular, Svelte, or vanilla HTML all have the same options. EDS works alongside Tailwind too — configure Tailwind to use EDS tokens as its design scale.

Note

A team that starts with just the CSS can migrate to web components later with zero visual regression — they've been building against the same token contract all along.

---

🪙 Token pipeline

One source. Multiple consumers.

🎨 Token Studio  →  ⚙️ Style Dictionary  →  📦 Outputs

• Token Studio — designers own this, it's the source of truth
• Style Dictionary — transforms px → rem for CSS, keeps px for Figma sync
• CSS — custom properties, typed selectively with @property
• Figma — stays in sync automatically, no longer the source of truth
• MCP server — AI agents get token context directly, no guessing

Important

Figma is no longer the source of truth for tokens. It becomes a visualisation and component design tool — a consumer of tokens rather than their origin. Token Studio is where tokens are authored. This is a healthier separation of concerns and decouples EDS from any single design tool.

Why @property selectively, not wholesale

Typing every token has a measurable memory and parse cost at scale. Type selectively:

• ✅ Tokens you want to animate or transition
• ✅ Colour tokens where type safety prevents bugs
• ✅ Tokens used in calc() where <length> or <number> typing helps
• ❌ Static spacing tokens used only in padding — unregistered costs almost nothing

---

⏳ Progressive enhancement — space toggles now, if() when ready

Today's space toggle pattern is clever but opaque — it exists because CSS lacked conditional logic. if() is already in Chrome Canary and moving fast.

/* Today — space toggle pattern */
.eds-button {
  --_is-sm: var(--is-size-sm) var(--font-size-sm);
  --_is-md: var(--is-size-md) var(--font-size-md);
  font-size: var(--_is-sm, var(--_is-md));
}

/* Tomorrow — native if() */
.eds-button {
  font-size: if(
    style(--size: sm): var(--font-size-sm);
    style(--size: md): var(--font-size-md);
    else: var(--font-size-lg)
  );
}

The @supports bridge makes the transition automatic — no breaking change, no migration:

/* Fallback — works today */
.eds-button { font-size: var(--_is-sm, var(--_is-md)); }

/* Progressive enhancement — takes over when supported */
@supports (font-size: if(style(--x: y): 1px)) {
  .eds-button {
    font-size: if(
      style(--size: sm): var(--font-size-sm);
      else: var(--font-size-md)
    );
  }
}

Tip

Our users are on evergreen browsers — Edge updates within approximately one week of a new Chromium release. This means we can use modern CSS now, not in two years. @layer, @property, :has(), container queries, text-box, color-mix() — all available today.

---

🛠️ Tooling & enforcement

Stylelint config (updated — BEM is gone)

selector-class-pattern:
  - '^eds-[a-z][a-z0-9]*(-[a-z0-9]+)*$'
  - message: "Use eds-component-name format"

declaration-property-value-disallowed-list:
  /^color/: ['/^#/', '/^rgb/']

property-disallowed-list:
  - ['margin-left', 'margin-right', 'padding-left', 'padding-right']

CLAUDE.md rules for AI agents

ONE class per component: eds-button
Variants via data-attrs: data-variant="primary"
No descendant classes — use nesting
No hardcoded values — use var()
Logical properties only (padding-inline not padding-left/right)
Local var contract at top of block:
  --btn-bg: var(--eds-color-bg, fallback)

Hover states:
  @media (hover: hover) and (pointer: fine)
  Use :where() to keep specificity at zero

Disabled states:
  :is(:disabled, [aria-disabled='true'])

Overrides go in eds-overrides @layer, never inside component selectors

---

✅ Summary — what we're building toward in EDS 2.0

🪙 Tokens in Token Studio
Designers own tokens. Style Dictionary transforms for CSS and Figma. MCP server for AI agents.

🌊 CUBE for the page layer
Embrace the cascade for native elements. l- for layout, global base styles, token inheritance.

🧩 Single class per component
Inspired by Designsystemet. Nesting for descendants. Data-attributes for consumer decisions only.

⚛️ React first, web components next
Same CSS throughout. React wraps web components in Phase 2. Teams never notice the transition.

⏳ Progressive enhancement
Space toggles today. if() via @supports when browser support arrives. No migrations needed.

🌐 Evergreen baseline
Edge updates within a week of Chromium. We can build for the web as it is today.

---

Note

This document is a living record of architectural decisions for EDS 2.0. Discussion and questions welcome below. 👇

Footnotes

1. Layout classes is something product teams have asked for. ↩

[pomfrida]

Some thoughts after reflecting on both this discussion and our meeting today:

What we're already doing
A lot of what you're proposing is already in place in /next:

• @layer eds-components used consistently
• Native CSS nesting throughout
• Local custom property contracts (--_ prefix)
• :has() for relational styling (Checkbox, Radio, Switch)
• @media (hover: hover) and (pointer: fine) hover guards
• :focus-visible everywhere
• No hardcoded values — everything uses tokens

We're closer to the vision than the document suggests.

Data attribute exposure
The critique that we "expose Figma's internal structure" isn't quite accurate. The consumer API is clean:

<Button variant="primary" size="default" tone="accent">Save</Button>

data-selectable-space, data-space-proportions etc. are internal implementation details set by the React component itself — consumers never see these. It's a naming question about internals, not an API problem.

That said — agreed the internal names could be simpler (e.g. data-size instead of data-selectable-space). Happy to simplify these gradually.

BEM "fights against the cascade" — does it though?
This is the point I want to push back on most. The traditional criticism of BEM is that it creates high-specificity selectors that fight the cascade. But that criticism assumes BEM without layers.

Our BEM classes live inside @layer eds-components. That means:

• Any consumer CSS outside the layer automatically wins — no specificity battle
• The cascade works exactly as intended — layers control the priority, not class name specificity
• BEM inside a layer gives us the best of both worlds: readable, debuggable class names with zero specificity cost

So the argument that BEM "fights the cascade" doesn't apply to how we're using it. @layer already solved the problem BEM was criticised for. Dropping BEM now removes the readability and debuggability benefits without solving a problem that still exists.

Concrete example — which is easier to reason about in the inspector?

/* BEM inside @layer — what we have */
.eds-switch__track { ... }
.eds-switch__handle { ... }

/* Single class + nesting — proposed */
.eds-switch > span:nth-child(2) { ... }
.eds-switch > span:nth-child(2) > span { ... }

To add concrete context: there's an open issue from OPT (#4533) that illustrates exactly this need. They want a stable way to target the internal typography element in Button for style overrides — not because they want to fight the design system, but because .eds-button > p breaks silently on internal refactoring.
Their ask is for a className prop on the internal element, but the underlying need is just a stable, documented handle on a sub-element. BEM class names satisfy that need directly, with no extra API surface. Whatever the alternative is — className prop, ::part(), data-part — it still requires an explicit decision from us about what to expose. BEM just happens to already make that decision in a way that's readable, debuggable, and costs nothing in the shadow DOM transition.

Reducing data attributes — agreed
This is where I'm most aligned with the proposal. The heavy use of data attributes has been a real pain point in development. Debugging components means mentally mapping data-selectable-space="md" + data-space-proportions="squished" + data-font-family="ui" + data-line-height="squished" back to what they actually mean. It's a lot of indirection for styling that could live directly in the component CSS.

If we can move typography and spacing decisions into the CSS itself — resolving them from a single data-size attribute or similar — that would simplify both the authoring experience and the DOM output. Fewer attributes to coordinate means fewer things to get wrong.

Shared CSS between React and Web Components
The argument that single-class CSS enables reuse across React and Web Components doesn't hold up on closer inspection. Shadow DOM scopes all CSS regardless — .eds-button__label works just as well inside a Shadow DOM as .eds-button > span. BEM classes aren't the obstacle to CSS reuse.

What actually has to match is the DOM structure. As long as the Web Component produces the same HTML as the React component, the same stylesheet works — whether it uses BEM classes or nesting selectors.

Ironically, it's the data attributes that create friction for a web component migration — not BEM. Today we write:

.eds-button[data-variant="primary"] { ... }

In a web component, the attributes live on the host element (<eds-button data-variant="primary">), but the CSS lives inside the shadow DOM. That selector won't match the host — it either needs to be rewritten to :host([data-variant="primary"]), or the web component needs JS boilerplate to reflect each attribute onto the internal element.

Neither option is a dealbreaker, but it's worth noting: BEM classes are zero-effort to reuse across React and Web Components, while data attributes require either CSS changes or extra JS. If we're optimising for a smooth web component transition, BEM is actually the lower-risk approach.

What I think we should actually do
Based on the meeting discussion, here's what seems valuable and actionable:

• Look into reducing data attributes — new components start with fewer attributes (move typography/spacing into CSS, keep only consumer-facing ones like data-variant and data-size). Existing components get updated opportunistically when we're already making changes. A guideline going forward, not a rewrite.
• Keep BEM for sub-elements — it works well inside layers, serves real consumer needs, and is zero-cost for web component migration
• Explore adopted stylesheets for the web components phase (research, not commitment)
• MCP server for Figma→tokens in Q3 as discussed
• Don't rewrite existing components — evolve the patterns forward

[millus]

Lots of good points here, and I think we're more aligned than it might seem — Victor sets the direction,
Frida keeps it grounded, and I think we mostly already do the right things in /next.

Just want to add one angle on the BEM discussion.

BEM, nesting and CUBE CSS

On the BEM question specifically — I'm not strongly attached to it either way, but one thing struck me
when working with native CSS nesting. In Sass you could write:

  .eds-switch {
    &__track { ... }
    &__handle { ... }
  }

In native CSS nesting that doesn't work, so you end up writing:

.eds-switch {
   & .eds-switch__track { ... }
   & .eds-switch__handle { ... }
 }

Which feels redundant — "eds-switch" appears twice. And just to clarify — I agree with Frida that
span:nth-child(2) is too messy and hard to read, that's not what I'm suggesting either.

What I mean is a middle ground: give those elements a simple class name and scope them to the parent block,
like CUBE CSS describes here: https://cube.fyi/block.html#no-formal-element-syntax — so we get the readability of
BEM without having to repeat the full component name in native nesting.

.eds-switch {
  & .track { ... }
  & .handle { ... }
}

Where native HTML is semantic enough — img, button, input — targeting the element directly is fine too.
It's only when elements are deeply nested or ambiguous that a class name earns its place.

Frida's point about stable handles for consumers is valid though — .eds-switch__track is unambiguous,
while .track could theoretically clash if a consumer has their own .track class. That's worth thinking
about. I still think .eds-switch .track is specific enough in practice, but it's a tradeoff worth being
deliberate about rather than just assuming it works.

Same readability and debuggability for consumers, but cleaner to write. Keep the root class
(eds-switch), simplify the sub-parts. @layer still works exactly the same regardless.

Data attributes — variants vs internal styling

On typography and spacing data attributes — in CUBE terms, data-color-appearance is exactly right as a
data attribute (it's a variant — what the component is). But data-font-size, data-font-family,
data-selectable-space are internal styling decisions (how it looks) that the component sets itself —
consumers never see these.

In CUBE terms these would either be utility classes or just resolved directly in the component CSS, rather than
data attributes.

Either way, reducing the number of attributes to coordinate would make components easier to reason about.
That's a bigger task though, best tracked as a separate issue.

CSS file organisation - keep it simple for now

On CSS file organisation — I think we continue with one file per component imported into the global CSS,
keeping the setup simple for consumers. The adopted stylesheets question feels like the right thing to
revisit when we get to web components, not now.

So that's my take — we could try the simpler sub-part class names on new components going forward, keep the bigger
architectural changes as separate tasks, and see how we feel about it. Happy to discuss further!

[vnys]

Thanks both of you – this is exactly the kind of discussion I was hoping for, and between the two of you you've sharpened the proposal considerably 😊

Where you're right and I was wrong

The consumer API point is fair. I was looking at the internal DOM output and conflating implementation details with the public API. The React component surface is clean – variant, size, tone – and the data attributes are an internal concern. That's a meaningful distinction I glossed over.

The BEM + @layer argument is also solid. The original criticism of BEM – that it fights the cascade through high specificity – genuinely doesn't apply when everything sits inside a named layer. You've already solved that problem, and I overstated the case there.

The native CSS nesting point is something I hadn't fully articulated, and it's a real practical concern. In Sass you could write .eds-switch { &__track { } } cleanly. In native CSS nesting that doesn't work, so you end up with .eds-switch { & .eds-switch__track { } } – which repeats the component name and feels redundant.

On sub-element naming

The middle ground – scoped simple class names like .track and .handle under .eds-switch, as the CUBE docs describe – is worth trying on new components. It gives readability without the verbosity of full BEM, and .eds-switch .track is specific enough in practice to avoid clashes. The concern about stable, unambiguous handles is valid though – .eds-switch__track is completely unambiguous in the inspector in a way that .track isn't. That's a real tradeoff worth being deliberate about rather than assuming either approach just works.

On data attributes

The CUBE-lens distinction here is useful and cleaner than anything I put in the original post: data-color-appearance is right as a data attribute because it's a variant – what the component is. But data-font-size, data-font-family, data-selectable-space are internal styling decisions the component sets itself, which consumers never touch. In CUBE terms those belong inside the component CSS, not on the element. Good rule of thumb going forward: if the consumer never sets it, it shouldn't be a data attribute.

On CSS file organisation

Agreed – one file per component imported into global CSS is the right approach for now. The adoptedStyleSheets question belongs in the web component planning conversation, not here.

What I'd propose as a concrete next step

Try the simpler scoped sub-part names on new components going forward and see how it feels in practice. Keep the bigger architectural questions – ::part() vs BEM for the web component phase, reducing internal data attributes – as separate tracked issues rather than blocking the current work.

The direction I care about – aligning with where CSS is heading, reducing internal complexity, cleaning up the consumer API – is largely compatible with the foundation that's already in /next. I should have framed it that way from the start.

[pomfrida]

Refining the data-attribute heuristic — decisions vs configuration

Coming back to this with a sharper formulation. The "if the consumer never sets it, it shouldn't be a data attribute" rule works as a first cut, but it covers two structurally different kinds of attributes — and the conflation makes it ambiguous in practice.

Two kinds of internal data attributes

Configuration — passes a styling decision through the DOM that the component already knows.

• data-font-family="ui", data-font-size="md", data-line-height="default"
• data-selectable-space="md", data-space-proportions="squished"

The component already knows what font and spacing it wants — that's a CSS concern, not a DOM concern. Resolving these attributes back into styles is internal coordination dressed up as state. This is the pattern the original post called out.

Decision / utility opt-in — interface to shared design system infrastructure.

• data-baseline="grid" — opts into the text-box trim utility defined in eds-tokens/typography.css
• data-density="comfortable" — opts into density tokens
• data-color-scheme="dark" — opts into theme inheritance

These don't pass styling through the DOM. They apply a named, shared behavior. Conceptually they're closer to utility classes (flow, sr-only) or semantic attributes (role="alert") than to configuration.

A sharper framing

Does the attribute express a semantic concept (variant/state/utility opt-in), or a low-level styling choice (font-family/line-height)?

• Semantic concept → fine as a data attribute
• Low-level styling → belongs in component CSS

This catches the original concern (don't leak Figma's variable collection into the DOM) without ruling out legitimate uses of data attributes as hooks into shared infrastructure.

Applying it to what's in /next today

Per ADR-0004, all of these are component-set — consumers use typed props (variant, color, placement), and the component maps them to data attributes. So the question isn't who sets the attribute, it's what the attribute expresses.

Scope: this is about EDS-specific attributes only. Standard web platform attributes (data-testid, aria-*, native form states) and third-party conventions (e.g. Floating UI's data-placement) aren't part of this discussion.

EDS-defined semantic state

Reflects a meaningful concept the component's API exposes or derives — these are real EDS API surface.

data-variant, data-color-appearance, data-position, data-icon-size, data-icon-only, data-round

EDS-defined utility opt-ins

Hooks into shared infrastructure defined elsewhere in the system.

data-baseline, data-density, data-color-scheme

EDS internal configuration — move into CSS

Low-level styling decisions, not concepts the API exposes.

data-font-family, data-font-size, data-line-height, data-selectable-space, data-space-proportions

Why this matters for scaling

For a single-source-of-truth pattern like text-box trim, having the math live in eds-tokens and components opt in via data-baseline:

• O(1) maintenance — update one rule, all components inherit
• Easy to add new components — just add the attribute
• Drift can't accumulate between components

The alternative — every component implementing its own @supports block with the trim calc — has O(N) maintenance and drift is almost guaranteed. We're already seeing small drift: var(--eds-padding-top-baseline) in some places, calc(round(1cap, 4px) - 1ex) in others. Equivalent today, but not the same expression — and that's how drift starts.

Concrete proposal

1. Adopt the decision-vs-configuration framing in component conventions
2. New components: typography/spacing decisions live in CSS, not DOM
3. Utility opt-ins via data attributes are fine and encouraged where shared infrastructure exists (currently data-baseline, data-density, data-color-scheme)
4. Existing components with configuration-style attributes get cleaned up opportunistically — not a rewrite, an ongoing direction