@brandon_m_behring/book-scaffold-astro 3.0.0-alpha.0

package/styles/convergence.css

@@ -0,0 +1,349 @@
+/* convergence.css — styling for the /convergence dashboard and the
+ * PatternTimeline cards it embeds. Follows the same warm-Tol language
+ * and spacing conventions as the rest of the book.
+ */
+
+/* ===== Dashboard page layout ===== */
+.convergence-header {
+  margin-bottom: var(--space-8);
+  border-bottom: 1px solid var(--color-border);
+  padding-bottom: var(--space-6);
+}
+.convergence-lede {
+  font-size: var(--text-lg);
+  color: var(--color-text-muted);
+  max-width: 65ch;
+}
+.convergence-metric {
+  font-size: var(--text-sm);
+  color: var(--color-text-muted);
+  max-width: 65ch;
+  margin-top: var(--space-3);
+  text-indent: 0;
+}
+
+.convergence-category {
+  margin: var(--space-8) 0;
+}
+.convergence-category-heading {
+  font-size: var(--text-sm);
+  font-family: var(--font-code);
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--color-text-muted);
+  border-bottom: 1px solid var(--color-border);
+  padding-bottom: var(--space-2);
+  margin-bottom: var(--space-4);
+  display: flex;
+  align-items: baseline;
+  gap: var(--space-3);
+}
+.convergence-category-label {
+  font-weight: 500;
+  color: var(--color-text);
+}
+.convergence-category-count {
+  font-size: var(--text-xs);
+  color: var(--color-text-muted);
+}
+.convergence-category-empty {
+  color: var(--color-text-muted);
+  font-style: italic;
+  padding: var(--space-3);
+  background: var(--color-bg-subtle);
+  border-radius: var(--radius-sm);
+  text-indent: 0;
+}
+.convergence-card-list {
+  display: grid;
+  gap: var(--space-4);
+}
+
+.convergence-method {
+  margin-top: var(--space-10);
+  padding-top: var(--space-6);
+  border-top: 1px solid var(--color-border);
+}
+
+/* ===== Pattern card ===== */
+.pattern-card {
+  padding: var(--space-4);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-md);
+  background: var(--color-bg);
+}
+
+.pattern-card-header {
+  margin-bottom: var(--space-3);
+}
+.pattern-card-title-row {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: var(--space-3);
+  margin-bottom: var(--space-2);
+}
+.pattern-card-title {
+  font-size: var(--text-lg);
+  font-weight: 500;
+  margin: 0;
+  color: var(--color-link);
+}
+.pattern-card-meta {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-3);
+  align-items: center;
+  font-size: var(--text-sm);
+}
+
+/* Category badges — use the warm palette semantically. */
+.pattern-category-badge {
+  display: inline-block;
+  padding: 0.1em 0.55em;
+  font-family: var(--font-code);
+  font-size: 0.75em;
+  font-weight: 500;
+  letter-spacing: 0.04em;
+  border-radius: var(--radius-sm);
+  border: 1px solid var(--color-border);
+  background: var(--color-bg);
+  color: var(--color-text);
+}
+.pattern-category-safety {
+  background: var(--warm-rose-tint);
+  color: var(--warm-rose);
+  border-color: var(--warm-rose);
+}
+.pattern-category-scale {
+  background: var(--warm-blue-tint);
+  color: var(--warm-blue);
+  border-color: var(--warm-blue);
+}
+.pattern-category-context {
+  background: var(--warm-gold-tint);
+  color: var(--warm-gold);
+  border-color: var(--warm-gold);
+}
+.pattern-category-interaction {
+  background: var(--warm-green-tint);
+  color: var(--warm-green);
+  border-color: var(--warm-green);
+}
+.pattern-category-extension {
+  background: var(--warm-plum-tint);
+  color: var(--warm-plum);
+  border-color: var(--warm-plum);
+}
+.pattern-category-other {
+  /* use default neutral styling */
+}
+
+/* Convergence badge — green for converged, gold for not-yet. */
+.pattern-convergence-badge {
+  display: inline-block;
+  padding: 0.1em 0.55em;
+  border-radius: var(--radius-sm);
+  font-family: var(--font-code);
+  font-size: 0.85em;
+  font-weight: 500;
+  letter-spacing: 0.03em;
+}
+.pattern-convergence-badge.converged {
+  background: var(--warm-green-tint);
+  color: var(--warm-green);
+  border: 1px solid var(--warm-green);
+}
+.pattern-convergence-badge.not-converged {
+  background: var(--warm-gold-tint);
+  color: var(--warm-gold);
+  border: 1px solid var(--warm-gold);
+}
+.pattern-adoption-count {
+  font-family: var(--font-code);
+  font-size: 0.85em;
+  color: var(--color-text-muted);
+}
+
+.pattern-description {
+  color: var(--color-text);
+  margin: 0 0 var(--space-3) 0;
+  text-indent: 0;
+  line-height: 1.5;
+}
+
+.pattern-empty-timeline {
+  color: var(--color-text-muted);
+  font-style: italic;
+  padding: var(--space-2) var(--space-3);
+  background: var(--color-bg-subtle);
+  border-radius: var(--radius-sm);
+  text-indent: 0;
+  margin: 0;
+}
+
+/* ===== Timeline ===== */
+.pattern-timeline {
+  display: grid;
+  grid-template-columns: 9rem 1fr;
+  gap: var(--space-2) var(--space-3);
+  margin-top: var(--space-3);
+  padding: var(--space-3);
+  background: var(--color-bg-subtle);
+  border-radius: var(--radius-sm);
+}
+
+.pattern-timeline-track {
+  display: contents;
+}
+.pattern-timeline-tool-label {
+  font-family: var(--font-code);
+  font-size: var(--text-sm);
+  color: var(--color-text-muted);
+  align-self: center;
+  white-space: nowrap;
+}
+.pattern-timeline-track[data-adopted='true'] .pattern-timeline-tool-label {
+  color: var(--color-text);
+}
+
+.pattern-timeline-rail {
+  position: relative;
+  min-height: 2.2rem;
+  border-bottom: 1px dashed var(--color-border);
+  display: flex;
+  align-items: center;
+}
+
+.pattern-timeline-not-yet {
+  font-style: italic;
+  color: var(--color-text-muted);
+  font-size: var(--text-xs);
+  padding-left: var(--space-1);
+}
+
+.pattern-timeline-dot {
+  position: absolute;
+  top: 50%;
+  transform: translate(-50%, -50%);
+  width: 0.85rem;
+  height: 0.85rem;
+  border-radius: 50%;
+  background: var(--warm-blue);
+  border: 2px solid var(--color-bg);
+  cursor: help;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  transition: transform 120ms ease;
+}
+.pattern-timeline-dot:hover {
+  transform: translate(-50%, -50%) scale(1.3);
+  z-index: 5;
+}
+
+.pattern-timeline-dot[data-kind='added'] {
+  background: var(--warm-green);
+}
+.pattern-timeline-dot[data-kind='changed'] {
+  background: var(--warm-gold);
+}
+.pattern-timeline-dot[data-kind='removed'],
+.pattern-timeline-dot[data-kind='deprecated'] {
+  background: var(--warm-rose);
+}
+
+.pattern-timeline-dot-label {
+  position: absolute;
+  top: calc(100% + 0.2em);
+  left: 50%;
+  transform: translateX(-50%);
+  font-family: var(--font-code);
+  font-size: 0.65rem;
+  color: var(--color-text-muted);
+  white-space: nowrap;
+  pointer-events: none;
+}
+
+.pattern-timeline-axis {
+  grid-column: 2;
+  display: flex;
+  justify-content: space-between;
+  font-family: var(--font-code);
+  font-size: 0.7rem;
+  color: var(--color-text-muted);
+  margin-top: var(--space-2);
+  padding-top: var(--space-1);
+  border-top: 1px solid var(--color-border);
+}
+
+/* ===== Mobile layout ===== */
+@media (max-width: 48rem) {
+  .pattern-timeline {
+    grid-template-columns: 1fr;
+    gap: var(--space-3);
+  }
+  .pattern-timeline-track {
+    display: grid;
+    grid-template-columns: 8rem 1fr;
+    gap: var(--space-2);
+  }
+  .pattern-timeline-axis {
+    grid-column: 1;
+  }
+
+  .convergence-category-heading {
+    flex-direction: column;
+    align-items: flex-start;
+    gap: var(--space-1);
+  }
+}
+
+/* Narrow phones (iPhone 5 / small folds): stack tool label above rail
+ * entirely. 8rem sidebar was still sharing ~200px with the rail on
+ * a 320px viewport, causing dots to crowd when multiple events
+ * fell within a tight date range. */
+@media (max-width: 26rem) {
+  .pattern-timeline-track {
+    grid-template-columns: 1fr;
+    gap: 0;
+  }
+  .pattern-timeline-tool-label {
+    font-size: var(--text-xs);
+    padding-top: var(--space-1);
+  }
+  .pattern-timeline-rail {
+    min-height: 2.6rem; /* a bit more vertical room so labels don't collide */
+  }
+}
+
+/* ===== Print ===== */
+@media print {
+  .pattern-card {
+    break-inside: avoid;
+    background: transparent !important;
+    border-width: 0.5pt;
+    border-color: #aaa;
+  }
+  .pattern-timeline {
+    background: transparent !important;
+    border: 0.5pt solid #aaa;
+  }
+  .pattern-timeline-dot {
+    border-color: #fff;
+    background: #333 !important;
+  }
+  .pattern-timeline-dot:hover {
+    transform: translate(-50%, -50%); /* no scale on paper */
+  }
+}
+
+/* ===== Reduced motion ===== */
+@media (prefers-reduced-motion: reduce) {
+  .pattern-timeline-dot {
+    transition: none;
+  }
+  .pattern-timeline-dot:hover {
+    transform: translate(-50%, -50%);
+  }
+}

