Layering, breakpoints and icons
The three scales that were never written down: what stacks above what, where the layout changes, and how big an icon is.
Layering
The masthead, the nav dropdowns, the search overlay, the mobile menu and the toasts all stack, and until now each picked its own number. One scale, six steps, and the order is the argument.
--p234-z-base | 0 | ||
--p234-z-raised | 10 | A mark lifted above its siblings. | |
--p234-z-sticky | 20 | The masthead and any sticky section rule. | |
--p234-z-dropdown | 30 | Nav menus, the account menu, select popovers. | |
--p234-z-overlay | 40 | Search overlay, dialogs, the mobile menu. | |
--p234-z-toast | 50 | Always on top. Nothing goes above a message about what just happened. |
- Use the named step, not a number. A component that needs a value between two steps is telling you the scale is missing a layer.
- Keep the toast on top. Nothing outranks a message about what just happened.
- No
z-index: 9999. That is not a layer, it is a surrender. - Do not create a stacking context by accident. A
transformor anopacityon an ancestor traps a dropdown inside it, and the fix is the ancestor, not a bigger number.
Breakpoints
Four widths. Custom properties cannot be used inside a media query, so unlike every other token on this site these are not read by a stylesheet: they are the agreed values, exported in build/tokens.json for JavaScript, and written literally into every media query the system ships.
--p234-breakpoint-sm | 30rem | 480px. Large phone. | |
--p234-breakpoint-md | 48rem | 768px. Tablet, and where the article column stops being full bleed. | |
--p234-breakpoint-lg | 62rem | 992px. Where a sidebar becomes worth having. | |
--p234-breakpoint-xl | 80rem | 1280px. Full container. |
That is an honest limitation rather than a design choice. The discipline it needs is simple: if a media query in this system uses a width that is not on this list, it is wrong.
- Design at
smfirst. Mobile is 64 per cent of search traffic, and the article page is where readers arrive. - Use
lgas the point a sidebar becomes worth having, which is what the documentation site itself does.
Icons
lucide-react, sized from this scale, at a slightly lighter stroke than the library default so the icons sit with the serif rather than shout over it.
--p234-icon-size-sm | 16px | Inline with ui-sm and meta text. | |
--p234-icon-size-md | 20px | Default: buttons, nav, controls. | |
--p234-icon-size-lg | 24px | Section headers and empty states. | |
--p234-icon-stroke | 1.75 | Slightly lighter than lucide's default 2, to sit with the serif rather than shout over it. |
- Pair every icon with a label, or give it an
aria-labelandrole="img". - Mark a decorative icon
aria-hidden="true"so it is not announced twice beside the text it duplicates. - Keep the icon on the text baseline, not centred in its own box.
- No icon-only control without an accessible name. A bare glyph is a guess.
- No icon below 16px. It stops being legible before it stops being clickable.
- No icon as the only carrier of meaning in a data context. See Delta, where the glyph and the colour work together.