Article Body - defuss-shadcn

On this page (6)

Component Skill — components/article-body/component-skill.md

Native basis

One wrapper around plain HTML - the elements a CMS or Markdown renderer emits, no classes needed inside: headings, paragraphs, links, lists, <blockquote>, code, tables, <figure>, <video> and <iframe> embeds, at a 42rem measure.

Built from

Code Mockup, Alert, Table, Image, Kbd, Heading Anchor, TOC, Badge.

Web Platform APIs

hanging-punctuationtext-wrap: pretty::first-letteraspect-ratioscroll-marginanimation-timeline: scroll()

Classes

.mk-article-body.mk-article-body-pullquote.mk-article-body-lead.mk-article-body-note.mk-article-body-ref.mk-article-body-footnotes.mk-article-body-wide.mk-article-body-layout.mk-article-body-progress

Data attributes

data-variant="serif", data-size (sm, lg), data-dropcap; .mk-article-body-note (callout), .mk-article-body-wide (a wider figure); .mk-article-body-lead, .mk-article-body-pullquote, .mk-article-body-ref + .mk-article-body-footnotes, .mk-article-body-layout (beside a TOC), .mk-article-body-progress.

§Default

A lead paragraph, Heading Anchors (§), a footnote ref, del / ins, a pull quote, Kbd keys, a Code Mockup with a diff, an Alert callout, a Table with Badges, an Image with its caption, a definition list and the footnotes - the components keep their own look, the prose rules only style class-less elements. Click the footnote 1: it jumps to the note and back.

<div class="mk-article-body">
  <p class="mk-article-body-lead">Sync is the feature nobody notices until it fails. For Acme 4.0 we set one rule: <strong>never lose a keystroke</strong> - online, offline, or somewhere in between.</p>
  <h2 id="why-crdts"><a class="heading-anchor" href="#why-crdts" aria-label="Link to section: Why CRDTs">§</a>Why CRDTs</h2>
  <p>A <abbr title="conflict-free replicated data type">CRDT</abbr> lets two devices edit the same document without a server deciding who wins.<span class="mk-article-body-ref"><a href="#fn-1" id="ref-1" aria-label="Footnote 1">1</a></span> Every change is an operation; every operation <a href="#">commutes</a>. We <del>resolve conflicts</del> <ins>never create them</ins>.</p>
  <blockquote class="mk-article-body-pullquote">The best sync is the one you forget is there.</blockquote>
  <h2 id="the-log"><a class="heading-anchor" href="#the-log" aria-label="Link to section: The log">§</a>The write-ahead log</h2>
  <p>Every operation lands in a local log before it touches the document. Press <kbd class="kbd">⌘</kbd> <kbd class="kbd">S</kbd>? You never have to. The flush is three lines:</p>
  <div class="mockup-code" data-title="sync/flush.ts" data-numbers>
    <pre><code>const ops = log.since(cursor);</code></pre>
    <pre data-diff="remove"><code>await server.push(ops);</code></pre>
    <pre data-diff="add"><code>await server.push(ops, { idempotent: true });</code></pre>
    <pre><code>cursor = ops.at(-1).id;</code></pre>
  </div>
  <div class="alert" role="note">
    <svg class="alert-icon" xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><path d="M12 16v-4M12 8h.01"/></svg>
    <div class="alert-content">
      <h5 class="alert-title">Offline for a month?</h5>
      <p class="alert-description">Edits older than 30 days merge as a branch - never silently.</p>
    </div>
  </div>
  <div class="table-container">
    <table class="table">
      <thead><tr class="table-row"><th class="table-head">Scenario</th><th class="table-head">Before</th><th class="table-head">4.0</th></tr></thead>
      <tbody>
        <tr class="table-row"><td class="table-cell">Edit offline, reconnect</td><td class="table-cell">Last write wins</td><td class="table-cell"><span class="badge" data-variant="secondary">Merged</span></td></tr>
        <tr class="table-row"><td class="table-cell">Two people, one paragraph</td><td class="table-cell">Conflict dialog</td><td class="table-cell"><span class="badge" data-variant="secondary">Merged</span></td></tr>
      </tbody>
    </table>
  </div>
  <figure class="image" data-ratio="16/9">
    <img src="images/mk-wide2.png" alt="Two laptops editing the same document">
    <figcaption class="image-caption">Two replicas, one document - merged without a server round trip.</figcaption>
  </figure>
  <h3>Glossary</h3>
  <dl>
    <dt>Replica</dt><dd>One device's copy of the document.</dd>
    <dt>Operation</dt><dd>One change - an insert, a delete, a format.</dd>
    <dt>Cursor</dt><dd>The last operation the server has acknowledged.</dd>
  </dl>
  <aside class="mk-article-body-footnotes" aria-label="Footnotes">
    <ol>
      <li id="fn-1">Shapiro et al., "Conflict-free replicated data types", 2011. <a href="#ref-1" aria-label="Back to the text">↩</a></li>
    </ol>
  </aside>
