Z-index
Eight named layers. The only scale where the name is the whole point and the number is an implementation detail.
Stacking order is not a quantity, it is a set of agreements about what sits over what. A tooltip is above a modal because of what a tooltip is, not because 600 is a larger number than 400. So these are named by role, and the numbers exist only to make the names true.
There is no preview column because a z-index has no appearance: it shows only where two things overlap, and a table row has nothing to overlap.
Layers
Read it top to bottom — this is the layering policy, not a lookup table.
| Token | Value |
|---|---|
| --z-base | … |
| --z-raised | … |
| --z-dropdown | … |
| --z-sticky | … |
| --z-overlay | … |
| --z-modal | … |
| --z-toast | … |
| --z-tooltip | … |
The gaps are the useful part. Hundreds between layers leaves room to insert one without renumbering everything above it — and the gap of ten between base and raised is deliberate too, because that is where local nudges belong: a hovered card lifting over its neighbour is not a new layer of the application.
The list is the policy. When two things collide, the fix is to decide which of these eight roles each one is — not to add 1, and never to write z-index: 9999, which is only ever a statement that nobody knows what the layers are.
Position and stacking contexts
z-index does nothing on a static element. It needs position to be anything but static — or a flex or grid item, which participate without it. So the first question when a layer misbehaves is not which token it used.
A stacking context is a prison. Certain properties — transform, filter, opacity below 1, will-change, backdrop-filter — make an element a new stacking context, and everything inside it is then ordered relative to its siblings only. A modal at --z-modal inside a card that happens to carry a transform cannot rise above that card, whatever number it holds. This is why an overlay belongs at the top of the document rather than beside the thing that opened it — a fact about where you put the element, which no token can express.
Naming
This scale and --shadow-* are both ranks rather than multipliers — neither is base × N, and neither supports arithmetic. Yet this one is named entirely by role and shadow is numbered 1 to 4. Two ordinal scales, two conventions, no stated reason.
What makes it more than tidiness: a shadow scale named by role would be almost this same list. Raised, dropdown, modal — a thing that sits higher casts further, and the two scales may be one concept, elevation, expressed twice. That is a question for Phase 4, when there are components to name against; renaming either one alone would only make the pair look intentional.