[material-ui] CSS-var density adapter experiment

[siriwatknp]

Preview: https://deploy-preview-48624--material-ui.netlify.app/experiments/density-showcase/

Not intended to merge as-is — opened for the deploy preview and review.

The idea

Let designers tune component density — per component, per size, or across the
whole app — without editing component source or writing calc.

Every density-bearing dimension (padding, gap, height…) becomes a plain CSS
variable with a literal-px fallback, so an un-configured theme renders today's
exact pixels (Argos zero-diff). You opt in only where you want a denser or
roomier UI; nothing else changes.

Consumer usage

Opt into holistic density with one function — enhanceDensity:

import { createTheme, enhanceDensity } from '@mui/material/styles';

// Defaults derive from theme.spacing → pixel-identical to today.
const theme = enhanceDensity(createTheme({ cssVariables: true }));

Make the app denser (or roomier) by tuning the 7-step scale:

const theme = enhanceDensity(createTheme({ cssVariables: true }), {
  scale: { xxs: '2px', xs: '4px', sm: '6px', md: '8px', lg: '12px', xl: '18px', xxl: '24px' },
});

enhanceDensity emits the scale as --mui-density-* vars (needs <CssBaseline />)
and wires every supported component to it. Change the numbers → the whole UI reflows.

Just one component? Scope its public token — no function required:

// every small Button inside is denser (custom props inherit)
<Box sx={{ '--Button-small-pad': '2px 8px' }}>…</Box>

Playground

/experiments/density-showcase —
the left sidebar toggles three presets (Compact / Normal / Comfort); the main
panel is a live gallery of every supported component.

Things to try:

• Flip a preset — the entire gallery reflows off the one scale. Normal is
  pixel-identical to today.
• Read the scale panel — the resolved --mui-density-* values for the active preset.
• Expand a component in the token panel — see exactly which sized tokens it
  pulls and what each resolves to.

Per-component token reference: /experiments/density-tokens.

Technical approach

Each component is read as three layers of responsibility, sharing one cascade:

--Component-<size>-<key>   public sized token   → the designer knob (what enhanceDensity targets)
--Component-<key>          agnostic seam        → the styled root's single consumption point
--_<key>                   internal default     → today's Material literal (lives in `variants`)

The styled root consumes the seam, which falls back to the internal default —
one consumption point per property, no JS branching on size/variant:

// agnostic root
padding: 'var(--Button-pad, var(--_pad))',

// Material layer routes the public sized token over the default, per size (in `variants`)
{ props: { size: 'small' }, style: { '--Button-pad': 'var(--Button-small-pad, var(--_pad))' } },

So three audiences each get their layer untouched: an agnostic root with no design
opinion, the Material sizes/variants on top, and a design-system override surface
through the public tokens.

A few shapes the model handles:

• Sized vs. base vs. state tokens. Axes are sized by default. A boolean dense
  prop uses a state token (only the on-state is named). A size-invariant base
  token is reserved for the rare axis where per-size override is meaningless.
• Paired siblings. A TextField's floating InputLabel is a preceding sibling
  of the input; OutlinedInput owns a :has bridge so one padding knob moves the
  input box and its label together.
• Shared base + interlocked geometry. Checkbox/Radio/Switch share SwitchBase's
  seam. A Switch tokenizes its real dims and derives the coupled values with
  calc, so the thumb stays centered at any density.

Supported today: Button · OutlinedInput (+ InputLabel, TextField outlined) · the
dashboard set (Chip, IconButton, MenuItem, ListItem/Button/Icon/Text, ListSubheader,
Toolbar, Tab/Tabs, TablePagination, CardContent, Select, Breadcrumbs, InputAdornment,
Badge) · the SwitchBase family (Checkbox, Radio, Switch).

Design notes:

• Decision record: docs/adr/0001-css-var-density-adapter.md
• Rollout recipes + gotchas: docs/adr/density-adapter-rollout.md

What's next

Still to settle before this could ship:

• Define the density token set per component. Which dimensions are
  density-bearing has been picked per component during rollout — we need an agreed,
  documented list of tokens for each component (and a rule for what deliberately
  gets none), so the surface is predictable instead of ad hoc.
• Edge cases.
  • Asymmetric padding — FilledInput and standard Input have uneven block
    padding (4/5, 25/8); a single padBlock won't cover it, they need a
    per-side seam.
  • :has() baseline — the outlined-label bridge relies on :has()
    (Chrome 105 / Safari 15.4 / Firefox 121); confirm the support target.
  • Vars outside theme.vars — enhanceDensity emits --mui-density-*
    post-createTheme, outside the standard css-var pipeline (see ADR-0001).
    Decide whether density should be a first-class createTheme node so it
    re-scopes at any level.
• Validate the default step mappings. The per-component scale-step mappings in
  enhanceDensity (e.g. Switch dims composed from steps) are hand-tuned to land on
  today's pixels — confirm they hold across the full set.

[code-infra-dashboard]

Deploy preview

https://deploy-preview-48624--material-ui.netlify.app/

Bundle size

Bundle	Parsed size	Gzip size
@mui/material	🔺+16.4KB(+3.15%)	🔺+3.15KB(+2.10%)
@mui/lab	0B(0.00%)	0B(0.00%)
@mui/private-theming	0B(0.00%)	0B(0.00%)
@mui/system	0B(0.00%)	0B(0.00%)
@mui/utils	0B(0.00%)	0B(0.00%)

Details of bundle changes

---

Check out the code infra dashboard for more information about this PR.