package/styles/layout.css

@@ -0,0 +1,156 @@
+/* layout.css — Tufte-inspired 2-column layout + optional docs-style sidebar
+ *
+ * Three structural layers:
+ *
+ * 1. Page chrome at very top: theme toggle (top-right, position: fixed).
+ *
+ * 2. Optional left sidebar (Sidebar.astro). At ≥64rem (1024px), grid
+ *    pins it to the left edge; below 1024px it's hidden (mobile pages
+ *    don't carry the nav). Toggle per-page via Base.astro's `showSidebar`
+ *    prop — default true; the landing page sets false.
+ *
+ * 3. Main content (.prose) — Tufte 2-column with sidenotes in right
+ *    margin on desktop (≥48rem), inline on mobile (<48rem). See
+ *    tokens.css for the three-tier --measure-main width strategy.
+ *
+ * Zero JavaScript. Pure CSS. Respects Gwern's "no effort" principle:
+ * sidenotes are always visible at reading speed; the only thing that
+ * changes across breakpoints is where they sit.
+ */
+
+/* ===== Optional left sidebar (docs-style nav) ===== */
+
+/* Default layout when sidebar is present but viewport too narrow:
+ * stack vertically, hide sidebar. Below 1024px the sidebar component
+ * is display:none; the slot occupies full width. */
+.layout-with-sidebar {
+  display: block;
+}
+.layout-with-sidebar > .sidebar {
+  display: none;
+}
+
+/* At 1024px+: pin sidebar to left, main content fills remainder. */
+@media (min-width: 64rem) {
+  .layout-with-sidebar {
+    display: grid;
+    grid-template-columns: 16rem 1fr;
+    grid-template-areas: 'sidebar main';
+    min-height: 100vh;
+  }
+  .layout-with-sidebar > .sidebar {
+    display: block;
+  }
+  .layout-with-sidebar > .layout-main {
+    grid-area: main;
+    min-width: 0; /* prevent overflow from long pre/code */
+  }
+}
+
+/* Slightly wider sidebar at 1440px+ — more breathing room for chapter
+ * titles. */
+@media (min-width: 90rem) {
+  .layout-with-sidebar {
+    grid-template-columns: 18rem 1fr;
+  }
+}
+
+.prose {
+  /* Container width = main + gutter + sidenote column + outer padding */
+  max-width: calc(
+    var(--measure-main) + var(--space-6) + var(--measure-side)
+    + 2 * var(--space-4)
+  );
+  margin: var(--space-8) auto;
+  padding: 0 var(--space-4);
+  position: relative;
+}
+
+/* Default: constrain direct children to the main-text measure.
+ * The remaining ~31ch becomes the right margin for sidenotes. */
+.prose > * {
+  max-width: var(--measure-main);
+}
+
+/* Sidenote: floats into the right margin on desktop.
+ * Float + negative margin-right is the classic Tufte-CSS technique —
+ * the element aligns to where it appears in document flow (roughly
+ * next to its referencing paragraph), not to a fixed row. */
+.sidenote {
+  float: right;
+  clear: right;
+  width: var(--measure-side);
+  margin-right: calc(-1 * (var(--measure-side) + var(--space-6)));
+  margin-top: 0.3rem;
+  margin-bottom: var(--space-3);
+  padding-left: var(--space-3);
+  border-left: var(--border-bar) solid var(--color-border);
+  font-size: var(--text-sm);
+  line-height: var(--leading-normal);
+  font-style: italic;
+  color: var(--color-text-muted);
+  display: block;
+  position: relative;
+}
+
+/* ===== Auto-numbered sidenote markers (CSS counters) =====
+ * Counter resets per .prose so each chapter numbers from 1. The marker
+ * and its matching sidenote share the same counter value because only
+ * the marker increments it. */
+.prose {
+  counter-reset: sidenote;
+}
+
+.sidenote-marker {
+  counter-increment: sidenote;
+  color: var(--color-link);
+  cursor: help;
+  font-size: 0.75em;
+  vertical-align: super;
+  line-height: 0;
+  margin-left: 0.1em;
+}
+.sidenote-marker::after {
+  content: counter(sidenote);
+}
+
+/* Sidenote itself prefixes with the counter so readers can match
+ * marker-in-main-text with note-in-margin. */
+.sidenote::before {
+  content: counter(sidenote) ". ";
+  font-weight: 500;
+  color: var(--color-link);
+  margin-right: 0.15em;
+}
+
+/* ===== Mobile breakpoint: inline-flow asides =====
+ * Sidenotes break out of float and become visually-distinct inline
+ * blocks immediately after their position in the document flow.
+ * No tap, no reveal, no layout shift — Gwern's "no effort" principle. */
+@media (max-width: 48rem) {
+  .prose {
+    max-width: var(--measure-main);
+  }
+
+  .sidenote {
+    float: none;
+    clear: none;
+    width: auto;
+    max-width: none;
+    margin: var(--space-3) 0 var(--space-3) var(--space-3);
+    padding: var(--space-2) var(--space-3);
+    border-left: var(--border-bar) solid var(--callout-info);
+    background: var(--warm-blue-tint);
+    border-radius: 0 var(--radius-sm) var(--radius-sm) 0;
+    font-size: var(--text-sm);
+    font-style: italic;
+    color: var(--color-text);
+  }
+}
+
+/* Escape class for wide content (figures, large tables, code blocks
+ * that need the full container width including the sidenote column). */
+.wide {
+  max-width: none !important;
+  width: 100%;
+}