</div>

§Plain HTML (CMS output)

What a CMS or Markdown renderer emits - headings, a list, a quote, inline and block code, a figure, a callout (.mk-article-body-note), a table, a video and a rule. No classes on the elements.

<div class="mk-article-body">
  <p>Sync is the feature nobody notices until it fails. When we started on Acme 4.0, our goal was simple to state and hard to build: <strong>never lose a keystroke</strong>, online or off.</p>
  <h2>Why CRDTs</h2>
  <p>A conflict-free replicated data type lets two devices edit the same document without a server deciding who wins. Every change is an operation; every operation <a href="#">commutes</a>. Merging becomes a set union.</p>
  <ul>
    <li>Edits apply instantly, on any device</li>
    <li>The server stores operations, not documents</li>
    <li>Any two replicas converge - in any order</li>
  </ul>
  <blockquote>
    <p>The best sync is the one you forget is there.</p>
    <cite>Hannah Lee, Design</cite>
  </blockquote>
  <h3>The write-ahead log</h3>
  <p>Every operation lands in a local log before it touches the document. Call <code>flush()</code> and the log ships in batches:</p>
  <div class="mockup-code" data-title="sync/flush.ts" data-numbers>
    <pre><code>const ops = log.since(cursor);</code></pre>
    <pre><code>await server.push(ops);</code></pre>
    <pre><code>cursor = ops.at(-1).id;</code></pre>
  </div>
  <figure>
    <img src="images/mk-wide2.png" alt="Two laptops editing the same document">
    <figcaption>Two replicas, one document - merged without a server round trip.</figcaption>
  </figure>
  <aside class="mk-article-body-note"><p><strong>Note:</strong> offline edits older than 30 days are merged as a branch, never silently.</p></aside>
  <table>
    <thead><tr><th scope="col">Scenario</th><th scope="col">Before</th><th scope="col">4.0</th></tr></thead>
    <tbody>
      <tr><td>Edit offline, reconnect</td><td>Last write wins</td><td>Merged</td></tr>
      <tr><td>Two people, one paragraph</td><td>Conflict dialog</td><td>Merged</td></tr>
    </tbody>
  </table>
  <figure>
    <video src="videos/demo.mp4" controls muted playsinline preload="metadata" aria-label="Sync demo"></video>
    <figcaption>Press <kbd>⌘</kbd> <kbd>S</kbd>? You never have to.</figcaption>
  </figure>
  <hr>
  <p>Next week: how we test sync with a <mark>simulated network</mark> that loses one packet in ten.</p>
</div>

§Serif with a drop cap

data-variant='serif' sets the running text in the serif stack (headings stay sans); data-dropcap opens the first paragraph.

§Sizes

data-size='sm' for dense docs, 'lg' (19px, a wider measure) for long reads.

§Beside a table of contents, with reading progress

The text in .mk-article-body-layout beside a sticky TOC component (from 56rem - narrow the demo and it hides). Scroll the box: .mk-article-body-progress fills as you read - a scroll-driven animation, no script.

