/* =========================================================================
Upline Bones — the rules layer
=========================================================================
This stylesheet contains NOTHING about how a site looks. It contains only
what every Upline-approved theme must do to work correctly with the Upline
for WooCommerce plugin. A child theme supplies the design; this supplies the
behaviour the design is not allowed to break.
BEFORE ADDING ANYTHING HERE — WHICH SURFACE ARE YOU ADDING TO?
-------------------------------------------------------------------------
The chassis offers skins two API surfaces, and they are not equally used.
Measured across all three skins that exist: the `ub-*` CLASS surface is
consumed heavily and everywhere — `ub-reveal-items` 24 times in one skin,
`ub-cap-4` 13, the whole `ub-archive__*` set, `ub-defer`, `ub-inline-menu`,
`ub-scroll-x` — while the `ub-*` TOKEN namespace is read exactly once, by
one skin, for one value. Two skins reference no `ub` token at all.
So: **declare classes generously, mint tokens reluctantly.** A class costs a
name and buys a place a skin can hook; a token costs a name, a default, a
contract row, and a reverse check that cannot be evaluated from inside this
artifact — three of them were removed in 2.3.12 having never been read by
anything. Gate 18's classifier watches the surface that carries the load;
gate 14's reverse direction watches the one that mostly does not.
Which is not a licence to name loosely. Every `ub-*` class here is one of
three things and the gate makes you say which: **structural** (emitted and
styled here), **slot** (emitted here, styled by the skin — naming a place
without decorating it is the design), or **opt-in** (styled here, applied by
the skin).
Everything here is either:
- a hard rule from Build Spec §4 expressed in CSS, or
- a motion or loading primitive that a child theme opts into by class, or
- a structural fact about how WordPress assembles the document.
Every colour in this file comes from a token. There is not one literal
colour value below, on purpose: if a rule here needs a colour that no token
provides, that is a missing token and it gets requested from the plugin
(Build Spec §4.4) rather than invented here.
WHAT IS NOT HERE ANY MORE — read this before adding a plugin selector
---------------------------------------------------------------------
Versions up to v7 carried a large section headed "PLUGIN SURFACE HOOKS —
VERIFIED": 49 rules, 14.8KB, styling .upline-menu, .upline-facet,
.upline-mega, .upline-tile and their internal descendants by hand. It was
63% of this file.
It was correct when it was written, because the plugin then ignored theme
tokens: the rail read none at all, and the token block was scoped to three
classes, so a theme setting accent got it on whatever it thought to check
and silently not on the rest. Hand-styling was the only route.
upline-facets 1.13.0 fixed that. Every storefront surface is now inside the
token scope, and a test in the plugin fails if its CSS and docs/theme-tokens.md
stop agreeing in either direction. So that section became three problems at
once: redundant, because tokens do the work; fragile, because half its
selectors reached below the top-level classes the plugin guarantees, into
__element and --modifier names it says will move; and actively harmful,
because where a theme rule and a token both apply the theme wins, so a
shop's own token setting does nothing — which is the exact failure 1.13.0
was released to fix.
It is deleted. Do not reinstate any of it. Per the plugin's own contract,
needing a plugin selector is a bug report, not a theme technique: if a
surface cannot be reached through the fifteen tokens, that is a missing
token, and it gets raised against the plugin.
THE ONE THING THE TOKENS CANNOT DO, AND WHERE IT IS HANDLED — 2.3.14
-------------------------------------------------------------------
There is exactly one class of problem the "request a token" route cannot
answer, because it is not the plugin failing to reach a surface: it is THIS
THEME reaching into the plugin's surface without meaning to. WordPress emits
styles.elements.link as a rule matching every on the page, the plugin's
panels included, and inheritance loses to any matching declaration. So the
plugin sets `color: panelFg` on its drawer and expects its links to inherit
it, and this theme's link colour overrides all of them. Measured on a bare
Bones install: drawer ground rgb(26,26,26), drawer links rgb(26,26,26),
contrast 1.00, thirty-seven invisible links.
The plugin cannot defend against this. Its rules live in @layer upline and
global styles are unlayered, so a `color: inherit` on its side loses no
matter how it is written. That is the @layer inversion in its hazard
direction and it makes the carve-out ours by construction.
The carve-out lives in theme.json under styles.blocks["upline-facets/menu"],
NOT in this file — it names a public block, WordPress emits the selector, and
no plugin internal is mentioned, so the rules below still hold exactly. It
declares currentColor, never a palette value: the ink belongs to the surface
and moves with it. Gate 20 asserts it, in both directions.
Rules this file is held to:
- No selectors into plugin markup at all.
- No !important. Not one.
- Never hide disabled filter options, never restyle the mobile toggle into
a JS-dependent control, never change chip height.
- Wide content scrolls in its own container, never the page.
========================================================================= */
/* -------------------------------------------------------------------------
1. Foundations
------------------------------------------------------------------------- */
/* Hard rule §4.5, applied globally: the page never scrolls sideways. Anything
that would force it scrolls inside itself instead. */
html,
body {
overflow-x: clip;
}
/* The named escape hatch for wide content — spec tables, wide grids, anything
the P2 two-column spec table brings. Applied as a block className. */
.ub-scroll-x {
overflow-x: auto;
overscroll-behavior-x: contain;
}
/* One focus treatment for every theme built on Bones, tokenised so a child
changes it without writing CSS. Plugin surfaces inherit this too. */
:where(a, button, input, select, textarea, summary, [tabindex]):focus-visible {
outline: var(--wp--custom--ub--focus-ring, 2px) solid var(--wp--custom--ub--focus-color, currentColor);
outline-offset: var(--wp--custom--ub--focus-offset, 2px);
border-radius: var(--wp--custom--upline--radius, 0px);
}
/* Minimum tap target, from the plugin's own `tap` token so a child and the
plugin cannot disagree about it. Scoped with :where() so it contributes no
specificity and a design can size a control up freely — it only ever raises
a floor. Lowering `tap` is an accessibility regression; the plugin says so
and this is where that statement lands in the theme. */
:where(.wp-block-button__link, .wp-element-button, button, [type="submit"], [type="button"]) {
min-block-size: var(--wp--custom--upline--tap, 44px);
}
/* The same floor, applied to pagination, because a page number is a control a
thumb has to hit and core ships it as a bare link with no minimum at all.
`core/query-pagination` renders `.page-numbers` on the archive and
`.wp-block-query-pagination-*` on the wrapper links; both spellings are
core's own published output, so both are named. Only the pill shape, the
type and the active treatment are look — the floor is not, which is why it
sits here and not in a skin. Flex rather than min-block-size alone: a link
with a 44px box and a 17px line still puts its glyph at the top. */
:where(.wp-block-query-pagination) :where(a, span).page-numbers,
:where(.wp-block-query-pagination-previous, .wp-block-query-pagination-next) {
display: inline-flex;
align-items: center;
justify-content: center;
min-block-size: var(--wp--custom--upline--tap, 44px);
min-inline-size: var(--wp--custom--upline--tap, 44px);
padding-inline: var(--wp--custom--upline--gap-sm, 0.5rem);
}
/* SCOPE THE FLOOR BY ROLE, NOT BY ELEMENT WORD — 2.3.14.
---------------------------------------------------------------------------
The floor above names `button`, `[type=submit]` and the block-button classes:
the elements a control is USUALLY built from. The requirement is about what a
thumb has to hit, and those are not the same set. A render leg on an unskinned
chassis measured three controls escaping a floor that reads as universal:
.wc-block-customer-account__link 36px Woo renders it as an
.ub-header__secondary a 17px a nav link in a paragraph
.ub-header__logo a 19px the site title, which is a
link to the home page
Every vendor surface that is a control-in-an-anchor is outside a floor named
by element word, and no static check sees it — it took a browser. The account
control is Woo's published class, which §6 makes fair game; the other two are
the chassis's own header slots.
WHY THESE ARE NAMED ONE BY ONE RATHER THAN AS `.ub-header a`.
A descendant floor on the header would reach the PLUGIN's menu links, which
sit inside it, and give its mega-panel entries a 44px box the plugin never
asked for — changing the geometry of a surface this theme does not own,
through a selector gate 6 cannot see because it names no plugin class. Reach
and assumption get scoped together, so each slot is named for itself.
A NOTE FOR THE SKIN THAT WANTS A THIN UTILITY LINE. This raises 2e's
secondary row from 17px to the tap floor, which is a visible change and the
correct one. A skin that wants the line to read thinner earns it with type,
colour and padding inside a 44px box — not by lowering the floor, which is
the one direction the token is not allowed to move.
TWO RULES, BECAUSE THE ROLES DIFFER IN THE INLINE AXIS. Written first as one
rule carrying only `min-block-size`, and measured on the unskinned chassis it
was wrong twice over: the icon control went to 60px tall and stayed 36px
WIDE. Woo ships that control `box-sizing: content-box` with 8px of padding,
so a 44px block floor becomes a 60px box — and an icon control's target is
square, so a block-axis floor alone leaves the thumb a 36px-wide strip. An
icon control takes both axes and a border box; a text link takes the block
floor and lets its own text decide the inline extent. Measured after the
split: 44x44, 44, 44, with the brand row unchanged at 72px and no overflow
at 390. The remedy needed the file, not the inventory. */
:where(.wc-block-customer-account__link, .wc-block-customer-account__toggle,
.wc-block-mini-cart__button) {
box-sizing: border-box;
display: inline-flex;
align-items: center;
justify-content: center;
min-block-size: var(--wp--custom--upline--tap, 44px);
min-inline-size: var(--wp--custom--upline--tap, 44px);
}
/* THE BAG JOINED THIS LIST LATE, AND THE REASON IS THE LESSON — 2.3.16.
2.3.14 gave the account control both axes because it was measured at 36x36.
The bag was measured at the same time, read 33x44, and was not fixed: the
generic `button` floor above had already given it its HEIGHT, so it did not
look like a member of the class — it looked like a control that was nearly
right. An icon control's target is SQUARE, and a floor that lands on one axis
leaves a 33px-wide strip for a thumb while reporting a compliant 44.
Measured on 2a's render leg, unskinned: `wc-block-mini-cart__button` 33x44,
the only header control under the floor once the instrument was scoped to
what a shopper can touch. Half a floor reads as a floor, which is why it
survived a release that was looking directly at it. */
:where(.ub-header__secondary) :where(a),
:where(.ub-header__logo) :where(a) {
display: inline-flex;
align-items: center;
min-block-size: var(--wp--custom--upline--tap, 44px);
}
/* ONE BRAND, NOT TWO — 2.3.31.
------------------------------------------------------------------------
MEASURED ON BIKECO at plugin 1.54.0 / Bones 2.3.30 / Ridgeline 2.15.7: the
logo slot renders `.wp-block-site-logo` (the image, at x922, 150 wide, with
the wordmark inside the artwork) AND `.wp-block-site-title` ("bike co." at
x1092) side by side. The shop's name appears twice in its own header.
IT IS THE CHASSIS'S, AND IT IS IN ALL SIX PATTERNS. Every
`header-*.php` places `wp:site-logo` and `wp:site-title` in this slot, and
has since they were written. What changed is only who met it: Ridgeline
2.14.0 rendered its OWN header part with `wp:site-logo` alone, so the pair
never co-existed; 2.15.0 handed the header to the switcher and inherited a
case the pattern never handled. Nothing was lost by the skin — a latent
chassis defect became reachable. Which also means it is waiting for every
other skin that adopts the switcher, Slope included.
WHY A RULE AND NOT SIX PATTERN EDITS. Both blocks are legitimate: a shop
with no logo needs the title, and a shop whose logo artwork contains the
wordmark does not. The pattern cannot know which it has; only the rendered
DOM can. So the condition belongs in CSS, keyed on core's own published
classes — the same dependency class as `wp-block-template-part` at section
4, and stable for the same reason.
`:has(.wp-block-site-logo img)` rather than `:has(.wp-block-site-logo)`: the
block still emits its wrapper in some contexts when no logo is set, and a
wrapper is not a logo. The image is the thing that makes the title
redundant, so the image is what the test asks for.
DEGRADATION IS THE POINT: no logo image, no match, title stays. A shop that
removes its logo gets its wordmark back with no theme change.
`:where()` on the title keeps this at (0,1,0)+0 so a skin that wants both —
a logo mark beside a typeset name is a real design — overrides it with one
plain declaration rather than fighting the chassis. */
.ub-header__logo:has(.wp-block-site-logo img) :where(.wp-block-site-title) {
display: none;
}
/* -------------------------------------------------------------------------
2. Motion primitives
-------------------------------------------------------------------------
Bones owns the MECHANISM; a child theme owns the taste — durations and
easings come from tokens, and a child opts a section in by adding a class.
Two hard constraints shape all of it:
- Build Spec §6.6 forbids layout shift on menu open, so nothing here
animates a property that triggers layout. Opacity and transform only.
- The theme ships no JavaScript, so nothing may depend on a script to
become visible. The failure mode of an IntersectionObserver reveal
(script never runs, content stays at opacity 0, page looks empty)
cannot occur here: the only reveal rules live inside a support query
whose animation END STATE is the normal rendered state.
------------------------------------------------------------------------- */
@media (prefers-reduced-motion: no-preference) {
/* Scroll-driven reveal. Where animation-timeline is unsupported nothing is
applied at all and content is simply visible. */
@supports (animation-timeline: view()) {
.ub-reveal {
animation: ub-rise linear both;
animation-timeline: view();
animation-range: entry 0% cover 24%;
}
/* Staggered children — cards, tiles, columns. Each child runs its own
view() timeline, so the stagger comes from their real positions
rather than hardcoded delays that go wrong at a different viewport
height. */
.ub-reveal-items > * {
animation: ub-rise linear both;
animation-timeline: view();
animation-range: entry 0% cover 20%;
}
}
@keyframes ub-rise {
from {
opacity: 0;
transform: translate3d(0, 14px, 0);
}
to {
opacity: 1;
transform: none;
}
}
/* Panels that appear from display:none — mega menu, search dropdown. A
child opts in; the duration and easing come from tokens. */
@keyframes ub-panel-in {
from {
opacity: 0;
transform: translate3d(0, -6px, 0);
}
to {
opacity: 1;
transform: none;
}
}
.ub-panel-in {
animation: ub-panel-in var(--wp--custom--ub--motion-panel, 380ms) both;
}
}
/* Reduced motion: neutralise every kind. The scroll-driven ones need their
TIMELINE removed, not just a short duration, or they keep binding scroll
position to opacity — which is why this is more than the usual blanket
rule. */
@media (prefers-reduced-motion: reduce) {
*,
*::before,
*::after {
animation-duration: 0.001ms;
animation-iteration-count: 1;
transition-duration: 0.001ms;
scroll-behavior: auto;
}
.ub-reveal,
.ub-reveal-items > *,
.ub-panel-in {
animation: none;
animation-timeline: auto;
opacity: 1;
transform: none;
}
}
/* -------------------------------------------------------------------------
2a. The collapse primitive
-------------------------------------------------------------------------
A header that shrinks as the page scrolls, with no JavaScript. Every header
option in the wireframe set except one needs this, so it is the chassis's,
and a skin supplies only the two heights.
THE PREVIOUS ATTEMPT NEVER RAN, AND THE REASON IS THE WHOLE DESIGN.
-------------------------------------------------------------------------
Ridgeline shipped `rl-header-compact` and it sat `pending: true` with
`currentTime: null` through every release — registered, correct in every
part anyone thought to check, and touching nothing. Reproduced in a browser
rather than reasoned about:
an ancestor with `overflow: hidden` → pending: true, never runs
an ancestor with `overflow-x: hidden` → pending: true, never runs
the same, with `scroll(root block)` → collapses, 72px -> 44px
`animation-timeline: scroll()` is shorthand for `scroll(nearest block)`, and
*nearest* is resolved against the ancestor chain. Any ancestor that is a
scroll container captures the timeline — **including one that only scrolls
on the inline axis** — and if it cannot scroll in the block axis the
timeline is INACTIVE, which presents as an animation that exists, validates,
and does nothing.
A theme does not own its ancestor chain. WordPress wraps template parts,
plugins wrap their blocks, Woo wraps its own, and any of them may set
`overflow-x: hidden` for reasons that have nothing to do with this. So
`nearest` is a rule whose correctness depends on a value it does not own —
scar 9, in the one place where being wrong produces no symptom at all.
**Name the source: `scroll(root block)`.** `root` is the document, which no
ancestor can take away. (`overflow-x: clip` does NOT capture it — clip makes
no scroll container — which is why Bones' own global clip in section 1 was
never the culprit, and why guessing would have pointed at the wrong file.)
THE HEIGHT IS RESERVED, so the collapse cannot feed back on itself. The
outer box holds `--ub-collapse-from` for the document's layout and the inner
bar is what shrinks. A sticky box that changed the page's own height while a
scroll timeline read that same height would be a rule driven by a value it
is simultaneously changing.
A skin opts in by class and sets the two heights. Below the browser floor
nothing animates and the header stays at its resting height, which is a
perfectly good header: this is an enhancement, not a dependency. */
.ub-collapse {
--ub-collapse-from: 72px;
--ub-collapse-to: 44px;
--ub-collapse-range: 120px;
min-block-size: var(--ub-collapse-from);
}
.ub-collapse__bar {
display: flex;
align-items: center;
min-block-size: var(--ub-collapse-from);
}
/* THE BAR'S CHILD MUST FILL IT — 2.3.27, and this is a defect fix with range's
numbers behind it.
------------------------------------------------------------------------
MEASURED ON RANGE (2.3.26, `header-drawer`, 1440x900): the bar's child — the
`alignwide is-content-justification-space-between` row with `max-width: 1280px`
— came out 521px wide at x460-981, so `space-between` had no free space to
distribute and all five slots packed into the middle of a 1440px bar: nav 460,
logo 572, search 717, secondary 771, actions 872. The frame for 2a is
edge-to-edge.
REPRODUCED HERE before anything was changed, in Chromium against this
stylesheet: child 422px at x509-931, nav 509 / logo 573 / search 721 /
secondary 790 / actions 889. Different text metrics, same geometry — and
`search` landing at 721 against range's 717 is the tell that it is the same
shape rather than a lookalike.
THE CAUSE IS TWO OWNERS OF ONE BOX. All three patterns that carry
`ub-collapse__bar` declare `layout: constrained` on that same group — drawer on
its brand row, two-row and utility-line on their strips. WordPress implements a
constrained layout by giving the CHILDREN a max-width and auto inline margins,
and it never sets `display` on the container: the arrangement only works while
the container is a block and the child is a block-level box filling it. The rule
above makes it a FLEX container, so the child stops filling and sizes to its
content. Nothing about either declaration is wrong on its own; they are
incompatible, and the chassis one wins silently.
FOUR CANDIDATES MEASURED, not reasoned:
as shipped child 422px x509 · vertical 25/25 centred
flex-grow: 1 child 1280px x80 · vertical 25/25 centred <- shipped
display: grid child 422px x509 · NO CHANGE
display: block child 1280px x80 · vertical 0/50, content pinned to top
`display: grid` was the candidate this bench expected to work — grid items
stretch on the inline axis by default — and it changed nothing, because WP's
constrained layout also gives the child `margin-inline: auto`, and auto margins
beat `justify-items: stretch` exactly as they beat `flex-grow`. Measured, not
assumed, and worth recording because it is a plausible "simplification".
`display: block` is the other obvious fix and it trades one defect for another:
the width comes right and the vertical centring goes, content pinned to the top
of a 72px bar. That is what the flex was for.
So: keep the flex, let the one child grow. `min-inline-size: 0` was tested
alongside and adds nothing measurable at 360 or 1440, so it is not here — and
neither width overflows (scrollWidth == innerWidth at both). The three patterns
with no collapse bar are untouched by this rule, confirmed in the same harness:
push's child measures 1280px at x80 before and after.
HONEST LIMIT ON ALL OF THE ABOVE: the harness emulates what WordPress emits for
`constrained` and `flex` layouts; it is not WordPress. It reproduces range's
geometry, which is what makes it evidence — but the fix is owed a read on range
like any other. */
.ub-collapse__bar > * {
flex-grow: 1;
}
@media (prefers-reduced-motion: no-preference) {
@supports (animation-timeline: scroll(root block)) {
.ub-collapse__bar {
animation: ub-collapse linear both;
animation-timeline: scroll(root block);
animation-range: 0 var(--ub-collapse-range);
}
/* THE KEYFRAME ANIMATED A MINIMUM THAT WAS NOT BINDING — fixed 2.3.36,
and the defect was this file's, in two rules that never met.
----------------------------------------------------------------
`min-block-size: var(--ub-collapse-to)` was the whole of the keyframe,
and on the drawer it moved nothing at all. The bar's height is
`max(min-block-size, content + padding-block)`, and the padding comes
from `.ub-header__brand-row` — 1,500 lines below, under a different
class, on THE SAME ELEMENT: the drawer pattern writes
`class="ub-header__brand-row ub-collapse__bar"`. Two rules of this
stylesheet, each correct alone, neither aware of the other. The second
instance of the same shape as the `display: flex` against
`layout: constrained` conflict documented above — same element, same
class pair, and that one took a four-candidate measurement to find too.
MEASURED ON BIKECO AT 1440, plugin 1.56.0, Ridgeline's tokens, by
applying each end state statically so the MECHANISM is tested and the
timeline is not in the way:
resting bar 72 min-block 64 pad 14/14
min-block-size -> --to ONLY bar 72 <- TODAY'S KEYFRAME
+ padding-block: 0 bar 52 <- --to, exactly
--to 44 + padding-block: 0 bar 44 <- 2a's spec, exactly
Row two is the defect with nothing left to argue about: the keyframe's
own end state, forced, does not move the bar one pixel. So this was
never a trigger problem — it would not move with a live timeline
either, which is why it is fixed ahead of that question being settled.
WHY `padding-block: 0` AND NOT A NEW TOKEN. The minimum already says
what the condensed height is; it simply was not reachable. Zero the
padding and `max(--to, content)` is the height, so the existing
declaration becomes binding WITHOUT ITS VALUE CHANGING, and a skin's
two heights keep their meaning. 44 is the floor this mechanism can
reach, because the content is tap-sized controls — which is exactly
what 2a's spec asks for in words, "burger · logo mark · search · bag
only", and row four is that number measured rather than argued.
`align-items: center` on the bar keeps the row centred as the box
shrinks, so nothing jumps; the outer `.ub-collapse` still holds its own
minimum, so the page height is not driven by the thing the timeline
reads.
LIMIT, STATED: `two-row` and `utility-line` carry this bar on
`.ub-header__strip`, which no stylesheet gives padding, so their
minimum was already binding and this line is a no-op for them. Read
from the stylesheets, not measured — neither option is flipped on a
bench right now. `bottom-bar`, `push` and `sidebar` carry neither
class and are untouched; their own docblocks say so. */
@keyframes ub-collapse {
to {
padding-block: 0;
min-block-size: var(--ub-collapse-to);
}
}
}
}
/* -------------------------------------------------------------------------
3. Deferred rendering
-------------------------------------------------------------------------
WordPress core already handles image loading attributes: it marks the first
in-viewport image fetchpriority="high", lazy-loads the rest, and adds
decoding="async". Re-implementing that would fight core and would put logic
in a theme that is meant to be dumb.
What a theme owns is deferring the RENDER of off-screen sections, not just
their images. content-visibility skips layout and paint until the user
reaches the section; contain-intrinsic-size supplies a placeholder height so
the scrollbar stays honest and in-page anchors still land.
The other half — reserving space so a lazily-loaded image never shifts the
page — is the child theme's job, because ratios are a design decision.
------------------------------------------------------------------------- */
.ub-defer {
content-visibility: auto;
contain-intrinsic-size: auto 640px;
}
/* -------------------------------------------------------------------------
4. Page structure
-------------------------------------------------------------------------
Rules about how WordPress assembles the document, not about how any one
theme looks. A child theme should never have to restate these.
------------------------------------------------------------------------- */
/* WordPress separates every top-level block with the root blockGap, and that
includes the seam between the header template part and . On a theme
whose header is a solid band and whose first section is a full-bleed hero,
the gap renders as a strip of page background wedged between them — a white
bar under a black header, which reads as a bug rather than as spacing.
Specificity note: WordPress emits its rule as
`:where(.wp-site-blocks) > * + *`, which contributes NOTHING to specificity,
so a single class here wins regardless of stylesheet order. */
.wp-site-blocks > main {
margin-block-start: 0;
}
/* Sticky offset. Logged-in WordPress renders a fixed admin bar over the top of
the viewport, so anything stuck to `top: 0` slides underneath it. Shops see
0; we see 32 (or 46 on the narrow breakpoint, where the admin bar is taller
and stops being fixed at all). Children position against this token instead
of guessing. */
:root {
--ub-sticky-top: 0px;
}
body.admin-bar {
--ub-sticky-top: 32px;
}
@media screen and (max-width: 782px) {
body.admin-bar {
/* Below 782px the admin bar is position:absolute, not fixed — it
scrolls away with the page, so nothing needs to clear it. */
--ub-sticky-top: 0px;
}
}
/* The sticky header, and why it has to live HERE rather than in the skin.
------------------------------------------------------------------------
A `wp:template-part` with `tagName:"header"` renders its own wrapper —
`` — around whatever the part file
contains. A skin that also opens a group with `tagName:"header"` therefore
produces two nested headers, and `position: sticky` on the INNER one does
nothing at all: a sticky box can only travel inside its parent's padding
box, and that parent is exactly as tall as it is. Zero travel. It scrolls
away looking exactly like a sticky rule that was never written.
Measured on bikeco before this rule existed: at scrollY 600 the header's
top was -568px, i.e. gone. Wrapper height 181, inner height 181.
So the sticky belongs on the wrapper, which only the parent can reach —
a child theme cannot add a class to a template-part call inside a Bones
template it inherits. `wp-block-template-part` is core-generated and
core-published, the same class of dependency as Woo's `wc-block-*`, and
unlike a plugin's `__element` names it does not move between releases.
A design that does not want a sticky header sets `position: static` on
this selector in its own stylesheet. Theme CSS is unlayered, so one plain
declaration wins — no `!important`, no specificity games. */
.wp-site-blocks > header.wp-block-template-part {
position: sticky;
top: var(--ub-sticky-top, 0px);
z-index: 40;
}
/* AND THE BAR HAS TO PAINT, or sticky is worse than nothing — 2.3.29.
------------------------------------------------------------------------
MEASURED ON RANGE, bare Bones, all widths (591 and 390, same chain at 1440):
every box from `.ub-header__logo` up through `.ub-header__brand-row`,
`.ub-collapse`, `.ub-header--drawer` to the template part itself computes
`background-color: rgba(0, 0, 0, 0)`. The rule above pins that transparent
stack over the page at z-40, so scrolled content renders straight THROUGH the
header. A header that scrolls away is a missing feature; a header you can
read the page through is a broken one.
THE ASSUMPTION THAT PUT IT THERE IS WRITTEN IN THIS FILE, at the checkout rule
in section 9: "on every other page the wrapper itself paints nothing and the
skin's own header group inside it supplies the opaque surface." That sentence
was true of the only skin anyone had rendered — Ridgeline paints `.rl-header`
from `base`, which is why bikeco never showed this in six releases of looking
at it. So the chassis has been shipping a sticky bar with no surface since
2.3.5 and a skin was quietly covering for it. A defect only visible when a
particular child theme is ABSENT is one that can live in a chassis for a long
time, because the chassis is almost never what anyone looks at.
IT PAINTS `.ub-header`, NOT THE STICKY WRAPPER, and the distinction is the
whole care in this fix. Painting the wrapper would be the obvious move and it
would reverse a ruling this file already made: section 9 rejected exactly that
("the other candidate fix was to paint this wrapper opaque"), because Woo's
checkout renders its OWN `checkout-header` part into the same wrapper, and
painting it would mean the chassis dressing a part it neither authors nor
paints. `.ub-header` is on the outermost group of all six header patterns —
markup this chassis does own — so this fix leaves that ruling standing rather
than quietly overturning it, and checkout is untouched because Woo's part
carries no `.ub-header`.
`surface` RATHER THAN `base`, chosen and not defaulted. Bare Bones paints the
page ground from `base`, so a base-painted bar would be opaque and correct and
look like no bar at all — and the chassis's standing instruction to itself is
that inheriting it unchanged should look UNFINISHED, not broken. An opaque bar
you can see is the minimum functional state. A skin overrides in one plain
declaration, which is what Ridgeline already does.
`Canvas` as the fallback, not a hex: it is the UA's own page-background system
colour, so it is opaque and it follows the user's light/dark preference. A
hardcoded `#fff` would be a guess about a palette this file does not own.
WHAT THIS DOES NOT REACH: a skin that renders its own header element and
paints nothing. The invariant is the sticky wrapper is transparent by design,
so whatever fills it must paint — Bones' own patterns now do, and a skin's own
header element is the skin's to paint. Gate 26 asserts it per artifact rather
than leaving it as this paragraph. */
.ub-header {
background-color: var(--wp--preset--color--surface, Canvas);
}
/* -------------------------------------------------------------------------
5. Grid column ceiling
-------------------------------------------------------------------------
THE PROBLEM THIS EXISTS FOR
---------------------------
A block grid set to "auto" columns emits
`repeat(auto-fill, minmax(, 1fr))`. That formula has no upper bound: it
fits as many tracks as the container allows. At a 1480px wide measure a
200px minimum yields SEVEN columns, so a four-item row fills the first four
and leaves three empty tracks — which looks exactly like a section that has
been left-aligned inside a container that is too wide. It is not an
alignment bug and no amount of justify/margin fixes it; the row genuinely
has seven cells.
The fix is to raise the track FLOOR to one-Nth of the row. Once a track can
never be narrower than a quarter of the available width, a fifth track can
never fit, and `auto-fill` still steps down to 3, 2 and 1 as the container
narrows. No media queries, no column counts to keep in sync.
NOTE: for the plugin's OWN product grids this is not the right lever — the
collection-grid column count is a plugin setting and should be set there.
These classes are for grids the theme renders itself.
Specificity note: WordPress's own rule is a single class
(`.wp-container-core-group-is-layout-XXXX`) in an INLINE stylesheet that
lands after the theme's linked file. A single class here would tie and lose.
Every selector below is therefore at least two classes. This is written down
so the next person does not rediscover it. */
/* TWO CORRECTIONS, Bones 2.3.8 — the ceiling was capping at N-1, everywhere.
-------------------------------------------------------------------------
1. THE GAP THE FORMULA SUBTRACTS MUST BE THE GAP THE GRID USES.
`--ub-cap-gap` read `--wp--custom--upline--gap` — the theme's SPACING token
— while the grid is laid out with `--wp--style--block-gap`, which is a
different value. On bikeco: token **10px**, real gap **20px**. The floor is
therefore computed one gap-size too generous, and a floor that is too large
is a column that cannot fit:
floor (1480 - 3 x 10) / 4 = 362.5px
available(1480 - 3 x 20) / 4 = 355px
four tracks cannot fit, by 7.5px — `auto-fill` steps down to three
Reported as "the confidence bar renders three columns with two entries
stacked in the first", and that is exactly what a four-item row does in a
three-track grid. But the defect is not that bar: **every capped grid on
every site is one column short whenever the block gap exceeds the spacing
token**, silently, because a grid that quietly caps at 3 looks like a
deliberate 3-column grid. The formula subtracted a number it did not own.
2. `auto-fill` -> `auto-fit`, because correcting (1) exposed what (1) had
been accidentally hiding.
The over-large floor was ALSO suppressing empty tracks: a three-item row in
a cap-4 grid rendered three tracks, which looks right. Fix the gap alone and
that row gains a fourth, empty track — the "section left-aligned inside a
container that is too wide" look this section's own problem statement exists
to kill. `auto-fit` collapses tracks with nothing in them, so a row shorter
than its cap fills the width instead of trailing a dead column.
Measured on the front page, both grids, before and after: the three-item row
holds 480/480/480 with the fourth track collapsed to 0px and its right edge
flush, and the four-item bar reads 355/355/355/355 on one row. Below roughly
660px `--ub-cap-min` dominates both formulas identically, so the mobile
stacking is arithmetically untouched — which is the constraint Ben set. */
.ub-cap-4.is-layout-grid,
.ub-cap-6.is-layout-grid {
--ub-cap-gap: var(--wp--style--block-gap, var(--wp--custom--upline--gap, 16px));
}
.ub-cap-4.is-layout-grid {
grid-template-columns: repeat(
auto-fit,
minmax(max(var(--ub-cap-min, 150px), calc((100% - 3 * var(--ub-cap-gap)) / 4)), 1fr)
);
}
.ub-cap-6.is-layout-grid {
grid-template-columns: repeat(
auto-fit,
minmax(max(var(--ub-cap-min, 120px), calc((100% - 5 * var(--ub-cap-gap)) / 6)), 1fr)
);
}
/* -------------------------------------------------------------------------
6. Archive shell
-------------------------------------------------------------------------
The two-column rail-and-grid arrangement that templates/archive-product.html
uses. It is here rather than in a child because the DEFAULT archive lives
here — but it is a default, not a decree.
A child theme that wants a different shape (filters in a drawer only,
filters across the top, no rail at all) replaces archive-product.html
wholesale and never uses these classes. That is expected, not a workaround.
The flex values are the "holy grail" arrangement: the rail holds its column
width, the results take everything else, and the pair wraps to one column
when there is no longer room for both — with no media query and no
breakpoint to keep in sync with the design.
------------------------------------------------------------------------- */
/* The archive head sits at the wide measure but its CONTENT reads at the
content measure, hard left. `layout: constrained` would do the capping and
then centre the box in the wide container — which renders as a title
floating in the middle of the page, not as a hero. `layout: default` plus a
cap here keeps the left edge aligned with the rail below it. */
.ub-archive__head > * {
max-inline-size: var(--wp--style--global--content-size, 720px);
margin-inline: 0;
}
.ub-archive__body {
display: flex;
flex-wrap: wrap;
gap: var(--wp--custom--upline--gap, 16px);
}
.ub-archive__rail {
flex: 1 1 var(--wp--custom--upline--column, 16rem);
}
/* 28rem, not 20rem, and the reason is the stacking point rather than the
width. These two flex bases decide when the pair wraps: it happens once
rail-basis + results-basis + gap exceeds the container. At 20rem that lands
near 590px, which leaves a window where the rail still holds its full column
and the grid is squeezed to ~330px — one cramped product per row. At 28rem
the pair stacks below roughly 720px instead, so the grid never renders
narrower than about two columns before it goes full width. Measured, not
guessed: side by side at 900 and 700, stacked at 390. */
.ub-archive__results {
flex: 999 1 28rem;
min-inline-size: 0;
}
/* The results toolbar — count on one side, sorting on the other.
archive-product.html has emitted `ub-archive__toolbar` since the shell
shipped and this stylesheet declared `__head`, `__body`, `__rail` and
`__results` and not this one, so the class arrived in every skin's DOM with
nothing behind it. Two independent skins each discovered they had to style
it and each did, privately, and on both sites it looked deliberate.
That is an undeclared token wearing markup's clothes: no runtime signal, and
every skin pays the same tax without knowing anyone else did. Gate 18 now
asserts the chassis's own classes in both directions so the next one cannot
ship silently.
The template already asks for flex with space-between, so the arrangement
is the block's; what belongs here is the pair's behaviour when the row runs
out of room, which is the part a template attribute cannot express. */
.ub-archive__toolbar {
gap: var(--wp--custom--upline--gap-sm, 0.5rem);
}
.ub-archive__toolbar > * {
margin-block: 0;
}
/* Sticky rail on viewports tall and wide enough to benefit. Offset by the
admin-bar token so it never slides under the toolbar. */
@media (min-width: 782px) {
.ub-archive__rail > * {
position: sticky;
top: calc(var(--ub-sticky-top, 0px) + var(--wp--custom--upline--gap, 16px));
}
}
/* -------------------------------------------------------------------------
6b. Product page shell
-------------------------------------------------------------------------
The media/buy pair that templates/single-product.html uses, on the same
terms as the archive shell: a replaceable DEFAULT, not a decree. A child
that wants a different PDP replaces the template and never sees these.
Bones shipped no `single-product.html` at all until 2.3.12, so an unskinned
Bones fell through to Woo's own fallback on the one page a shopper decides
to buy on — `source: plugin` in the template registry, which reads like
ownership and is actually a gap.
The gallery column takes the larger share and holds it; the buy column
never drops below a readable measure. `columns` stacks on its own below
781px, which is core's behaviour and not a number this file owns. */
.ub-pdp__media {
flex-basis: 55%;
min-inline-size: 0;
}
.ub-pdp__buy {
flex-basis: 45%;
min-inline-size: 0;
}
/* Woo's classic gallery floats its images and caps the wrapper; both are
Woo's layout opinion arriving on a block page. Released here rather than in
a skin because every skin meets it. Qualified with the element Woo itself
targets, because `.woocommerce div.product div.images` measures (0,3,2) and
a three-class override loses on element count — the rule would sit in the
file and nothing would move. */
.ub-pdp__media .woocommerce div.images,
.ub-pdp__media div.woocommerce-product-gallery {
inline-size: 100%;
max-inline-size: none;
float: none;
}
.ub-pdp__detail {
min-inline-size: 0;
}
/* -------------------------------------------------------------------------
7. Form controls
-------------------------------------------------------------------------
Browsers ship a look for inputs, selects and buttons, and neither WordPress
nor a block theme overrides it. So a bare renders as OS chrome in
the middle of a designed page — which is what the Upline search block and
every Woo field currently do.
This was briefly mistaken for a missing plugin token. It is not: no token
would help, because the problem is that nothing in the stack normalises form
elements at all. The fix belongs here, at element level, where it reaches
every control on the site — the plugin's, Woo's and the theme's — without
naming a single plugin class.
Everything below inherits: font from the theme, colour from currentColor,
border from the rule token, corners from the radius token. Bones states no
opinion about how a field should look, only that it should look like the
theme it is sitting in.
------------------------------------------------------------------------- */
:where(input, select, textarea) {
font: inherit;
color: inherit;
background-color: transparent;
border: 1px solid var(--wp--custom--upline--rule, currentColor);
border-radius: var(--wp--custom--upline--radius, 0px);
padding-block: var(--wp--custom--upline--gap-sm, 8px);
padding-inline: var(--wp--custom--upline--gap, 16px);
min-block-size: var(--wp--custom--upline--tap, 44px);
}
/* Checkboxes and radios are the exception: the rules above would blow them up
to a 44px box. They keep their native rendering and only take the accent. */
:where(input[type="checkbox"], input[type="radio"]) {
min-block-size: auto;
padding: 0;
border: 0;
border-radius: 0;
accent-color: var(--wp--custom--upline--accent, currentColor);
}
:where(input[type="search"]) {
-webkit-appearance: none;
appearance: none;
}
:where(select) {
-webkit-appearance: none;
appearance: none;
/* Room for the caret drawn below, on whichever side the language runs. */
padding-inline-end: calc(var(--wp--custom--upline--gap, 16px) * 2);
background-image: linear-gradient(45deg, transparent 50%, currentColor 50%),
linear-gradient(135deg, currentColor 50%, transparent 50%);
background-position: right 1.05em top 55%, right 0.75em top 55%;
background-size: 0.3em 0.3em, 0.3em 0.3em;
background-repeat: no-repeat;
}
:where(input, select, textarea)::placeholder {
color: var(--wp--custom--upline--muted, currentColor);
opacity: 1;
}
/* `details > summary` before any skin can draw its own +/−.
The marker is drawn two different ways depending on the engine — a
`list-item` display with a `::marker`, or WebKit's own
`::-webkit-details-marker` pseudo — so suppressing one leaves the other
rendering beside whatever the skin draws. All three declarations are the same
mechanism, and every skin needs all three before it can start: Ridgeline and
Slope each rediscovered it privately. `cursor` belongs here for the same
reason the tap floor does — a disclosure that does not look clickable is a
control the shopper does not find.
:where() keeps it at zero specificity: this clears the ground, it does not
decide what stands on it. */
:where(details > summary) {
list-style: none;
cursor: pointer;
}
:where(details > summary)::-webkit-details-marker {
display: none;
}
:where(details > summary)::marker {
content: "";
}
/* A