Cards, dividers and disabled states: the layers color never shows
These three are where a palette scheme most easily misleads. Numerically they are almost identical to the background, and they are exactly what makes an interface feel layered. All 69 layered roles in the library fall below 1.5:1, and the pages still do not look flat.
Start with the numbers, because they look wrong
| Role | Median vs background | Full range | Reaching 1.5:1 |
|---|---|---|---|
Border / divider (border, divider) | 1.21:1 | 1.10 to 1.39:1 | none |
Card / surface (surface, card) | 1.04:1 | 1.03 to 1.10:1 | none |
Disabled (btnDisabled) | 1.59:1 | 1.21 to 3.30:1 | about a third |
The first reaction is usually that the data must be broken. A 1.04:1 ratio means the card and the background have almost the same luminance, so how is the card visible at all?
Because it was never visible through color.
Why something this low still reads
Take a card. Four things make it identifiable on screen, and color comes last:
- Position and space. A 16 or 24 pixel gap surrounds the card, and the gap is a different color from the card, so the boundary gets drawn by emptiness. This does most of the work.
- Shadow. Not a color role but a render result, and the one that expresses elevation. The library does not encode shadows, because a shadow is not a color value.
- Corner radius. A 12px radius says "separate region" more clearly than any border.
- A very small color difference. The 1.04:1.
So 1.04:1 is intent, not defect. A card should float in whitespace rather than be boxed by a stroke. That became the default after iOS, because outlines make an interface look like a spreadsheet and a faint fill makes it look clean.
Same story for borders. 1.21:1 is roughly #e2e8f0 on white. It barely registers, and it does register, because the eye picks up the edge of a thin line more readily than a broad area of slightly different color.
Where this breaks
Two situations, both common.
One: exporting the palette for someone else. This site's CSS variable export is a case in point. Whoever receives --surface and --bg does not receive your spacing, your radius or your shadow, only two colors that are nearly identical. They lay out a screen and the card genuinely disappears. That is not their mistake; the information was lost in transit.
Two: poor screens and bright light. A 1.04:1 difference is gone on an OLED phone at half brightness and completely gone outdoors. What still works is whitespace and shadow, and if neither was built, the interface really is flat.
So the test should read: layering through color may be extremely low, provided position and shadow are both present. If color is all you can ship, whether for theming, for a third party, or on a platform that forbids shadows, then color cannot sit that low.
If color is all you have, these three values work
- Borders need 1.5:1 or more before the eye reliably reads a line. At 1.21:1 it is a line on a good screen and noise on a bad one. Concretely: a border on white should not be lighter than roughly
#d4d4d8. - Cards need 1.15:1 before they read as raised. At 1.04:1 they stop being cards the moment the shadow goes. Dark themes invert the direction, cards lighter than the background, and still need that 1.15:1 gap.
- Disabled states cannot be handled by color alone. The 1.59:1 median says "unavailable" but says nothing about whether the label is still readable. Text on a disabled button still needs to be legible; the disabled signal belongs in reduced opacity and
cursor: not-allowed, not in crushing the value until nothing can be seen.
These are not standards. They are lower bounds back-calculated from "still distinguishable on a bad screen". The robust answer uses both layers: color contributes a little, position and shadow contribute the rest.
One role that gets misjudged: the mini program tag
The mini program tag is routinely flagged. Its median contrast against the background is only 2.91:1, which looks like a failing text color.
But tag is not text. It is the background of a label, and dark text sits on top of it. Holding it to 4.5:1 is the wrong test entirely: it is a light fill, and the lighter the fill, the clearer the text on it.
The pair worth checking is "tag fill plus text on the tag", not "tag fill plus page background". This one slips through checklists easily, because 4.5 applies to text and not to backgrounds. Before asking whether a color should pass a contrast threshold, ask whether it carries letters or area.
In a dark theme, these three invert
Every figure above comes from a light background. Dark backgrounds do not follow the same rules with darker values, they invert the direction, and they are easier to get wrong.
- Cards go lighter than the background, never darker. On a light background a card reads as raised by being whiter. On a dark background it reads as raised by being lighter in the same way. Invert that and the card looks like a dent.
- Borders go lighter too. A
#1a1a1aborder on a#121212background lands near 1.1, harder to see than the light-mode equivalent, because luminance differences compress at the dark end. - Disabled states go darker and flatter, but only so far. The direction is right and the amount is easy to overshoot. Darken a button on a dark background too much and it becomes a black shape nobody recognizes as a button.
One more real difference: dark backgrounds are more sensitive to hue. The same hue angle that looks neutral on white picks up a cast on black. So layering in dark mode often cannot be carried by lightness alone; saturation has to be controlled at the same time, or a "neutral gray" card turns faintly blue or yellow.
Two working rules: dark cards at 1.15:1 or more above the background, dark borders at 1.5:1 or more. Same numbers as light mode, opposite direction. And a dark interface with the direction inverted fails quietly: nothing errors, everything just looks pressed in.
Where the numbers come from
Every ratio above compares a role against its own palette's background, computed with the WCAG 2.1 relative luminance formula, across the 69 palettes in the library that carry layered roles. The layering thresholds come from whether the eye can resolve a hairline on an ordinary screen, not from WCAG's text requirement. WCAG's 3:1 for non-text elements governs control boundaries that must be identifiable; cards against a page background are decorative layering and outside that scope. The two get cited interchangeably and should not be.
Related: the editorial standard documents the gates and the calculation, and the three-platform guide explains why web has a border and the app does not.