@master/internal-site 0.0.0-stage → 0.1.0

package/src/styles/blog-article.css

@@ -0,0 +1,670 @@
+/*
+ * Blog post pages: what is a post's own. The text itself reads with the documentation's typography
+ * (`docs-shell/prose.css`, code wells in `docs-shell/code.css`) and its contents with the shared contents ruler
+ * (`ui-toc`, `docs-shell/page-content.css`); this sheet places them and draws the post's header and close.
+ *
+ * - The article is a framed drawing, as the homepage frames its sections (`.blog-rails`, `.blog-rails-rule` from
+ *   blog-materials.css): the frame is the reading column and the room its wells bleed into; rails with rulers run just
+ *   outside it, and a rule crossed at the rails opens the text and the close, the long ticks restarting at each.
+ * - The contents ruler stands outside the drawing, in the page's left margin; narrower screens get the documentation's
+ *   contents disclosure in the text instead.
+ * - One fixed, soft light falls from above and to the left, felt in a faint lift of the ground at the top of the page.
+ * - The title carries a trace of stone (`.blog-stone-text`): obsidian in light mode, moonstone in dark mode.
+ * - No gold of its own: the contents' live mark is ink, like the documentation's.
+ */
+
+@layer components {
+  .blog-article-page {
+    /* The page's margin outside the frame; the frame itself carries the room the wells bleed into. */
+    --blog-article-gutter: 0rem;
+    /* The room the frame keeps on each side of the text, which code, examples, media and the next read bleed into. */
+    --blog-article-bleed: 1.25rem;
+    /* The documentation's reading measure (`--docs-text`): the text keeps it while the frame around it widens. */
+    --blog-article-measure: 41rem;
+    /* How far wide surfaces hang past the text: the documentation's 2rem, never past the frame; none on phones. */
+    --blog-article-hang: 0rem;
+    /* Strong ink is the shared title tone (soft obsidian / moonstone), so nothing on the page is pure black or white. */
+    --blog-article-text: var(--blog-title, var(--color-text-strong));
+    --blog-article-body: var(--color-text-body);
+    --blog-article-quiet: var(--color-text-muted);
+    --blog-article-faint: color-mix(in oklab, var(--color-text-muted) 72%, var(--color-text-subtle));
+    --blog-article-rule: var(--color-line-divider);
+    /* Motion follows the shared layer, so a hover settles at the same unhurried pace as on the blog index. */
+    --blog-article-ease: var(--blog-ease, cubic-bezier(0.25, 0.1, 0.25, 1));
+    --blog-article-base: var(--blog-base, 360ms);
+    --blog-article-slow: var(--blog-slow, 720ms);
+    /* The light from above-left, felt as a faint lift of the ground at the top of the page. */
+    background-image: radial-gradient(ellipse 130% 100% at 0% -25%, light-dark(rgb(255 255 255 / 0.7), rgb(255 255 255 / 0.025)), transparent 80%);
+    background-size: 100% min(110vh, 64rem);
+    background-repeat: no-repeat;
+
+    /* From 40rem the text keeps 2.5rem from the screen's edge, as on the index, and the wells stop short of it. */
+    @media (width >= 40rem) {
+      --blog-article-gutter: calc(2.5rem - var(--blog-article-bleed));
+      --blog-article-hang: min(2rem, var(--blog-article-bleed));
+    }
+
+    @media (--sm) {
+      --blog-article-bleed: 1.5rem;
+    }
+
+    /* Room for a rail and its ruler (2rem) outside the frame, and air beyond them, as on the index. The frame opens
+       wide around the measure, so surfaces hang well past the text while the text keeps its width. */
+    @media (--md) {
+      --blog-article-bleed: 5rem;
+      --blog-article-gutter: 3.5rem;
+    }
+  }
+
+  /* ───────────────────────── Frame ───────────────────────── */
+
+  /*
+   * The frame is the reading column and the room its wells bleed into, centred on a whole pixel so the rails and
+   * rules never straddle two. The article is a grid across the page: the frame in the middle, the contents ruler in
+   * the outer left margin beside the text. The container is the page's own room, in rem, so enlarged text keeps one
+   * column.
+   */
+  .blog-article-main {
+    --frame: min(100%, var(--blog-article-measure) + var(--blog-article-bleed) * 2);
+    container: blog-article / inline-size;
+    padding-inline: var(--blog-article-gutter);
+
+    & > .blog-article-end {
+      max-width: var(--frame);
+      margin-inline-start: max(0px, round(down, (100% - var(--frame)) / 2, 1px));
+    }
+  }
+
+  .blog-article {
+    display: grid;
+    grid-template-columns: max(0px, round(down, (100% - var(--frame)) / 2, 1px)) var(--frame) minmax(0, 1fr);
+
+    & > :is(.blog-article-masthead, .blog-article-body) {
+      grid-column: 2;
+    }
+  }
+
+  .blog-article-body,
+  .blog-article-end {
+    padding-inline: var(--blog-article-bleed);
+  }
+
+  /* ───────────────────────── Masthead ───────────────────────── */
+
+  .blog-article-masthead {
+    position: relative;
+    min-width: 0;
+    /* The post's first lines still sit in the first screen. The header steps out of the text column to the wide
+       surfaces' edge, so it opens the drawing closer to the rails than the reading does. */
+    padding: calc(3.75rem + round(clamp(3rem, 1.5rem + 4vw, 5rem), 1rem)) calc(var(--blog-article-bleed) - var(--blog-article-hang)) round(clamp(2.5rem, 1.75rem + 2vw, 3.5rem), 1rem);
+    grid-row: 1;
+
+    @media (width >= 48rem) and (height < 50rem) {
+      padding-top: 7.5rem;
+    }
+  }
+
+  /* As in the homepage hero and on the index, the rails start below the fixed header and fade in. They start at 4rem
+     rather than the header's 60px, so the ruler's ticks fall on whole rem from the page's top and the last tick above
+     each crossed rule meets the cross instead of doubling it 4px higher. */
+  @media (--md) {
+    .blog-article-masthead.blog-rails::after {
+      top: 4rem;
+      mask-image: linear-gradient(transparent, black 6rem);
+    }
+  }
+
+  /* The category and date are the post's kicker: an eyebrow, as the documentation's page head opens. */
+  .blog-article-meta {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: baseline;
+    gap: 0.25rem 0.75rem;
+    margin: 0;
+    color: var(--blog-article-quiet);
+    @apply --ui-eyebrow-type;
+
+    & > * + *::before {
+      margin-right: 0.75rem;
+      color: var(--blog-article-faint);
+      content: '·' / '';
+    }
+
+    & time {
+      font-variant-numeric: tabular-nums;
+    }
+  }
+
+  /*
+   * The title, regular weight in the shared title tone, nearly twice the section titles' size (54px on desktops, 48px
+   * before; at 54px "choose when to generate CSS" still holds one line). A "Subject: question" title breaks at its
+   * colon; a half longer than the column wraps evenly.
+   */
+  .blog-article-title {
+    min-width: 0;
+    margin: 1.25rem 0 0;
+    font-size: clamp(1.75rem, 1.25rem + 2vw, 2.75rem);
+    font-weight: 400;
+    line-height: 1.12;
+    letter-spacing: -0.034em;
+    color: var(--blog-article-text);
+    text-wrap: balance;
+    overflow-wrap: anywhere;
+
+    /* Display tracking opens a little at phone sizes, where it starts to crowd the letters. */
+    @media (width < 40rem) {
+      letter-spacing: -0.024em;
+    }
+
+    &:lang(zh) {
+      letter-spacing: -0.01em;
+      word-break: keep-all;
+      /* Full-width punctuation that opens a line, or meets another, is set half-width, so it leaves no gap. */
+      text-spacing-trim: trim-start;
+      text-autospace: normal;
+    }
+  }
+
+  .blog-article-title-line {
+    display: block;
+  }
+
+  .blog-article-dek {
+    max-width: 34em;
+    margin: 1.5rem 0 0;
+    font-size: clamp(1.0625rem, 1rem + 0.25vw, 1.125rem);
+    /* Supporting text in italic (Geist has no italic face; the browser slants the roman), a step quieter than the
+       reading. Han text stays upright. */
+    font-style: italic;
+    line-height: 1.9;
+    color: var(--blog-article-quiet);
+    /* Balanced, so a last pair of words never hangs alone; on a phone balancing four lines would only narrow them. */
+    text-wrap: balance;
+
+    @media (width < 40rem) {
+      text-wrap: pretty;
+    }
+
+    &:lang(zh) {
+      font-style: normal;
+      line-height: 1.95;
+    }
+  }
+
+  .blog-article-byline {
+    margin-top: 1.75rem;
+  }
+
+  /* Portraits and names already say who wrote the post; the label stays for assistive technology. */
+  .blog-article-byline-label {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+
+  .blog-article-authors {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.25rem 1.25rem;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .blog-article-author {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.625rem;
+    min-height: 2.75rem;
+    font-size: 0.875rem;
+    /* Names are quiet links, a step under the title; they take full ink only under the pointer. */
+    color: var(--blog-article-body);
+    text-decoration: none;
+    transition: color var(--blog-article-base) var(--blog-article-ease);
+
+    &[href]:hover {
+      color: var(--blog-article-text);
+    }
+
+    & span {
+      text-decoration: underline;
+      text-decoration-thickness: 1px;
+      text-decoration-color: transparent;
+      text-underline-offset: 0.24em;
+      transition: text-decoration-color var(--blog-article-base) var(--blog-article-ease);
+    }
+
+    &[href]:hover span {
+      text-decoration-color: color-mix(in oklab, currentColor 40%, transparent);
+    }
+
+    &:focus-visible {
+      border-radius: 0.375rem;
+      outline: 2px solid var(--color-focus);
+      outline-offset: 2px;
+    }
+  }
+
+  .blog-article-avatar {
+    display: block;
+    width: 1.75rem;
+    height: 1.75rem;
+    margin: 0;
+    border-radius: 50%;
+    object-fit: cover;
+    box-shadow: 0 0 0 1px var(--color-line-contour), 0 1px 2px light-dark(oklch(0.18 0 none / 0.08), rgb(0 0 0 / 0.35));
+  }
+
+  /* ───────────────────────── Reading column ───────────────────────── */
+
+  /* Each section is a whole number of rem tall where the browser can say so, so the 16px ruler ticks run on
+     unbroken across the crossed rules; only the long ticks restart at each section, as a ruler set to a new origin. */
+  @supports (height: calc-size(auto, size)) {
+    .blog-article-masthead,
+    .blog-article-body {
+      height: calc-size(auto, round(up, size, 1rem));
+    }
+  }
+
+  /* The bottom room belongs to the section, so the contents ruler comes to rest above the closing rule. Below md the
+     rails are not drawn; a hairline across the frame still closes the header. */
+  .blog-article-body {
+    grid-row: 2;
+    padding-block: round(clamp(2.5rem, 1.75rem + 2vw, 3.5rem), 1rem) round(clamp(3rem, 2rem + 3vw, 5rem), 1rem);
+
+    @media (width < 64rem) {
+      border-top: 1px solid var(--blog-guide, var(--color-line-subtle));
+    }
+  }
+
+  /* Surfaces hang past the text as in the documentation, short of the frame, and keep their own padding; on phones
+     they stay on the text. (0,2,0)
+     outranks the shared prose's own bleed. */
+  .blog-article-prose.ui-prose {
+    --prose-bleed: 0rem;
+    min-width: 0;
+
+    @media (width >= 40rem) {
+      --prose-bleed: var(--blog-article-hang);
+    }
+
+    & > :first-child {
+      margin-top: 0;
+    }
+  }
+
+  /* ───────────────────────── Contents ───────────────────────── */
+
+  /*
+   * In the outer left margin the contents ruler hangs on the header logo's edge and stays beside the text being read,
+   * clear of the rails and their rulers. Narrower (below a 1392px window), the contents disclosure the post places in
+   * its text stands in.
+   */
+  .blog-article-contents {
+    display: none;
+  }
+
+  @container blog-article (width >= 80rem) {
+    .blog-article-contents {
+      /* Its ticks start on the header logo's edge, without the documentation rail's inset, so the titles keep their
+         room beside the wide frame; air is kept before the left ruler (2rem outside the frame). The caption sits on
+         the first line of text. */
+      --edge: 2rem;
+      --air: 1.5rem;
+      grid-column: 1;
+      grid-row: 2;
+      position: sticky;
+      top: 6.5rem;
+      display: block;
+      align-self: start;
+      justify-self: start;
+      width: min(17rem, 100% - (var(--edge) - var(--blog-article-gutter)) - 2rem - var(--air));
+      max-height: calc(100dvh - 8.5rem);
+      margin: round(clamp(2.5rem, 1.75rem + 2vw, 3.5rem), 1rem) 0 0 calc(var(--edge) - var(--blog-article-gutter));
+      padding: 0.5rem 0 var(--ui-space-xl);
+      overflow-y: auto;
+      overscroll-behavior: contain;
+    }
+
+    /* Beside the margin contents, the post's own contents disclosure would only repeat them. */
+    .blog-article-prose [data-contents-disclosure] {
+      display: none;
+    }
+
+    /* With the disclosure hidden, the section after it takes its own hairline again. */
+    .blog-article-prose > [data-contents-disclosure] + hr + a[id]:empty + h2,
+    .blog-article-prose > [data-contents-disclosure] + hr + h2,
+    .blog-article-prose > [data-contents-disclosure] + h2 {
+      --section-rule: block;
+    }
+  }
+
+  /* Below the margin contents, the post's contents disclosure stands in (whatever the documentation's own switch
+     width); it is already a row between two hairlines, so the section rule the post sets right after it would make a
+     third line. */
+  @container blog-article (width < 80rem) {
+    .blog-article-prose [data-contents-disclosure] {
+      display: block;
+    }
+
+    .blog-article-prose > [data-contents-disclosure] + hr {
+      display: none;
+    }
+  }
+
+  @container blog-article (width >= 88rem) {
+    .blog-article-contents {
+      --air: 2.5rem;
+    }
+  }
+
+  /* ───────────────────────── End of post ───────────────────────── */
+
+  /* The close mirrors the header: it steps out to the wide surfaces' edge, as the masthead does. */
+  .blog-article-end {
+    padding-top: round(clamp(3rem, 2rem + 2.5vw, 4.5rem), 1rem);
+    padding-bottom: round(clamp(5rem, 3rem + 6vw, 8rem), 1rem);
+
+    @media (width >= 40rem) {
+      padding-inline: calc(var(--blog-article-bleed) - var(--blog-article-hang));
+    }
+
+    @media (width < 64rem) {
+      border-top: 1px solid var(--blog-guide, var(--color-line-subtle));
+    }
+  }
+
+  /* The post's guides fade out above the footer rather than running into it. */
+  @media (--md) {
+    .blog-article-end.blog-rails::after {
+      mask-image: linear-gradient(black calc(100% - 7rem), transparent);
+    }
+  }
+
+  .blog-article-end-title {
+    margin: 0 0 2.5rem;
+    color: var(--blog-article-quiet);
+    @apply --ui-eyebrow-type;
+  }
+
+  /*
+   * The next read is an open title, not a card: the meta as the header's kicker, the title in the post's own tone a
+   * step under the post's title, the description in the dek's italic. Under the pointer the index's artboard corners
+   * draw around it and the arrow steps on; keyboard focus closes the corners into a frame.
+   */
+  .blog-article-next {
+    --blog-marks-inset: 1rem;
+    display: grid;
+    width: fit-content;
+    max-width: min(100%, 38rem);
+    color: var(--blog-article-text);
+    text-decoration: none;
+
+    &::before {
+      opacity: 0;
+      transition: opacity var(--blog-article-slow) var(--blog-article-ease), inset var(--blog-article-base) var(--blog-article-ease);
+    }
+
+    &:is(:hover, :focus-visible)::before {
+      opacity: 1;
+      transition-duration: var(--blog-article-base);
+    }
+
+    &:active {
+      --blog-marks-inset: calc(1rem - 2px);
+    }
+
+    &:is(:hover, :focus-visible) .blog-article-next-arrow {
+      color: var(--blog-article-text);
+      translate: 4px 0;
+      transition-duration: var(--blog-article-base);
+    }
+
+    &:focus-visible {
+      outline: 2px solid transparent;
+
+      &::before {
+        background: none;
+        outline: 2px solid var(--blog-article-faint);
+        outline-offset: -2px;
+      }
+    }
+  }
+
+  .blog-article-next-meta {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.25rem 0.75rem;
+    color: var(--blog-article-quiet);
+    @apply --ui-eyebrow-type;
+
+    & > * + *::before {
+      margin-right: 0.75rem;
+      color: var(--blog-article-faint);
+      content: '·' / '';
+    }
+
+    & time {
+      font-variant-numeric: tabular-nums;
+    }
+  }
+
+  .blog-article-next-title {
+    margin-top: 1rem;
+    color: var(--blog-article-text);
+    font-size: clamp(1.5rem, 1.25rem + 1vw, 2rem);
+    font-weight: 400;
+    line-height: 1.2;
+    letter-spacing: -0.026em;
+    text-wrap: balance;
+
+    &:lang(zh) {
+      letter-spacing: -0.01em;
+      word-break: keep-all;
+    }
+  }
+
+  /* The first half of a "Subject: question" title takes its own line; the arrow follows the last word. */
+  .blog-article-next-title-line:first-child:not(:last-of-type) {
+    display: block;
+  }
+
+  .blog-article-next-arrow {
+    display: inline-block;
+    margin-left: 0.3em;
+    vertical-align: -0.12em;
+    color: var(--blog-article-faint);
+    transition: translate var(--blog-article-slow) var(--blog-article-ease), color var(--blog-article-slow) var(--blog-article-ease);
+  }
+
+  /* As the header's dek: supporting text in the same italic, a step smaller. */
+  .blog-article-next-description {
+    max-width: 34em;
+    margin-top: 0.875rem;
+    color: var(--blog-article-quiet);
+    font-size: 0.9375rem;
+    font-style: italic;
+    line-height: 1.85;
+    text-wrap: pretty;
+
+    &:lang(zh) {
+      font-style: normal;
+      line-height: 1.9;
+    }
+  }
+
+  /* The way back and the other neighbour close the drawing under one hairline. */
+  .blog-article-end-links {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: space-between;
+    gap: var(--spacing-sm) var(--spacing-lg);
+    margin-top: 3.5rem;
+    padding-top: 0.5rem;
+    box-shadow: inset 0 1px 0 var(--blog-guide, var(--color-line-subtle));
+  }
+
+  .blog-article-end-link {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--spacing-xs);
+    min-height: 2.75rem;
+    min-width: 0;
+    font-size: 0.875rem;
+    color: var(--blog-article-quiet);
+    transition: color var(--blog-article-base) var(--blog-article-ease);
+
+    & svg {
+      flex: none;
+      transition: translate var(--blog-article-base) var(--blog-article-ease);
+    }
+
+    &:hover {
+      color: var(--blog-article-text);
+
+      & svg:first-child {
+        translate: -2px 0;
+      }
+
+      & svg:last-child:not(:first-child) {
+        translate: 2px 0;
+      }
+    }
+
+    &:focus-visible {
+      border-radius: 2px;
+      outline: 2px solid var(--color-focus);
+      outline-offset: 2px;
+    }
+  }
+
+  .blog-article-end-link-label {
+    flex: none;
+    color: var(--blog-article-quiet);
+  }
+
+  .blog-article-end-link-title {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  /* ───────────────────────── Preferences, contrast and print ───────────────────────── */
+
+  /* Every transition here is timed by these two tokens, so asking for less motion stills them all at once. */
+  @media (prefers-reduced-motion: reduce) {
+    .blog-article-page {
+      --blog-article-base: 0s;
+      --blog-article-slow: 0s;
+    }
+  }
+
+  /* Asked for more contrast, annotations take the body's gray. */
+  @media (prefers-contrast: more) {
+    .blog-article-page {
+      --blog-article-text: var(--color-text-strong);
+      --blog-article-faint: var(--color-text-body);
+      --blog-article-quiet: var(--color-text-body);
+    }
+
+    /* Plain ink; the shared title tone is outranked from the masthead, whatever order the stylesheets load in. */
+    .blog-article-masthead .blog-article-title {
+      background-image: none;
+      -webkit-text-fill-color: currentColor;
+    }
+  }
+
+  @media (forced-colors: active) {
+    .blog-article-masthead .blog-article-title {
+      color: CanvasText;
+      background-image: none;
+      -webkit-text-fill-color: currentColor;
+    }
+
+    /* The corners are hidden here: the next read keeps an outline under the pointer and on focus. */
+    .blog-article-page .blog-article-next:is(:hover, :focus-visible) {
+      outline: 1px solid CanvasText;
+      outline-offset: 0.75rem;
+    }
+
+    .blog-article-body,
+    .blog-article-end {
+      border-top: 1px solid CanvasText;
+    }
+  }
+
+  @media print {
+    .blog-article-page {
+      color-scheme: light;
+      background: none;
+    }
+
+    .blog-article-contents,
+    .blog-article-end,
+    .blog-article-footer {
+      display: none;
+    }
+
+    .blog-article-main {
+      padding: 0;
+    }
+
+    .blog-article {
+      display: block;
+    }
+
+    .blog-article-body {
+      height: auto;
+      padding: 1.5rem 0 0;
+      border-top: 1px solid #ccc;
+    }
+
+    .blog-article-masthead {
+      height: auto;
+      padding: 0 0 1.25rem;
+    }
+
+    .blog-article-masthead .blog-article-title {
+      margin-right: 0;
+      font-size: 2rem;
+      color: #000;
+      background: none;
+      -webkit-text-fill-color: currentColor;
+    }
+
+    .blog-article-byline {
+      margin-top: 0.75rem;
+    }
+
+    .blog-article-prose {
+      color: #222;
+
+      & a {
+        color: inherit;
+      }
+    }
+  }
+}
+
+/* The page ground runs under the overscroll and behind the footer. */
+:root:has(.blog-article-page),
+:root:has(.blog-article-page) > body {
+  background-color: light-dark(var(--color-zinc-0), var(--color-zinc-95));
+  background-image: none;
+}
+
+/* Paper is white whatever the screen's scheme: every token resolves its light value. */
+@media print {
+  :root:has(.blog-article-page) {
+    color-scheme: light;
+  }
+
+  :root:has(.blog-article-page),
+  :root:has(.blog-article-page) > body {
+    background-color: #fff;
+  }
+}