@pagesmith/docs 0.1.0

package/theme/styles/content/prose.css

@@ -0,0 +1,225 @@
+/* ─── Root ─── */
+html {
+  font-family: var(--font-sans);
+  font-size: 16px;
+  color: var(--color-text);
+  background: var(--color-bg);
+  transition: background-color var(--transition-fast), color var(--transition-fast);
+}
+body {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+/* ─── Headings ─── */
+h1 {
+  font-size: clamp(1.75rem, 4vw, var(--font-size-3xl));
+  font-weight: 700;
+  letter-spacing: -0.02em;
+  line-height: 1.2;
+  margin-bottom: 1rem;
+}
+h2 {
+  font-size: var(--font-size-2xl);
+  font-weight: 600;
+  letter-spacing: -0.01em;
+  line-height: 1.3;
+  margin-top: 2.5rem;
+  margin-bottom: 0.75rem;
+  padding-bottom: 0.5rem;
+  border-bottom: 1px solid var(--color-border-subtle);
+}
+h3 {
+  font-size: var(--font-size-xl);
+  font-weight: 600;
+  line-height: 1.4;
+  margin-top: 2rem;
+  margin-bottom: 0.5rem;
+}
+h4 {
+  font-size: var(--font-size-base);
+  font-weight: 500;
+  line-height: 1.5;
+  margin-top: 1.5rem;
+  margin-bottom: 0.5rem;
+}
+
+/* ─── Prose (markdown content) ─── */
+.prose {
+  color: var(--color-text-secondary);
+  line-height: 1.8;
+  font-size: 17px;
+  overflow-wrap: break-word;
+}
+.prose p {
+  margin-bottom: 1.25rem;
+}
+.prose a {
+  color: var(--color-text);
+  text-decoration: underline;
+  text-decoration-color: var(--color-border);
+  text-underline-offset: 2px;
+  transition: text-decoration-color var(--transition-fast);
+}
+.prose a:hover {
+  text-decoration-color: var(--color-text);
+}
+.prose h1 a, .prose h2 a, .prose h3 a, .prose h4 a {
+  text-decoration: none;
+}
+.prose h1 a:hover, .prose h2 a:hover, .prose h3 a:hover, .prose h4 a:hover {
+  text-decoration: underline;
+  text-decoration-color: var(--color-border);
+}
+.prose strong {
+  font-weight: 600;
+  color: var(--color-text);
+}
+.prose em {
+  font-style: italic;
+}
+.prose ul, .prose ol {
+  padding-left: 1.5rem;
+  margin-bottom: 1.25rem;
+}
+.prose ul {
+  list-style: disc;
+}
+.prose ol {
+  list-style: decimal;
+}
+.prose li {
+  margin-bottom: 0.35rem;
+}
+.prose li::marker {
+  color: var(--color-text-muted);
+}
+.prose hr {
+  border: none;
+  border-top: 1px solid var(--color-border);
+  margin: 2.5rem 0;
+}
+.prose img {
+  border-radius: var(--radius-md);
+  margin: 1.5rem 0;
+}
+.prose > *:first-child {
+  margin-top: 0;
+}
+.prose > *:last-child {
+  margin-bottom: 0;
+}
+
+/* ─── Figures ─── */
+.prose figure {
+  margin: 2rem 0;
+}
+.prose figure img {
+  display: block;
+  max-width: 100%;
+  max-height: 100vh;
+  height: auto;
+  margin: 0 auto;
+  border-radius: var(--radius-md);
+}
+.prose figure img.only-light,
+.prose figure img.only-dark {
+  width: 100%;
+}
+.prose figcaption {
+  margin-top: 0.5rem;
+  font-size: var(--font-size-sm);
+  color: var(--color-text-muted);
+  text-align: center;
+  line-height: 1.5;
+}
+
+/* ─── Tables ─── */
+.prose table {
+  display: block;
+  width: max-content;
+  max-width: 100%;
+  overflow-x: auto;
+  border-collapse: collapse;
+  margin-bottom: 1.25rem;
+  font-size: var(--font-size-sm);
+}
+.prose th, .prose td {
+  padding: 0.6rem 1.25rem;
+  text-align: left;
+  border-bottom: 1px solid var(--color-border);
+  min-width: 10ch;
+}
+.prose th {
+  font-weight: 600;
+  color: var(--color-text);
+  background: var(--color-bg-alt);
+}
+.prose tr:last-child td {
+  border-bottom: none;
+}
+
+/* ─── Blockquotes ─── */
+.prose blockquote {
+  border-left: 3px solid var(--color-blockquote-border);
+  padding: 0.5rem 1.25rem;
+  margin-bottom: 1.25rem;
+  color: var(--color-text-muted);
+  background: var(--color-blockquote-bg);
+  border-radius: 0 var(--radius-sm) var(--radius-sm) 0;
+}
+.prose blockquote p:last-child {
+  margin-bottom: 0;
+}
+
+/* ─── Task lists (GFM) ─── */
+.prose .contains-task-list {
+  list-style: none;
+  padding-left: 0;
+}
+.prose .task-list-item {
+  display: flex;
+  align-items: baseline;
+  gap: 0.5rem;
+}
+.prose .task-list-item input[type="checkbox"] {
+  accent-color: var(--color-text-muted);
+}
+
+/* ─── Light/dark image switching ─── */
+img.only-dark, .prose figure img.only-dark {
+  display: none;
+}
+
+@media (prefers-color-scheme: dark) {
+  img.only-light,
+  .prose figure img.only-light {
+    display: none;
+  }
+  img.only-dark,
+  .prose figure img.only-dark {
+    display: block;
+  }
+}
+
+/* ─── Inline SVGs (embedded, use currentColor) ─── */
+.prose .inline-svg {
+  display: block;
+  max-width: 100%;
+  height: auto;
+  margin: 1.5rem auto;
+  color: var(--color-text-secondary);
+}
+
+/* ─── Invert images in dark mode (.invert. naming convention) ─── */
+@media (prefers-color-scheme: dark) {
+  .prose img.invert-on-dark {
+    filter: invert(1) hue-rotate(180deg);
+  }
+}
+
+/* ─── Scroll margin for anchors ─── */
+.prose h1, .prose h2, .prose h3, .prose h4, h2[id], h3[id] {
+  scroll-margin-top: calc(var(--header-height) + 1.5rem);
+}

package/theme/styles/content/toc.css

@@ -0,0 +1,90 @@
+/* ─── TOC ─── */
+.doc-toc {
+  font-size: var(--font-size-sm);
+}
+.doc-toc-title {
+  font-size: var(--font-size-xs);
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--color-text-muted);
+  margin-bottom: 0.75rem;
+}
+.doc-toc-list {
+  display: flex;
+  flex-direction: column;
+  gap: 0.15rem;
+  border-left: 2px solid var(--color-border-subtle);
+  padding-left: 0;
+}
+.doc-toc-item a {
+  display: block;
+  padding: 0.2rem 0 0.2rem 0.75rem;
+  color: var(--color-text-muted);
+  transition: color var(--transition-fast), border-color var(--transition-fast);
+  line-height: 1.4;
+  border-left: 2px solid transparent;
+  margin-left: -2px;
+}
+.doc-toc-item a:hover {
+  color: var(--color-text);
+}
+.doc-toc-item.active a {
+  color: var(--color-text);
+  border-left-color: var(--color-accent);
+}
+.doc-toc-item.depth-2 a {
+  padding-left: 0.75rem;
+}
+.doc-toc-item.depth-3 a {
+  padding-left: 1.5rem;
+  font-size: 0.8125rem;
+}
+
+/* ─── Mobile TOC accordion ─── */
+/* Visibility controlled by layout/grid.css breakpoints */
+.doc-toc-mobile {
+  margin-bottom: 1.5rem;
+  border: 1px solid var(--color-border-subtle);
+  border-radius: var(--radius-md);
+  background: var(--color-bg-alt);
+}
+.doc-toc-mobile summary {
+  padding: 0.75rem 1rem;
+  font-size: var(--font-size-sm);
+  font-weight: 600;
+  color: var(--color-text-muted);
+  cursor: pointer;
+  list-style: none;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+.doc-toc-mobile summary::-webkit-details-marker {
+  display: none;
+}
+.doc-toc-mobile summary::after {
+  content: "";
+  width: 16px;
+  height: 16px;
+  background: currentColor;
+  clip-path: polygon(25% 20%, 75% 50%, 25% 80%);
+  transition: transform var(--transition-fast);
+  flex-shrink: 0;
+}
+.doc-toc-mobile[open] summary::after {
+  transform: rotate(90deg);
+}
+.doc-toc-mobile .doc-toc {
+  padding: 0 1rem 0.75rem;
+}
+.doc-toc-mobile .doc-toc-title {
+  display: none;
+}
+.doc-toc-mobile .doc-toc-list {
+  border-left: none;
+}
+.doc-toc-mobile .doc-toc-item a {
+  border-left: none;
+  margin-left: 0;
+}

package/theme/styles/foundations/fonts.css

@@ -0,0 +1,37 @@
+/* Self-hosted fonts — bundled with @pagesmith/docs */
+
+/* ─── Adjusted fallback for Open Sans (matches system-ui metrics) ─── */
+@font-face {
+  font-family: 'Open Sans Fallback';
+  src: local('Arial'), local('Helvetica Neue'), local('Helvetica');
+  size-adjust: 105.4%;
+  ascent-override: 101%;
+  descent-override: 28%;
+  line-gap-override: 0%;
+}
+
+@font-face {
+  font-family: 'Open Sans';
+  src: url('fonts/open-sans-variable.woff2') format('woff2');
+  font-weight: 300 800;
+  font-style: normal;
+  font-display: swap;
+}
+
+/* ─── Adjusted fallback for JetBrains Mono (matches Menlo/Consolas) ─── */
+@font-face {
+  font-family: 'JetBrains Mono Fallback';
+  src: local('Menlo'), local('Consolas'), local('DejaVu Sans Mono');
+  size-adjust: 115.6%;
+  ascent-override: 78%;
+  descent-override: 22%;
+  line-gap-override: 0%;
+}
+
+@font-face {
+  font-family: 'JetBrains Mono';
+  src: url('fonts/jetbrains-mono-variable.woff2') format('woff2');
+  font-weight: 400 700;
+  font-style: normal;
+  font-display: swap;
+}

package/theme/styles/foundations/reset.css

@@ -0,0 +1,49 @@
+*, *::before, *::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+html {
+  -webkit-text-size-adjust: 100%;
+  tab-size: 4;
+  scroll-behavior: smooth;
+  scrollbar-gutter: stable;
+}
+body {
+  line-height: 1.7;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+img, svg, video {
+  display: block;
+  max-width: 100%;
+}
+h1, h2, h3, h4, h5, h6, p {
+  overflow-wrap: break-word;
+}
+ul, ol {
+  list-style: none;
+}
+a {
+  color: inherit;
+  text-decoration: none;
+}
+button, input, textarea, select {
+  font: inherit;
+}
+table {
+  border-collapse: collapse;
+}
+
+/* Screen-reader only */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}

package/theme/styles/foundations/tokens.css

@@ -0,0 +1,66 @@
+/* -- Design Tokens -- */
+
+:root {
+  color-scheme: light dark;
+
+  /* Colors */
+  --color-bg: light-dark(#f5f4f0, #111110);
+  --color-bg-alt: light-dark(#eeeee8, #1a1a18);
+  --color-bg-elevated: light-dark(#f5f4f0, #1e1e1c);
+  --color-bg-code: light-dark(#eeeee8, #1a1a18);
+  --color-bg-hover: light-dark(#e8e7e2, #252524);
+
+  --color-text: light-dark(#111110, #f5f4f0);
+  --color-text-secondary: light-dark(#333330, #ccccca);
+  --color-text-muted: light-dark(#7a7a72, #888882);
+
+  --color-border: light-dark(#d0cfc9, #2a2a28);
+  --color-border-subtle: light-dark(#e0dfd9, #222220);
+  --color-border-hover: light-dark(#c0bfb9, #3a3a38);
+
+  --color-accent: light-dark(#1a1a18, #e8e7e2);
+  --color-accent-hover: light-dark(#333330, #ccccca);
+  --color-accent-subtle: light-dark(rgba(26, 26, 24, 0.06), rgba(232, 231, 226, 0.08));
+
+  --color-code-bg: light-dark(#eeeee8, #1a1a18);
+  --color-code-text: light-dark(#333330, #ccccca);
+
+  --color-blockquote-border: light-dark(#d0cfc9, #333330);
+  --color-blockquote-bg: light-dark(#eeeee8, #1a1a18);
+
+  --color-overlay-bg: light-dark(rgba(0, 0, 0, 0.3), rgba(0, 0, 0, 0.5));
+  --color-header-bg: light-dark(#f5f4f0, #111110);
+  --color-text-inverse: light-dark(#f5f4f0, #111110);
+
+  /* Shadows -- split color since light-dark() returns <color> */
+  --shadow-color: light-dark(rgba(0, 0, 0, 0.04), rgba(0, 0, 0, 0.2));
+  --shadow-color-md: light-dark(rgba(0, 0, 0, 0.04), rgba(0, 0, 0, 0.25));
+  --shadow-color-lg: light-dark(rgba(0, 0, 0, 0.06), rgba(0, 0, 0, 0.3));
+  --shadow-sm: 0 1px 2px var(--shadow-color);
+  --shadow-md: 0 4px 6px var(--shadow-color-md);
+  --shadow-lg: 0 10px 25px var(--shadow-color-lg);
+
+  /* Typography */
+  --font-sans: 'Open Sans', 'Open Sans Fallback', system-ui, -apple-system, 'Segoe UI', sans-serif;
+  --font-mono: 'JetBrains Mono', 'JetBrains Mono Fallback', 'Fira Code', Menlo, Consolas, monospace;
+
+  --font-size-xs: 0.75rem;
+  --font-size-sm: 0.875rem;
+  --font-size-base: 1rem;
+  --font-size-lg: 1.125rem;
+  --font-size-xl: 1.25rem;
+  --font-size-2xl: 1.5rem;
+  --font-size-3xl: 2rem;
+
+  /* Spacing */
+  --radius-sm: 2px;
+  --radius-md: 4px;
+  --radius-lg: 6px;
+
+  /* Transitions */
+  --transition-fast: 150ms cubic-bezier(0.4, 0, 0.2, 1);
+  --transition-normal: 250ms cubic-bezier(0.4, 0, 0.2, 1);
+
+  /* Layout */
+  --header-height: 60px;
+}

package/theme/styles/layout/footer.css

@@ -0,0 +1,119 @@
+/* ═══════════════════════════════════════════════════════════════
+   Doc footer — prev/next navigation + copyright
+   ═══════════════════════════════════════════════════════════════ */
+
+.doc-footer {
+  margin-top: 3rem;
+  padding-top: 1.5rem;
+  border-top: 1px solid var(--color-border);
+}
+
+.doc-footer-links {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: 1rem;
+  margin-top: 1.5rem;
+}
+
+.doc-footer-links a {
+  font-size: var(--font-size-sm);
+  color: var(--color-text-muted);
+}
+
+.doc-footer-links a:hover {
+  color: var(--color-text);
+}
+
+/* ─── Prev / Next navigation grid ─── */
+.doc-footer-nav {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 1rem;
+}
+
+/* ─── Prev/Next card link ─── */
+.doc-footer-link {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+  padding: 1rem 1.25rem;
+  border: 1px solid var(--color-border-subtle);
+  border-radius: var(--radius-lg);
+  transition:
+    border-color var(--transition-fast),
+    background var(--transition-fast);
+}
+.doc-footer-link:hover {
+  border-color: var(--color-border-hover);
+  background: var(--color-bg-hover);
+}
+
+/* ─── Alignment ─── */
+.doc-footer-prev {
+  text-align: left;
+}
+.doc-footer-next {
+  text-align: right;
+  grid-column: 2;
+}
+
+/* When only "next" is present, push it to the right */
+.doc-footer-next:first-child {
+  grid-column: 2;
+}
+
+/* ─── Label: "Previous" / "Next" ─── */
+.doc-footer-label {
+  font-size: var(--font-size-xs);
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--color-text-muted);
+}
+
+/* ─── Page title ─── */
+.doc-footer-title {
+  font-size: var(--font-size-sm);
+  font-weight: 500;
+  color: var(--color-text);
+  transition: color var(--transition-fast);
+}
+.doc-footer-link:hover .doc-footer-title {
+  color: var(--color-text-secondary);
+}
+
+/* ─── Copyright line ─── */
+.doc-footer-copyright {
+  margin-top: 2rem;
+  padding: 1.5rem 0;
+  border-top: 1px solid var(--color-border);
+  font-size: var(--font-size-xs);
+  color: var(--color-text-muted);
+  text-align: center;
+  letter-spacing: 0.02em;
+}
+
+.doc-footer-copyright:first-child {
+  margin-top: 0;
+  border-top: none;
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Responsive
+   ═══════════════════════════════════════════════════════════════ */
+
+@media (max-width: 800px) {
+  .doc-footer-nav {
+    grid-template-columns: 1fr;
+  }
+
+  .doc-footer-next {
+    text-align: left;
+    grid-column: 1;
+  }
+
+  .doc-footer-next:first-child {
+    grid-column: 1;
+  }
+}

package/theme/styles/layout/grid.css

@@ -0,0 +1,98 @@
+/* ═══════════════════════════════════════════════════════════════
+   Documentation 3-column responsive layout
+
+   Breakpoints (ch-based, consistent with content width):
+   < 110ch  — single column, both sidebars hidden
+   ≥ 110ch  — content + right sidebar (30ch)
+   ≥ 140ch  — left sidebar (30ch) + content + right sidebar (30ch)
+   ≥ 160ch  — centered: left (30ch) + content (100ch max) + right (30ch)
+
+   Sidebars always render in the DOM when space allows, even if empty.
+   ═══════════════════════════════════════════════════════════════ */
+
+/* ─── Base: single column (< 110ch) ─── */
+.doc-layout {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  min-height: calc(100vh - var(--header-height));
+  padding-top: var(--header-height);
+}
+
+/* ─── Main content column ─── */
+.doc-main {
+  max-width: 100ch;
+  width: 100%;
+  margin: 0 auto;
+  padding: 2rem 1.25rem;
+}
+
+/* ─── Right aside — hidden by default, visible when space allows ─── */
+.doc-aside {
+  display: none;
+}
+
+/* ─── Mobile TOC — visible when right aside is hidden ─── */
+.doc-toc-mobile {
+  display: block;
+}
+
+/* ─── Home page — centered, no sidebars ─── */
+.doc-home {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  min-height: calc(100vh - var(--header-height));
+  padding-top: var(--header-height);
+  padding-bottom: 3rem;
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   ≥ 110ch — show right aside
+   ═══════════════════════════════════════════════════════════════ */
+@media (min-width: 110ch) {
+  .doc-layout {
+    grid-template-columns: minmax(0, 1fr) 30ch;
+  }
+
+  .doc-aside {
+    display: block;
+    position: sticky;
+    top: var(--header-height);
+    height: fit-content;
+    max-height: calc(100vh - var(--header-height));
+    overflow-y: auto;
+    padding: 2rem 1.5rem 2rem 0;
+    scrollbar-width: thin;
+  }
+
+  .doc-toc-mobile {
+    display: none;
+  }
+
+  .doc-main {
+    padding: 2rem 2.5rem;
+  }
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   ≥ 140ch — show left sidebar in grid
+   ═══════════════════════════════════════════════════════════════ */
+@media (min-width: 140ch) {
+  .doc-layout {
+    grid-template-columns: 30ch minmax(0, 1fr) 30ch;
+  }
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   ≥ 160ch — centered 3-column with fixed content max
+   ═══════════════════════════════════════════════════════════════ */
+@media (min-width: 160ch) {
+  .doc-layout {
+    grid-template-columns: 30ch minmax(0, 100ch) 30ch;
+    justify-content: center;
+  }
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Small screens
+   ═══════════════════════════════════════════════════════════════ */