docs: add ADR 0006 — flat CSS class names for EDS 2.0 components

[millus]

Summary

Documents the flat class name convention for EDS 2.0 `/next` components as an Architecture Decision Record, superseding the BEM-inspired naming mentioned in ADR 0002.

This ADR can be reviewed and merged independently of the component migration PRs (#5114, #5115, #5127).

Changes

• Adds `documentation/adr/0006-flat-class-names-for-eds-2-components.md`
• Updates ADR 0002 status to note the naming convention section is superseded
• References discussion #4639 as the origin of the "one root selector, nesting for everything else" direction
• References CUBE CSS blocks — no formal element syntax as the inspiration
• Includes a note on native element selectors vs flat class names and why flat classes are preferred for consumer-facing stability

Related

• chore: convert remaining /next components from BEM to flat class names #5104 — migration issue
• fix!: convert Banner BEM classes to flat class names #5114 — Banner
• fix!: convert Field, Switch, Radio, Checkbox BEM classes to flat class names #5115 — Field + Switch + Radio + Checkbox
• fix!: convert Input and TextField BEM classes to flat class names #5127 — Input + TextField

[millus]

@claude review

[claude]

Claude finished @millus's task in 1m 5s —— View job

---

Review: ADR 0006 — Flat CSS class names

I read both changed files, cross-checked against the ADR template, the existing ADRs, AGENTS.md, and .claude/rules/eds-component.md.

• Read ADR 0006 and the ADR 0002 status change
• Verify template conformance and cross-references
• Check the "Confirmation" claims against the actual files
• Post review

---

Verdict

This is a well-written, well-structured ADR and it's safe to merge as a docs-only change. It follows 0000-template.md faithfully (Context → Decision Drivers → Options Considered → Decision → Consequences → Confirmation → Related), the rationale is sound, and it's consistent with what AGENTS.md already says. Below are minor points — none are blocking.

Consistency checks (all ✅)

• AGENTS.md CSS section does document the convention — line 333 ("simple nested names for internal elements (.label-row, .icon); variants via data attributes") and line 238 (data attributes, not modifier classes). The Confirmation claim holds.
• ADR 0002 status note is a good call — only the naming sub-decision is superseded, so the partial-supersede wording (rather than flipping the whole status to "Superseded") is more accurate than the template's binary option.
• Numbering — 0006 is unique (the repo has duplicate 0004/0005 numbers, but that's pre-existing).
• Cross-references — links to Designing with CSS, not around it 🎨 #4639, CUBE CSS, ADR 0002/0004, and issue chore: convert remaining /next components from BEM to flat class names #5104 all resolve correctly.

Minor suggestions (optional)

1. Confirmation bullet slightly overstates the rule file (0006:117):

   The eds-component.md rule file loaded by Claude Code in .claude/rules/ references this convention

   .claude/rules/eds-component.md currently only says "Variants and states via data-* attributes, not modifier classes" — it doesn't mention flat inner class names. The claim is half-true. Either soften it to "…references the data-* convention" or add one bullet to the rule file so the doc matches reality. Fix this →

2. Tension between Rule 5 and the "Native element selectors vs flat class names" section. Rule 5 (0006:73) says "Cross-component selectors — target native HTML elements … rather than another component's internal class names", while the section at 0006:75-77 argues flat classes are preferred for stability. They aren't contradictory (Rule 5 is about EDS-internal cross-component coupling; the section is about the consumer-facing surface), but a reader could trip on it. One clause — e.g. "Rule 5 applies to EDS-internal cross-component selectors; consumer-facing inner elements still get classes" — would remove the ambiguity.

3. Example attribute value (0006:83): data-standalone={true} renders as data-standalone="true" in the DOM, whereas the prose at 0006:71 lists data-standalone as a bare boolean state (matching the [data-icon-only] / [data-round] style in AGENTS.md). The [data-standalone] selector matches either way, so this is purely cosmetic, but using data-standalone (presence) in the example would align with the boolean-state convention.

4. Typographic ellipsis in code (0006:96-97): the CSS example uses … as a placeholder inside rule bodies. Fine for an illustrative snippet, but /* … */ would read more clearly as "elided" since … isn't valid CSS.

None of these affect the decision itself. Nice, clear ADR. 👍
• docs/adr-006-flat-class-names

[pomfrida]

Great 👏