Name the parts of the admin markup so themes can target them

[marks-zyz]

Splitting this out of #1493 because it is small, separable, and useful even if nothing else there lands.

The admin already names things, just not the parts a stylesheet needs. Here is a dashboard metric card as rendered by 0.36:

<div data-testid="dashboard-metric" class="flex w-full flex-col rounded-lg bg-kumo-elevated ring ring-kumo-hairline">
  <div class="-my-2 flex items-center gap-2 bg-kumo-elevated p-4 font-medium text-kumo-subtle">
    <h2 class="px-3">Draft</h2>
  </div>
  <div class="relative flex flex-col gap-2 rounded-lg bg-kumo-base p-4 pr-3">
    <div data-testid="dashboard-metric-value" class="px-3">0</div>
  </div>
</div>

The shell has a name and the value has a name. The two divs in between, the card header and the card body, have none, and those two are exactly what a theme has to paint. So the only way to reach them is to describe their paint:

main .bg-kumo-elevated.ring-kumo-hairline > div:first-child { border-bottom: 1px solid #dcdcde; }

Nothing in that selector says "card header". When a utility class is swapped or a wrapper is added, the rule stops matching, with no error and no failing test. The panel just quietly loses a line.

What would fix it is naming, not theming. Something like data-emdash-part="card-header" on the pieces that carry the look. The ones we keep hitting: card header and card body, table wrapper, section (metabox) header, and the search field wrapper.

The project already believes in this where it owns the component: Kumo's Sidebar exposes 21 named parts via data-sidebar, and the rules we write against the sidebar are by far the most stable in our stylesheet. This is asking for the same treatment on the screens EmDash composes itself.

Concrete numbers from our side, in case they help scope it. We ship a WordPress-looking admin theme (emdash-classic-theme, MIT), and it currently carries 456 !important declarations and about 100 selectors anchored on Tailwind utility classes. We re-anchored what we could onto structure, and every remaining one is a container with no name. Each of those is a silent break waiting for the next release, paid separately by everyone who tries this.

It also matters beyond themes: any white-label work runs into the same wall, since branding is not only the logo.

Happy to open the PR ourselves if the shape is agreed. We have the list of elements and the measurements behind it, and we would rather contribute the attributes than keep guessing at class names from the outside.

[marks-zyz]

Following up on my own opening post with two corrections, from a conversation elsewhere about this same issue.

Sidebar parts: 21, not 12. Recounted in @cloudflare/kumo 2.6.0, dist/chunks/sidebar-*.js, distinct data-sidebar values: content, content-container, footer, group, group-label, header, menu, menu-badge, menu-button, menu-item, menu-sub, menu-sub-button, menu-sub-item, peek-zone, rail, resize-handle, separator, sidebar, sliding-view, sliding-views, trigger. My 12 was the subset my own stylesheet happens to use. Corrected in the opening post.

The cards need nothing from Kumo. In 2.6.0 LayerCard.Secondary and LayerCard.Primary are literally <div className={cn(base, className)} {...rest}>, so a data-* passed at an EmDash call site lands on the element; LayerCard itself goes through Base UI's mergeProps, same result. That part of the original ask is one attribute per call site in EmDash, with zero changes in Cloudflare's design system.

One thing I had backwards, worth recording because it shrinks what needs naming: corners and spacing are reachable by token. In @emdash-cms/admin 0.37.0, .rounded-md compiles to border-radius: var(--radius-md) and .p-4 to padding: calc(var(--spacing) * 4). Redeclaring --radius-* retunes every corner in the panel and --spacing retunes the whole density, with no !important and no class name involved. I split my stylesheet in two along that line: a token layer that ships on its own, and the rest.

What survives that split is what this discussion is about, and I can put a number on it now: 109 selectors with no way in except a generated class name, against 281 riding on an attribute, a tag, or a .emdash-* / .kumo-* class. The 109 are the metabox header band, the collapsed menu tabs, the listing state cells, the editor panel rows. Every one of them paints an element that has no name.

I count it on every release now and CI fails when the number grows, so if any of the naming here lands I can report exactly how many of the 109 it retires.

[marks-zyz]

A data point from 1.1.0: the 0.42 redesign broke our admin skin on several screens at once, because nothing in the new markup is named. Giving the page-header action one look took 37 structural selectors in emdash-admin-theme-classic 0.2.3, across five header shapes. Two attributes, for example data-emdash-part="page-header" and "page-header-actions", would replace them and survive the next layout change. Happy to send the PR if the shape works for you.