Patterns

Layout

layout-grid: a page-level grid with named tracks. Children sit in `content`
unless they ask for another track.

  | full | wide |        content        | wide | full |
                | start      |     end  |

layout-full | layout-wide | layout-content | layout-narrow:
  inside layout-grid they pick a track; anywhere else they cap the width and
  centre the element, keeping --gutter clear of the viewport edge.

layout-start | layout-end: the two halves of the content track, side by
side from md up. Only valid inside layout-grid.

layout-grid--ruled: Kite Co.'s keyline down the inline-start edge of the
wide track, through the grid's padding, from md up. --layout--inset keeps
content clear of it.

layout-width-{size}: a gutter-aware max width for any --container-* token.

Role widths are set below; point them at different containers per project.
--layout--inset is the least space between the wide and content edges.
Kite Co. runs content the full width of the frame, inset from the keyline,
and lets each element cap its own measure, so text sits to the left.

Section

Vertical padding for a page band. Combine with a surface and layout-grid:
  <section class="section surface-blue layout-grid">…</section>

For Kite Co.'s ruled bands, add rule-block-start and layout-grid--ruled.

Block knob: --section--padding-y.

Grids

grid-simple: --cols equal columns. Set the count with cols-{n}, which works
with variants: <ul class="grid-simple cols-1 md:cols-2 lg:cols-4">

grid-auto: as many columns as fit, each at least --grid-auto--min-inline-size.

Both read the global --gap, --col-gap and --row-gap. --cols is registered as
non-inheriting (tokens/globals.css), so nested grids start from one column.

Flex grid

Like grid-simple, but the last row's items can be centred or justified,
because it's flexbox. Children are sized to --cols columns (set with cols-{n}).

flex-grid-auto: children keep their own width and wrap.

Flex list

A wrapping row of items at their natural width: tags, inline nav, buttons.
Only a <ul>/<ol> has its list styles reset.

Type styles

Sizes are theme tokens (text-h1 …, see tokens/theme.css), each carrying its
line height and letter spacing. These compose family and weight with a size.
Headings get them in base/elements.css.

  type-h1 … type-h6, type-hero   IBM Plex Serif Medium
  type-base                      IBM Plex Sans, the body default
  type-label, type-label-sm      IBM Plex Mono SemiBold: surtitles, nav, tags
  type-meta                      IBM Plex Serif Medium, small: captions, credits, dates
  type-code                      IBM Plex Mono, small: code blocks (pre gets it by default)

Flow

Space between siblings. Each child declares the space above itself with
--flow-space (registered as non-inheriting in tokens/globals.css); anything
that doesn't falls back to --space-layout.

Element defaults (p, headings, lists) are in base/elements.css. For one
fixed gap regardless of element, use stack-{n} instead.

Prose

Flow plus a reading measure and list styling, for rich text you don't
control (CMS content, Markdown).

Add the class not-prose to opt a subtree out of the list styling. It needs no
CSS of its own: prose's selectors exclude it with :where(). It's an exclusion,
not a reset, so a .prose nested inside .not-prose stays excluded.

Link

Applied to every <a> in base/elements.css.

Context knobs (never declared, so a surface or parent can set them):
  --link--color          falls back to --color-accent
  --link--color--hover   falls back to --link--color mixed toward the foreground

Block knobs (declared here, set by variants):
  --link--text-decoration-line, --link--text-decoration-thickness (+ --hover)