<div class="mk-article-body-layout">
  <nav class="toc" aria-label="On this page">
    <p class="toc-title">On this page</p>
    <a class="toc-link" href="#tc-intro" aria-current="location">Introduction</a>
    <a class="toc-link" href="#tc-model">The model</a>
    <a class="toc-link" href="#tc-tests">Testing it</a>
    <a class="toc-link" href="#tc-next">What is next</a>
  </nav>
  <div style="height:26rem;overflow:auto;overscroll-behavior:contain">
    <div class="mk-article-body-progress" aria-hidden="true"></div>
    <div class="mk-article-body" data-size="sm">
      <h2 id="tc-intro">Introduction</h2>
      <p>Scroll this box: the bar at its top fills as you read (a scroll-driven animation - no script). The table of contents links jump inside the example.</p>
      <p>Offline sync, a faster editor and shared spaces for small teams: what is new in the biggest release since launch. The company crossed a million weekly users this summer - and kept its team at forty people.</p>
      <h2 id="tc-model">The model</h2>
      <p>A post-mortem of Tuesday's 42-minute outage and the three changes it led to. Offline sync, a faster editor and shared spaces for small teams: what is new in the biggest release since launch.</p>
      <p>The company crossed a million weekly users this summer - and kept its team at forty people. A post-mortem of Tuesday's 42-minute outage and the three changes it led to.</p>
      <h2 id="tc-tests">Testing it</h2>
      <p>We replay a million random edit sequences against two replicas and assert they converge. Offline sync, a faster editor and shared spaces for small teams: what is new in the biggest release since launch.</p>
      <p>The company crossed a million weekly users this summer - and kept its team at forty people. A post-mortem of Tuesday's 42-minute outage and the three changes it led to.</p>
      <h2 id="tc-next">What is next</h2>
      <p>Garbage-collecting acknowledged operations - next week. The company crossed a million weekly users this summer - and kept its team at forty people.</p>
    </div>
  </div>
</div>

§CSS view file

/* -- Article Body (website) -----------------------------------------

   Renders an article's formatted text. Plain elements - what a CMS or a

   Markdown renderer emits - are styled without classes; library components

   dropped into the text (.mockup-code, .table, .alert, .image, .kbd,

   .heading-anchor, .toc…) keep their own look, because the prose rules only

   reach class-less elements. Adds a lead, pull quotes, footnotes, a table of

   contents layout and a reading-progress bar. */

