@apisurf/canonui 0.1.1

package/theme/styles/theme.css

@@ -0,0 +1,543 @@
+/*
+ * The default theme.
+ *
+ * One stylesheet, no framework, no build step of its own. It is meant to be
+ * legible first and replaceable second: every rule here is scoped to a class
+ * the layout puts on the page, so a site that wants its own look overrides
+ * the classes rather than fighting a cascade.
+ *
+ * Colours are tokens on :root and the theme is light in every context. Paper
+ * rather than white and ink rather than black: the pages are read for minutes
+ * at a time, and the lower contrast of a warm ground is the difference between
+ * comfortable and glaring. A site that wants a dark theme overrides the
+ * tokens; nothing here switches on its own, because the output is a folder of
+ * files served from anywhere with no runtime to ask the viewer.
+ */
+
+:root {
+  color-scheme: light;
+
+  --bg: #fbfaf7;
+  --surface: #f2f0ea;
+  --border: #e3e0d7;
+  --ink: #24231f;
+  --ink-muted: #6a6760;
+  --accent: #2a5cb8;
+  --accent-soft: #e9eefa;
+  --code-bg: #efece3;
+  --radius: 6px;
+  /* The reading column. Wide enough that a code block or a three-column
+     table is not the first thing to overflow it. */
+  --measure: 44rem;
+  --rail: 12rem;
+  --gutter: 3rem;
+  --font: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--ink);
+  font-family: var(--font);
+  font-size: 17px;
+  line-height: 1.7;
+  -webkit-text-size-adjust: 100%;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+::selection {
+  background: var(--accent-soft);
+}
+
+a {
+  color: var(--accent);
+  text-decoration-thickness: 1px;
+  text-underline-offset: 2px;
+}
+
+/* Keyboard users get the link; everyone else never sees it. */
+.skip {
+  position: absolute;
+  left: -9999px;
+}
+.skip:focus {
+  left: 1rem;
+  top: 1rem;
+  padding: 0.5rem 0.75rem;
+  background: var(--accent-soft);
+  border-radius: var(--radius);
+  z-index: 10;
+}
+
+/* -----------------------------------------------------------------------------
+ * The shell
+ *
+ * Two columns, centred as a whole: the document, and what is in it. The rail
+ * keeps its column whether or not it has contents to draw, so the measure is
+ * the same for every document.
+ * -------------------------------------------------------------------------- */
+
+.shell {
+  max-width: calc(var(--measure) + var(--gutter) + var(--rail) + 2.5rem);
+  margin: 0 auto;
+  padding: 0 1.25rem;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) var(--rail);
+  column-gap: var(--gutter);
+  align-items: start;
+}
+
+.site-main {
+  min-width: 0;
+  max-width: var(--measure);
+  width: 100%;
+  margin: 0 auto;
+  padding: 3rem 0 4rem;
+}
+
+.site-rail {
+  position: sticky;
+  top: 2.25rem;
+  max-height: calc(100vh - 4.5rem);
+  overflow-y: auto;
+  padding: 3rem 0 2rem;
+  overscroll-behavior: contain;
+}
+
+.site-footer {
+  margin-top: 3rem;
+  padding-top: 1.25rem;
+  border-top: 1px solid var(--border);
+  color: var(--ink-muted);
+  font-size: 0.8125rem;
+}
+
+.site-footer p {
+  margin: 0;
+}
+
+/* -----------------------------------------------------------------------------
+ * On this page
+ * -------------------------------------------------------------------------- */
+
+.toc {
+  font-size: 0.8125rem;
+  border-left: 1px solid var(--border);
+  padding-left: 1rem;
+}
+
+.toc-title {
+  margin: 0 0 0.5rem;
+  font-size: 0.6875rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--ink-muted);
+}
+
+.toc-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: grid;
+  gap: 0.3rem;
+}
+
+.toc-list a {
+  color: var(--ink-muted);
+  text-decoration: none;
+  display: block;
+}
+
+.toc-list a:hover {
+  color: var(--ink);
+}
+
+.toc-list a[aria-current] {
+  color: var(--accent);
+}
+
+.toc-depth-2 {
+  padding-left: 0.85rem;
+}
+
+/* -----------------------------------------------------------------------------
+ * Page furniture
+ * -------------------------------------------------------------------------- */
+
+h1 {
+  font-size: 2rem;
+  line-height: 1.25;
+  margin: 0 0 0.6rem;
+  letter-spacing: -0.015em;
+}
+
+.lede {
+  font-size: 1.15rem;
+  line-height: 1.6;
+  color: var(--ink-muted);
+  margin: 0 0 1.75rem;
+}
+
+.page-header {
+  margin-bottom: 2rem;
+}
+
+/* -----------------------------------------------------------------------------
+ * Blocks and prose
+ * -------------------------------------------------------------------------- */
+
+.block {
+  margin: 0 0 2.5rem;
+}
+
+.block-title {
+  font-size: 1.35rem;
+  line-height: 1.3;
+  letter-spacing: -0.01em;
+  margin: 0 0 0.75rem;
+}
+
+/*
+ * A heading is a link to itself, and looks like neither until it is hovered.
+ * The `#` is drawn in the margin so turning it on does not move the text.
+ */
+.anchor {
+  color: inherit;
+  text-decoration: none;
+  /* Containing block for the `#`, so it hangs off this heading and not off
+     whatever happens to be positioned further up the tree. */
+  position: relative;
+}
+
+.anchor::before {
+  content: "#";
+  position: absolute;
+  left: -1.1em;
+  color: var(--ink-muted);
+  opacity: 0;
+  font-weight: 400;
+}
+
+.anchor:hover::before,
+:hover > .anchor::before,
+.anchor:focus-visible::before {
+  opacity: 1;
+}
+
+.prose > :first-child {
+  margin-top: 0;
+}
+
+.prose > :last-child {
+  margin-bottom: 0;
+}
+
+.prose h2 {
+  font-size: 1.35rem;
+  line-height: 1.3;
+  letter-spacing: -0.01em;
+  margin: 2.5rem 0 0.7rem;
+}
+
+.prose h3 {
+  font-size: 1.1rem;
+  line-height: 1.35;
+  margin: 2rem 0 0.5rem;
+}
+
+/* Paragraph rhythm follows the leading: loose text needs loose gaps to keep
+   the block boundaries visible. */
+.prose p,
+.prose ul,
+.prose ol {
+  margin: 0 0 1.15em;
+}
+
+.prose li + li {
+  margin-top: 0.35em;
+}
+
+.prose li > ul,
+.prose li > ol {
+  margin: 0.35em 0 0;
+}
+
+.prose code {
+  font-family: var(--mono);
+  font-size: 0.85em;
+  padding: 0.1em 0.35em;
+  background: var(--code-bg);
+  border-radius: 4px;
+}
+
+/* Wide content scrolls inside its own box; the page body never does. */
+.prose pre {
+  overflow-x: auto;
+  padding: 0.95rem 1.1rem;
+  margin: 0 0 1.5rem;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  font-size: 0.85em;
+  line-height: 1.6;
+}
+
+.prose pre code {
+  padding: 0;
+  background: none;
+}
+
+.prose blockquote {
+  margin: 1.5rem 0;
+  padding-left: 1.1rem;
+  border-left: 3px solid var(--border);
+  color: var(--ink-muted);
+}
+
+.prose table {
+  width: 100%;
+  border-collapse: collapse;
+  display: block;
+  overflow-x: auto;
+  margin: 0 0 1.5rem;
+  font-size: 0.9375em;
+}
+
+.prose th,
+.prose td {
+  border: 1px solid var(--border);
+  padding: 0.45rem 0.7rem;
+  text-align: left;
+}
+
+.prose th {
+  background: var(--surface);
+  font-weight: 600;
+}
+
+figure {
+  margin: 0;
+}
+
+figure img {
+  max-width: 100%;
+  height: auto;
+  border-radius: var(--radius);
+}
+
+figcaption {
+  margin-top: 0.5rem;
+  color: var(--ink-muted);
+  font-size: 0.875rem;
+}
+
+pre.mermaid {
+  background: none;
+  border: none;
+  padding: 0;
+  text-align: center;
+  /* Until the client script swaps the source for an SVG there is nothing worth
+     showing, and a wall of diagram source is worse than a gap. */
+  visibility: hidden;
+}
+
+pre.mermaid[data-processed="true"] {
+  visibility: visible;
+}
+
+.empty,
+.block-unknown {
+  padding: 0.9rem 1rem;
+  border: 1px dashed var(--border);
+  border-radius: var(--radius);
+  color: var(--ink-muted);
+}
+
+/* -----------------------------------------------------------------------------
+ * Copy as markdown
+ *
+ * One button, under the title where the document begins. Quiet — an outline
+ * and muted ink, no fill — because the reader came for the prose and this is a
+ * tool beside it.
+ * -------------------------------------------------------------------------- */
+
+.copy {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  padding: 0.25rem 0.6rem;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  background: transparent;
+  color: var(--ink-muted);
+  font-family: inherit;
+  font-size: 0.8125rem;
+  line-height: 1.5;
+  cursor: pointer;
+  transition:
+    color 120ms ease,
+    border-color 120ms ease,
+    background-color 120ms ease;
+}
+
+.copy:hover,
+.copy:focus-visible {
+  color: var(--ink);
+  border-color: var(--accent);
+  background: var(--surface);
+}
+
+.copy[data-state="done"] {
+  color: var(--accent);
+  border-color: var(--accent);
+  background: var(--accent-soft);
+}
+
+.copy-icon {
+  display: none;
+}
+
+.copy[data-state="idle"] .copy-icon-idle,
+.copy[data-state="failed"] .copy-icon-idle,
+.copy[data-state="done"] .copy-icon-done {
+  display: inline;
+}
+
+/*
+ * All three labels are stacked in one grid cell, so the button is as wide as
+ * the longest of them and saying "Copied" does not resize it mid-click. They
+ * are hidden rather than removed for the same reason — a removed label takes
+ * its width with it.
+ */
+.copy-label {
+  display: grid;
+}
+
+.copy-text {
+  grid-area: 1 / 1;
+  white-space: nowrap;
+  visibility: hidden;
+}
+
+.copy[data-state="idle"] .copy-text-idle,
+.copy[data-state="done"] .copy-text-done,
+.copy[data-state="failed"] .copy-text-failed {
+  visibility: visible;
+}
+
+/* The lede above it already sets the gap; a document without one gets the h1's. */
+.page-actions {
+  margin: 0;
+}
+
+/* -----------------------------------------------------------------------------
+ * Narrower screens
+ *
+ * The rail goes: it is the column whose job the reader can do by scrolling.
+ * -------------------------------------------------------------------------- */
+
+@media (max-width: 60rem) {
+  .shell {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .site-rail {
+    display: none;
+  }
+}
+
+@media (max-width: 52rem) {
+  .site-main {
+    padding: 2rem 0 3rem;
+  }
+}
+
+/* -----------------------------------------------------------------------------
+ * The wide view
+ *
+ * One mode for the page rather than an escape hatch per block. The rail goes,
+ * the gutters tighten and the measure comes off, so the content is bounded by
+ * the window and nothing else. Everything here is a class on
+ * the root element, so the whole layout switches in one place and every rule
+ * that draws the narrow page is left exactly as it was.
+ * -------------------------------------------------------------------------- */
+
+.wide-toggle {
+  position: fixed;
+  right: 1rem;
+  bottom: 1rem;
+  z-index: 5;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  padding: 0.3rem 0.65rem;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  background: var(--bg);
+  color: var(--ink-muted);
+  font-family: inherit;
+  font-size: 0.8125rem;
+  line-height: 1.5;
+  cursor: pointer;
+  box-shadow: 0 2px 10px rgb(36 35 31 / 8%);
+  /* Chrome, not content: quiet until the reader goes looking for it. */
+  opacity: 0.65;
+  transition:
+    opacity 120ms ease,
+    color 120ms ease,
+    border-color 120ms ease;
+}
+
+.wide-toggle:hover,
+.wide-toggle:focus-visible {
+  opacity: 1;
+  color: var(--ink);
+  border-color: var(--accent);
+}
+
+.wide-icon,
+.wide-label {
+  display: none;
+}
+
+.wide-icon-out,
+.wide-label-out {
+  display: inline;
+}
+
+.wide .wide-icon-out,
+.wide .wide-label-out {
+  display: none;
+}
+
+.wide .wide-icon-in,
+.wide .wide-label-in {
+  display: inline;
+}
+
+.wide .site-rail {
+  display: none;
+}
+
+.wide .site-main {
+  max-width: none;
+}
+
+.wide .shell {
+  max-width: none;
+  grid-template-columns: minmax(0, 1fr);
+}
+
+/* Mermaid writes onto the diagram the pixel width that fitted the measure.
+   There is more room now, so let it take it. */
+.wide pre.mermaid svg {
+  max-width: 100%;
+  width: 100%;
+  height: auto;
+}

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "theme/**/*", "astro.config.mjs"],
+  "exclude": ["dist", "src", "test"]
+}