@bwui/css 0.0.0-stage → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,1460 @@
1
+ /* brickwork shell layout: app / auth / centred. Structure only; colour comes
2
+ * from the semantic tokens (theme-aware) and spacing from the density tokens.
3
+ * Logical CSS properties throughout (BR-BW-TOK-005), so RTL is handled by the
4
+ * `dir` attribute alone, no mirrored stylesheet. Nothing here needs JavaScript
5
+ * (BR-BW-HTMX-001): the sidebar toggle and mobile drawer are native <details>.
6
+ */
7
+
8
+ .bw-body {
9
+ margin: 0;
10
+ min-height: 100vh;
11
+ background: var(--bw-color-surface-sunken);
12
+ color: var(--bw-color-fg);
13
+ /* Consume the font tokens so a consumer rebrands typography token-first
14
+ (override --bw-font-family-sans) rather than reaching into these classes. */
15
+ font-family: var(--bw-font-family-sans);
16
+ font-size: var(--bw-font-size-md);
17
+ line-height: var(--bw-font-line-height-normal);
18
+ }
19
+
20
+ /* Branded text selection (0.7.0 craft): a 22% accent wash over whatever sits
21
+ * beneath, so selecting text feels like the product, not the UA default. The
22
+ * text keeps its own ink; fg measures 13.18:1 light / 10.71:1 dark over the
23
+ * composited wash on the surface, comfortably AA. */
24
+ .bw-body ::selection,
25
+ .bw-body::selection {
26
+ background-color: color-mix(in oklab, var(--bw-color-accent) 22%, transparent);
27
+ }
28
+
29
+ /* The stable modal swap target (BR-BW-HTMX-005): an empty container the
30
+ * shell ships for the htmx path's hx-target="#bw-modal-root". display:
31
+ * contents keeps it zero-footprint whether empty or holding the
32
+ * fixed-position modal, so an insertion never reflows the page
33
+ * (BR-BW-HTMX-009). */
34
+ #bw-modal-root {
35
+ display: contents;
36
+ }
37
+
38
+ /* The stable slide-over swap target (BR-BW-HTMX-005, 0.14.0, brickwork#55):
39
+ * a SEPARATE root from #bw-modal-root so a modal and a slide-over can be
40
+ * open at once. Same zero-footprint contract. */
41
+ #bw-slide-over-root {
42
+ display: contents;
43
+ }
44
+
45
+ /* --- App shell: sidebar + main column -------------------------------------- */
46
+
47
+ .bw-app {
48
+ display: grid;
49
+ grid-template-columns: var(--bw-density-sidebar-width) 1fr;
50
+ min-height: 100vh;
51
+ }
52
+
53
+ /* The collapsed column tracks the sidebar's own width so the grid narrows
54
+ * with it (SHL-003/004, brickwork#58); [data-bw-collapsed] lives on
55
+ * .bw-sidebar (set by bwSidebarCollapse), so this selector reaches up via
56
+ * :has() to retarget the OUTER grid template. Chromium/Firefox/Safari all
57
+ * support :has() as of this package's baseline; the graceful fallback with
58
+ * no :has() support is simply an un-narrowed main column beside a narrowed
59
+ * sidebar, a cosmetic gap only, never a functional break. */
60
+ /* Sidebar/topbar layouts only: regions mode owns its tracks via
61
+ * --bw-shell-sidebar-track (see [data-layout="regions"] below). */
62
+ .bw-app:not([data-layout="regions"]):has(.bw-sidebar[data-bw-collapsed]) {
63
+ grid-template-columns: var(--bw-density-sidebar-width-collapsed) 1fr;
64
+ }
65
+
66
+ /* Capability rail: sibling region for layout="regions" only (brickwork#700).
67
+ * Hidden in sidebar/topbar layouts so the default two-column shell stays
68
+ * byte-stable; regions mode turns it on and seats it beside the sidebar. */
69
+ .bw-rail {
70
+ display: none;
71
+ flex-direction: column;
72
+ background: var(--bw-color-surface);
73
+ border-inline-end: var(--bw-size-border-hairline) solid
74
+ color-mix(in oklab, var(--bw-color-fg) 14%, var(--bw-color-surface));
75
+ padding-block: var(--bw-space-2) var(--bw-density-stack-gap);
76
+ padding-inline: var(--bw-space-2);
77
+ inline-size: var(--bw-density-rail-width);
78
+ overflow: hidden;
79
+ }
80
+
81
+ .bw-rail__nav {
82
+ flex: 1 1 auto;
83
+ overflow-y: auto;
84
+ scrollbar-width: thin;
85
+ scrollbar-color: var(--bw-color-border) transparent;
86
+ }
87
+
88
+ /* Transparent in sidebar/topbar so subnav/breadcrumbs/workspace remain flex
89
+ * children of .bw-app__main (pre-#700 box tree). Regions mode promotes this
90
+ * to a real column under the full-width topbar. */
91
+ .bw-app__body {
92
+ display: contents;
93
+ }
94
+
95
+ .bw-sidebar {
96
+ display: flex;
97
+ flex-direction: column;
98
+ background: var(--bw-color-surface);
99
+ /* Stronger edge mix so the rail separates from a white workspace without
100
+ * touching nav link / active overlays (border only, no fill change). */
101
+ border-inline-end: var(--bw-size-border-hairline) solid
102
+ color-mix(in oklab, var(--bw-color-fg) 14%, var(--bw-color-surface));
103
+ /* space-2 at the top puts the first nav row on the topbar's centreline. */
104
+ padding-block: var(--bw-space-2) var(--bw-density-stack-gap);
105
+ padding-inline: var(--bw-space-3);
106
+ inline-size: var(--bw-density-sidebar-width);
107
+ transition: inline-size var(--bw-duration-normal) var(--bw-ease-standard);
108
+ }
109
+
110
+ /* --- Collapsed (icon-only) state (SHL-003/004, brickwork#58) --------------- */
111
+
112
+ /* [data-bw-collapsed] narrows the sidebar to the collapsed-width token and
113
+ * hides text labels while KEEPING every icon and every accessible name: the
114
+ * label text is visually hidden (.bw-visually-hidden's own clip technique),
115
+ * never aria-hidden or removed, so a screen reader still announces the full
116
+ * nav item name regardless of the visual collapse state (SHL-004's own
117
+ * "narrows, hides text, keeps icons" contract). */
118
+ .bw-sidebar[data-bw-collapsed] {
119
+ inline-size: var(--bw-density-sidebar-width-collapsed);
120
+ }
121
+ .bw-sidebar[data-bw-collapsed] .bw-nav__label,
122
+ .bw-sidebar[data-bw-collapsed] .bw-nav__badge,
123
+ .bw-sidebar[data-bw-collapsed] .bw-nav__external,
124
+ .bw-sidebar[data-bw-collapsed] .bw-sidebar__switcher,
125
+ .bw-sidebar[data-bw-collapsed] .bw-sidebar__footer,
126
+ .bw-sidebar[data-bw-collapsed] .bw-sidebar__brand-wordmark {
127
+ position: absolute;
128
+ inline-size: var(--bw-space-px);
129
+ block-size: var(--bw-space-px);
130
+ margin: calc(var(--bw-space-px) * -1);
131
+ padding: 0;
132
+ overflow: hidden;
133
+ clip-path: inset(50%);
134
+ white-space: nowrap;
135
+ border: 0;
136
+ }
137
+ /* The nav row centres its icon once the label collapses out of flow (the
138
+ * label's own flex:1 auto no longer exists to push things, but the row
139
+ * still reserves label space via its own layout unless re-centred). */
140
+ .bw-sidebar[data-bw-collapsed] .bw-nav__link,
141
+ .bw-sidebar[data-bw-collapsed] .bw-nav__link--disabled {
142
+ justify-content: center;
143
+ }
144
+ /* Section headers read as pure text with no icon; collapsing them to
145
+ * clipped text would leave an empty, confusing row, so the whole header
146
+ * hides (its accessible name is redundant with the icon-only items below it
147
+ * once collapsed, unlike a nav link whose name IS the destination). */
148
+ .bw-sidebar[data-bw-collapsed] .bw-nav__section-label {
149
+ display: none;
150
+ }
151
+ /* Nested (child) lists never show icon-only: a collapsed sidebar has no
152
+ * room to indicate hierarchy with icons alone, so submenus simply do not
153
+ * render open in the collapsed rail (consistent with SHL-004: this package
154
+ * ships no flyout-on-hover mechanism; a consumer wanting one composes
155
+ * bw_dropdown per nav item, its own template work). */
156
+ .bw-sidebar[data-bw-collapsed] .bw-nav__list--nested {
157
+ display: none;
158
+ }
159
+ @media (prefers-reduced-motion: reduce) {
160
+ .bw-sidebar {
161
+ transition: none;
162
+ }
163
+ }
164
+
165
+ .bw-sidebar__header {
166
+ display: flex;
167
+ align-items: center;
168
+ gap: var(--bw-space-2);
169
+ padding-inline: var(--bw-space-2);
170
+ padding-block-end: var(--bw-density-stack-gap);
171
+ }
172
+
173
+ /* The brand wrappers (app.html) give the collapsed rail a stable element to
174
+ * hide (the wordmark) and one to keep (the mark), independent of the
175
+ * consumer's own inner markup or classes. They are inline-flex so they sit in
176
+ * the header's flex row exactly where the bare blocks did (the consumer's
177
+ * inner anchor/mark/text is unchanged); an unfilled block leaves an :empty
178
+ * wrapper, which takes no space. Note: NOT `display: contents` here, because
179
+ * the collapsed rule below clips the wordmark via position/clip-path, which a
180
+ * box-less `display: contents` element cannot honour. */
181
+ .bw-sidebar__brand-mark,
182
+ .bw-sidebar__brand-wordmark {
183
+ display: inline-flex;
184
+ align-items: center;
185
+ }
186
+ .bw-sidebar__brand-mark:empty,
187
+ .bw-sidebar__brand-wordmark:empty {
188
+ display: none;
189
+ }
190
+
191
+ /* The collapse toggle seats at the row end regardless of whether
192
+ * brand_logo/brand_wordmark are filled (brickwork#58). */
193
+ .bw-sidebar__toggle {
194
+ margin-inline-start: auto;
195
+ flex-shrink: 0;
196
+ }
197
+ /* Collapsed: the wordmark clips like the nav labels above (SHL-004), but the
198
+ * MARK stays visible (brickwork#93: an icon-only rail keeps its brand mark,
199
+ * the standard collapsed-sidebar affordance), so the header centres the
200
+ * remaining mark and toggle instead of pinning the toggle to a now-empty
201
+ * end. The mark wrapper needs no collapsed override: it keeps its base
202
+ * inline-flex box and simply is not in the clip group above. */
203
+ .bw-sidebar[data-bw-collapsed] .bw-sidebar__toggle {
204
+ margin-inline-start: 0;
205
+ }
206
+ .bw-sidebar[data-bw-collapsed] .bw-sidebar__header {
207
+ justify-content: center;
208
+ }
209
+
210
+ /* The nav slot (brickwork#21, BR-BW-NAV-007): a quiet, positioned seat for a
211
+ consumer-authored switcher above the nav list, shared by the sidebar and
212
+ the mobile drawer (one class, both containers, mirroring the nav's own one
213
+ render). Structure and spacing only, never switcher behaviour; the gap to
214
+ the nav below is the density section gap so a consumer never guesses it.
215
+ Inline padding matches the sidebar header's inset so slot content aligns
216
+ with the rows above and below. */
217
+ .bw-sidebar__switcher {
218
+ padding-inline: var(--bw-space-2);
219
+ padding-block: var(--bw-space-2);
220
+ margin-block-end: var(--bw-density-section-gap);
221
+ border-block-end: var(--bw-size-border-hairline) solid var(--bw-color-border);
222
+ }
223
+
224
+ .bw-sidebar__nav {
225
+ flex: 1 1 auto;
226
+ overflow-y: auto;
227
+ /* Thin, border-toned scrollbar (0.7.0 craft): navigation chrome scrolls
228
+ * quietly instead of hoisting the UA's full-width gutter. Decorative. */
229
+ scrollbar-width: thin;
230
+ scrollbar-color: var(--bw-color-border) transparent;
231
+ }
232
+
233
+ .bw-sidebar__footer {
234
+ padding-block-start: var(--bw-density-stack-gap);
235
+ border-block-start: var(--bw-size-border-hairline) solid var(--bw-color-border);
236
+ }
237
+
238
+ .bw-app__main {
239
+ display: flex;
240
+ flex-direction: column;
241
+ min-width: 0; /* let the workspace shrink rather than force overflow */
242
+ }
243
+
244
+ /* flex-wrap (icvoss/django-brickwork#209): the drawer trigger, search,
245
+ * notifications and account cluster are all fixed-content flex children
246
+ * with no shrink floor of their own; a long account label (a real
247
+ * consumer's name/email, not the short "Account" default) pushes the row
248
+ * past a narrow viewport with nowhere to give, scrolling the whole page
249
+ * sideways. Wrapping lets the account cluster (and notifications, if
250
+ * present) drop to a second row instead, the same fix shape #125 used for
251
+ * the marketing header. */
252
+ .bw-topbar {
253
+ display: flex;
254
+ flex-wrap: wrap;
255
+ align-items: center;
256
+ gap: var(--bw-space-3);
257
+ padding-inline: var(--bw-density-page-gutter-inline);
258
+ min-block-size: var(--bw-density-topbar-height);
259
+ background: var(--bw-color-surface);
260
+ border-block-end: var(--bw-size-border-hairline) solid var(--bw-color-border);
261
+ /* Light elev-1 + soft ambient so sticky chrome reads on a white canvas. */
262
+ box-shadow:
263
+ var(--bw-elevation-1),
264
+ 0 4px 14px -4px oklch(0 0 0 / 0.1);
265
+ position: var(--bw-component-topbar-position);
266
+ inset-block-start: 0;
267
+ z-index: var(--bw-z-sticky);
268
+ }
269
+
270
+ .bw-topbar__spacer {
271
+ flex: 1 1 auto;
272
+ }
273
+
274
+ .bw-topbar__search {
275
+ flex: 1 1 18rem;
276
+ min-inline-size: 0;
277
+ max-inline-size: 42rem;
278
+ }
279
+
280
+ /* The account cluster is the widest fixed-content item on the row (icon +
281
+ * label + caret, and a real consumer's name/email can be long); it must not
282
+ * be forced to shrink below its own content, which is exactly what pushed
283
+ * the row past the viewport at #209's narrow widths. flex-shrink: 0 lets
284
+ * flex-wrap do the work instead of the item compressing into an unreadable
285
+ * sliver first. */
286
+ .bw-topbar__notifications,
287
+ .bw-topbar__account {
288
+ flex-shrink: 0;
289
+ }
290
+
291
+ .bw-workspace {
292
+ flex: 1 1 auto;
293
+ padding: var(--bw-density-stack-gap) var(--bw-density-page-gutter-inline);
294
+ outline: none; /* focus ring on the skip-link target is handled by :focus-visible */
295
+ }
296
+
297
+ .bw-content {
298
+ max-inline-size: var(--bw-component-content-max-width);
299
+ margin-inline: auto; /* centres the column when --bw-component-content-max-width is finite */
300
+ }
301
+
302
+ /* --- Content typography floor ---------------------------------------------- */
303
+
304
+ /* Unclassed consumer markup inside .bw-content gets designed defaults instead
305
+ * of UA styles, so "our defaults are beautiful" holds for content, not just
306
+ * chrome. :not([class]) keeps every bw-* component out of scope; :where()
307
+ * keeps specificity at the bare .bw-content class so consumer CSS still wins.
308
+ * Roles are theme-aware tokens, so both themes resolve correctly.
309
+ *
310
+ * htmx lifecycle classes (interactions-2, 0.9.0): htmx stamps exactly one of
311
+ * htmx-added / htmx-settling / htmx-swapping onto an otherwise-unclassed
312
+ * swapped-in element during its transition window, which makes :not([class])
313
+ * stop matching mid-settle and the UA default margins flip back in (a CLS
314
+ * bounce on every swap into classless prose). [class="htmx-<x>"] is an EXACT
315
+ * attribute match, so it only ever matches an element carrying that one
316
+ * lifecycle class and nothing else; a real author class alongside it still
317
+ * falls outside :where() here, exactly as :not([class]) already excludes one. */
318
+ .bw-content
319
+ :where(
320
+ h1:not([class]),
321
+ h1[class="htmx-added"],
322
+ h1[class="htmx-settling"],
323
+ h1[class="htmx-swapping"]
324
+ ) {
325
+ font-family: var(--bw-text-heading-xl-family);
326
+ font-size: var(--bw-text-heading-xl-size);
327
+ font-weight: var(--bw-text-heading-xl-weight);
328
+ line-height: var(--bw-text-heading-xl-line-height);
329
+ letter-spacing: var(--bw-text-heading-xl-tracking);
330
+ margin-block: 0 var(--bw-space-4);
331
+ }
332
+ .bw-content
333
+ :where(
334
+ h2:not([class]),
335
+ h2[class="htmx-added"],
336
+ h2[class="htmx-settling"],
337
+ h2[class="htmx-swapping"]
338
+ ) {
339
+ font-family: var(--bw-text-heading-lg-family);
340
+ font-size: var(--bw-text-heading-lg-size);
341
+ font-weight: var(--bw-text-heading-lg-weight);
342
+ line-height: var(--bw-text-heading-lg-line-height);
343
+ letter-spacing: var(--bw-text-heading-lg-tracking);
344
+ margin-block: var(--bw-density-section-gap) var(--bw-space-3);
345
+ }
346
+ .bw-content
347
+ :where(
348
+ h3:not([class]),
349
+ h3[class="htmx-added"],
350
+ h3[class="htmx-settling"],
351
+ h3[class="htmx-swapping"]
352
+ ) {
353
+ font-family: var(--bw-text-heading-md-family);
354
+ font-size: var(--bw-text-heading-md-size);
355
+ font-weight: var(--bw-text-heading-md-weight);
356
+ line-height: var(--bw-text-heading-md-line-height);
357
+ margin-block: var(--bw-space-6) var(--bw-space-2);
358
+ }
359
+ .bw-content
360
+ :where(
361
+ h4:not([class]), h5:not([class]), h6:not([class]),
362
+ h4[class="htmx-added"], h5[class="htmx-added"], h6[class="htmx-added"],
363
+ h4[class="htmx-settling"], h5[class="htmx-settling"], h6[class="htmx-settling"],
364
+ h4[class="htmx-swapping"], h5[class="htmx-swapping"], h6[class="htmx-swapping"]
365
+ ) {
366
+ font-family: var(--bw-text-heading-sm-family);
367
+ font-size: var(--bw-text-heading-sm-size);
368
+ font-weight: var(--bw-text-heading-sm-weight);
369
+ line-height: var(--bw-text-heading-sm-line-height);
370
+ margin-block: var(--bw-space-4) var(--bw-space-2);
371
+ }
372
+ .bw-content
373
+ :where(
374
+ p:not([class]),
375
+ p[class="htmx-added"],
376
+ p[class="htmx-settling"],
377
+ p[class="htmx-swapping"]
378
+ ) {
379
+ font-size: var(--bw-text-body-md-size);
380
+ line-height: var(--bw-text-body-md-line-height);
381
+ margin-block: 0 var(--bw-space-3);
382
+ max-inline-size: var(--bw-size-max-width-prose);
383
+ }
384
+ .bw-content
385
+ :where(
386
+ ul:not([class]), ol:not([class]),
387
+ ul[class="htmx-added"], ol[class="htmx-added"],
388
+ ul[class="htmx-settling"], ol[class="htmx-settling"],
389
+ ul[class="htmx-swapping"], ol[class="htmx-swapping"]
390
+ ) {
391
+ margin-block: 0 var(--bw-space-3);
392
+ padding-inline-start: var(--bw-space-5);
393
+ max-inline-size: var(--bw-size-max-width-prose);
394
+ }
395
+ .bw-content
396
+ :where(
397
+ ul:not([class]), ol:not([class]),
398
+ ul[class="htmx-added"], ol[class="htmx-added"],
399
+ ul[class="htmx-settling"], ol[class="htmx-settling"],
400
+ ul[class="htmx-swapping"], ol[class="htmx-swapping"]
401
+ )
402
+ :where(li)::marker {
403
+ color: var(--bw-color-fg-subtle); /* decorative; adjacent text carries meaning */
404
+ }
405
+
406
+ .bw-page-header-region {
407
+ display: flex;
408
+ align-items: flex-start;
409
+ justify-content: space-between;
410
+ gap: var(--bw-space-4);
411
+ margin-block-end: var(--bw-density-section-gap);
412
+ }
413
+
414
+ /* --- Page patterns (0.5.0): composition scaffolding only -------------------- */
415
+
416
+ /* The dashboard stat row (patterns/dashboard.html): a responsive auto-fit
417
+ grid the consumer drops _stat.html includes into, section-gap-spaced per
418
+ the pattern contract (04-interfaces.md 4a). 14rem is the structural floor
419
+ below which a tabular-numeral tile stops reading as a tile; min() keeps a
420
+ single column on viewports narrower than one tile. */
421
+ .bw-stat-grid {
422
+ display: grid;
423
+ grid-template-columns: repeat(auto-fit, minmax(min(14rem, 100%), 1fr));
424
+ gap: var(--bw-density-section-gap);
425
+ }
426
+
427
+ /* The detail section stack (patterns/detail.html): section-gap between
428
+ sibling cards, no other opinion (the pattern imposes no count or shape). */
429
+ .bw-section-stack {
430
+ display: grid;
431
+ gap: var(--bw-density-section-gap);
432
+ }
433
+ /* A grid item's default min-inline-size is auto, not 0: without this on every
434
+ * direct child, a wide child (a .bw-card wrapping a data table scroll wrap)
435
+ * refuses to shrink below its content width, blows out the track, and the
436
+ * scroll container inside never gets a constrained width to scroll within
437
+ * (icvoss/django-brickwork#136). */
438
+ .bw-section-stack > * {
439
+ min-inline-size: 0;
440
+ }
441
+
442
+ /* The app-surface N-column arrangement primitive (icvoss/django-brickwork#399,
443
+ ruling on #371 gap 3): before this, an app-surface page could express a
444
+ vertical stack of full-width bands and nothing else. Two ranked lists side
445
+ by side is the motivating case (#371).
446
+
447
+ Deliberately NOT `bw-feature-grid`/`bw-media-text`/`bw-listing-list__item`,
448
+ which ship in the same `brickwork.css` bundle and would work mechanically:
449
+ those are marketing-family, styled for marketing surfaces and restyled for
450
+ marketing reasons, so permitting them here would make a marketing visual
451
+ change silently an app-surface regression. `bw-band-grid` is the app
452
+ family's own primitive; `tests/test_family_boundary.py` is the check that
453
+ keeps marketing-family classes out of app-surface templates.
454
+
455
+ Same auto-fit idiom as `.bw-stat-grid` above: `minmax(min(X, 100%), 1fr)`
456
+ keeps a single column on viewports narrower than one tile. The floor
457
+ widens as the explicit column count drops, so a 2-up pair of ranked lists
458
+ does not fragment into four narrow columns on a wide viewport: the bare
459
+ class and `--2` share a 24rem floor (two comfortable reading-width
460
+ columns), `--3` steps to 18rem, and `--4` reuses `.bw-stat-grid`'s own
461
+ 14rem floor, below which a tile stops reading as a tile. */
462
+ .bw-band-grid,
463
+ .bw-band-grid--2 {
464
+ display: grid;
465
+ grid-template-columns: repeat(auto-fit, minmax(min(24rem, 100%), 1fr));
466
+ gap: var(--bw-density-section-gap);
467
+ }
468
+ .bw-band-grid--3 {
469
+ display: grid;
470
+ grid-template-columns: repeat(auto-fit, minmax(min(18rem, 100%), 1fr));
471
+ gap: var(--bw-density-section-gap);
472
+ }
473
+ .bw-band-grid--4 {
474
+ display: grid;
475
+ grid-template-columns: repeat(auto-fit, minmax(min(14rem, 100%), 1fr));
476
+ gap: var(--bw-density-section-gap);
477
+ }
478
+ /* Same trap, same guard, same fix as .bw-section-stack above
479
+ * (icvoss/django-brickwork#136): a grid item's default min-inline-size is
480
+ * auto, not 0, so a wide child refuses to shrink below its content width,
481
+ * blows out the track, and an inner scroll container never gets a
482
+ * constrained width to scroll within. */
483
+ .bw-band-grid > *,
484
+ .bw-band-grid--2 > *,
485
+ .bw-band-grid--3 > *,
486
+ .bw-band-grid--4 > * {
487
+ min-inline-size: 0;
488
+ }
489
+
490
+ /* An unfilled pattern region renders nothing, never empty chrome or a stray
491
+ gap (BR-BW-TPL-006). */
492
+ .bw-stat-grid:empty,
493
+ .bw-section-stack:empty,
494
+ .bw-band-grid:empty,
495
+ .bw-band-grid--2:empty,
496
+ .bw-band-grid--3:empty,
497
+ .bw-band-grid--4:empty {
498
+ display: none;
499
+ }
500
+
501
+ .bw-footer {
502
+ margin-block-start: var(--bw-density-section-gap);
503
+ padding-block-start: var(--bw-space-4);
504
+ padding-block-end: var(--bw-space-6);
505
+ border-block-start: var(--bw-size-border-hairline) solid var(--bw-color-border);
506
+ color: var(--bw-color-fg-muted);
507
+ font-family: var(--bw-text-caption-family);
508
+ font-size: var(--bw-text-caption-size);
509
+ line-height: var(--bw-text-caption-line-height);
510
+ font-weight: var(--bw-text-caption-weight);
511
+ letter-spacing: var(--bw-text-caption-tracking);
512
+ }
513
+
514
+ .bw-subnav:empty,
515
+ .bw-breadcrumbs:empty,
516
+ .bw-footer:empty,
517
+ .bw-page-actions:empty,
518
+ .bw-sidebar__header:empty,
519
+ .bw-sidebar__footer:empty,
520
+ .bw-sidebar__switcher:empty {
521
+ display: none; /* empty blocks render nothing, never a placeholder (SHL-006/20, AC-BW-078) */
522
+ }
523
+
524
+ /* Breadcrumbs list (#25): the <ol> inside the shell's labelled bw-breadcrumbs
525
+ <nav>. A "/" separator is drawn before every item except the first, via a
526
+ pseudo-element. Pseudo-element content IS read by some screen readers, so the
527
+ alternative-text form (content: "/" / "") gives it an empty accessible name.
528
+ Logical properties for RTL. */
529
+ .bw-breadcrumbs {
530
+ /* Align the crumbs with the page title's gutter below and clear the topbar
531
+ border above; the :empty rule keeps hidden breadcrumbs paddingless. */
532
+ padding-inline: var(--bw-density-page-gutter-inline);
533
+ padding-block: var(--bw-space-4) 0;
534
+ }
535
+ /* Crumbs are context for the title: when breadcrumbs render, tighten the
536
+ workspace's top padding so the crumbs bind to the title (16/8 rhythm), not
537
+ to the topbar. Graceful no-op in engines without :has(). */
538
+ .bw-app__main:has(.bw-breadcrumbs:not(:empty)) .bw-workspace {
539
+ padding-block-start: var(--bw-space-2);
540
+ }
541
+ .bw-breadcrumbs__list {
542
+ display: flex;
543
+ flex-wrap: wrap;
544
+ align-items: center;
545
+ gap: var(--bw-space-2);
546
+ margin: 0;
547
+ padding: 0;
548
+ list-style: none;
549
+ font-size: var(--bw-text-body-sm-size);
550
+ line-height: var(--bw-text-body-sm-line-height);
551
+ }
552
+ .bw-breadcrumbs__item {
553
+ display: inline-flex;
554
+ align-items: center;
555
+ gap: var(--bw-space-2);
556
+ }
557
+ .bw-breadcrumbs__item + .bw-breadcrumbs__item::before {
558
+ content: "/" / "";
559
+ color: var(--bw-component-breadcrumb-separator);
560
+ }
561
+ /* Two-tier target size (icvoss/django-brickwork#208, then #242): a
562
+ * breadcrumb is a navigational control, not inline prose, so WCAG 2.5.8's
563
+ * text-run exception does not apply; the crumb was sized to its line-height
564
+ * alone (21px at 375px). The AA floor here is min-block-size: 1.5rem
565
+ * (24px), unconditional. #242 adds a coarse-pointer-only 44px tier below,
566
+ * the WCAG 2.5.5/platform-HIG bar, above what the package's AA claim
567
+ * requires; align-items keeps the crumb centred, so a fine-pointer desktop
568
+ * click never sees the larger target and the trail's layout does not shift
569
+ * there. */
570
+ .bw-breadcrumbs__link {
571
+ display: inline-flex;
572
+ align-items: center;
573
+ min-block-size: 1.5rem;
574
+ color: var(--bw-color-fg-muted);
575
+ text-decoration: none;
576
+ transition: var(--bw-transition-colors);
577
+ }
578
+ .bw-breadcrumbs__link:hover {
579
+ color: var(--bw-color-accent);
580
+ text-decoration: underline;
581
+ }
582
+
583
+ @media (pointer: coarse) {
584
+ .bw-breadcrumbs__link {
585
+ min-block-size: var(--bw-size-touch-target-min);
586
+ }
587
+ }
588
+ .bw-breadcrumbs__text {
589
+ color: var(--bw-color-fg-muted);
590
+ }
591
+ .bw-breadcrumbs__current {
592
+ color: var(--bw-component-breadcrumb-current);
593
+ font-weight: var(--bw-font-weight-medium);
594
+ }
595
+
596
+ /* --- Native <details> drawer for mobile nav (no JS, SHL-015/016) ----------- */
597
+
598
+ .bw-drawer {
599
+ display: none; /* shown only at the mobile breakpoint */
600
+ }
601
+ .bw-drawer__trigger {
602
+ display: inline-flex;
603
+ align-items: center;
604
+ justify-content: center;
605
+ padding: var(--bw-space-2);
606
+ border-radius: var(--bw-radius-md);
607
+ min-block-size: var(--bw-size-touch-target-min);
608
+ min-inline-size: var(--bw-size-touch-target-min);
609
+ cursor: pointer;
610
+ list-style: none;
611
+ transition: var(--bw-transition-colors);
612
+ }
613
+ .bw-drawer__trigger:hover {
614
+ background-color: var(--bw-state-hover-overlay);
615
+ }
616
+ .bw-drawer__trigger::-webkit-details-marker {
617
+ display: none;
618
+ }
619
+ .bw-drawer__panel {
620
+ position: absolute;
621
+ inset-block-start: var(--bw-density-topbar-height); /* sits flush under the topbar */
622
+ inset-inline-start: 0;
623
+ inline-size: var(--bw-component-drawer-width);
624
+ background: var(--bw-color-surface-raised);
625
+ border-inline-end: var(--bw-size-border-hairline) solid var(--bw-color-border);
626
+ box-shadow: var(--bw-elevation-4);
627
+ padding: var(--bw-density-stack-gap) var(--bw-space-3);
628
+ z-index: var(--bw-z-drawer);
629
+ }
630
+
631
+ /* --- Shared site chrome (ADR-113 / BR-BW-TPL-008) --------------------------
632
+ * Family-neutral header/footer band and measure. Canonical classes are
633
+ * .bw-site-*. The marketing shell emits these names only (4.0.0 closed the
634
+ * dual-class marketing alias window). Docs and other non-marketing surfaces
635
+ * include _site_header.html / _site_footer.html and wear .bw-site-* only
636
+ * (ADR-090). Overlay (ADR-105) stays in marketing.css. App / auth / centred
637
+ * shells do not compose this chrome by default.
638
+ */
639
+
640
+ .bw-site-header {
641
+ background: var(--bw-color-surface);
642
+ border-block-end: var(--bw-size-border-hairline) solid var(--bw-color-border);
643
+ box-shadow:
644
+ var(--bw-elevation-1),
645
+ 0 4px 14px -4px oklch(0 0 0 / 0.1);
646
+ position: sticky;
647
+ inset-block-start: 0;
648
+ z-index: var(--bw-z-sticky);
649
+ }
650
+
651
+ .bw-site-header__inner {
652
+ max-inline-size: var(--bw-component-content-max-width-marketing);
653
+ margin-inline: auto;
654
+ padding-inline: var(--bw-density-page-gutter-inline);
655
+ padding-block: var(--bw-space-3);
656
+ }
657
+
658
+ .bw-site-header__brand {
659
+ display: flex;
660
+ flex-wrap: wrap;
661
+ align-items: center;
662
+ gap: var(--bw-space-2) var(--bw-space-6);
663
+ position: relative;
664
+ }
665
+
666
+ .bw-site-header__brand-mark,
667
+ .bw-site-header__brand-wordmark {
668
+ display: inline-flex;
669
+ align-items: center;
670
+ flex: 0 0 auto;
671
+ }
672
+
673
+ .bw-site-header__brand-mark:empty,
674
+ .bw-site-header__brand-wordmark:empty {
675
+ display: none;
676
+ }
677
+
678
+ .bw-site-header__brand-mark :where(img, svg),
679
+ .bw-site-header__brand-wordmark :where(img, svg) {
680
+ block-size: var(--bw-component-logo-height);
681
+ inline-size: auto;
682
+ }
683
+
684
+ .bw-site-header__nav {
685
+ display: flex;
686
+ flex-wrap: wrap;
687
+ align-items: center;
688
+ gap: var(--bw-space-4);
689
+ flex: 1 1 auto;
690
+ min-inline-size: 0;
691
+ }
692
+
693
+ .bw-site-header__nav:empty {
694
+ display: none;
695
+ }
696
+
697
+ .bw-site-header__nav :where(a):not(.bw-btn) {
698
+ display: inline-flex;
699
+ align-items: center;
700
+ min-block-size: 1.5rem;
701
+ color: var(--bw-color-fg-muted);
702
+ font-size: var(--bw-text-label-size);
703
+ font-weight: var(--bw-text-label-weight);
704
+ text-decoration: none;
705
+ transition: var(--bw-transition-colors);
706
+ }
707
+
708
+ .bw-site-header__nav :where(a:hover):not(.bw-btn) {
709
+ color: var(--bw-color-fg);
710
+ }
711
+
712
+ @media (pointer: coarse) {
713
+ .bw-site-header__nav :where(a):not(.bw-btn) {
714
+ min-block-size: var(--bw-size-touch-target-min);
715
+ }
716
+ }
717
+
718
+ .bw-site-header__actions {
719
+ display: flex;
720
+ flex-wrap: wrap;
721
+ align-items: center;
722
+ justify-content: flex-end;
723
+ gap: var(--bw-space-2);
724
+ }
725
+
726
+ .bw-site-header__actions:empty {
727
+ display: none;
728
+ }
729
+
730
+ .bw-site-header__actions > :where(a):not(.bw-btn) {
731
+ display: inline-flex;
732
+ align-items: center;
733
+ min-block-size: 1.5rem;
734
+ color: var(--bw-color-fg-muted);
735
+ font-size: var(--bw-text-label-size);
736
+ font-weight: var(--bw-text-label-weight);
737
+ text-decoration: none;
738
+ transition: var(--bw-transition-colors);
739
+ }
740
+
741
+ .bw-site-header__actions > :where(a:hover):not(.bw-btn) {
742
+ color: var(--bw-color-fg);
743
+ }
744
+
745
+ @media (pointer: coarse) {
746
+ .bw-site-header__actions > :where(a):not(.bw-btn) {
747
+ min-block-size: var(--bw-size-touch-target-min);
748
+ }
749
+ }
750
+
751
+ @media (width >= --theme(--breakpoint-lg)) {
752
+ .bw-site-header__brand {
753
+ flex-wrap: nowrap;
754
+ }
755
+ }
756
+
757
+ .bw-site-footer {
758
+ border-block-start: var(--bw-size-border-hairline) solid var(--bw-color-border);
759
+ background: var(--bw-color-surface-sunken);
760
+ margin-block-start: auto;
761
+ }
762
+
763
+ .bw-site-footer__inner {
764
+ max-inline-size: var(--bw-component-content-max-width-marketing);
765
+ margin-inline: auto;
766
+ padding-inline: var(--bw-density-page-gutter-inline);
767
+ padding-block: var(--bw-space-8) var(--bw-space-4);
768
+ }
769
+
770
+ .bw-site-footer__inner :where(a):not(.bw-btn) {
771
+ display: inline-flex;
772
+ align-items: center;
773
+ min-block-size: 1.5rem;
774
+ color: var(--bw-color-fg-muted);
775
+ text-decoration: none;
776
+ transition: var(--bw-transition-colors);
777
+ }
778
+
779
+ .bw-site-footer__inner :where(a:hover):not(.bw-btn) {
780
+ color: var(--bw-color-fg);
781
+ }
782
+
783
+ @media (pointer: coarse) {
784
+ .bw-site-footer__inner :where(a):not(.bw-btn) {
785
+ min-block-size: var(--bw-size-touch-target-min);
786
+ }
787
+ }
788
+
789
+ .bw-site-footer__legal {
790
+ margin-block-start: var(--bw-space-6);
791
+ padding-block-start: var(--bw-space-4);
792
+ border-block-start: var(--bw-size-border-hairline) solid var(--bw-color-border);
793
+ color: var(--bw-color-fg-muted);
794
+ font-size: var(--bw-text-caption-size);
795
+ line-height: var(--bw-text-caption-line-height);
796
+ }
797
+
798
+ .bw-site-footer__legal:empty {
799
+ display: none;
800
+ }
801
+
802
+ .bw-site-footer:has(.bw-site-footer__legal:only-child:empty) {
803
+ display: none;
804
+ }
805
+
806
+ [data-theme="dark"] .bw-site-header {
807
+ box-shadow: var(--bw-elevation-1);
808
+ }
809
+
810
+ /* --- Docs shell: [article | rail] two-column layout (ADR-091, #439) ------- */
811
+
812
+ /* Site-chrome column (icvoss/django-brickwork#448 item 1): .bw-docs-shell
813
+ * wraps the whole shell (docs_site_header_region, <main class="bw-docs">,
814
+ * docs_site_footer_region) in a flex column at min-block-size: 100vh, the
815
+ * docs-family counterpart of .bw-marketing's own role for the marketing
816
+ * shell. A DIFFERENT class name deliberately: tests/test_family_boundary.py
817
+ * forbids a marketing-family class (one marketing.css itself defines a rule
818
+ * for) from appearing in a non-marketing-family shell, so this rule and
819
+ * .bw-marketing's are independent, coincidentally identical declarations
820
+ * rather than a shared class. flex: 1 1 auto on <main class="bw-docs"> below
821
+ * makes it the column's one growing member, and docs_site_footer_region's
822
+ * <footer class="bw-docs-site-footer"> takes margin-block-start: auto (the
823
+ * same mechanism as .bw-marketing-footer), so a short docs page still pins
824
+ * its site footer to the viewport bottom instead of floating it mid-page.
825
+ * With docs_site_header/docs_site_footer both unfilled the two <header>/
826
+ * <footer> elements collapse via the :empty rule below, so this wrapper
827
+ * changes nothing visible for an existing 3.15.0 consumer. */
828
+ .bw-docs-shell {
829
+ display: flex;
830
+ flex-direction: column;
831
+ min-block-size: 100vh;
832
+ }
833
+
834
+ .bw-docs-site-header:empty,
835
+ .bw-docs-site-footer:empty {
836
+ display: none;
837
+ }
838
+
839
+ .bw-docs-site-header {
840
+ display: flex;
841
+ align-items: center;
842
+ gap: var(--bw-space-4);
843
+ padding-inline: var(--bw-density-page-gutter-inline);
844
+ padding-block: var(--bw-space-3);
845
+ border-block-end: var(--bw-size-border-hairline) solid var(--bw-color-border);
846
+ background: var(--bw-color-surface);
847
+ }
848
+
849
+ /* Brand mark and search in docs_site_header (Beat S7 craft): the header is a
850
+ * flex row; brand stays put, search claims the remaining inline space so the
851
+ * control stays discoverable at every viewport without a Plus-shaped chrome
852
+ * redesign. max-inline-size keeps a wide monitor from stretching the input
853
+ * into a full-bleed bar. */
854
+ .bw-docs-site-header__brand {
855
+ flex: 0 0 auto;
856
+ color: var(--bw-color-fg);
857
+ font-family: var(--bw-font-family-display);
858
+ font-weight: var(--bw-font-weight-semibold);
859
+ text-decoration: none;
860
+ }
861
+
862
+ .bw-docs-site-header .bw-search {
863
+ flex: 1 1 12rem;
864
+ max-inline-size: 28rem;
865
+ margin-inline-start: auto;
866
+ }
867
+
868
+ .bw-docs-site-footer {
869
+ margin-block-start: auto;
870
+ }
871
+
872
+ /* A bare <a> in docs_site_header/docs_site_footer takes themed ink, never
873
+ * the UA default blue, the same contrast defect .bw-docs-layout__footer's
874
+ * own rule fixes below and for the same reason: a consumer's site chrome is
875
+ * arbitrary markup, and a plain anchor is the obvious thing to write in a
876
+ * site nav or footer link list. Written at zero specificity via :where() so
877
+ * a consumer's own class wins without !important. :not(.bw-btn) excludes a
878
+ * bw_button composed into either slot, matching every other bare-link rule
879
+ * in this file. The 1.5rem floor is the WCAG 2.5.8 AA target size
880
+ * (icvoss/django-brickwork#208) and the coarse-pointer tier below is
881
+ * 2.5.5/platform-HIG (icvoss/django-brickwork#242). */
882
+ .bw-docs-site-header :where(a):not(.bw-btn),
883
+ .bw-docs-site-footer :where(a):not(.bw-btn) {
884
+ display: inline-flex;
885
+ align-items: center;
886
+ min-block-size: 1.5rem;
887
+ color: var(--bw-color-fg-muted);
888
+ text-decoration: none;
889
+ transition: var(--bw-transition-colors);
890
+ }
891
+
892
+ .bw-docs-site-header :where(a:hover):not(.bw-btn),
893
+ .bw-docs-site-footer :where(a:hover):not(.bw-btn) {
894
+ color: var(--bw-color-fg);
895
+ }
896
+
897
+ @media (pointer: coarse) {
898
+ .bw-docs-site-header :where(a):not(.bw-btn),
899
+ .bw-docs-site-footer :where(a):not(.bw-btn) {
900
+ min-block-size: var(--bw-size-touch-target-min);
901
+ }
902
+ }
903
+
904
+ /* .bw-docs is the shell's own <main>; the layout root .bw-docs-layout is a
905
+ * SINGLE DIRECT CHILD of it, so the shell can apply the content measure,
906
+ * inline centring, and page gutter to the whole layout once rather than each
907
+ * column claiming it independently (carried from the consumer's own
908
+ * main.css:930-933, ADR-091 decision 4). flex: 1 1 auto makes it the
909
+ * .bw-docs-shell column's one growing member (icvoss/django-brickwork#448
910
+ * item 1), the same role .bw-marketing__content plays inside .bw-marketing.
911
+ *
912
+ * inline-size: 100% is load-bearing under the column flex parent
913
+ * (icvoss/django-brickwork#668): without it, auto margin-inline on a flex
914
+ * item sizes the item fit-content, so pages with different longest lines
915
+ * render .bw-docs at different widths and the rail/article jump sideways
916
+ * when navigating. The auto margins then only centre within the measure. */
917
+ .bw-docs {
918
+ display: block;
919
+ flex: 1 1 auto;
920
+ inline-size: 100%;
921
+ max-inline-size: var(--bw-component-content-max-width-marketing);
922
+ margin-inline: auto;
923
+ padding-inline: var(--bw-density-page-gutter-inline);
924
+ padding-block: var(--bw-density-section-gap);
925
+ }
926
+
927
+ /* Mobile-first: the BASE (narrow, < --bw-breakpoint-lg) layout is a single
928
+ * column. Source order in docs.html is article-then-rail (ADR-091 decision
929
+ * 3, the normative constraint): the article renders first so its own
930
+ * heading is reachable before the rail on every viewport, and the rail
931
+ * collapses to a <details> disclosure below it. */
932
+ .bw-docs-layout {
933
+ display: grid;
934
+ gap: var(--bw-density-section-gap);
935
+ }
936
+
937
+ /* Mobile-only jump to the section rail (icvoss/django-brickwork#523). Sticky
938
+ * so it stays above the fold while the reader starts the article; hidden at
939
+ * the two-column breakpoint where the rail is already visible. */
940
+ .bw-docs-nav-jump {
941
+ position: sticky;
942
+ inset-block-start: 0;
943
+ z-index: 1;
944
+ margin: 0;
945
+ margin-block-end: var(--bw-space-3);
946
+ padding-block: var(--bw-space-2);
947
+ background: var(--bw-color-surface);
948
+ }
949
+ .bw-docs-nav-jump a {
950
+ display: inline-flex;
951
+ align-items: center;
952
+ min-block-size: var(--bw-size-touch-target-min);
953
+ padding-inline: var(--bw-space-3);
954
+ border: var(--bw-size-border-hairline) solid var(--bw-color-border);
955
+ border-radius: var(--bw-radius-md);
956
+ color: var(--bw-color-fg);
957
+ font-family: var(--bw-font-family-display);
958
+ font-weight: var(--bw-font-weight-semibold);
959
+ text-decoration: none;
960
+ }
961
+ .bw-docs-nav-jump a:hover {
962
+ background: var(--bw-color-surface-raised);
963
+ }
964
+ .bw-docs-nav-jump a:focus-visible {
965
+ outline: 2px solid var(--bw-color-accent);
966
+ outline-offset: 2px;
967
+ }
968
+
969
+ .bw-docs-layout__nav-summary {
970
+ display: flex;
971
+ align-items: center;
972
+ min-block-size: var(--bw-size-touch-target-min);
973
+ padding-inline: var(--bw-space-3);
974
+ border: var(--bw-size-border-hairline) solid var(--bw-color-border);
975
+ border-radius: var(--bw-radius-md);
976
+ font-family: var(--bw-font-family-display);
977
+ font-weight: var(--bw-font-weight-semibold);
978
+ color: var(--bw-color-fg);
979
+ cursor: pointer;
980
+ }
981
+
982
+ .bw-docs-layout__nav-summary:focus-visible {
983
+ outline: 2px solid var(--bw-color-accent);
984
+ outline-offset: 2px;
985
+ }
986
+
987
+ .bw-docs-layout__nav-body {
988
+ padding-block-start: var(--bw-space-3);
989
+ }
990
+
991
+ /* Desktop scale-up (>= --bw-breakpoint-lg, 64rem): a persistent two-column
992
+ * layout. --bw-breakpoint-md (48rem, the sidebar/drawer collapse point) is
993
+ * the wrong token here: a 16rem rail plus a readable measure does not fit at
994
+ * 48rem, and --bw-breakpoint-lg is already exactly the value a consumer
995
+ * chose independently, so no new token is added (ADR-091 decision 5).
996
+ *
997
+ * The <details> summary is hidden (nothing to disclose, the rail is always
998
+ * shown) and the nav body is forced visible regardless of the [open] state,
999
+ * so a user who collapsed the rail on a narrow viewport before resizing
1000
+ * still sees it at this breakpoint. `order: -1` puts the rail back in the
1001
+ * FIRST visual grid column even though it is second in DOM order (the
1002
+ * mobile-first source order above): at this single persistent two-column
1003
+ * viewport both the rail and the article are always visible together, so
1004
+ * reordering the grid item here is the standard, a11y-safe use of `order`
1005
+ * (no content is hidden or reachable only out of visual sequence, unlike an
1006
+ * `order`-based mobile reflow). If a future change ever hides either column
1007
+ * at any viewport, this `order` usage must be re-examined, not preserved
1008
+ * (ADR-091 decision 3). */
1009
+ @media (width >= --theme(--breakpoint-lg)) {
1010
+ .bw-docs-layout {
1011
+ grid-template-columns: var(--bw-component-docs-nav-inline-size) minmax(0, 1fr);
1012
+ gap: var(--bw-space-10);
1013
+ align-items: start;
1014
+ }
1015
+
1016
+ .bw-docs-nav-jump {
1017
+ display: none;
1018
+ }
1019
+
1020
+ /* Sticky rail scroll (icvoss/django-brickwork#671): without a max block
1021
+ * size the rail sticks with its tail below the fold when it has more
1022
+ * links than fit the viewport. scrollbar-gutter keeps the column width
1023
+ * stable when the overflow scrollbar appears. */
1024
+ .bw-docs-layout__nav {
1025
+ order: -1;
1026
+ position: sticky;
1027
+ inset-block-start: var(--bw-space-6);
1028
+ max-block-size: calc(100dvh - 2 * var(--bw-space-6));
1029
+ overflow-y: auto;
1030
+ scrollbar-gutter: stable;
1031
+ }
1032
+
1033
+ .bw-docs-layout__nav-summary {
1034
+ display: none;
1035
+ }
1036
+
1037
+ /* Reveal the rail at this breakpoint (icvoss/django-brickwork#451).
1038
+ *
1039
+ * A closed <details> collapses everything that is not its <summary>,
1040
+ * and it does so on the ::details-content pseudo-element that wraps
1041
+ * that content, NOT on the content's own boxes. So a display rule on
1042
+ * .bw-docs-layout__nav-body below cannot reveal anything while the
1043
+ * details is closed: the child is inside a collapsed wrapper, and its
1044
+ * own display value never gets the chance to matter. The shell sets no
1045
+ * [open] and the summary above is display:none here, so before this
1046
+ * rule a desktop docs page rendered a 16rem grid track containing a
1047
+ * zero-height rail, with every link present in the DOM and no control
1048
+ * anywhere on the page to open it. Shipped in 3.15.0 and found on a
1049
+ * rendered page rather than by any suite: the markup is correct, so
1050
+ * the template tests pass, and links that are still in the
1051
+ * accessibility tree are not a WCAG violation, so axe passes too.
1052
+ *
1053
+ * block-size is set alongside content-visibility because the closed
1054
+ * state zeroes the pseudo's block-size as well; revealing the content
1055
+ * without it leaves the same 0px rail. */
1056
+ .bw-docs-layout__nav::details-content {
1057
+ content-visibility: visible;
1058
+ block-size: auto;
1059
+ }
1060
+
1061
+ .bw-docs-layout__nav-body {
1062
+ display: block;
1063
+ padding-block-start: 0;
1064
+ }
1065
+ }
1066
+
1067
+ /* A grid item's default min-inline-size is auto, not 0: without this the
1068
+ * article column refuses to shrink below its content width (a wide code
1069
+ * sample or data table) and blows out the track, the same trap
1070
+ * .bw-section-stack and .bw-band-grid guard against (icvoss/django-brickwork#136). */
1071
+ .bw-docs-layout > * {
1072
+ min-inline-size: 0;
1073
+ }
1074
+
1075
+ /* An unfilled region renders nothing, never empty chrome or a stray gap
1076
+ * (BR-BW-TPL-006), matching .bw-subnav/.bw-breadcrumbs/.bw-footer above. */
1077
+ .bw-docs-layout__header:empty,
1078
+ .bw-docs-layout__footer:empty {
1079
+ display: none;
1080
+ }
1081
+
1082
+ /* Versioned-content archetype (#414): title stack beside the version
1083
+ * switcher in docs_header. Wraps on narrow viewports so the switcher stays
1084
+ * reachable under the heading rather than competing for one row. */
1085
+ .bw-docs-version-header {
1086
+ display: flex;
1087
+ flex-wrap: wrap;
1088
+ align-items: flex-start;
1089
+ justify-content: space-between;
1090
+ gap: var(--bw-space-4);
1091
+ }
1092
+ .bw-docs-version-header > :first-child {
1093
+ flex: 1 1 16rem;
1094
+ min-inline-size: 0;
1095
+ }
1096
+ .bw-docs-version-header .bw-version-switch {
1097
+ flex: 0 0 auto;
1098
+ margin-block-start: var(--bw-space-1);
1099
+ }
1100
+
1101
+ /* In-page TOC composition (Beat S7 craft, first-class since #627): ADR-091
1102
+ * declines a package-owned TOC region because heading trees are a
1103
+ * content-pipeline concern. {% bw_toc %} / _toc.html is the consumer-authored
1104
+ * control once heading ids are known: a labelled nav landmark, not a
1105
+ * generator. */
1106
+ .bw-docs-toc {
1107
+ margin: 0;
1108
+ margin-block-end: var(--bw-space-6);
1109
+ padding: var(--bw-space-4) var(--bw-space-5);
1110
+ border: var(--bw-size-border-hairline) solid var(--bw-color-border);
1111
+ border-radius: var(--bw-radius-lg);
1112
+ background: var(--bw-color-surface-raised);
1113
+ max-inline-size: var(--bw-size-max-width-prose);
1114
+ }
1115
+
1116
+ .bw-docs-toc__title {
1117
+ margin: 0;
1118
+ margin-block-end: var(--bw-space-3);
1119
+ color: var(--bw-color-fg);
1120
+ font-family: var(--bw-font-family-display);
1121
+ font-size: var(--bw-text-label-size);
1122
+ font-weight: var(--bw-font-weight-semibold);
1123
+ }
1124
+
1125
+ .bw-docs-toc__list {
1126
+ margin: 0;
1127
+ padding: 0;
1128
+ list-style: none;
1129
+ }
1130
+
1131
+ .bw-docs-toc__list > li + li {
1132
+ margin-block-start: var(--bw-space-2);
1133
+ }
1134
+
1135
+ .bw-docs-toc__list a {
1136
+ display: inline-flex;
1137
+ align-items: center;
1138
+ /* WCAG 2.5.8 AA target size (#208): TOC entries are navigational controls. */
1139
+ min-block-size: 1.5rem;
1140
+ color: var(--bw-color-fg-muted);
1141
+ font-size: var(--bw-text-body-sm-size);
1142
+ line-height: var(--bw-text-body-sm-line-height);
1143
+ text-decoration: none;
1144
+ }
1145
+
1146
+ .bw-docs-toc__list a:hover {
1147
+ color: var(--bw-color-accent);
1148
+ }
1149
+
1150
+ .bw-docs-toc__list a:focus-visible {
1151
+ outline: 2px solid var(--bw-color-accent);
1152
+ outline-offset: 2px;
1153
+ }
1154
+
1155
+ /* Nested heading entries read indented without inventing a second TOC
1156
+ * chrome; the indent is typography only. */
1157
+ .bw-docs-toc__list .bw-docs-toc__sub {
1158
+ padding-inline-start: var(--bw-space-4);
1159
+ }
1160
+
1161
+ /* A bare <a> in docs_header, docs_footer or the docs rail takes themed ink,
1162
+ * never the UA default blue. This mirrors the marketing footer's rule
1163
+ * (BR-BW-MKT-002, .bw-marketing-footer__inner) and exists for the same
1164
+ * reason: those blocks are consumer-owned prose, so the obvious thing to
1165
+ * write there is a plain anchor, and without this it renders #0000ee.
1166
+ * Against the dark theme's surface that measured 2.12:1, an axe
1167
+ * color-contrast failure at the 4.5:1 AA bar. First found by the docs
1168
+ * fixture's own dark-theme sweep on the footer before this shell had
1169
+ * shipped to anyone; re-found on docs_header by the editorial article
1170
+ * archetype (icvoss/django-brickwork#415) whose byline author link sits
1171
+ * outside .bw-prose. Written at zero specificity via :where() so a
1172
+ * consumer's own class on the anchor wins without !important.
1173
+ * :not(.bw-btn) excludes a bw_button composed into the slot, since buttons
1174
+ * carry their own tier, matching the marketing rule this follows.
1175
+ * The 1.5rem floor is the WCAG 2.5.8 AA target size
1176
+ * (icvoss/django-brickwork#208) and the coarse-pointer tier below is
1177
+ * 2.5.5/platform-HIG (icvoss/django-brickwork#242); a fine-pointer desktop
1178
+ * render stays at the 24px floor and the layout does not shift. */
1179
+ .bw-docs-layout__header :where(a):not(.bw-btn),
1180
+ .bw-docs-layout__footer :where(a):not(.bw-btn),
1181
+ .bw-docs-layout__nav-body :where(a):not(.bw-btn) {
1182
+ display: inline-flex;
1183
+ align-items: center;
1184
+ min-block-size: 1.5rem;
1185
+ color: var(--bw-color-fg-muted);
1186
+ text-decoration: none;
1187
+ transition: var(--bw-transition-colors);
1188
+ }
1189
+
1190
+ .bw-docs-layout__header :where(a:hover):not(.bw-btn),
1191
+ .bw-docs-layout__footer :where(a:hover):not(.bw-btn),
1192
+ .bw-docs-layout__nav-body :where(a:hover):not(.bw-btn) {
1193
+ color: var(--bw-color-fg);
1194
+ }
1195
+
1196
+ @media (pointer: coarse) {
1197
+ .bw-docs-layout__header :where(a):not(.bw-btn),
1198
+ .bw-docs-layout__footer :where(a):not(.bw-btn),
1199
+ .bw-docs-layout__nav-body :where(a):not(.bw-btn) {
1200
+ min-block-size: var(--bw-size-touch-target-min);
1201
+ }
1202
+ }
1203
+
1204
+ /* --- Auth + centred shells ------------------------------------------------- */
1205
+
1206
+ /* grid-template-columns (icvoss/django-brickwork#209): a single implicit
1207
+ * grid track defaults to auto, sized to fit its content's min-content
1208
+ * width; unbreakable content inside .bw-auth__panel (a long URL, an
1209
+ * unwrapped error string) grows that track past the viewport, and since the
1210
+ * panel's own `inline-size: min(28rem, 100%)` resolves its 100% against
1211
+ * that oversized track rather than the viewport, the panel itself follows
1212
+ * it wide. minmax(0, 1fr) caps the track at the available inline space,
1213
+ * the grid counterpart of the min-inline-size: 0 fix flex items need for
1214
+ * the same "child refuses to shrink below its content" hazard (see #125's
1215
+ * note on .bw-marketing-header__nav). */
1216
+ .bw-auth,
1217
+ .bw-centred {
1218
+ display: grid;
1219
+ grid-template-columns: minmax(0, 1fr);
1220
+ place-items: center;
1221
+ min-block-size: 100vh;
1222
+ padding: var(--bw-space-6);
1223
+ }
1224
+
1225
+ .bw-auth__panel,
1226
+ .bw-centred__panel {
1227
+ inline-size: min(var(--bw-size-max-width-modal-sm), 100%);
1228
+ background: var(--bw-color-surface-raised);
1229
+ border: var(--bw-size-border-hairline) solid
1230
+ color-mix(in oklab, var(--bw-color-fg) 12%, var(--bw-color-surface-raised));
1231
+ border-radius: var(--bw-radius-lg);
1232
+ /* Alone on a sunken page: elev-2 plus soft ambient under the token. */
1233
+ box-shadow:
1234
+ var(--bw-elevation-2),
1235
+ 0 8px 20px -6px oklch(0 0 0 / 0.12);
1236
+ padding: var(--bw-space-8);
1237
+ outline: none;
1238
+ }
1239
+
1240
+ .bw-auth__header {
1241
+ display: flex;
1242
+ justify-content: center;
1243
+ margin-block-end: var(--bw-density-stack-gap);
1244
+ }
1245
+
1246
+ /* A plain <a> in the panel's prose ("Back to sign in", "Forgotten your
1247
+ * password?") is the documented default shape for auth examples, but the
1248
+ * panel itself sets no colour for it, so it fell back to the UA default
1249
+ * blue, invisible against a dark-theme surface (WCAG 1.4.3, caught by the
1250
+ * W0.3 archetype harness). Same fix as .bw-marketing-footer__inner :where(a)
1251
+ * (BR-BW-MKT-002): theme it explicitly, never leave a prose link unstyled. */
1252
+ .bw-auth__panel :where(a),
1253
+ .bw-centred__panel :where(a) {
1254
+ color: var(--bw-color-accent);
1255
+ }
1256
+
1257
+ .bw-auth__panel :where(a:hover),
1258
+ .bw-centred__panel :where(a:hover) {
1259
+ color: var(--bw-color-accent-hover);
1260
+ }
1261
+
1262
+ /* --- Three-region layout (SHL-001 / brickwork#700): [data-layout="regions"] -- */
1263
+
1264
+ /* Full-width topbar above sibling rail + contextual sidebar + workspace.
1265
+ * .bw-app__main dissolves (display: contents) so the topbar and .bw-app__body
1266
+ * become grid items; the body is a real flex column in the workspace area.
1267
+ * Track widths are CSS variables so an empty or omitted rail or sidebar
1268
+ * collapses to 0 and the workspace reclaims the space (brickwork#703). The
1269
+ * rail tokens name the complete grid track, including its chrome. */
1270
+
1271
+ .bw-app[data-layout="regions"] {
1272
+ --bw-shell-rail-track: var(--bw-density-rail-width);
1273
+ --bw-shell-sidebar-track: var(--bw-density-sidebar-width);
1274
+ display: grid;
1275
+ /* Fallbacks keep these local cascade hooks off the emitted-token gate. */
1276
+ grid-template-columns: var(--bw-shell-rail-track, 0px) var(--bw-shell-sidebar-track, 0px) minmax(0, 1fr);
1277
+ grid-template-rows: auto minmax(0, 1fr);
1278
+ grid-template-areas:
1279
+ "topbar topbar topbar"
1280
+ "rail sidebar main";
1281
+ }
1282
+
1283
+ .bw-app[data-layout="regions"] .bw-rail {
1284
+ display: flex;
1285
+ grid-area: rail;
1286
+ inline-size: auto; /* track owns the width, including rail chrome */
1287
+ min-inline-size: 0;
1288
+ /* Icon links carry their own inline target padding. Keeping this outer
1289
+ * chrome at zero lets the density token remain the complete rail track. */
1290
+ padding-inline: 0;
1291
+ /* The icon list owns clipping in its resting state. This parent must not
1292
+ * clip its expanded child at the track edge. */
1293
+ overflow: visible;
1294
+ }
1295
+
1296
+ .bw-app[data-layout="regions"] .bw-sidebar {
1297
+ grid-area: sidebar;
1298
+ inline-size: auto;
1299
+ min-inline-size: 0;
1300
+ }
1301
+
1302
+ .bw-app[data-layout="regions"] .bw-app__main {
1303
+ display: contents;
1304
+ }
1305
+
1306
+ .bw-app[data-layout="regions"] .bw-topbar {
1307
+ grid-area: topbar;
1308
+ }
1309
+
1310
+ .bw-app[data-layout="regions"] .bw-app__body {
1311
+ display: flex;
1312
+ flex-direction: column;
1313
+ min-width: 0;
1314
+ grid-area: main;
1315
+ }
1316
+
1317
+ /* Empty-suppression / width reclaim (brickwork#703): unfilled rail or
1318
+ * sidebar blocks leave truly :empty nav containers; an overridden region can
1319
+ * omit its aside altogether. Both cases collapse the matching track, so no
1320
+ * empty strip remains. */
1321
+ .bw-app[data-layout="regions"]:has(.bw-rail__nav:empty) {
1322
+ --bw-shell-rail-track: 0px;
1323
+ }
1324
+ .bw-app[data-layout="regions"]:has(.bw-rail__nav:empty) .bw-rail {
1325
+ display: none;
1326
+ }
1327
+ .bw-app[data-layout="regions"]:has(.bw-sidebar__nav:empty) {
1328
+ --bw-shell-sidebar-track: 0px;
1329
+ }
1330
+ .bw-app[data-layout="regions"]:has(.bw-sidebar__nav:empty) .bw-sidebar {
1331
+ display: none;
1332
+ }
1333
+ .bw-app[data-layout="regions"]:not(:has(.bw-rail)) {
1334
+ --bw-shell-rail-track: 0px;
1335
+ }
1336
+ .bw-app[data-layout="regions"]:not(:has(.bw-sidebar)) {
1337
+ --bw-shell-sidebar-track: 0px;
1338
+ }
1339
+
1340
+ /* The icon rail's renderer grows on hover and focus-within. Grow this grid
1341
+ * track to the documented expanded rail token too; the list owns its own
1342
+ * resting-state clipping, while the parent remains visible at the edge. */
1343
+ .bw-app[data-layout="regions"]:has(.bw-nav-rail__list--icons:hover),
1344
+ .bw-app[data-layout="regions"]:has(.bw-nav-rail__list--icons:focus-within) {
1345
+ --bw-shell-rail-track: var(--bw-density-rail-width-expanded);
1346
+ }
1347
+
1348
+ /* Collapsed contextual sidebar still narrows its track in regions mode. */
1349
+ .bw-app[data-layout="regions"]:has(.bw-sidebar[data-bw-collapsed]) {
1350
+ --bw-shell-sidebar-track: var(--bw-density-sidebar-width-collapsed);
1351
+ }
1352
+
1353
+ /* --- Topbar-primary layout (SHL-001): [data-layout="topbar"] ---------------- */
1354
+
1355
+ /* Same DOM as the sidebar layout, restyled: the aside becomes a full-width
1356
+ * horizontal nav band directly under the topbar. `.bw-app__main` dissolves
1357
+ * (display: contents) so the topbar, the band, and the workspace order as
1358
+ * siblings in one column; `order: -1` seats the topbar first while everything
1359
+ * else keeps document order (band, subnav, breadcrumbs, workspace). Every rule
1360
+ * here is scoped under the attribute, so no sidebar-layout default changes.
1361
+ *
1362
+ * Reading-order note (A11Y-015): the shared DOM keeps the primary nav before
1363
+ * the topbar in reading/tab order in BOTH layouts; here the topbar is lifted
1364
+ * visually above the band, so visual order and DOM order differ by that one
1365
+ * adjacent swap. This is the deliberate cost of one DOM for two shapes (no
1366
+ * template fork); the skip link remains the first tab stop either way.
1367
+ */
1368
+
1369
+ .bw-app[data-layout="topbar"] {
1370
+ display: flex; /* flex column absorbs the optional subnav/breadcrumbs rows */
1371
+ flex-direction: column;
1372
+ }
1373
+
1374
+ [data-layout="topbar"] .bw-app__main {
1375
+ display: contents;
1376
+ }
1377
+
1378
+ [data-layout="topbar"] .bw-topbar {
1379
+ order: -1;
1380
+ }
1381
+
1382
+ /* The band: full width, hairline below instead of at the inline end,
1383
+ * background unchanged. No z-index of its own: the sticky topbar's
1384
+ * --bw-z-sticky already paints above the static band on scroll. */
1385
+ [data-layout="topbar"] .bw-sidebar {
1386
+ flex-direction: row;
1387
+ align-items: center;
1388
+ border-inline-end: none;
1389
+ border-block-end: var(--bw-size-border-hairline) solid var(--bw-color-border);
1390
+ padding-block: 0; /* vertical rhythm comes from the nav row's own padding */
1391
+ padding-inline: var(--bw-density-page-gutter-inline);
1392
+ }
1393
+
1394
+ [data-layout="topbar"] .bw-sidebar__header {
1395
+ padding-block-end: 0;
1396
+ }
1397
+
1398
+ /* The switcher slot sits inline at the row start: auto width, the hairline
1399
+ * rotates from below (block-end) to the trailing edge (inline-end), and the
1400
+ * gap to the nav stays the density section gap, rotated to the inline axis
1401
+ * so a consumer still never guesses it. */
1402
+ [data-layout="topbar"] .bw-sidebar > .bw-sidebar__switcher {
1403
+ flex: 0 0 auto;
1404
+ margin-block-end: 0;
1405
+ margin-inline-end: var(--bw-density-section-gap);
1406
+ border-block-end: none;
1407
+ border-inline-end: var(--bw-size-border-hairline) solid var(--bw-color-border);
1408
+ }
1409
+
1410
+ /* The band never scrolls internally; the wrapping nav row grows it instead. */
1411
+ [data-layout="topbar"] .bw-sidebar__nav {
1412
+ overflow-y: visible;
1413
+ }
1414
+
1415
+ /* Footer content seats at the row end, its divider rotated to match. */
1416
+ [data-layout="topbar"] .bw-sidebar__footer {
1417
+ margin-inline-start: auto;
1418
+ padding-block-start: 0;
1419
+ padding-inline-start: var(--bw-density-stack-gap);
1420
+ border-block-start: none;
1421
+ border-inline-start: var(--bw-size-border-hairline) solid var(--bw-color-border);
1422
+ }
1423
+
1424
+ /* --- Responsive: collapse the sidebar into the mobile drawer at md --------- */
1425
+
1426
+ @media (width < --theme(--breakpoint-md)) { /* SHL-017: the fixed sidebar-collapse point, ADR-079 */
1427
+ .bw-app {
1428
+ grid-template-columns: 1fr; /* sidebar out of flow, drawer takes over */
1429
+ }
1430
+ .bw-app[data-layout="regions"] {
1431
+ grid-template-columns: 1fr;
1432
+ grid-template-areas:
1433
+ "topbar"
1434
+ "main";
1435
+ }
1436
+ .bw-sidebar,
1437
+ .bw-rail,
1438
+ .bw-app[data-layout="regions"] .bw-sidebar,
1439
+ .bw-app[data-layout="regions"] .bw-rail {
1440
+ /* Covers sidebar, topbar-band, and regions columns: desktop nav hides
1441
+ below md and the single drawer takes over in every shape. One drawer
1442
+ tree (never two): fill mobile_nav with the full reachable nav. */
1443
+ display: none;
1444
+ }
1445
+ .bw-drawer {
1446
+ display: block;
1447
+ }
1448
+ }
1449
+
1450
+ /* --- Dark-theme resets for light-only shell ambient (beautiful defaults) --- */
1451
+
1452
+ /* Soft ambient under elevation-* is a LIGHT-theme treatment so chrome reads
1453
+ * on white canvas; dark elevation tokens already carry their own depth. */
1454
+ [data-theme="dark"] .bw-topbar {
1455
+ box-shadow: var(--bw-elevation-1);
1456
+ }
1457
+ [data-theme="dark"] .bw-auth__panel,
1458
+ [data-theme="dark"] .bw-centred__panel {
1459
+ box-shadow: var(--bw-elevation-2);
1460
+ }