with no `scope` at all gets the header
fill but does not pin. That follows the contract rather than guessing,
and it is worth knowing if a writer reports a header that will not
stick.
The fill above is what makes it legible once pinned: a transparent
sticky cell would let the body rows scroll through it. `z-index` is
local and deliberately 1, not a step off Codex's scale -- the only
thing it has to outrank is a positioned element inside a body cell,
such as a callout, which would otherwise paint over the pinned row. It
stays far below the page-level layers either way. */
position: sticky;
inset-block-start: 0;
z-index: 1;
/* Moved here off `tr:first-child` on 2026-10-27, for the same markup
reason as the fill above: a scope="col" header is not necessarily in
row one. It was already inert for `td`, which declares `vertical-align:
top` on itself and so beats any value inherited from the row. */
vertical-align: middle;
}
th[scope='rowgroup'],
th[scope='row'] {
text-align: start !important;
font-weight: var(--font-bold);
vertical-align: top;
}
/* FLAT, AND NOT ON THE --space-* SCALE. The rhythm pass on 2026-10-28 put
this and the two list rules below onto --space-xs; Joy's call the same day
was to take all three back to the flat 1rem they had. A table is a
component and a cell is its inside, so this is the callout-list argument
at css-page-article.css:3526 and the field padding at
css-components.css:3123 applied once more: --space-xs is
`clamp(0.75rem, …, 1.125rem)`, which would have made a cell TIGHTER than
1rem on a phone and looser on a desktop -- a dense, narrow context moving
in the wrong direction at the end that is already cramped. The page's flow
rhythm breathes; the inside of a cell does not.
The cell's own padding (--space-xs/--space-2xs at :4043, and the
`!important` at :4385) predates the rhythm pass and is untouched here --
by this same argument it is a candidate, but it was never part of the
question Joy answered. */
td > * + * {
margin-block-start: 1rem;
}
td {
vertical-align: top;
font-size: var(--step-0);
text-align: start !important;
[class*='callout-'] {
padding: 0.5rem 0.75rem;
border: none;
display: inline-flex;
/* Was `var(--size-0)`, an undefined token, until 2026-10-26. As in the
list block further up, that made the declaration invalid at
computed-value time and so equivalent to `inherit` -- but here the
parent is the `td` above, which sets --step-0 itself, so this one was
already rendering at exactly --step-0. Naming it is therefore a
pixel-for-pixel no-op that stops the size depending on a sibling
rule's value. One step below the base callout's --step-1, which is
reasonable inside a table cell and is why this is corrected where the
list block's copy was deleted. */
font-size: var(--step-0);
/* THE CELL'S FLOW SPACING IS SINGLE-SOURCED on `td > * + *` above.
This rule used to restate the cell's flow margin as well (`1rem`,
briefly `var(--space-xs)` during the 2026-10-28 rhythm pass and flat
1rem again after it), and at
(0,3,2) against that rule's (0,2,2) it won -- so a callout authored
as the FIRST thing in a cell got a top margin anyway and sat a line
lower than the plain text in the cells beside it. Dropping the
declaration hands the gap back to `td > * + *`, which applies it
between siblings only: the same gap in every other position, and a
leading callout now sits flush with the cell's own padding.
`margin-block-end` stays unset. Nothing in the callout's own block
(css-components.css:1165) sets a bottom margin, so this is defending
against the article's prose rules reaching into cells rather than
against the component -- and one source of spacing per gap is the
whole point of the rule it defers to. */
margin-block-end: unset;
/* Was a bare `svg`, i.e. every svg anywhere inside a callout in a table
cell. That hid the injected severity icon, which is the intent, and
also every inline icon in the callout's own text, which is not: those
are section 12 of the authoring contract and writers use a lot of
them. Narrowed to the direct first child on 2026-10-26, which is
exactly and only what callout-icons.js inserts. Same as the list
block above. */
> svg:first-child {
display: none;
}
}
}
/*************************/
/* Lists in tables */
/* A tighter item rhythm than the body's is kept deliberately: a flat
0.25rem against the --space-xs the body list gets, because a table cell
is a narrow column and the body's rhythm strands bullets in it. FLAT for
the reason given on `td > * + *` above -- these two went onto --space-xs
in the rhythm pass and came back on Joy's call the same day.
0.25rem, tightened from 1rem in three steps on 2026-10-28 -- Joy, on the
first preview of the body change: "There's not much in the tables
either," then on the 0.75rem that followed: "tighten up the list items a
bit more," and finally, deciding it outright against a callout in
preview: "Within tables, I think the spacing like we have in the callouts
is the best."
SO THIS IS THE SAME 4px AS THE CALLOUT LIST BLOCK, ON PURPOSE, and the
two should move together if either is ever revisited -- see the
Codex-spacing block at the Lists section above. The shared argument is
that both are dense containers rather than open prose, and the shared
mechanism is that both are FLAT rather than on --space-*. A cell now
reads as tight as a card, which is what Joy chose. Only
the INDENT rules went out of this block on 2026-10-28, with the rest of
the custom list styling: `:is(ol, ul) { margin-inline-start: 1.5rem }`,
its `p { margin-inline-start: 0 }` counterpart, which existed only to
cancel it again inside a list item, and a `p + ul { 3rem }` that indented
a list further for no reason beyond a paragraph preceding it. Indent is
now owned in one place, by the `revert` pair in the Lists section, so a
list in a cell starts flush with the cell's text exactly like one in the
body does.
A NARROW CELL IS THE ONE PLACE THE BROWSER'S 40px GENUINELY READS BADLY
-- Joy: "inside tables the padding-inline can be an issue."
THE CELL-ONLY INDENT IS BACK, 2026-10-28, on Joy's ask after previewing
the flat spacing: "when a list is on its own in a cell, there is no
inline-padding. When it follows a , or if it is a sublist, it will
have a smaller margin-inline padding." This is the one thing the sitewide
park left on the table, and it is reopened HERE ONLY -- the sitewide
default is untouched, so the team's parked decision still stands for
every list outside a table.
KNOWN COST, ACCEPTED: a cell-only indent is what this block used to
carry, and keeping lists on one sitewide value is what had stopped cell
and body lists from drifting. They can drift again now. The three
declarations below are the whole mechanism, so that is the place to look
if they do.
WHY THE LONE LIST FLIPS TO `inside` AND THE OTHER TWO DO NOT. Markers are
`outside` by default, which paints them LEFT of the content box; at a zero
indent they hang into the cell's own inline padding, which is --space-2xs
and so only 8px narrow / 12px wide. Cell text is --step-0, about 14px, at
which an `a.` or `1.` marker runs 10-11px and `iii.` or `10.` more -- so
at the NARROW end the marker is already wider than the 8px it has to hang
in, and an outside marker at zero indent sits on or past the cell's left
border in exactly the cramped column that prompted this. `inside` puts the marker in the first line box instead,
where nothing can overflow. Joy chose that trade on 2026-10-28 knowing
what it costs: a WRAPPED item runs back under its own marker rather than
hanging, which is the common case in a ~160px column. The two indented
cases keep `outside` because 2em is a real gutter for the marker to
hang in, so they get an even text column for free.
`list-style-position` INHERITS, which is why the sublist rule sets
`outside` back explicitly -- without it a sublist inside a lone list
would pick up `inside` from its ancestor and lose its gutter.
2em, not a --space-* token, and that is deliberate: an indent has to
scale with the TEXT it indents, not with the viewport. Against --step-0
that is about 28px, down from the browser's 40px. It started at 1.5em
(candidate 4's value from the Lists section above, ~21px) and went up on
Joy's preview call the same day: "on sub-list in cell, let's put a little
bit more of an indent." 1.5em is still the shape the team would start
from if they ever reopen the sitewide default. */
ul > * + *,
ol > * + * {
margin-block-start: 0.25rem;
}
:is(ol, ul) li:first-child {
margin-block-start: 0;
}
/* (a) A list on its own in a cell -- flush, marker in the line box. Only
direct children of the cell, so a sublist can never match it. */
td > :is(ol, ul) {
padding-inline-start: 0;
list-style-position: inside;
}
/* (b) ...unless a paragraph introduces it, which makes it a nested thought
rather than the cell's content. At (0,2,3) against the rule above's
(0,2,2) this wins on specificity, not on order. */
td > p + :is(ol, ul) {
padding-inline-start: 2em;
list-style-position: outside;
}
/* (b) ...and a sublist, at any depth. Carries the flow margin too.
THE LEADING `td` IS THE th EXCLUSION, and it is the only one of the three
indent rules that needed adding -- (a) and (b) above are already `td >`,
but this one matched a sublist in a `th` as well until Joy confirmed on
2026-10-28 that header cells should stay out. A `th` holds a column label,
not authored prose; if a list ever appears in one it keeps the browser's
40px, same as the parked sitewide default. Note this is a DESCENDANT `td`,
not a child combinator, because a sublist is never a direct child of the
cell. The flat 0.25rem flow spacing above is deliberately NOT scoped this
way -- that predates the indent work and applies in both cell types. */
td :is(ol, ul) :is(ol, ul) {
margin-block-start: 0.25rem;
padding-inline-start: 2em;
list-style-position: outside;
}
}
/* Tables in Tabs */
.tab-inner {
/* `.article-table-scroll:first-child` was added on 2026-10-27 alongside
assets/table-frame.js, and without it this rule silently stopped working.
A bare table in a tab panel used to BE the panel's first child; now the
script's wrapper is, and the table is one level down -- so `table:
first-child` still matched (the table is the wrapper's only child) but
the margin it zeroed was no longer the one pushing the panel open. The
wrapper is the element that now carries the flow margin from
`.article-content > * + *`, so it is the element that has to be zeroed.
Both selectors are kept: a table with JavaScript off is still a direct
child here. */
.article-table-scroll:first-child,
table:first-child,
figure:first-child {
margin-block-start: 0;
}
figure.wysiwyg-table,
figure.wysiwyg-table-align-left,
figure.wysiwyg-table-align-right {
margin-block-start: 0;
}
}
/**********************/
/* Images and video */
img,
iframe,
video {
border: 1px solid var(--clr-neutral-40);
border-radius: 0.25rem;
}
video {
display: block;
width: 100%;
}
/* THE CODE BLOCK, round 1 of the `article_page` pass: SURFACES ONLY.
Joy chose the Codex route on 2026-10-29 from three options -- a
tier-following card, a dark slab kept in both tiers, and a tier-aware dark
slab. What shipped before this was the second of those by accident rather
than by decision: a hardcoded --clr-neutral-160 slab with an
rgba(255,255,255,.1) hairline and an rgba(255,255,255,.9) ink, identical in
both tiers, under a LIGHT --clr-neutral-10 header bar -- which is ΔE00 65.8
off the slab it sat on and read as glare in dark mode.
THE CODE BLOCK IS THE INVERSE OF THE TABS CASE, and that is why this is one
declaration rather than a tier-split. Tabs had to sit RAISED off the page,
and --neutral-bg-soft sank into our dark .article-container card, which is
what forced the two-tier fill documented in the .nav-tabs block of
css-components.css. A code block wants to sit RECESSED, and --neutral-bg-soft
is recessed from the card by effectively the same amount in each tier:
ΔE00 3.77 light (#ebf8f8 under a #faffff card), 3.27 dark (#172029 under a
#1e2a35 card). So the same fill reads the same way in both, and no second
token is needed.
MEASURED, light / dark (AA 4.5:1 required, AAA 7:1 the target):
code ink, --neutral-text on the fill 16.60:1 / 14.35:1 AAA both
language label, --neutral-text-soft 6.13:1 / 9.12:1 AA light
copy button at rest, same ink 6.13:1 / 9.12:1 AA light
copy button hovered, --neutral-text 14.79:1 / 9.56:1 AAA both
copy button copied, --success-text 5.89:1 / 12.47:1 AA light
link hovered, --brand-text 7.53:1 / 9.68:1 AAA both
1px --neutral-border on the fill ΔE00 14.85 / 17.06 decorative
scrollbar thumb on its track 8.04:1 / 4.79:1 clears 3:1
The three light-tier AA rows are deviations by the same argument the
inactive tab label makes: reaching AAA on them means --neutral-text, which
is the code ink itself, and that would erase the one thing a muted ink
exists to say. Logged in plan.md's Phase 1 deviations.
THREE CODEX FEATURES DELIBERATELY NOT FAKED. shiki tokenising (§9 of
article-authoring-contract.md is the whole contract -- Zendesk emits flat
text in a single `code`, so there is nothing to colour and no tokenizer to
colour it with), the line-number gutter (no per-line spans for the same
reason), and the file-name header (authors have no field for it; the
contract gives them a second `language-*` class instead, which is what the
label already renders).
WHAT THIS ROUND DOES NOT TOUCH, named so the next one does not have to
rediscover it:
- THE HEADER'S LAYOUT. Codex puts the language in a small
`bg-neutral-component` BADGE inside a `px-4 py-2` header and moves the
copy control out of the header entirely, to an icon-only button pinned
`absolute right-2 bottom-2` over the code body, revealed on hover or
keyboard focus. Ours is still a 200px uppercase "COPY TO CLIPBOARD"
stretched to the header's full height, which is why the header keeps
`padding: 0` and a `min-height` here. The badge cannot land without the
button moving -- a chip needs the header's own inline padding, and that
padding is exactly what `align-self: stretch` is living without. One
decision, round 2.
- TYPE. The body is still --step-1, which is BIGGER than prose; Codex's is
`--font-size-sm`, smaller. Same round as the header.
- THE FLOW MARGIN. `margin: var(--space-s) 0` restates what
`.article-content > * + *` already gives this wrapper. It is redundant
for a top-level block and load-bearing for one nested in a `td` or a
callout, where the flow rule cannot reach it. The spacing pass closed on
2026-10-28 and this is not a surfaces change, so it stays as found. */
.zd-code-wrapper {
position: relative;
margin: var(--space-s) 0;
border-radius: var(--radius-md);
overflow: hidden;
background: var(--neutral-bg-soft);
border: var(--border-width-regular) solid var(--neutral-border);
font-family: var(--ff-mono);
}
/* A BORDER, NOT A FILL, and Codex's own reason for it is measurable: its
header is `border-b border-neutral` over the same `bg-neutral-soft` as the
body. A --neutral-bg-component bar instead would be ΔE00 2.76 from the body
in light -- near-invisible -- and 9.86 in dark, which is loud. One
declaration reading two different ways per tier is the thing to avoid, and
the 1px --neutral-border does not do it: 14.85 light, 17.06 dark. Codex
does still use the component fill, but on the language BADGE, where at
chip size the dark figure reads as intent rather than glare -- see the
round-2 note above. */
/* THE HEADER NO LONGER EXISTS ON EVERY BLOCK. code-block-copy.js builds it
only when detectLanguage finds a language, because once the copy button
moved onto the code surface the badge became the header's only content and
an undeclared language left a bordered strip with nothing in it. Most
authors never pick a language, so that was the common case, not the edge.
`min-height: 42px` is gone and the padding below replaces it: the pin was
sizing a bar that had a 200px-wide stretched button in it, and the badge
alone does not need propping to that height. Both values are FLAT, not
--space-* -- a header bar is a component's inside, and only page flow rides
the fluid scale (the spacing pass, 2026-10-28).
KNOWN MISALIGNMENT, not fixed here: the 1rem inline padding does not line
up with the code body's left edge, because the pre below uses
`padding: var(--space-xs)`, which is fluid and lands anywhere from 12 to
18px. The badge had the same 1rem before this round, so this is inherited
rather than introduced. It resolves when the body padding does -- that is
already queued as its own item, for the same insides-stay-flat reason. */
.zd-code-header {
display: flex;
align-items: center;
padding: 0.5rem 1rem;
border-block-end: var(--border-width-regular) solid var(--neutral-border);
font-family: var(--ff-mono);
margin-block-start: 0;
}
/* PLAIN LOWERCASE TEXT, NOT A CHIP, which is Codex ("typescript") and which
the measurement happens to agree with. It was uppercase, 600 weight, 0.1em
tracked, and briefly on a --neutral-bg-component fill; dropping the fill
puts the ink back on the code surface and IMPROVES it, from 5.46:1 light /
6.07:1 dark on the chip to 6.13:1 / 9.12:1 here. Dark clears AAA outright
and light is AA, short of the 7:1 target -- reaching it means
--neutral-text, which is the code ink itself, and a label that matches the
code it is labelling stops reading as a label. Same trade as the inactive
tab, logged with it in plan.md Phase 1.
The 0.1em tracking went with the uppercase rather than being kept
separately. Tracking is what makes an uppercase micro-label legible; on
lowercase it just reads as spaced-out text. That one is a judgment call
rather than a measurement, so it is the easy thing to put back.
No padding here any more -- the header's own 0.5rem/1rem gutter is the
spacing now that there is no chip to size. */
.zd-code-lang {
font-size: var(--step--1);
text-transform: lowercase;
color: var(--neutral-text-soft);
font-family: inherit;
user-select: none;
}
/* AN ICON-ONLY BUTTON PINNED TO THE CODE SURFACE, which is Codex's. It was a
200px `align-self: stretch` slab reading "COPY TO CLIPBOARD" inside the
header; code-block-copy.js now appends it to .zd-code-wrapper instead, and
it is positioned against that wrapper's `position: relative` so a long line
of code scrolls underneath it rather than carrying it out of view. Dropped
with the text: min-width, align-self, gap, text-align, justify-items,
letter-spacing, text-transform, white-space and .zd-copy-inner, which had
no remaining job once there was one child instead of two.
`transition: all` WITH NO DURATION IS FIXED HERE, which was queued as its
own defect and became unavoidable: `all` with the duration supplied only by
:hover and .copied meant every state animated IN over 0.3s and snapped back
OUT at 0s, and a hover-revealed button cannot fade in on a rule like that.
Now a named list on --motion-duration-control, which reduced motion already
takes to 0s in css-brand-tokens.css, so the fade respects it for free. The
properties are named rather than `all` so the absolute insets and the
outline are not swept in.
FLAT 0.5rem INSETS AND FLAT PADDING on purpose: this is a control's own
geometry, not page flow, so it does not ride the fluid --space-* scale.
font-size is flat 1rem for the same reason -- it is not type here, it is
the icon's size, and both icons track it (see ICON_CHECK's note in
code-block-copy.js).
The fill is ΔE00 2.76 from the code surface in light (1.12:1) and 9.86 in
dark. Light is faint, and that is Codex's own figure, not a deviation we
introduce -- their code surface is the same --neutral-bg-soft and their
button the same --neutral-bg-component. It holds up because the button is
identified by its ICON, at 14.79:1 light / 9.56:1 dark, and 1.4.11 asks for
3:1 on a boundary only where the boundary is what identifies the control.
The 1px --neutral-border-alpha-strong edge is Codex's too and is decorative
by the same measurement: 1.51:1 light / 1.84:1 dark against the fill. */
/* ONE PINNED ROW HOLDING THE STATUS TEXT AND THE BUTTON, which is what lets
the confirmation sit beside a button that has to stay circular. A circle
cannot hold the word "Copied!", so the text is a sibling rather than button
content, and a flex row means its width never has to be guessed in a
`calc()` against the button's offset -- the text simply pushes left.
`pointer-events: none` with `auto` put back on the button alone, because
this row spans more than the button: the gap and the full width of the
status text would otherwise sit over the code as a dead strip that swallows
a click-drag selection. Only the button needs to be hittable. */
.zd-copy-affordance {
position: absolute;
inset-block-end: 0.75rem;
inset-inline-end: 0.75rem;
z-index: var(--z-index-raised);
display: flex;
align-items: center;
gap: 0.5rem;
pointer-events: none;
}
/* ALWAYS VISIBLE. This was revealed on hover inside a `(hover: hover)` block,
which is Codex's behaviour but costs more than it buys here: a copy button
nobody knows is there is a copy button nobody uses, and on a touch device
-- where the media query never matched and the button showed anyway -- the
two tiers of behaviour did not agree. Showing it always also removes the
`:focus-visible` and `.copied` reveal rules that existed only to work
around the hiding, and `opacity` leaves the transition list with them.
A FIXED SQUARE BOX, not padding around an icon, and it is doing two jobs.
The first is the second half of the flash fix. `padding: 0.375rem` on
`line-height: 1` meant the button was sized by whatever its icon currently
measured -- and the two icons do not match, since Font Awesome's copy glyph
is 0.875em wide against the check's 1em. So the button changed width on
every state change, and collapsed to bare padding for the frame when it had
no icon at all. At a fixed 1.75rem it cannot do either, and 28px clears the
24px minimum target size (WCAG 2.5.8) with room to spare.
The second is the circle. --radius-round is 9999px, which clamps to half the
shorter side, so it only draws as a true circle on a box whose two axes
already agree -- on the old icon-sized box it would have been a stadium
that changed shape with the glyph. The button is round in EVERY state now,
which is Codex's, so the radius belongs here rather than on .copied.
That leaves the transition list at two properties, and deliberately only
two. `border-radius` came off it because the shape no longer changes, and
`border-color` because no state changes that either -- the edge is one
token in every state, so animating it was animating nothing. Success moves
the fill and the ink; those are what is listed.
The fill is ΔE00 2.76 from the code surface in light (1.12:1) and 9.86 in
dark. Light is faint, and that is Codex's own figure, not a deviation we
introduce -- their code surface is the same --neutral-bg-soft and their
button the same --neutral-bg-component. It holds up because the button is
identified by its ICON, at 14.79:1 light / 9.56:1 dark, and 1.4.11 asks for
3:1 on a boundary only where the boundary is what identifies the control.
The 1px --neutral-border-alpha-strong edge is Codex's too and is decorative
by the same measurement: 1.51:1 light / 1.84:1 dark against the fill. */
.zd-copy-btn {
display: inline-flex;
align-items: center;
justify-content: center;
inline-size: 1.75rem;
block-size: 1.75rem;
padding: 0;
pointer-events: auto;
border: var(--border-width-regular) solid var(--neutral-border-alpha-strong);
border-radius: var(--radius-round);
background-color: var(--neutral-bg-component);
color: var(--neutral-text);
font-size: 1rem;
font-family: inherit;
line-height: 1;
cursor: pointer;
transition:
background-color var(--motion-duration-control),
color var(--motion-duration-control);
}
/* THE ICONS ARE BOTH IN THE BUTTON FROM THE START AND ONLY ONE IS DISPLAYED.
Nothing is inserted or removed at click time, which is what stops the
flash -- see the icon note in code-block-copy.js for the Font Awesome
mechanism behind it.
Targeted on `.fa-copy` rather than on a bare `i`, because the kit JS
replaces the with an and only the fa-* classes survive that swap.
These selectors are (0,4,0) nested, so they beat the kit's own
`.svg-inline--fa { display: inline-block }` at (0,1,0). */
.zd-copy-btn .zd-copy-check {
display: none;
}
.zd-copy-btn.copied .fa-copy {
display: none;
}
.zd-copy-btn.copied .zd-copy-check {
display: block;
}
/* The visible half of the confirmation, and plain text to match the language
label rather than a second pill competing with the button beside it.
--success-text sits on the code surface here, not on a fill, which is the
better of the two: 5.89:1 light / 12.47:1 dark, against 5.25:1 / 8.30:1 on
--neutral-bg-component. Light is AA, short of the 7:1 target, and the green
is the point of it -- this is the one piece of text in the component whose
job is to mean "success" rather than to be read neutrally.
It fades rather than appearing, since unlike the icons there is no flash
risk: the node is built once and empty, and only its text content changes.
`:has()` carries .copied across from the button because the status is its
PRECEDING sibling, which no sibling combinator can reach backwards to. */
.zd-copy-status {
font-size: var(--step--1);
font-family: inherit;
line-height: 1;
white-space: nowrap;
color: var(--success-text);
opacity: 0;
transition: opacity var(--motion-duration-control);
}
.zd-copy-affordance:has(.zd-copy-btn.copied) .zd-copy-status {
opacity: 1;
}
/* The fill steps up and the ink stays put, which is what Codex's regular
button variant does. Ink is already --neutral-text at rest now that the
button has its own fill, so hover has nothing left to lift: 14.79:1 light /
9.56:1 dark at rest, 13.58:1 / 6.84:1 hovered. Both tiers lose a little
here and both stay well clear of AAA, which is the right direction for a
state whose job is to say "this is the thing under your pointer". */
.zd-copy-btn:hover {
background-color: var(--neutral-bg-component-hover);
}
.zd-copy-btn:active {
background-color: var(--neutral-bg-component-active);
}
/* THE INSET RING IS GONE AND SO IS THE WHOLE OVERRIDE, which the move earns
twice over. It was `outline: none` plus an inset box-shadow, and the stated
reason was the clip: the button used to be flush to the header's full
height inside a wrapper that is `overflow: hidden`, so the sitewide outline
was cut off along its top and right edges. The button now sits 0.75rem in
from both edges it used to touch, and the sitewide ring extends 4px (2px
wide, 2px offset) against 12px of clearance, so there is nothing left to
clip.
The second reason is the one that forces it. An INSET ring is drawn over
the button's own fill, and this button's fill now changes in four states.
Over --neutral-bg-component-active in dark the ring measures 1.79:1, which
misses the 3:1 non-text floor outright -- a keyboard user holding Space
would watch their own focus indicator fail. An OUTSET ring never touches
the fill: both its edges sit on the code surface, which does not move, at
4.25:1 light / 5.25:1 dark in every state the button can be in.
So the rule reduces to pinning the offset. css-reset.css's *:focus-visible
draws the ring sitewide and defaults the offset to max(2px, 0.15em); the
flat 2px is Codex's figure, and pinning it is how the components that care
already do this (see the accordion label and the tab list). This feeds the
page-wide focus pass rather than pre-empting it -- the mechanism here had to
change because the geometry changed under it. */
.zd-copy-btn:focus-visible {
--outline-offset: 2px;
}
/* THE SUCCESS STATE IS A FILL, NOT AN INK, and that correction is the whole
rule. Reading Codex's success button as green CHECKMARK ink is what the
earlier version of this block did -- hence --success-text on a neutral fill
-- and the DevTools dump settles it: the class swaps kb-button-regular for
kb-button-success, the background goes to the strong green, and icon_color
stays rgb(16,23,30) in both states. Both of Codex's captured fills were
hover variants because the pointer was still on the button when they were
read, so the resting pair is --success-bg-strong / --neutral-bg-component
and the hover pair is one step along from each.
THE INK CANNOT BE --neutral-text AND THAT IS THE ONLY PLACE THE COPY BREAKS.
Codex's literal declaration is dark ink on green, which is 12.00:1 in light
-- and 1.47:1 in DARK, a flat fail, because --neutral-text flips near-white
in the dark tier while --success-bg-strong stays a bright green (#98d95c).
A fill that is bright in both tiers needs ink that is dark in both, and no
single semantic token in the set does that. --neutral-text is #10171e in
light and --neutral-text-inverse is #10171e in dark, so --zd-copy-ink takes
one per tier and resolves to the same #10171e either way: 12.00:1 light /
10.67:1 dark, AAA both. Hovered it is 8.57:1 / 14.28:1.
A ratio cannot see this state change, because both fills sit on the same
surface -- measured as ΔE00 against the rest fill it is 28.15 light / 66.07
dark, so it reads unmistakably in both tiers even though the green itself is
only 1.38:1 against the code surface in light. .copied is last so it beats
:hover and :active on equal specificity, and the hovered variant is spelled
out because a pointer that just clicked is still on the button.
NO RADIUS AND NO BORDER COLOUR HERE, and both of those were mine to
remove. The circle was briefly this rule's, on the reading that Codex only
rounds the button on success; it is round at rest too, so the radius moved
to .zd-copy-btn. The `border-color: var(--neutral-border-alpha-strong)`
that sat here was a plain no-op -- it restated the token the base rule
already sets, so it could not have changed a pixel in either tier.
What it was reaching for is real but is NOT a defect, so it is recorded
rather than fixed: --neutral-border-alpha-strong tier-flips from #10171e33
to #ffffff33, while this fill stays a bright green in both tiers. So the
copied button's edge is a dark alpha in light and a white alpha in dark,
where the INK deliberately stays dark in both. Codex's captured border was
rgba(16,23,30,0.2) in light and their dark success state was never read, so
there is nothing to match against; the edge measures 1.51:1 light / 1.84:1
dark against the fill either way, which is decorative by the same standard
the base rule's note applies. Worth a second look only if the dark tier's
lighter ring reads as a halo in preview. */
.zd-copy-btn.copied {
--zd-copy-ink: var(--neutral-text);
background-color: var(--success-bg-strong);
color: var(--zd-copy-ink);
/* The dark half of the split. `:root[data-theme='dark'] &` with an explicit
`&`, not a plain nested selector -- :root has to sit to the LEFT of this
element, and a nested selector with no & gets a descendant & instead,
which would look for a .zd-copy-btn.copied inside a :root inside the
button and match nothing. Same form as the coloured cards in
css-page-home.css. */
:root[data-theme='dark'] & {
--zd-copy-ink: var(--neutral-text-inverse);
}
}
.zd-copy-btn.copied:hover {
background-color: var(--success-bg-strong-hover);
}
/* THE FOURTEEN `!important`s ARE GONE AND NOTHING NEEDED THEM. What they were
written against is `pre:has(code)` in css-reset.css, which hands every code
block a --clr-neutral-5 fill, a --clr-neutral-160 border, 0.5rem of padding
and a 0.25rem radius. That selector is (0,1,1). These rules are nested in
`.article-content`, so they resolve to `.article-content .zd-code-wrapper
pre` at (0,2,1) -- they already win on specificity, in a file that also
loads after the reset. The one near-miss is the `pre` rule inside the
callout block of css-components.css, also (0,2,1), and this file loading
later settles that too.
THE INK IS --neutral-text, NOT AN rgba WHITE. The old
rgba(255,255,255,0.9) resolved to #ebebeb over the slab -- a fixed value
that could only ever be read as light-on-dark, which is exactly why the
block could not follow the tier.
TWO DEAD RULES DELETED WITH IT, and they were dead by each other's hand.
`pre.language-auto a` set an rgba-white ink and a --clr-secondary hover
plum; `.zd-code-wrapper pre code *` then forced `color: inherit !important`
over the top of them, and since the anchor is always inside the `code`, the
important always won -- so a link in a code block has never once taken
either colour. Removing both leaves links to the settled article behaviour:
`a:not([class])` gives them `color: inherit`, which is now the code ink, and
--brand-text on hover at 7.53:1 light / 9.68:1 dark.
THAT RULE MUST STAY DELETED, and the reason has changed since it went. It
was removed as harmless -- per §9 of the authoring contract Zendesk emits
flat text in one `code`, so there were no token spans for it to flatten.
There are now: prism.js wraps the code in .token spans and the syntax
palette below colours them. `color: inherit !important` on
`.zd-code-wrapper pre code *` would flatten every one of them back to the
plain ink and silently delete syntax highlighting from the whole site. */
.zd-code-wrapper pre {
margin: 0;
padding: var(--space-xs);
/* ROOM RESERVED FOR THE COPY BUTTON, which only became necessary when the
button stopped hiding itself. Hover-revealed, it covered the bottom-right
of the code only while the pointer was over the block, so overlapping the
last line did not matter. Permanently visible, it would sit on top of
that line forever. 3rem is the button's own 1.75rem plus its 0.75rem
inset plus 0.5rem of clearance, flat because all three of those are, and
it is spelled as its own longhand so it overrides only the inline-end of
the --space-xs shorthand above rather than replacing the padding.
This cannot be made airtight and should not be mistaken for airtight: the
pre is the horizontal scroll container, so padding reserves space at the
END of the scrollable width. A line long enough to scroll still passes
under the button mid-scroll. That is why the button carries a fill and a
border rather than being a bare glyph -- it has to read as a layer over
the code, not as part of it. */
padding-inline-end: 3rem;
background: transparent;
border: none;
border-radius: 0;
box-shadow: none;
color: var(--neutral-text);
overflow-y: visible;
overflow-x: auto;
font-family: var(--ff-mono);
}
/* THE SCROLLER IS A TAB STOP, and that is the browser's doing rather than
ours. Chrome gives any scroll container its own place in the tab order when
it holds no keyboard-focusable children -- no tabindex needed -- so the
`overflow-x: auto` above is the entire reason a reader can pan a wide block
by keyboard. ONLY A BLOCK WIDE ENOUGH TO ACTUALLY SCROLL EARNS THE STOP,
which is why Joy saw a focus cue on one code block and not on its
neighbours (2026-10-29). code-block-copy.js already assumed this: its
`focusin` listener on the pre expands a collapsed block, and nothing else
in that block is focusable.
SO THE RING GOES ON THE WRAPPER, NOT ON THE PRE. .zd-code-wrapper is
`overflow: hidden` -- it has to be, to hold its radius -- and an outline
paints OUTSIDE the border box, so the pre's own ring lost its inline-start,
inline-end and block-end edges to the clip and survived as a stray rule
across the top of the card, reading as a border nobody wrote. An element's
overflow never clips its own outline, only its descendants', so moving the
ring one level up draws it whole, at the card's radius, and says the true
thing: what holds focus is the block. The framed table does this correctly
already for the one reason that `.article-table-scroll` is not nested
inside a clipper.
`:has(pre:focus-visible)` RATHER THAN `:focus-within`, the same test as
`.header-search.expand:has(input:focus-visible)` in css-page-header.css.
:focus-within follows plain :focus, so it would also fire for the copy
button and the collapse toggle -- both of which carry their own cue at
.zd-copy-btn:focus-visible and .zd-code-toggle:focus-visible -- and ring
the whole card a second time around them. */
.zd-code-wrapper:has(pre:focus-visible) {
outline: var(--border-width-heavy) solid var(--form-focus-ring);
outline-offset: 2px;
}
/* ONE RING, NOT TWO: without this the pre's own outline still paints, clipped
to the fragment the note above describes. */
.zd-code-wrapper pre:focus-visible {
outline: none;
}
/* TYPE, settled 2026-10-29 once Space Mono was on screen -- Joy signed off the
typeface first ("looks great"), then took this recommendation, because
Space Mono is markedly wider with a bigger x-height than Inconsolata and
the right size is not judgeable from the numbers alone.
--step-0, DOWN FROM --step-1, which had code rendering BIGGER than the prose
around it. We were exactly inverted from Codex:
Codex body --font-size-base 16px code --font-size-sm 14px one DOWN
ours body --step-0 ~14px code --step-1 ~16px one UP
Our base size is settled (c1d47a9), so the whole scale sits a step below
Codex's and the two ways of following them diverge. Matching the RATIO means
--step--1, ~12.4px. Matching the ABSOLUTE size means --step-0, ~14px, which
is what Codex's 14px code block actually measures.
--step--1, AND THAT IS THE RATIO ANSWER WINNING ON THE PREVIEW RATHER THAN
ON THE ARGUMENT. This rule said --step-0 for about ten minutes, on the
reasoning that 12.4px mono was "small enough to hurt". Joy looked at
--step-0 rendered in Space Mono and asked for another step down, so the
recommendation was wrong and the measurement is what settled it: Space Mono
is wide with a large x-height, so it holds legibility at a size where
Inconsolata would not have, and the face is what made the ratio choice
viable. Worth keeping in mind for any future type call on this component --
the arithmetic picked the wrong one of two defensible answers, and only the
render could tell them apart.
--step--1 is also what .zd-code-lang and .zd-copy-btn already use, so the
whole component now sits on one step. Note the table block in this file
claims --step-0 is the floor of the scale with nothing below it, which is
wrong on both counts -- that page is signed off, so it is flagged rather
than edited.
A CODE BLOCK IN A TABLE CELL FOLLOWS THIS, which is worth stating because
css-reset.css pins `td pre, td code` to --step-0 and that is NOT what wins:
this rule is (0,2,2) against the reset's (0,0,2), so a block in a cell takes
--step--1 like any other. The two were a step apart before this change and
they are still a step apart, in the same direction; the cell pin is now the
larger of the two rather than the smaller.
LINE-HEIGHT 1.5, DOWN FROM 1.7, which is Codex's and is the ordinary value
for code: 1.7 is prose leading, and prose leading on a monospace face reads
as gappy because the glyphs are already wide. The line box goes from ~27px
at the old --step-1/1.7 to ~19px here, so a long block loses close to a
third of its height -- and the leading is the bigger half of that, not the
size.
THE BODY PADDING IS NOT TOUCHED AND IS A CANDIDATE. `padding: var(--space-xs)`
on the `pre` above is a FLUID token on a component's inside, which is the
one thing the spacing pass concluded not to do -- insides stay flat, page
flow rides the scale. It ranges 12px to 18px with the viewport, so the block
is differently proportioned at the two ends. The spacing pass closed on
2026-10-28 and this is a type round, so it is named here rather than swept. */
/* THE LINE HEIGHT IS A VARIABLE BECAUSE THE CLAMP HAS TO DO ARITHMETIC WITH
IT. --zd-code-line-height is declared in the EXPANDABLE block below and
read in two places: here, where it sets the actual leading, and there,
where N lines are turned into a max-height. A literal in both would let
them drift, and the symptom of that drift is a "Show more" that reveals a
sliver or clips mid-glyph. */
.zd-code-wrapper pre code {
background: transparent;
padding: 0;
font-size: var(--step--1);
line-height: var(--zd-code-line-height);
color: var(--neutral-text);
white-space: pre;
font-family: var(--ff-mono);
}
/* ── SYNTAX PALETTE ───────────────────────────────────────────────────────
FIVE INKS, EVERY ONE A TOKEN REFERENCE AND NOT ONE NEW HEX VALUE. The
colours were first measured off Codex's own code block, which gave six
slots; this is the palette rebuilt out of the brand ramps instead, which is
what Joy asked for once she saw it was possible.
WHY IT IS FIVE AND NOT SIX. Codex spends two separate inks on things we
have to merge: a purple for functions at hue 308 and a violet-navy for
variables and types at hue 295. Those are 13 degrees apart, and no palette
ramp can supply two distinguishable hues that close together. Worse, at the
7:1 contrast this needs on a light surface the palette has NO blue at all
with any chroma left in it -- deep-teal has to go so dark to reach 7:1 on
--neutral-bg-soft that it reads as black, not as blue. So the two collapse
into one `ident` slot, which is the same merge Codex itself already makes
between its variables and its types.
WHICH RAMP GOT WHICH SLOT was searched rather than picked: every step of
every ramp, filtered to contrast >= 7:1 on the code surface, chroma >= 28
so the ink reads as a hue instead of a near-black, and L* inside the band
Codex's own three sit in (25-32 light), then ranked by hue distance from
the Codex reading and checked for mutual separation. Two things fell out of
that which are worth recording because they look arbitrary otherwise:
- FUNCTIONS ARE PINK, NOT PURPLE, and `ident` took the indigo. Codex has
this the other way round. Giving indigo to `ident` puts it 5 degrees from
Codex's navy instead of 9 from its purple, and it leaves aubergine for
functions -- which is also what Prism's own default theme does (#DD4A68
pink for function and class-name), so the result is conventional even
though it is not a copy.
- KEYWORDS ARE VERMILLION, NOT CHERRY, which is a worse hue match (41.9
against Codex's 31.7, where cherry-12 is 37.6) and was still the right
pick. Cherry and aubergine are 35 degrees apart in light but only 25 in
dark, where both ramps have gone pale pink: cherry-3 against aubergine-3
is ΔE00 10.4, close enough that keyword and function start to read as one
colour. Vermillion moves away from aubergine rather than toward it and
lifts the worst syntax pair to 13.7 in dark and 21.0 in light.
ONLY THREE NAMES NEED A DARK VALUE. --code-string and --code-comment point
at semantic tokens that already tier-flip on their own, so repeating them
below would be a second copy of a decision made in css-brand-tokens.css.
The three ramp primitives do not flip -- the dark tier redefines no
--color-* name at all -- so each of those slots names its own step per
tier, staying on ONE ramp across both. The hue family is the constant and
the step is the tier's business, which is what a ramp is for.
MEASURED, on --neutral-bg-soft (#ebf8f8 light / #172029 dark):
keyword vermillion-12 #992008 7.53:1 | vermillion-2 #fdb5a6 9.68:1
function aubergine-11 #7c3149 8.07:1 | aubergine-3 #f3afc6 9.22:1
ident indigo-11 #523f8e 7.85:1 | indigo-2 #bdb0f2 8.36:1
string success-text #476827 5.89:1 | success-text #b2f27e 12.47:1
comment text-soft #4f5f63 6.13:1 | text-soft #b2c3d2 9.12:1
plain neutral-text #10171e 16.60:1 | neutral-text #ebf0f4 14.35:1
Nine of the twelve clear AAA. The three that do not are AA, all above 5.8:1,
and all three are existing tokens used at their published value rather than
anything chosen here -- comment and string in light, and comment is the
lowest of the set at 6.13:1. */
.zd-code-wrapper {
--code-keyword: var(--color-vermillion-12);
--code-function: var(--color-aubergine-11);
--code-ident: var(--color-indigo-11);
--code-string: var(--success-text);
--code-comment: var(--neutral-text-soft);
/* Explicit `&`, because a nested selector without one gets a DESCENDANT
`&` -- this would otherwise look for a .zd-code-wrapper inside a :root
inside the wrapper and match nothing, silently. */
:root[data-theme='dark'] & {
--code-keyword: var(--color-vermillion-2);
--code-function: var(--color-aubergine-3);
--code-ident: var(--color-indigo-2);
}
}
/* WHAT IS DELIBERATELY NOT LISTED BELOW IS MOST OF PRISM. The vendored build
emits 199 distinct token names across its 62 grammars, and anything without
a rule here inherits the code block's own --neutral-text. That fallback is
the design, not an omission: an unmapped token renders as plain code, which
is correct-looking in every language, so a grammar can name whatever it
likes without this file having to have anticipated it.
PUNCTUATION AND OPERATORS ARE IN THAT UNMAPPED SET ON PURPOSE. Prism nests
tokens -- markup's `tag` contains the angle brackets and the attr-name
inside it -- so leaving punctuation unstyled lets brackets take the colour
of whatever they belong to, which is what Prism's default theme does and
what keeps a tag reading as one object. Pinning punctuation to plain ink
instead would cut every tag and every selector into coloured and
uncoloured halves.
The groupings follow Prism's own default theme where it has an opinion,
because that taxonomy is tested against all 62 grammars and a hand-made one
would not be. The one place it is overruled is class-name: Prism colours it
with functions, and it is in `ident` here, which is what Codex does and
what makes a type read like the thing it names. */
.zd-code-wrapper .token.comment,
.zd-code-wrapper .token.prolog,
.zd-code-wrapper .token.doctype,
.zd-code-wrapper .token.cdata,
.zd-code-wrapper .token.hashbang {
color: var(--code-comment);
}
.zd-code-wrapper .token.keyword,
.zd-code-wrapper .token.atrule,
.zd-code-wrapper .token.important,
.zd-code-wrapper .token.directive,
.zd-code-wrapper .token.decorator,
.zd-code-wrapper .token.annotation {
color: var(--code-keyword);
}
.zd-code-wrapper .token.function,
.zd-code-wrapper .token.function-name,
.zd-code-wrapper .token.function-variable,
.zd-code-wrapper .token.function-definition,
.zd-code-wrapper .token.generic-function,
.zd-code-wrapper .token.method-definition {
color: var(--code-function);
}
/* The wide one -- names, types and the non-string literals. These are the
tokens that carry what a snippet is ABOUT, and in markup, CSS and JSON they
are nearly all of it: with tag, attr-name and property unstyled, an HTML
block would come out almost monochrome. */
.zd-code-wrapper .token.class-name,
.zd-code-wrapper .token.type,
.zd-code-wrapper .token.return-type,
.zd-code-wrapper .token.generic,
.zd-code-wrapper .token.builtin,
.zd-code-wrapper .token.tag,
.zd-code-wrapper .token.name,
.zd-code-wrapper .token.attr-name,
.zd-code-wrapper .token.property,
.zd-code-wrapper .token.string-property,
.zd-code-wrapper .token.literal-property,
.zd-code-wrapper .token.key,
.zd-code-wrapper .token.variable,
.zd-code-wrapper .token.hvariable,
.zd-code-wrapper .token.parameter,
.zd-code-wrapper .token.constant,
.zd-code-wrapper .token.symbol,
.zd-code-wrapper .token.namespace,
.zd-code-wrapper .token.number,
.zd-code-wrapper .token.boolean,
.zd-code-wrapper .token.null,
.zd-code-wrapper .token.nil,
.zd-code-wrapper .token.atom,
.zd-code-wrapper .token.scalar,
.zd-code-wrapper .token.entity,
.zd-code-wrapper .token.url {
color: var(--code-ident);
}
/* Every flavour of literal text. The long tail of *-string names is real --
Python, Ruby, PHP, Rust and the shells each name their own quoting forms,
and a heredoc that fell through to plain ink would be the one part of a
shell script that stopped looking like data. `selector` and `regex` sit
here for the same reason Prism's default puts them with strings: both are
patterns being quoted at the language, not code being executed. */
.zd-code-wrapper .token.string,
.zd-code-wrapper .token.char,
.zd-code-wrapper .token.attr-value,
.zd-code-wrapper .token.regex,
.zd-code-wrapper .token.selector,
.zd-code-wrapper .token.template-string,
.zd-code-wrapper .token.string-literal,
.zd-code-wrapper .token.triple-quoted-string,
.zd-code-wrapper .token.heredoc-string,
.zd-code-wrapper .token.raw-string,
.zd-code-wrapper .token.double-quoted-string,
.zd-code-wrapper .token.single-quoted-string,
.zd-code-wrapper .token.backtick-quoted-string {
color: var(--code-string);
}
/* THE ONLY TWO NON-COLOUR RULES, and they are both markdown's. `**x**` inside
a fenced markdown sample is bold text being quoted, so rendering it bold is
showing what the source means rather than decorating it. This is not the
bold Joy took off .zd-code-lang -- that one was a label shouting at the
reader; these two only ever fire on markdown emphasis. */
.zd-code-wrapper .token.bold {
font-weight: bold;
}
.zd-code-wrapper .token.italic {
font-style: italic;
}
/* Scrollbar styling for code blocks. Same conversion as the rules above and
for the same reason: four rgba whites that could only read over a dark
slab. A thumb is a control, so it is held to the 3:1 non-text floor against
the track it moves along -- --neutral-border-strong on --neutral-bg-component
is 8.04:1 light / 4.79:1 dark, and the hover pair is 5.46:1 / 6.07:1. The
old values did not survive that test in light at all: 0.15 alpha white over
a #333 slab is a thumb you can see, over a #ebf8f8 one it is nothing.
THE TRACK IS THE SAME --neutral-bg-component THE BUTTON HOVERS TO, which
the header rule above rejects for a permanent surface at ΔE00 2.76 in
light. Here that near-invisibility is the point: the track should barely
register and the thumb riding it should not. */
.zd-code-wrapper pre::-webkit-scrollbar {
height: 8px;
}
.zd-code-wrapper pre::-webkit-scrollbar-track {
background: var(--neutral-bg-component);
}
.zd-code-wrapper pre::-webkit-scrollbar-thumb {
background: var(--neutral-border-strong);
border-radius: var(--radius-round);
}
.zd-code-wrapper pre::-webkit-scrollbar-track:hover {
background: var(--neutral-bg-component-hover);
}
.zd-code-wrapper pre::-webkit-scrollbar-thumb:hover {
background: var(--neutral-text-soft);
}
/* ── EXPANDABLE ───────────────────────────────────────────────────────────
Codex clamps a long block, fades its lower edge and offers "Show more",
with the control omitted when the code is short enough to show whole. All
three of those are here. What is NOT here is Codex's way of asking for it:
its KbCodeBlock takes a `maxLines` prop per block, and a Zendesk article
body has no props. Per §9 of the authoring contract the author's whole
vocabulary is a language picked from a CKEditor dropdown, so the limit is
one sitewide number instead -- see code-block-copy.js's maxLines() for why
that is the only shape available, and what it costs.
THE NUMBER LIVES HERE AND NOWHERE ELSE. JS reads it back off the wrapper
to decide whether to build the control. If it were declared in both
places, a block between the two values would get a "Show more" that
reveals nothing, or none when it needed one.
15 lines is a judgment call, not a measurement -- about 280-320px tall
depending on where --step--1 lands. It is long enough that a short
example, which is most of them, is untouched, and short enough that a
collapsed block does not dominate the page it is on. */
.zd-code-wrapper {
--zd-code-max-lines: 15;
--zd-code-line-height: 1.5;
}
/* The positioning context for the fade and the copy row both. It replaces
.zd-code-wrapper's own for those two -- the wrapper's `position: relative`
stays, because the card still needs it. */
.zd-code-body {
position: relative;
}
/* THE PADDING TERM IS NOT OPTIONAL. `box-sizing: border-box` is global (see
css-reset.css's universal rule), so a max-height on the `pre` is measured
to the outside of its padding. Without `+ 2 * var(--space-xs)` the clamp
would spend the pre's own top and bottom padding out of the 15 lines and
show about 13 and a half of them.
The last visible line lands flush against the fade rather than being half
cut, which is deliberate: a clean edge under a gradient reads as "there is
more", where a sliced row of glyphs reads as a rendering fault.
This beats `overflow-y: visible` on `.zd-code-wrapper pre` on specificity
-- two classes and a :not() against that rule's one class. */
.zd-code-collapsible:not(.zd-code-expanded) .zd-code-body pre {
max-height: calc(
var(--zd-code-max-lines) * var(--zd-code-line-height) * var(--step--1) + 2 *
var(--space-xs)
);
overflow-y: hidden;
}
/* THE FADE ENDS ON THE EXACT SURFACE BEHIND IT. --neutral-bg-soft is the
wrapper's background and the pre's is `transparent`, so the gradient's far
stop and the real surface are the same colour in both tiers -- no seam to
line up, and the tier flip is handled by the token rather than by a second
rule.
`transparent` as the near stop is safe here. CSS gradients interpolate in
premultiplied alpha, so transparent-to-colour does not drag the midpoint
through grey the way the equivalent rgba(255,255,255,0) would.
Two lines tall is enough to read as a fade and short enough that it never
covers a whole line of code. It sits UNDER the copy button, which carries
`z-index: var(--z-index-raised)` on .zd-copy-affordance, and
`pointer-events: none` keeps it from eating a click meant for the code. */
.zd-code-collapsible:not(.zd-code-expanded) .zd-code-body::after {
content: '';
position: absolute;
inset-inline: 0;
inset-block-end: 0;
block-size: calc(2 * var(--zd-code-line-height) * var(--step--1));
background: linear-gradient(to bottom, transparent, var(--neutral-bg-soft));
pointer-events: none;
}
/* NO FILL ON THE FOOTER, AND THAT IS A MEASUREMENT RATHER THAN A TASTE. The
focus ring has to be legible against whatever it is drawn on. The ring is
outset at a 2px offset, so it lands on the footer's bare surface and never
on the button's own fill: 4.25:1 light / 5.25:1 dark, clearing the 3:1
non-text floor in both tiers. Giving the FOOTER the component fill instead
would put the ring on 3.48:1 / 2.50:1, and dark fails. That the fill
belongs on the button and not on the bar behind it is the whole reason
this measures safely -- it is also the same correction that moved the copy
button's ring from inset to outset.
The divider mirrors the header's `border-block-end`, same token on the
same surface, so a card with both is symmetrical. It measures 1.86:1 light
/ 2.10:1 dark, under 3:1, and that is acceptable for the same reason it is
acceptable on the header: it is a divider, not the boundary that
identifies a control. The control is identified by its text.
The padding is FLAT, not --space-*: a footer bar is a component's inside
and only page flow rides the fluid scale (the spacing pass, 2026-10-28).
0.75rem IS THE SHADOW'S CLEARANCE, not a round number. The wrapper is
`overflow: hidden` -- it has to be, to hold its radius -- so anything the
button paints outside itself gets clipped, which is the hazard
css-reset.css catalogues for focus rings. The hover shadow below is
`0 6px 16px`, reaching 6 + 16/2 = 14px past the border box, so 12px of
padding clips its outermost 2px. That is deliberate rather than missed:
14px of padding to save 2px of a 10%-alpha blur would make the bar
visibly bottom-heavy, and those 2px are the faintest part of the
gradient. The 2px focus ring at its 2px offset needs 4px and is clear. */
.zd-code-footer {
display: flex;
justify-content: center;
padding: 0.75rem;
border-block-start: var(--border-width-regular) solid var(--neutral-border);
}
/* CODEX'S `kb-button-sm`, EMPHASIS REGULAR -- the same control Codex puts in
this exact position, transcribed from a DevTools dump of
`.kb-button` + `.kb-button-sm` + `.kb-button-regular` rather than guessed.
Codex's own declarations resolve to: pill radius, --font-family-primary,
--font-weight-strong, `line-height: 1`, --font-size-xs, 8px of padding,
a 1px --neutral-border-alpha-strong rim, --neutral-bg-component and the
regular shadow.
THE DUMP CONTAINS TWO COMPETING PADDINGS and the render settles which won.
`.kb-button-sm` declares `padding: calc(var(--spacing) * 2)` (8px) while
`.kb-button` in @layer utilities declares `padding-block: *3` /
`padding-inline: *4` (12px / 16px). Measuring Codex's shipped button gives
79x29px outer at a 1px border, which is 1 + 8 + 12 + 8 + 1 = 30 tall
against 8px, and 38 against 12px. So the sm padding wins -- unlayered
beating a layer, the ordinary cascade -- and it is 8px on all four sides.
--spacing is Tailwind's 0.25rem base and is not a token we have, so the
literal rem is written out, which is also what the four existing copies of
this recipe do.
THIS IS THE FIFTH COPY OF CODEX'S REGULAR BUTTON in the theme --
.back-to-top-link (css-components.css), .kb-error-home
(css-page-error.css), .kb-footer-theme (css-page-footer.css) and the
header's locale chip are the others, and all four are the `md` size.
Extracting one shared .kb-button-regular is still the button migration's
job (docs/brand-refresh/plan.md), not this file's -- the same note
.kb-error-home carries. If that recipe is retuned, this changes with it.
--font-family-primary is Codex's Sora and carries no fallbacks of its own,
hence the two added here; that is css-buttons.css's `.btn` idiom verbatim.
It has to be stated at all because .zd-code-wrapper forces --ff-mono on
everything inside it, and this label is interface text, not code.
Font size is --step--1, not Codex's --font-size-xs. The two are 12.4px and
12px, and the theme's documented decision is to keep KB4's step scale
rather than port Codex's three custom sizes (css-brand-tokens.css header).
It also matches .zd-code-lang and .zd-copy-btn, the component's other two
bits of chrome.
INK CLEARS AA IN EVERY STATE, both tiers: 14.79:1 light / 9.56:1 dark at
rest, 13.58:1 / 6.84:1 hovered, 12.21:1 / 4.89:1 pressed. The two dark
figures fall short of the 7:1 target and that is the floor of the ramp,
not a tuning choice -- the fill has to keep stepping to read as a state
change at all. AA is the requirement, AAA the target where reachable.
THE FILL IS NOT WHAT MAKES THE PILL VISIBLE IN LIGHT MODE. Against the
footer surface it is ΔE00 2.76 -- the same near-invisible figure the
header rule above rejects a component-fill bar for, and 9.86 in dark.
Here the rim and the shadow do that work instead, which is why this is a
fill-plus-border-plus-shadow recipe and the header bar is a bare border.
Same reason the rest -> hover step survives light mode at only ΔE00 2.08:
the shadow growing from 2px/6px to 6px/16px is the perceptible half of
that state, not the colour. */
.zd-code-toggle {
display: inline-flex;
align-items: center;
justify-content: center;
gap: 0.5rem;
max-inline-size: 100%;
padding: 0.5rem;
border: var(--border-width-regular) solid var(--neutral-border-alpha-strong);
border-radius: var(--radius-round);
background: var(--neutral-bg-component);
box-shadow: 0 var(--shadow-y-offset) var(--shadow-blur) 0
var(--shadow-regular);
color: var(--neutral-text);
font-family: var(--font-family-primary), system-ui, sans-serif;
font-size: var(--step--1);
font-weight: var(--font-weight-strong);
line-height: 1;
cursor: pointer;
/* Tokens, where .back-to-top-link's copy of this ramp hardcodes
`200ms ease-in-out`. --motion-duration-control IS 0.2s, so this renders
identically -- but the token drops to 0s under the reduced-motion block
in css-brand-tokens.css and the literal does not, so the hardcoded copy
animates for readers who asked it not to. */
transition:
background-color var(--motion-duration-control) var(--ease-in-out),
box-shadow var(--motion-duration-control) var(--ease-in-out),
color var(--motion-duration-control) var(--ease-in-out);
}
/* Codex's `.kb-button-regular:hover`: a background step plus a taller,
softer shadow. --shadow-hover is the same colour as --shadow-regular, so
only the geometry changes -- 2px/6px becomes 6px/16px, which reads as the
button rising. Derived once at css-components.css's .back-to-top-link:hover
and not re-derived here. */
.zd-code-toggle:hover {
background: var(--neutral-bg-component-hover);
box-shadow: 0 var(--shadow-y-offset-hover) var(--shadow-blur-hover) 0
var(--shadow-hover);
}
/* Codex drops the shadow outright on press rather than returning it to the
resting 2px/6px, so the press is the exact inverse of the hover lift:
raised, to flat, to below flat. */
.zd-code-toggle:active {
background: var(--neutral-bg-component-active);
box-shadow: none;
}
/* ORDERED AFTER :hover AND :active DELIBERATELY. All three are the same
specificity, so source order is what lets the ring survive on a button
that is hovered and focused at once.
The ring itself is the sitewide one from css-reset.css's *:focus-visible;
only the offset is set here. Dropping the shadow is the same call
.back-to-top-link:focus-visible makes -- a 16px blur reading through a 2px
ring muddies it, and the ring is the more important of the two. */
.zd-code-toggle:focus-visible {
--outline-offset: 2px;
box-shadow: none;
}
/* NOTHING ANIMATES THE HEIGHT, and that is a constraint rather than an
omission. A transition needs two resolvable lengths, and the expanded
state is `auto`; the way around that is to measure scrollHeight and write
a pixel height inline, which puts an inline style back on this component.
The copy button's fade was removed for exactly that reason -- an inline
style beats every stylesheet rule this component will ever want. A
snap is the honest trade, and reduced-motion readers get it for free. */
/* ── Keyboard keys ──────────────────────────────────────────────────────── */
/* A KEYCAP, TAKEN FROM CODEX'S KbKbd AND OFF THE LEGACY PALETTE. What draws
a `kbd` today comes from css-reset.css, which gives every one in the theme
a --clr-neutral-5 fill, a --clr-neutral-160 border and a two-layer rgba
shadow faking a 3D key -- pre-refresh values with no token behind them.
This rule is (0,1,1) against that block's (0,0,1), so it wins on
specificity and needs no !important. The reset's block is left standing:
no template emits a `kbd`, so the only ones on the site are in article
bodies and this covers them, and rewriting it sitewide is not this page's
call to make.
THE BORDER IS WHAT MAKES THIS READ AS A CAP, NOT THE FILL, and that is a
measurement rather than a preference. --neutral-bg-soft against the page is
only ΔE00 3.77 light / 2.97 dark, and in the corners -- where `main`'s
radial gradients darken it to --page-bg-corner -- the light tier falls to
1.32, under a just-noticeable difference, so the fill alone would vanish
exactly there. --neutral-border measures ΔE00 17.01 / 19.95 against the
page middle and still holds 13.61 / 13.86 in those corners. Same division
of labour the Show more toggle arrived at: the rim and the shadow do the
work and the fill is a tint.
That border is 2.01:1 light / 2.30:1 dark, under the 3:1 non-text floor,
and it is acceptable here for the reason the table header's divider is --
a `kbd` is text, not a control, so nothing is identified by its boundary.
The ink carries the meaning and is AAA in both tiers: --neutral-text on
--neutral-bg-soft is 16.60:1 / 14.35:1, the same pair the code block
already measures.
NO FIXED HEIGHT, which is where this parts company with Codex. Its cap is
`h-6`, a flat 24px. Ours is built from its type and its padding instead,
so it tracks the text it is set in rather than being a number that only
suits one context.
TWO STEPS DOWN, AND MORE PADDING THAN CODEX, both Joy's calls off the
preview. `calc(1em / 1.125 / 1.125)` resolves to --step--1 exactly at both
ends of the clamp in body prose, because 1.125 is the ratio between our
steps -- so the keycap, the inline chip and the code block all sit on one
step now. That is the third time Space Mono has wanted a size below what
the arithmetic recommended. Relative rather than pinned so a key in an h2
scales with the heading instead of shrinking to body size, and --step--1
is the floor of the scale, so this lands ON it rather than under it.
THE NEGATIVE MARGIN IS WHAT BUYS THE PADDING, and without it the padding
she asked for was not available at this type size. A `kbd` is
`inline-flex`, which makes it an atomic inline-level box: its MARGIN box
sets the height of the line box it sits in, so vertical padding on it
pushes the whole line apart -- unlike the inline chip below, where padding
grows the painted box without touching the line at all. Prose here is
--step-1 at line-height 1.5, a 23.6px line box, and 12.4px of type inside
6px paddings and 1px borders is a 26.4px cap, 2.8px over.
`margin-block: -0.1875rem` takes 6px back off the margin box, bringing it
to 20.4px and comfortably inside the line box, while the cap still PAINTS
at 26.4px. A key in a sentence gets a generous cap and costs no leading.
The two declarations have to move together: the margin is half the
padding, negated.
The 1.4px per side that the cap overhangs the line box lands in prose's
half-leading rather than on the glyphs above or below, which is where the
inline chip's own padding goes too. Codex needs none of this because its
`h-6` cap is drawn standing on its own rather than set in a sentence.
The paddings are flat, not --space-*: a component's insides do not ride
the fluid scale. Codex's are 4px vertical (implied by `h-6`) and 6px from
`px-1.5`; 6px against 8px here is what makes a single key near square at
the smaller type -- one Space Mono glyph is about 7.5px wide, so `f` draws
25.5x26.4 and a word like `ctrl` simply gets longer. That leaves the 1.5em
minimum rarely binding, and it is kept as a floor rather than removed.
--radius-sm is the house value for Codex's `rounded-sm`, which the dump
does not resolve. */
kbd {
display: inline-flex;
align-items: center;
justify-content: center;
min-inline-size: 1.5em;
margin-block: -0.1875rem;
padding-block: 0.375rem;
padding-inline: 0.5rem;
border: var(--border-width-regular) solid var(--neutral-border);
border-radius: var(--radius-sm);
background-color: var(--neutral-bg-soft);
box-shadow: 0 var(--shadow-y-offset) var(--shadow-blur) 0
var(--shadow-regular);
color: var(--neutral-text);
font-size: calc(1em / 1.125 / 1.125);
line-height: 1;
white-space: nowrap;
}
/* ── Inline code ────────────────────────────────────────────────────────── */
/* INLINE CODE HAD NO TREATMENT AT ALL BEFORE THIS. css-reset.css gives every
`code` the mono family and --font-regular, and that was the whole of it --
a backticked term in a sentence was monospace text on the bare page with
no chip around it. The code BLOCK has been styled for a while; this is its
inline counterpart, from Codex's `.inline-code`.
`:not(pre) > code` is what makes it inline-only. Every code block in this
theme is `pre > code`, whether Zendesk emitted it or code-block-copy.js
wrapped it, so excluding a `pre` parent excludes all of them while still
catching inline code wherever authors put it -- a paragraph, a list item,
a table cell, a heading, or nested inside `strong`. (0,1,2) here, so it
also beats the reset's `td pre, td code` pin at (0,0,2) and a term in a
table cell matches the one in the paragraph above it.
FOUR HUES WERE PUT ON THE PREVIEW AND INDIGO WON, 2026-10-29. Magenta and
blue were ruled out on the measurements below; --success-text was tried
last, on Joy's ask, and rejected on sight. Worth recording that it was
also the only candidate that failed to reach AAA in both tiers -- 5.89:1
light and 12.47:1 dark, so AA in light against a 7:1 target -- and that
the shortfall was the token's and not the hue's: --color-lime-13-5 /
--color-lime-11 is the same green family at 8.42:1 / 7.82:1 and clears AAA
in both. If a green is ever wanted here, that is the pair to reach for.
INDIGO INK, Joy's call on 2026-10-29 to try a hue here rather than the
inherited prose ink, and indigo out of the three she named because of what
--brand-text means in this container. Article prose links are
`color: inherit` at rest and take --brand-text on :hover and :active, so a
warm red in an article body already reads as "link under the pointer".
Magenta is the closest of the three to it -- --color-ruby-12 is only ΔE00
17.6 light / 14.5 dark from --brand-text -- and would have put a resting
chip next door to a live interaction cue. Indigo clears it at 38.9 / 30.8
while staying plainly coloured against the prose it sits in (17.3 / 13.7).
Blue was the third option and is the furthest from the brand red of all
(45.5 / 45.8), but at ΔE00 14.4 from the prose ink it is the quietest, and
--color-deep-teal is the same hue family as this fill and the page behind
it, so it reads as a tint of the background rather than as a decision.
Both steps are AAA on this fill: --color-indigo-11 is 7.85:1 light and
--color-indigo-3 is 7.18:1 dark. The ramps are primitives and are NOT
redefined per tier -- only semantic tokens are -- so the dark value has to
be written out, which is what the nested `:root[data-theme='dark'] &` is
for. There is no semantic ink to reach for instead: inline code is not a
status, so --info-text and its neighbours are the wrong names even where
the value would pass. Swapping hues is a two-line change to the two
--inline-code-ink declarations; magenta is --color-ruby-12 / --color-ruby-3
(7.63:1 / 8.30:1) and blue is --color-deep-teal-11 / --color-deep-teal-5
(7.25:1 / 7.92:1), both AAA in both tiers as well.
A LINK'S OWN COLOUR WINS INSIDE IT, which is the rule below and is what
keeps the hover cue working for `…