@master/internal-site 0.0.0-stage → 0.1.0

package/src/styles/blog.css

@@ -0,0 +1,568 @@
+/*
+ * The blog index: a timeline drawn with the homepage's drafting guides. A masthead whose title is engraved like the
+ * homepage footer's wordmark, then one section per year, each opened like a homepage section: a rule across its
+ * top, crossed where it meets the rails, with the rulers restarting there. A vertical time line runs beside the
+ * years; each year's rule crosses it, and each post hangs from it on a tick, so the line reads as a ruler that
+ * measures time. The newest post's tick carries the page's one gold mark. Recipes and tokens come from
+ * blog-materials.css.
+ *
+ * Every vertical size is a whole number of pixels (rounded where it scales with the viewport), and the frame is
+ * placed on whole pixels, so 1px guides stay crisp at 1x.
+ */
+@layer components {
+  .blog-index {
+    /*
+     * The drawing's width: the homepage's content column (its 100rem wrapper minus gutters), so the title and the
+     * years hang on the same left edge as the header's logo and the rails run where the homepage's do, 20px outside
+     * the content edges with their rulers beyond.
+     */
+    --blog-frame: 95rem;
+    --blog-gutter: 1.25rem;
+    /* From the time line to an entry's text; the node tick takes the first .75rem of it. */
+    --blog-indent: 1.25rem;
+    --blog-node-y: 0.5rem;
+    /*
+     * The years' column, the posts' column beside the time line, and open ground to the right: the line sits about a
+     * quarter in on wide screens, and the spare width goes to air on both sides of the posts, never into the measure.
+     */
+    --blog-timeline-columns: minmax(10rem, 1fr) minmax(0, 44rem) minmax(0, 1fr);
+    /* A cross on the time line, drawn in an 11px box centred on the crossing, as the rails' crosses are. */
+    --blog-cross-mark:
+      linear-gradient(var(--blog-cross), var(--blog-cross)) 0 5px / 11px 1px no-repeat,
+      linear-gradient(var(--blog-cross), var(--blog-cross)) 5px 0 / 1px 11px no-repeat;
+    position: relative;
+    isolation: isolate;
+    overflow-x: clip;
+    padding-inline: var(--blog-gutter);
+
+    @media (width >= 40rem) {
+      --blog-gutter: 2.5rem;
+    }
+
+    @media (width >= 48rem) {
+      --blog-indent: 1.5rem;
+    }
+
+    /* A Han date's ink ("6 月 15 日") centres a pixel higher than a Latin one's; the node follows it. */
+    &:lang(zh) {
+      --blog-node-y: calc(0.5rem - 1px);
+    }
+
+    /* Light falls from above and slightly left; on the ground it is felt more than seen. */
+    &::before {
+      position: absolute;
+      inset: 0 0 auto;
+      z-index: -1;
+      height: min(56rem, 100%);
+      background-image: radial-gradient(ellipse 60% 70% at 18% 0%, light-dark(oklch(1 0.006 85 / 0.9), oklch(0.3 0.006 80 / 0.2)), transparent 72%);
+      pointer-events: none;
+      content: '';
+    }
+
+    /* Centred on a whole pixel, so the rails, rules and time line never straddle two. */
+    & > * {
+      max-width: var(--blog-frame);
+      margin-inline: auto;
+      margin-inline-start: max(0px, round(down, (100% - var(--blog-frame)) / 2, 1px));
+    }
+  }
+
+  /* Selected text sits on a soft wash of its own ink, as selected prose does on the articles (the hatched title
+     sets its own: solid letters on the same wash). */
+  .blog-index :not(.blog-hatch-text)::selection {
+    color: inherit;
+    background-color: color-mix(in oklab, var(--blog-text) 16%, transparent);
+  }
+
+  /* ---------- Masthead ---------- */
+  /*
+   * The rulers here count from below the header, so a whole number of rems puts the title's cap height on a tick:
+   * on wide screens the long one, 128px down, as a section's first long tick meets its cross.
+   */
+  .blog-masthead {
+    padding-top: calc(3.75rem + round(clamp(4rem, 1rem + 8vw, 8rem), 1rem));
+    padding-bottom: round(clamp(3.5rem, 2rem + 4vw, 6rem), 1rem);
+  }
+
+  /* As in the homepage hero, the rails start below the fixed header (60px) and fade in. */
+  @media (--md) {
+    .blog-masthead.blog-rails::after {
+      top: 3.75rem;
+      mask-image: linear-gradient(transparent, black 6rem);
+    }
+  }
+
+  /*
+   * The footer wordmark's engraving (.blog-hatch-text), set as the page title: large and regular weight, a fine
+   * hatch over a tint that carries the letterforms. A real heading; the text stays selectable. On phones it keeps
+   * one line where it fits, as the Han title does.
+   */
+  .blog-masthead-title {
+    max-width: 12em;
+    margin: 0;
+    font-size: round(clamp(2.875rem, 1.5rem + 5.25vw, 7rem), 1px);
+    font-weight: var(--font-weight-regular);
+    line-height: round(1.04em, 1px);
+    letter-spacing: -0.03em;
+    text-wrap: balance;
+    word-break: keep-all;
+    overflow-wrap: anywhere;
+
+    /*
+     * Latin letters hang from their cap height, exactly on the ruler's tick, and stand on their baseline. The hatch
+     * is painted only inside the box, so padding opens it again past the trim (round overshoots and descenders
+     * keep their ink) and equal negative margins take the room back; the bottom padding also rounds the trimmed
+     * box back to whole pixels. The N's side bearing would set its stem inside the frame's edge, so it steps out.
+     */
+    &:not(:lang(zh)) {
+      margin-block: calc(round(0.25em, 1px) * -1);
+      margin-inline-start: -0.06em;
+      padding-block: round(0.25em, 1px) calc(round(0.25em, 1px) + round(up, 1cap, 1px) - 1cap);
+      text-box: trim-both cap alphabetic;
+    }
+
+    /*
+     * Han glyphs fill the em square: a smaller size, lightly tracked, carries the Latin title's weight. Their ink
+     * starts about 0.11em into the line and ends 0.18em above its foot, so the margins hang them from the same tick
+     * and leave the same air below as the Latin title (whole pixels, so the rules stay crisp).
+     */
+    &:lang(zh) {
+      margin-block: round(-0.11em, 1px) round(-0.18em, 1px);
+      font-size: round(calc(clamp(2.875rem, 1.5rem + 5.25vw, 7rem) * 0.84), 1px);
+      line-height: round(1.2em, 1px);
+      letter-spacing: 0.04em;
+    }
+  }
+
+  /* ---------- A year ---------- */
+  .blog-year {
+    display: grid;
+    grid-template-columns: var(--blog-timeline-columns);
+    align-items: start;
+  }
+
+  /*
+   * The year, named once beside its posts: large but well below the title (about 1.8 : 1), quiet, and hung level
+   * with its first date: the list's 3.5rem, then 13px Geist's cap top in its 16px line, then the digits' round
+   * overshoot, so their ink starts where the date's does.
+   */
+  .blog-year-label {
+    position: sticky;
+    top: 6rem;
+    grid-area: 1 / 1;
+    /* The bottom margin keeps a held year clear of the next year's rule as it is pushed along. */
+    margin: calc(3.5rem + 0.1725rem + 0.016em) 0 3.5rem;
+    font-size: round(clamp(2rem, 1rem + 2.75vw, 3.5rem), 1px);
+    font-weight: var(--font-weight-regular);
+    line-height: 1;
+    letter-spacing: -0.03em;
+    font-variant-numeric: tabular-nums;
+    /* Large, so the faintest text ink (still 4.5:1) keeps it from outweighing the posts beside it. */
+    color: var(--blog-text-faint);
+    text-box: trim-both cap alphabetic;
+  }
+
+  /* The time line runs the year's full height, so consecutive years join into one line. */
+  .blog-year-posts {
+    position: relative;
+    container: blog-posts / inline-size;
+    grid-area: 1 / 2;
+    margin: 0;
+    padding: 3.5rem 0 5rem var(--blog-indent);
+    list-style: none;
+
+    /* A border, so forced colors keep the line. */
+    &::before {
+      position: absolute;
+      inset: 0 auto 0 0;
+      border-inline-start: 1px solid var(--blog-guide);
+      content: '';
+    }
+
+    /* Where the year's rule meets the time line, a cross. */
+    &::after {
+      position: absolute;
+      top: -5px;
+      left: -5px;
+      width: 11px;
+      height: 11px;
+      background: var(--blog-cross-mark);
+      pointer-events: none;
+      content: '';
+    }
+  }
+
+  /* The year's rule, on tablets (from md the rails' rule draws it, crossed at the rails). */
+  @media (48rem <= width < 64rem) {
+    .blog-year {
+      border-top: 1px solid var(--blog-guide);
+    }
+
+    /* The border sits above the list, so the cross centres one pixel higher. */
+    .blog-year-posts::after {
+      top: -6px;
+    }
+  }
+
+  /*
+   * The drawing's lower edge is the footer's rule, reached with a year's usual air, so it reads as the next rule:
+   * crosses where it meets the rails (the rule recipe, drawn on the footer's line) and the time line. Decorative
+   * and empty; it adds no height.
+   */
+  .blog-timeline-end {
+    position: relative;
+    display: grid;
+    grid-template-columns: var(--blog-timeline-columns);
+    height: 0;
+
+    &::after {
+      position: absolute;
+      top: -5px;
+      left: -5px;
+      grid-column: 2;
+      width: 11px;
+      height: 11px;
+      background: var(--blog-cross-mark);
+      pointer-events: none;
+      content: '';
+    }
+  }
+
+  /* ---------- A post on the line ---------- */
+  .blog-entry {
+    position: relative;
+
+    & + & {
+      margin-top: 4rem;
+    }
+
+    /* Its node: a long ruler tick from the time line, level with the date. */
+    &::before {
+      position: absolute;
+      top: var(--blog-node-y);
+      left: calc(var(--blog-indent) * -1);
+      width: 0.75rem;
+      border-top: 1px solid var(--blog-tick-major);
+      transition: border-color var(--blog-slow) var(--blog-ease);
+      content: '';
+    }
+
+    /* The newest post: the one gold mark, on the line itself (above it, where the line is drawn later). */
+    & > .blog-entry-signal {
+      position: absolute;
+      z-index: 1;
+      top: calc(var(--blog-node-y) - 2px);
+      left: calc(var(--blog-indent) * -1 - 2px);
+    }
+
+    &:has(> .blog-entry-link:focus-visible)::before {
+      border-color: var(--blog-text-quiet);
+      transition-duration: var(--blog-base);
+    }
+
+    /* Only a real pointer hovers: a tap on a touch screen must not leave a selection drawn behind on return. */
+    @media (hover: hover) {
+      &:has(> .blog-entry-link:hover)::before {
+        border-color: var(--blog-text-quiet);
+        transition-duration: var(--blog-base);
+      }
+    }
+  }
+
+  /*
+   * The whole entry is the link, as wide as its text's measure. On arrival a design tool's selection appears
+   * around it: artboard marks at the corners, 12px from the ink above (the date's cap top), below (the last
+   * baseline) and on the left, where the node's tick ends; on the right they follow the measure. A press draws
+   * them in a step and darker; keyboard focus closes them into the whole frame.
+   */
+  .blog-entry-link {
+    --blog-marks-inset: 0.75rem;
+    display: block;
+    width: fit-content;
+    /* One measure for title and excerpt, so the selection frame is never wider than the text it holds. */
+    max-width: 36rem;
+    color: var(--blog-text-body);
+    text-decoration: none;
+    /* Focus scrolled into view keeps its ring clear of the fixed header (60px) and the screen's foot. */
+    scroll-margin-block: 5.5rem 2rem;
+
+    &::before {
+      /* The bottom follows the excerpt's last baseline in its 30px line. */
+      inset: calc(0.1725rem - var(--blog-marks-inset)) calc(var(--blog-marks-inset) * -1) calc(0.6rem - var(--blog-marks-inset));
+      opacity: 0;
+      transition: opacity var(--blog-slow) var(--blog-ease), inset var(--blog-quick) var(--blog-ease);
+    }
+
+    &:is(:focus-visible, :active)::before {
+      opacity: 1;
+      transition-duration: var(--blog-base), var(--blog-quick);
+    }
+
+    @media (hover: hover) {
+      &:hover::before {
+        opacity: 1;
+        transition-duration: var(--blog-base), var(--blog-quick);
+      }
+
+      /* Hover intent: a pointer passing over the list on its way elsewhere leaves no trail of half-drawn marks. */
+      &:hover:not(:focus-visible, :active)::before {
+        transition-delay: 80ms;
+      }
+    }
+
+    &:active {
+      --blog-mark: var(--blog-text-faint);
+      --blog-marks-inset: calc(0.75rem - 2px);
+    }
+
+    /*
+     * The ring is the marks' own frame, so it sits as evenly on the ink as they do. The link's transparent outline
+     * is what forced colors paint, where the marks are hidden.
+     */
+    &:focus-visible {
+      outline: 2px solid transparent;
+      outline-offset: 0.5rem;
+
+      &::before {
+        background: none;
+        outline: 2px solid var(--blog-text-faint);
+        outline-offset: -2px;
+      }
+    }
+  }
+
+  /* A Han excerpt's last baseline sits higher in its taller line. */
+  .blog-entry-link:has(> .blog-entry-description:lang(zh))::before {
+    inset-block-end: calc(0.625rem - var(--blog-marks-inset));
+  }
+
+  .blog-entry-meta {
+    display: flex;
+    flex-wrap: wrap;
+    column-gap: 0.5rem;
+    font-size: 0.8125rem;
+    line-height: 1rem;
+    color: var(--blog-text-quiet);
+
+    & > :nth-child(n + 2)::before {
+      margin-inline-end: 0.5rem;
+      color: var(--blog-text-faint);
+      content: '·';
+    }
+  }
+
+  /* Title and excerpt breathe like the articles' own text: a full step of air between them, double-leaded excerpts. */
+  .blog-entry-title {
+    margin: 1rem 0 0;
+    font-size: 1.5rem;
+    font-weight: var(--font-weight-regular);
+    line-height: 2.25rem;
+    letter-spacing: -0.015em;
+    color: var(--blog-title);
+    text-wrap: balance;
+    overflow-wrap: break-word;
+
+    /* Geist's stems stand 0.09em inside the glyph box: a Latin title steps out by about half of that, so its first
+       stem lines up with the date and the excerpt at 24px and 20px alike. */
+    &:not(:lang(zh)) {
+      margin-inline-start: -0.04em;
+    }
+
+    /*
+     * Han lines need a little more air than Latin ones (an untranslated title is marked lang="en"). Breaks fall at
+     * the spaces around Latin terms and after punctuation, never inside a phrase.
+     */
+    &:lang(zh) {
+      line-height: 2.5rem;
+      letter-spacing: 0;
+      word-break: keep-all;
+      text-autospace: normal;
+    }
+  }
+
+  /* A "Subject: question" title breaks at its colon, as the article does; a half that needs two lines wraps evenly. */
+  .blog-title-half {
+    display: block;
+  }
+
+  .blog-entry-description {
+    margin: 1rem 0 0;
+    font-size: 0.9375rem;
+    line-height: 1.875rem;
+    text-wrap: pretty;
+
+    /*
+     * Han body text reads best with a taller line. It has no spaces to break at, so it breaks between characters,
+     * with the strict rules that keep closing punctuation off a line's start (titles keep their phrases whole).
+     */
+    &:lang(zh) {
+      line-height: 2rem;
+      line-break: strict;
+    }
+  }
+
+  /*
+   * Only when the column is very narrow for its text (a small phone with enlarged text), Latin words hyphenate
+   * instead of breaking at an arbitrary letter; at normal sizes nothing is hyphenated.
+   */
+  @container blog-posts (width < 14em) {
+    .blog-entry :is(.blog-entry-title, .blog-entry-description):lang(en) {
+      hyphens: auto;
+    }
+  }
+
+  /* ---------- Phones ---------- */
+  /*
+   * One column: the time line keeps the column's left edge, the year sits above its posts on the line's right,
+   * and each year's rule crosses the line at the column's edge. A tap dims the entry for a moment.
+   */
+  @media (width < 48rem) {
+    .blog-year {
+      display: block;
+      padding-inline-start: var(--blog-indent);
+      border-top: 1px solid var(--blog-guide);
+
+      &::before {
+        position: absolute;
+        top: -6px;
+        left: -5px;
+        width: 11px;
+        height: 11px;
+        background: var(--blog-cross-mark);
+        pointer-events: none;
+        content: '';
+      }
+
+      &::after {
+        position: absolute;
+        inset: 0 auto 0 0;
+        border-inline-start: 1px solid var(--blog-guide);
+        content: '';
+      }
+    }
+
+    .blog-timeline-end {
+      display: block;
+    }
+
+    /* In the flow here, so its trimmed box is rounded back to whole pixels; its 2 steps out like the titles. */
+    .blog-year-label {
+      position: static;
+      height: round(up, 1cap, 1px);
+      margin-block: 2.5rem 0;
+      margin-inline-start: -0.02em;
+    }
+
+    /* The year sits closer to its posts than to the rule above it. */
+    .blog-year-posts {
+      position: static;
+      padding: 2rem 0 4rem;
+
+      &::before,
+      &::after {
+        display: none;
+      }
+    }
+
+    /* At 46px the hatch's smallest tile is coarser for the letters, so they get a little more room. */
+    .blog-masthead-title:not(:lang(zh)) {
+      letter-spacing: -0.02em;
+    }
+
+    .blog-entry-title {
+      font-size: 1.25rem;
+      line-height: 2rem;
+
+      &:lang(zh) {
+        line-height: 2.25rem;
+      }
+    }
+
+    .blog-entry-link {
+      --blog-marks-inset: 0.5rem;
+      width: auto;
+      transition: opacity var(--blog-base) var(--blog-ease);
+
+      &:active {
+        --blog-marks-inset: calc(0.5rem - 2px);
+        opacity: 0.64;
+        transition-duration: var(--blog-quick);
+      }
+    }
+  }
+
+  /* ---------- Preferences ---------- */
+  /* Same selectors as the rules they cancel, so specificity never lets a transition back in. */
+  @media (prefers-reduced-motion: reduce) {
+    .blog-entry::before,
+    .blog-entry:has(> .blog-entry-link:is(:hover, :focus-visible))::before,
+    .blog-entry-link,
+    .blog-entry-link::before,
+    .blog-entry-link:is(:hover, :focus-visible, :active)::before,
+    .blog-entry-link:hover:not(:focus-visible, :active)::before {
+      transition: none;
+    }
+  }
+
+  /* Paper is light: the index prints in light ink whatever the screen's scheme. */
+  @media print {
+    .blog-index {
+      color-scheme: light;
+      background-color: Canvas;
+    }
+
+    .blog-masthead {
+      padding-top: var(--spacing-xl);
+    }
+
+    .blog-year-label {
+      position: static;
+    }
+
+    /* A post is never split across two sheets of paper. */
+    .blog-entry {
+      break-inside: avoid;
+    }
+  }
+
+  @media (forced-colors: active), print {
+    .blog-index::before,
+    .blog-year-posts::after,
+    .blog-timeline-end::after {
+      display: none;
+    }
+
+    .blog-entry-link:hover:not(:focus-visible) {
+      outline: 1px solid CanvasText;
+      outline-offset: 0.375rem;
+    }
+  }
+
+  @media (forced-colors: active), print {
+    @media (width < 48rem) {
+      .blog-year::before {
+        display: none;
+      }
+    }
+
+    /* Without the drawn guides, each year keeps its rule as a border (on paper, as light as the time line). */
+    @media (--md) {
+      .blog-year {
+        border-top: 1px solid CanvasText;
+
+        @media print {
+          border-top-color: var(--blog-guide);
+        }
+      }
+    }
+  }
+}
+
+/*
+ * The header's and footer's rows share the drawing's column (--blog-frame), as the homepage's do, so the logo, the
+ * title, the years and the footer hang on one edge at every width, not only below 100rem. Unlayered: the footer
+ * rows carry a max-width utility, and utilities outrank the components layer.
+ */
+:root:has(.blog-index) :is(.ui-header, .ui-footer) > :not(hr) {
+  max-width: 95rem;
+}