@layer components {

  .mk-article-body {

    --_measure: 42rem;

    box-sizing: border-box;

    width: 100%;

    max-width: var(--_measure);

    margin-inline: auto;

    padding-inline: 1.25rem;

    color: var(--foreground);

    font-size: 1.0625rem;

    line-height: 1.75;

    hanging-punctuation: first last;

    overflow-wrap: break-word;

    & > * { margin-block: 0; }

    & > * + * { margin-block-start: 1.25em; }

    & :is(h2, h3, h4) {

      line-height: 1.25;

      letter-spacing: -0.02em;

      text-wrap: balance;

      scroll-margin-block-start: 5rem;

    & > h2 { margin-block-start: 2em; font-size: 1.625em; font-weight: 700; }

    & > h3 { margin-block-start: 1.75em; font-size: 1.25em; font-weight: 600; }

    & > h4 { margin-block-start: 1.5em; font-size: 1em; font-weight: 600; }

    & > :is(h2, h3, h4) + * { margin-block-start: 0.75em; }

    & p { text-wrap: pretty; }

    /* prose links - links with a class are components (heading anchors, buttons…) */

    & a:not([class]) {

      color: var(--primary);

      text-decoration: underline;

      text-decoration-thickness: 1px;

      text-underline-offset: 0.2em;

      &:hover { text-decoration-thickness: 2px; }

      &:focus-visible { outline: 2px solid var(--ring); outline-offset: 2px; border-radius: 2px; }

    & :is(strong, b) { font-weight: 650; }

    & > :is(ul, ol) { padding-inline-start: 1.5em; }

    & > :is(ul, ol) li + li { margin-block-start: 0.4em; }

    & > :is(ul, ol) li::marker { color: var(--muted-foreground); }

    & > dl {

      display: grid;

      grid-template-columns: max-content 1fr;

      gap: 0.5em 1.25em;

      & dt { font-weight: 600; }

      & dd { margin: 0; color: var(--muted-foreground); }

    & > blockquote:not([class]) {

      margin-inline: 0;

      padding-inline-start: 1.25em;

      border-inline-start: 3px solid var(--primary);

      font-size: 1.125em;

      font-style: italic;

      & p { margin: 0; }

      & cite {

        display: block;

        margin-block-start: 0.5em;

        color: var(--muted-foreground);

        font-size: 0.8em;

        font-style: normal;

        &::before { content: "- "; }

    & :not(pre) > code:not([class]) {

      padding: 0.125em 0.375em;

      border-radius: var(--radius-sm);

      background: var(--muted);

      font-family: var(--font-mono);

      font-size: 0.875em;

    /* a bare <pre>; a .mockup-code brings its own window */

    & > pre {

      padding: 1em 1.25em;

      overflow-x: auto;

      border: 1px solid var(--border);

      border-radius: var(--radius-md);

      background: var(--muted);

      font-family: var(--font-mono);

      font-size: 0.875em;

      line-height: 1.6;

      tab-size: 2;

    & > hr {

      height: 1px;

      margin-block: 2.5em;

      border: 0;

      background: var(--border);

    & figure:not([class]) {

      margin-inline: 0;

      & :is(img, video) { display: block; width: 100%; height: auto; border-radius: var(--radius-lg); }

      & figcaption { margin-block-start: 0.625em; color: var(--muted-foreground); font-size: 0.8125em; text-align: center; }

    & > :is(img, video) { display: block; width: 100%; height: auto; border-radius: var(--radius-lg); }

    /* embeds (YouTube, maps…): 16:9 unless the iframe says otherwise */

    & iframe {

      display: block;

      width: 100%;

      height: auto;

      aspect-ratio: 16 / 9;

      border: 0;

      border-radius: var(--radius-lg);

      background: var(--muted);

    /* a bare table; a .table (in its .table-container) is the component */

    & > table {

      display: block;

      width: 100%;

      overflow-x: auto;

      border-collapse: collapse;

      font-size: 0.875em;

      line-height: 1.5;

      & :is(th, td) { padding: 0.5em 0.75em; border-block-end: 1px solid var(--border); text-align: start; }

      & th { color: var(--muted-foreground); font-weight: 600; }

    & kbd:not([class]) {

      padding: 0.0625em 0.375em;

      border: 1px solid var(--border);

      border-block-end-width: 2px;

      border-radius: var(--radius-sm);

      font-family: var(--font-mono);

      font-size: 0.8em;

    & mark { padding-inline: 0.125em; border-radius: 2px; background: color-mix(in oklch, var(--primary) 22%, transparent); color: inherit; }

    & abbr[title] { text-decoration: underline dotted; text-underline-offset: 0.2em; cursor: help; }

    & :is(del, s) { color: var(--muted-foreground); }

    & ins { text-decoration: none; background: color-mix(in oklch, oklch(0.72 0.17 150) 22%, transparent); }

    /* the library components inside the text */

    & > :is(.mockup-code, .table-container, .alert, .image, .mk-article-body-pullquote) { margin-block-start: 1.75em; }

    & > :is(.mockup-code, .table-container, .alert, .image) + * { margin-block-start: 1.75em; }

    & .heading-anchor { margin-inline-end: 0.25em; }

  /* the opening paragraph, larger */

  .mk-article-body-lead {

    color: var(--muted-foreground);

    font-size: 1.25em;

    line-height: 1.6;

  /* a callout box inside the text */

  .mk-article-body-note {

    padding: 1em 1.25em;

    border: 1px solid var(--border);

    border-inline-start: 3px solid var(--primary);

    border-radius: var(--radius-md);

    background: color-mix(in oklch, var(--muted) 60%, transparent);

    font-size: 0.9375em;

    & > :first-child { margin-block-start: 0; }

    & > :last-child { margin-block-end: 0; }

  /* a pull quote - set large between rules, the line repeated from the text */

  .mk-article-body-pullquote {

    margin-inline: 0;

    padding-block: 0.75em;

    border-block: 1px solid var(--border);

    font-family: var(--font-serif);

    font-size: 1.5em;

    font-weight: 600;

    line-height: 1.35;

    text-align: center;

    text-wrap: balance;

    &::before { content: "“"; display: block; color: var(--primary); font-size: 2em; line-height: 0.5; }

  /* footnotes: numbered refs jump to the notes, the notes jump back */

  .mk-article-body-ref {

    font-size: 0.75em;

    line-height: 0;

    vertical-align: super;

    & a { padding-inline: 0.125em; color: var(--primary); font-weight: 600; text-decoration: none; }

    & a:focus-visible { outline: 2px solid var(--ring); outline-offset: 1px; border-radius: 2px; }

  .mk-article-body-footnotes {

    padding-block-start: 1em;

    border-block-start: 1px solid var(--border);

    color: var(--muted-foreground);

    font-size: 0.875em;

    & ol { margin: 0; padding-inline-start: 1.25em; }

    & li { padding: 0.25em 0.5em; margin-inline-start: -0.5em; border-radius: var(--radius-sm); scroll-margin-block-start: 5rem; }

    & li:target { background: color-mix(in oklch, var(--primary) 12%, transparent); color: var(--foreground); }

    & a[href^="#"] { color: var(--primary); text-decoration: none; }

  /* a wider figure than the measure (it stays inside the viewport) */

  .mk-article-body > .mk-article-body-wide {

    width: min(100vw - 2.5rem, var(--_measure) + 16rem);

    margin-inline: calc((100% - min(100vw - 2.5rem, var(--_measure) + 16rem)) / 2);

  /* the text beside a sticky table of contents (the .toc component) */

  .mk-article-body-layout {

    display: grid;

    grid-template-columns: minmax(0, 1fr);

    gap: 2rem;

    box-sizing: border-box;

    width: 100%;

    max-width: 64rem;

    margin-inline: auto;

    & > .toc { display: none; }

    & > .mk-article-body { margin-inline: 0; }

  @media (min-width: 56rem) {

    .mk-article-body-layout {

      grid-template-columns: 12rem minmax(0, 1fr);

      & > .toc { display: flex; position: sticky; inset-block-start: 1rem; align-self: start; }

  /* a reading-progress bar - driven by the scroll of the nearest scroller */

  .mk-article-body-progress {

    position: sticky;

    inset-block-start: 0;

    z-index: 2;

    height: 3px;

    margin-block-end: 1rem;

    background: var(--primary);

    transform-origin: left;

    scale: 0 1;

    animation: mk-article-body-read linear both;

  /* the timeline in its own rule: a minifier must not fold it into the

     `animation` shorthand (where it is reset-only - the declaration would be

     dropped); unsupported, the bar hides */

  @supports (animation-timeline: scroll()) {

    .mk-article-body-progress { animation-timeline: scroll(nearest block); }

  @supports not (animation-timeline: scroll()) {

    .mk-article-body-progress { display: none; }

  /* serif: an editorial voice for the running text */

  .mk-article-body[data-variant="serif"] {

    font-family: var(--font-serif);

    font-size: 1.1875rem;

    & :is(h2, h3, h4) { font-family: var(--font-sans); }

  /* sizes */

  .mk-article-body[data-size="sm"] { font-size: 0.9375rem; line-height: 1.7; }

  .mk-article-body[data-size="lg"] { font-size: 1.1875rem; --_measure: 46rem; }

  /* a drop cap opens the first paragraph */

  .mk-article-body[data-dropcap] > p:first-of-type::first-letter {

    float: inline-start;

    margin: 0.06em 0.12em 0 0;

    font-family: var(--font-serif);

    font-size: 3.6em;

    font-weight: 700;

    line-height: 0.8;

    color: var(--primary);

  @keyframes mk-article-body-read {

    to { scale: 1 1; }

  /* -- Accessibility ------------------------------------------- */

  @media (prefers-reduced-motion: reduce) {

    .mk-article-body-progress { animation: none; display: none; }

  @media (prefers-contrast: more) {

    .mk-article-body :is(blockquote cite, figcaption),

    .mk-article-body-lead,

    .mk-article-body-footnotes { color: var(--foreground); }

    .mk-article-body li::marker { color: var(--foreground); }

    .mk-article-body a:not([class]) { text-decoration-thickness: 2px; }

  @media (forced-colors: active) {

    .mk-article-body a:not([class]) { color: LinkText; }

    .mk-article-body :not(pre) > code:not([class]),

    .mk-article-body > pre { border: 1px solid CanvasText; }

    .mk-article-body-progress { background: Highlight; }

Comments, ideas or improvements? Edit this page's source on GitHub

Article BodyBLK

§CSS view file