The underline thickens on hover, so there's feedback even where the accent
and the foreground are the same colour (Kite Co.'s blue on neutral).

Blockquote

Applied to <blockquote> in base/elements.css. Kite Co.'s pixel quote mark
above the quote, the quote set in the h1 style, the <cite> as body text.

  <blockquote><p>Quote</p><cite>Name, role</cite></blockquote>

Block knobs: --blockquote--gap, --blockquote__mark--block-size,
--blockquote__mark--background-color.

Button

  <a class="btn" href="…">Label</a>
  <button class="btn btn--secondary">Label <span class="btn__icon"></span></button>
  <button class="btn btn--square"><span class="btn__icon"></span><span class="sr-only">Close</span></button>

Set in Plex Mono (type-label), with Kite Co.'s 6px corners. Colours come
from the role tokens, so a button follows its surface without per-context
overrides. Hover colours are derived with color-mix().

Block knobs, declared here and set by variants:
  --btn--padding-x, --btn--padding-y, --btn--gap, --btn--border-width,
  --btn--border-radius, --btn--background-color, --btn--border-color,
  --btn--color, and each colour's --hover state.

Read with a fallback (set on the button):
  --btn--size        btn--square's minimum size, defaults to 44px. Below
                     44px, add hit-area to keep the target 44px

Icon knobs (set on the button or the icon):
  --btn--icon        url() of a mask image for an empty .btn__icon
  --btn--icon-size   defaults to 1em

Tag

A small outlined label in Plex Mono, for services, categories and filters:
  <ul class="flex-list"><li class="tag">Websites</li></ul>
  <a class="tag" href="…">Websites</a>

Drawn in currentColor, so it follows the text colour on every surface.
A linked tag fills faintly on hover.

Block knobs: --tag--padding-x, --tag--padding-y, --tag--border-width,
--tag--border-radius, --tag--background-color (+ --hover).

Input

Text inputs and textareas. select builds on it (select.css). base/forms.css
applies it to bare elements when that file is turned on.

Block knobs: --input--padding-x, --input--padding-y, --input--border-width,
--input--border-color, --input--border-radius, --input--background-color
(+ --hover, --focus), --input--color.

Focus uses the global :focus-visible ring.

Select

An input with a chevron. The chevron is two currentColor gradients, so it
follows the text colour in every context. (A <select> can't have a pseudo-
element, which rules out a mask icon.)

Block knobs: --select--icon-size, plus everything from input.

Checkbox

Restyles the input itself (appearance: none), so no wrapper is needed:
  <label><input type="checkbox" class="checkbox"> Remember me</label>

Block knobs: --checkbox--size, --checkbox--border-width, --checkbox--border-color,
--checkbox--border-radius, --checkbox--background-color (+ --checked),
--checkbox--color--checked (the tick).

Radio

Restyles the input itself (appearance: none):
  <label><input type="radio" name="size" class="radio"> Small</label>

Block knobs: --radio--size, --radio--border-width, --radio--border-color,
--radio--background-color, --radio--color--checked (the dot).

Focus ring

Applied to :focus-visible in base/reset.css. Reads the global knobs:
  --focus-color   not declared; falls back to the context's foreground
  --focus-width, --focus-offset   declared in tokens/globals.css

Media embed

A figure holding an iframe or video at a fixed aspect ratio, with a caption.
  <figure class="media-embed"><iframe …></iframe><figcaption>…</figcaption></figure>

Block knob: --media-embed--aspect-ratio (16 / 9).

Mask icon

Paints a mask image in currentColor, so icons follow the text colour.
  .thing::after { @apply mask-icon; mask-image: url("/icons/arrow.svg"); }

Block knob: --mask-icon--size (1em).

Cross

Two bars drawn with pseudo-elements, in currentColor. Rotate or scale them
for a burger-to-close transition.

Read with fallbacks: --cross--size (arm length, 100%), --cross--stroke-width (2px).

Disclosure: show and hide any element from one or more triggers.
https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/

  <button aria-controls="faq-1" aria-expanded="false">Question</button>
  <div id="faq-1" data-disclosure hidden>Answer</div>

The target is hidden with `hidden` and made `inert` while collapsed, so its
contents leave the tab order and the accessibility tree without touching
tabindex. Triggers get aria-expanded; a non-button trigger also gets
role="button", a tab stop and Enter/Space.

For a simple accordion, prefer native <details name="group">: it needs no JS.
Use this when the trigger and target can't be <summary> and <details>, or you
need escape-to-close, focus-out, hash or grouping behaviour.

Data attributes on the target (all optional):
  data-disclosure-animate            animate height (skipped for reduced motion)
  data-disclosure-group="name"       expanding one collapses the others in the group
  data-disclosure-focusout           collapse when focus or a click leaves it
  data-disclosure-focus-within       move focus into the target on expand
  data-disclosure-expand-on-hash="false"   don't expand when the URL hash is its id

Show or hide parts of a trigger by state with data-show-expanded and friends
(css/utilities/aria-expanded.css).

Events, dispatched on the target and bubbling: expandbegin, expandend,
collapsebegin, collapseend.

Show or hide parts of a disclosure trigger based on its aria-expanded state:

  <button aria-controls="menu" aria-expanded="false">
      <span data-show-collapsed>Open menu</span>
      <span data-show-expanded>Close menu</span>
  </button>

data-show-expanded / data-hide-collapsed: visible only when expanded.
data-hide-expanded / data-show-collapsed: visible only when collapsed.

Dialog: extras on top of native <dialog>.

  <button commandfor="signup" command="show-modal">Sign up</button>
  <button data-dialog-open="signup" data-dialog-template="signup-form">Sign up</button>

  <dialog id="signup" data-dialog aria-labelledby="signup-title">
      <h2 id="signup-title">Sign up</h2>
      <div data-dialog-slot></div>
      <button commandfor="signup" command="close">Close</button>
  </dialog>

  <template id="signup-form">…</template>

Opening:
- Invoker commands (commandfor + command="show-modal" | "close" | "request-close")
  work natively where supported; this adds them where they aren't.
- data-dialog-open="id" and data-dialog-close="id" work anywhere on the page,
  and a bare data-dialog-close works inside the dialog.

Content: an opener (or the dialog) with data-dialog-template="template-id" has
that <template> cloned into [data-dialog-slot] on open. The slot is emptied once
the dialog has closed and finished animating, which also stops embedded media.

Other data attributes on the dialog:
  data-dialog-modal="false"           open with show() instead of showModal()
  data-dialog-backdrop-close="false"  don't close on a backdrop click

Scroll locking is CSS (css/utilities/scroll-lock.css). Native <dialog> handles
focus trapping, Escape and returning focus to the opener.

Animate on scroll

  <div data-animate data-animate-stagger="80">
      <p data-animate-item>…</p>
      <p data-animate-item>…</p>
  </div>

  <h2 data-animate-item>…</h2>                 no trigger: plays itself

  <section id="intro" data-animate>…</section>
  <img data-animate-item="intro" …>            played by #intro, wherever it is

js/animate.ts sets [data-playing] on each item when its trigger scrolls into
view; this file does the animating. An item's trigger is the id in its value,
else its nearest [data-animate] ancestor, else the item itself, so nested
triggers each play only their own items.

Data attributes rather than classes: the hidden state has to match exactly
what the script will reveal (see docs/decisions/009-animate-hooks.md).

Items stay visible without JS (the html.js class), when the user prefers
reduced motion, and in print.

Knobs (never declared, read with a fallback). Set them on the item or any
ancestor, the trigger included; a remote item doesn't inherit from its trigger.
  --animate--animation-name              fade-in, or fade-in-translate
  --animate--animation-duration          300ms
  --animate--animation-timing-function   ease-out
  --animate--animation-delay             50ms, added to the item's place in the queue
  --animate--translate                   fade-in-translate's start offset, 0 16px

Set by the script: --animate__item--animation-delay, the item's place in the queue.

Animate on scroll. Sets [data-playing] on [data-animate-item] elements when
their trigger scrolls into view; css/patterns/animate.css does the rest.

  <div data-animate data-animate-stagger="80">
      <p data-animate-item>…</p>
  </div>

  <h2 data-animate-item>…</h2>                 no trigger: plays itself

  <section id="intro" data-animate>…</section>
  <img data-animate-item="intro" …>            played by #intro, wherever it is

An item's trigger is the element its value names by id, else its nearest
[data-animate] ancestor (not itself), else the item itself. Each item has
exactly one trigger, so nested triggers play only their own items, and an
element can be an item of an outer trigger and a trigger for its own
(data-animate data-animate-item). A named trigger must be in the DOM when
the item is set up; if it isn't, the item plays itself.

Items that start together play one after another in document order, across
triggers: each waits the stagger of the one before (its trigger's
data-animate-stagger, default 100ms), capped at 600ms from now so a fast
scroll never queues a backlog. The wait goes in --animate__item--animation-delay.

Items replay when their trigger goes back below the viewport (the user
scrolled up past it), not when it scrolls off the top. A trigger already
above the viewport (an anchor link, a restored scroll) plays straight away,
off screen, without holding up the queue.

Needs the no-js → js class swap in <head> so items start hidden only when
this script will run.