package/src/styles/demo.css

@@ -0,0 +1,30 @@
+/* Demo family: compositions the system surfaces leave to the examples. Trays, stages, browsers and specimens live in styles/system. */
+@layer components {
+  /* Generated output closes the source panel: a native disclosure joined under the code window */
+  .ui-tray > .ui-disclosure { margin-top: var(--ui-inset); padding-inline: var(--ui-space-sm); border-radius: var(--ui-radius-xl); background: var(--ui-surface-code); }
+  .ui-tray > .ui-code:has(+ .ui-disclosure) { border-end-start-radius: 0; border-end-end-radius: 0; }
+  .ui-tray > .ui-code + .ui-disclosure { margin-top: 0; border-start-start-radius: 0; border-start-end-radius: 0; box-shadow: inset 0 1px 0 var(--ui-line-hair); }
+  .ui-tray > .ui-disclosure > :not(summary) { margin-inline: calc(var(--ui-space-sm) * -1); }
+  /* The panel's own padding is part of the summary's inset: its chevron starts where the code lines start. */
+  .ui-tray > details.ui-disclosure > summary { padding-inline: calc(var(--ui-space-md) - var(--ui-space-sm)); }
+  .ui-tray > .ui-disclosure .ui-code { border-radius: 0 0 var(--ui-radius-xl) var(--ui-radius-xl); background: transparent; box-shadow: inset 0 1px 0 var(--ui-line-hair); }
+
+  /* A copy group's instruction is a caption over its swatches, not a button's status: one start-aligned sans line. */
+  p.ui-copy > .ui-copy-status { max-width: none; color: var(--ui-text-muted); font: var(--ui-weight-regular) var(--ui-text-caption)/1.5 var(--font-family-sans); text-align: start; }
+
+  /* Playback starts paused before hydration; the player owns the native timelines afterwards */
+  [data-playback="paused"] * { animation-play-state: paused !important; }
+
+  /* Catalog: groups of closed recipes, each a complete example */
+  .ui-catalog > section { min-width: 0; margin-block: var(--ui-space-xl); }
+  .ui-catalog h3 { display: flex; flex-wrap: wrap; align-items: baseline; gap: var(--ui-space-sm); margin: 0 0 var(--ui-space-sm); color: var(--ui-text-strong); font-size: var(--ui-text-h3); font-weight: var(--ui-weight-heading); line-height: var(--ui-leading-h3); letter-spacing: var(--ui-tracking-h3); scroll-margin-top: 6rem; overflow-wrap: anywhere; }
+  .ui-catalog h3 > small { margin-left: auto; color: var(--ui-text-muted); font: var(--ui-weight-regular) .6875rem/1.5 var(--font-family-mono); letter-spacing: 0; }
+  .ui-catalog-entry { display: grid; gap: var(--ui-space-sm); min-width: 0; padding-bottom: var(--ui-space-md); }
+  .ui-catalog-entry > a { width: fit-content; color: var(--ui-text-body); font-size: .78125rem; text-decoration: underline; text-decoration-color: var(--ui-line-mark); text-underline-offset: .2em; }
+  .ui-catalog-entry > a:hover { color: var(--ui-text-strong); text-decoration-color: currentColor; }
+  .ui-catalog-entry > a:focus-visible { @apply --ui-focus-ring; outline-offset: 2px; border-radius: 3px; }
+
+  /* Skip link: hidden until focused, then a raised control */
+  .ui-skip:not(:focus) { position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
+  .ui-skip:focus { display: inline-flex; align-items: center; min-height: 2rem; margin-bottom: var(--ui-space-sm); padding: 0 var(--ui-space-sm); border-radius: 8px; background: var(--ui-surface-sheet); color: var(--ui-text-strong); box-shadow: var(--ui-elevation-rise-1); font-size: .78125rem; @apply --ui-focus-ring; outline-offset: 2px; }
+}

package/src/styles/design-system.css

@@ -0,0 +1,15 @@
+/* Design system handbook: wide reading pages whose sections hold complete trays and indexes. */
+@layer components {
+  .ui-handbook { --measure: 46rem; width: min(100%, 64rem); min-width: 0; margin-inline: auto; padding: 5rem 1.25rem 4rem; }
+  @media (width >= 48rem) { .ui-handbook { padding: 6.5rem 2.5rem 5rem; } }
+  .ui-handbook > .ui-pagehead > h1 { font-size: clamp(var(--ui-text-title), 4vw, var(--ui-text-display)); line-height: var(--ui-leading-display); letter-spacing: var(--ui-tracking-display); }
+  .ui-handbook-section { display: grid; gap: var(--ui-space-md); min-width: 0; margin-block: var(--ui-space-lg) var(--ui-space-2xl); }
+  .ui-handbook-section[data-columns="2"] { grid-template-columns: repeat(auto-fit, minmax(min(100%, 22rem), 1fr)); align-items: start; }
+  /* A section's framed surfaces hang like the article's own (prose.css), so specimens and usage code share both edges.
+     Two columns hang as one grid. */
+  .ui-prose > .ui-handbook-section:not([data-columns]) > :is(.ui-tray, .ui-code, .ui-table, .ui-params),
+  .ui-prose > .ui-handbook-section[data-columns="2"] { margin-inline: calc(var(--bleed) * -1); }
+  .ui-handbook-section > h3 { margin: var(--ui-space-md) 0 0; color: var(--ui-text-strong); font-size: var(--ui-text-base); font-weight: var(--ui-weight-heading); }
+  .ui-handbook-section > :is(h3, p):first-child { margin-top: 0; }
+  .ui-handbook-section > p { max-width: var(--measure); margin: 0; color: var(--ui-text-muted); font-size: var(--ui-text-small); line-height: var(--ui-leading-small); }
+}

package/src/styles/docs-shell/code.css

@@ -0,0 +1,61 @@
+/*
+ * Code panels (`ui-code`, styles/system/code.css) as the site renders them: Shiki lines are `ui-code-line` parts, the
+ * copy action sits in the bar or, without one, in the corner, and tab panels all show on paper and without scripts.
+ */
+@layer components {
+  /* The file's name keeps its width; a long result wraps in the room left beside the copy button. */
+  .ui-code-bar > .ui-code-file { flex: 1 0 auto; }
+  .ui-code-bar > .ui-copy { flex: 0 1 auto; min-width: 0; margin-left: auto; }
+  /* Without a bar the copy takes the panel's corner (`--code-corner`, code.css). A long line scrolls under it: the panel's own face fades in behind the button and runs to the edge, so code never runs through it. */
+  .ui-code > .ui-copy { position: absolute; z-index: 1; top: var(--code-corner); right: var(--code-corner); padding-left: var(--ui-space-sm); border-radius: var(--ui-radius-md); background: linear-gradient(90deg, transparent, var(--ui-surface-code) var(--ui-space-sm));
+    /* The face runs on to the panel's contour (1px short of the edge), so a scrolled line never shows again past the button. */
+    box-shadow: calc(var(--code-corner) - 1px) 0 0 var(--ui-surface-code); }
+  .ui-code:has(> .ui-copy) .ui-code-line { padding-right: 3rem; }
+  /* A shell command is read whole: it wraps under a hanging indent instead of hiding its flags behind the copy button. */
+  :is(.ui-code, [role="tabpanel"])[data-lang="bash"] > pre, .ui-code[data-lang="sh"] > pre, .ui-code[data-lang="shell"] > pre { white-space: pre-wrap; overflow-wrap: anywhere; }
+  :is(.ui-code, [role="tabpanel"])[data-lang="bash"] > pre .ui-code-line, .ui-code:is([data-lang="sh"], [data-lang="shell"]) > pre .ui-code-line { padding-left: calc(var(--ui-space-md) + 2ch); text-indent: -2ch; }
+  /* Flags wrap whole: a token never breaks at its own hyphen, so `--yes` cannot split into `-` and `-yes`. */
+  :is(.ui-code, [role="tabpanel"])[data-lang="bash"] > pre .ui-code-line > span, .ui-code:is([data-lang="sh"], [data-lang="shell"]) > pre .ui-code-line > span { display: inline-block; text-indent: 0; }
+  /* Plain text, such as a prompt for an agent, is prose set in mono: it wraps at the panel like prose. */
+  :is(.ui-code, [role="tabpanel"])[data-lang="text"] > pre { white-space: pre-wrap; overflow-wrap: break-word; }
+  .ui-copy-status:empty { display: none; }
+
+  /* A Generated CSS disclosure right after its source closes the same panel: one frame, the output under a hairline,
+     as in a demo tray. Alone (after a table or a paragraph) it stays a quiet disclosure. */
+  .ui-prose > .ui-code:has(+ .ui-disclosure[data-generated]) { margin-bottom: 0; border-end-start-radius: 0; border-end-end-radius: 0; box-shadow: inset 1px 0 0 var(--ui-line-contour), inset -1px 0 0 var(--ui-line-contour), inset 0 1px 0 var(--ui-line-contour); }
+  .ui-prose > .ui-code + .ui-disclosure[data-generated] {
+    max-width: none; margin-top: 0; margin-inline: calc(var(--bleed) * -1); padding-inline: var(--ui-space-md);
+    border-radius: 0 0 var(--ui-radius-xl) var(--ui-radius-xl); background: var(--ui-surface-code);
+    box-shadow: inset 0 0 0 1px var(--ui-line-contour), 0 1px 0 var(--ui-lip);
+  }
+  .ui-prose > .ui-code + .ui-disclosure[data-generated] > summary { margin-inline: calc(var(--ui-space-md) * -1); padding-inline: var(--ui-space-md); box-shadow: inset 0 1px 0 var(--ui-line-hair); }
+  .ui-prose > .ui-code + .ui-disclosure[data-generated] > .ui-code { margin-inline: calc(var(--ui-space-md) * -1); border-radius: 0 0 var(--ui-radius-xl) var(--ui-radius-xl); background: transparent; box-shadow: inset 0 1px 0 var(--ui-line-hair); }
+  .ui-copy > .ui-copy-status { min-width: 0; max-width: 16rem; text-align: end; line-height: 1.3; }
+
+  /* @WARN and @ERROR marks: a wavy underline in the status tone instead of a wash. */
+  .ui-code-line mark[data-tone] { padding: 0; background: none; box-shadow: none; text-decoration: underline wavy 1px; text-underline-offset: 3px; }
+  .ui-code-line mark[data-tone="warning"] { text-decoration-color: var(--ui-status-warning); }
+  .ui-code-line mark[data-tone="danger"] { text-decoration-color: var(--ui-status-danger); }
+  /* [!code focus] blurs the other lines until the pointer reaches the code. */
+  .ui-code pre.has-focused .ui-code-line { transition: filter var(--ui-duration-base) var(--ui-ease); }
+  .ui-code pre.has-focused:not(:hover, :focus-visible) .ui-code-line:not(.focus) { filter: blur(3px); }
+  .ui-code ::selection { background: color-mix(in oklab, var(--ui-code-function) 22%, transparent); }
+
+  [data-code-tabs] > [role="tabpanel"] > .ui-code-file { display: none; }
+  @media (scripting: none), print {
+    [data-code-tabs] > .ui-code-bar { display: none; }
+    [data-code-tabs] > [role="tabpanel"][hidden] { display: block; }
+    [data-code-tabs] > [role="tabpanel"] > .ui-code-file { display: flex; padding: var(--ui-space-sm) var(--ui-space-md) 0; }
+    .ui-copy { display: none; }
+  }
+  @media print {
+    .ui-code { break-inside: avoid; }
+    /* Paper cannot scroll: keep complete commands and long source lines readable. */
+    .ui-code pre { overflow: visible; white-space: pre-wrap; overflow-wrap: anywhere; }
+    .ui-code pre.has-focused .ui-code-line { filter: none; }
+  }
+  @media (prefers-reduced-motion: reduce) { .ui-code pre.has-focused .ui-code-line { transition: none; } }
+  @media (forced-colors: active) { .ui-code { border: 1px solid CanvasText; } }
+
+  .ui-tree img { flex: none; align-self: center; width: 14px; height: 14px; }
+}