package/styles/print.css

@@ -0,0 +1,203 @@
+/* print.css — Print + Paged.js styling.
+ *
+ * Applied by the browser when the user prints, and by pagedjs-cli
+ * when rendering the PDF edition. `@page` rules configure the page
+ * size, margins, and running headers; `@media print` overrides
+ * screen-specific layout (Tufte 2-column becomes a single flow with
+ * sidenotes floating in the page margin).
+ */
+
+@page {
+  size: letter;
+  margin: 1in 0.9in 1in 0.9in;
+
+  @bottom-center {
+    content: counter(page);
+    font-family: var(--font-body);
+    font-size: 9pt;
+    color: #555;
+  }
+}
+
+/* Front-matter pages without page numbers (optional — expand later). */
+@page :first {
+  @bottom-center { content: none; }
+}
+
+@media print {
+  /* Hide interactive chrome */
+  .chrome-buttons,
+  .chapter-nav,
+  .chapter-toc,
+  .pagefind-ui,
+  .version-selector,
+  nav[aria-label="On this page"],
+  script {
+    display: none !important;
+  }
+
+  html, body {
+    background: white !important;
+    color: black !important;
+    font-size: 10.5pt;
+  }
+
+  /* Reset Tufte container for page flow */
+  .prose {
+    max-width: 100%;
+    margin: 0;
+    padding: 0;
+  }
+  .prose > * {
+    max-width: 100%;
+  }
+
+  /* Sidenotes stay floated in the right margin of the printed page.
+   * 30% width leaves the main column ~65% — similar proportion to
+   * the screen Tufte grid. */
+  .sidenote {
+    float: right;
+    clear: right;
+    width: 30%;
+    margin-right: -35%;
+    margin-top: 0;
+    padding-left: 0.5em;
+    border-left: 2px solid #aaa;
+    font-size: 9pt;
+    font-style: italic;
+    color: #333;
+    background: transparent;
+  }
+
+  /* Sidenote marker stays inline as superscript. */
+  .sidenote-marker {
+    color: #000;
+    font-size: 0.7em;
+  }
+
+  /* Page breaks — chapters start on a fresh page; keep headings + blocks together. */
+  section.chapter-print {
+    break-before: page;
+  }
+  section.chapter-print:first-of-type {
+    break-before: auto;
+  }
+  h1 {
+    break-before: page;
+    break-after: avoid;
+  }
+  h2, h3, h4 {
+    break-after: avoid;
+  }
+  pre, table, .callout, blockquote {
+    break-inside: avoid;
+  }
+
+  /* Links: show the URL alongside the link text for print. */
+  a[href]:not([href^="#"])::after {
+    content: " (" attr(href) ")";
+    font-size: 0.85em;
+    color: #555;
+    word-break: break-all;
+  }
+
+  /* Don't print the URL for in-page anchors or images. */
+  .citation-link::after,
+  .sidenote a::after {
+    content: "" !important;
+  }
+
+  /* Callouts: keep palette but reduce visual weight for print economy */
+  .callout {
+    padding: 0.4em 0.7em;
+    margin: 0.6em 0;
+    border-left-width: 2px;
+    background: #f6f4ee !important;
+    color: black !important;
+  }
+  .callout-title {
+    color: black;
+  }
+
+  /* Tables: light borders, normal weight */
+  table {
+    page-break-inside: avoid;
+    font-size: 9pt;
+  }
+  th, td {
+    border-bottom: 0.5pt solid #aaa;
+  }
+
+  /* Code blocks: keep the background subtle on paper. */
+  pre {
+    background: #f6f4ee !important;
+    border: 0.5pt solid #ccc;
+    font-size: 8.5pt;
+    /* Long lines wrap rather than overflow the page edge. */
+    white-space: pre-wrap !important;
+    word-wrap: break-word;
+    overflow-x: visible !important;
+  }
+  code {
+    background: transparent;
+    border: 0;
+  }
+  .astro-code,
+  .astro-code span {
+    color: black !important;
+    background: transparent !important;
+  }
+
+  /* ===== Polish pass (commit 17) =====
+   * Widows/orphans, keep-with-next rules, and a few edge-cases that
+   * only surface in real paginated output. */
+
+  /* Keep at least 3 lines together at page boundaries so paragraphs
+   * don't leave a stranded first/last line. */
+  p, li, blockquote {
+    orphans: 3;
+    widows: 3;
+  }
+
+  /* Callout titles should stay with their body; don't let a pagebreak
+   * split the title from its explanation. */
+  .callout-title {
+    break-after: avoid;
+  }
+
+  /* Chapter header is introductory material; the page break should
+   * land either before it or after the header's content area — never
+   * mid-header, and never orphaning the h1 from the first paragraph. */
+  .chapter-header {
+    break-after: avoid;
+  }
+  .chapter-header h1 {
+    break-before: auto;  /* overrides the general h1 break-before:page */
+  }
+
+  /* Headings followed by content: don't let a break leave a heading
+   * alone at the end of a page. */
+  h2, h3, h4 {
+    break-inside: avoid;
+  }
+  h2 + p, h3 + p, h4 + p {
+    break-before: avoid;
+  }
+
+  /* Lists: keep small lists together. */
+  ul, ol {
+    break-inside: avoid-page;
+  }
+
+  /* Tables: try not to split short tables across pages. */
+  table {
+    break-inside: avoid-page;
+  }
+
+  /* Hide the caret on <details> TOC — it's already hidden by chrome
+   * display:none above, but belt-and-suspenders for printers that
+   * ignore the rule. */
+  details > summary {
+    list-style: none;
+  }
+}