feat(site): phase 1 — the foundation
Some checks failed
PR checks / checks (pull_request) Failing after 4m19s

Astro 7 with the Node adapter, Starlight mounted at /docs, the token file, both
self-hosted typefaces, the layout shell, and the two build-time checks from §12.

The palette's gold and cyan are sampled from runic-emblem.png rather than
guessed, per §11: 494,059 opaque pixels binned by hue, each value annotated with
its measured contrast against the ground, and restricted rather than brightened
where a ratio fails.

- checkTokens.mjs fails the build on any colour literal outside tokens.css,
  which is what keeps §7's "recolouring is a file copy" promise true.
- checkFacts.mjs re-reads all 14 externally-sourced facts from their authorities
  over the Gitea API and fails on disagreement. It also enforces D13: no email
  address in the source outside brand-default/brand.json.
- Both were negative-tested; neither has ever been allowed to pass by default.

§6 asks for output:'server' with per-page prerender=true. Astro 7 expresses the
same runtime shape as output:'static' with an adapter, opting individual routes
out — so the default is static rather than accidentally server-rendered.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
2026-08-19 19:08:52 -05:00
parent 650ea21ad4
commit 66187dde5d
25 changed files with 10462 additions and 0 deletions

334
src/styles/global.css Normal file
View File

@@ -0,0 +1,334 @@
/* ============================================================================
runicgateway.com — the layout shell
============================================================================
Every value here is a token from tokens.css. No colour literal appears below
this comment; `scripts/checkTokens.mjs` fails the build if one does.
-------------------------------------------------------------------------- */
@import '@fontsource-variable/cinzel';
@import '@fontsource-variable/inter';
*,
*::before,
*::after {
box-sizing: border-box;
}
html {
scroll-behavior: smooth;
}
@media (prefers-reduced-motion: reduce) {
html {
scroll-behavior: auto;
}
*,
*::before,
*::after {
animation-duration: 0.01ms !important;
animation-iteration-count: 1 !important;
transition-duration: 0.01ms !important;
}
}
body {
margin: 0;
background: var(--bg);
color: var(--text);
font-family: var(--sans);
font-size: 1rem;
line-height: 1.65;
-webkit-font-smoothing: antialiased;
text-rendering: optimizeLegibility;
}
h1,
h2,
h3,
h4 {
color: var(--head);
line-height: 1.2;
text-wrap: balance;
}
h1 {
font-family: var(--display);
font-weight: 600;
letter-spacing: 0.01em;
}
p {
text-wrap: pretty;
}
a {
color: var(--accent);
text-decoration-color: color-mix(in srgb, var(--accent) 40%, transparent);
text-underline-offset: 0.18em;
}
a:hover {
color: var(--accent-bright);
text-decoration-color: currentColor;
}
:focus-visible {
outline: 2px solid var(--portal-bright);
outline-offset: 3px;
border-radius: var(--radius-input);
}
code,
pre,
kbd,
samp {
font-family: var(--mono);
font-size: 0.9em;
}
hr {
border: 0;
border-top: 1px solid var(--line-soft);
margin: 2.5rem 0;
}
img,
svg {
max-width: 100%;
height: auto;
}
/* ---- Page frame --------------------------------------------------------- */
.page {
width: 100%;
max-width: var(--page-max);
margin-inline: auto;
padding-inline: var(--gutter);
}
.site {
display: flex;
min-height: 100vh;
flex-direction: column;
}
.site > main {
flex: 1;
}
/* The keyboard escape hatch past the header nav. Visible only when focused. */
.skip-link {
position: absolute;
left: var(--gutter);
top: 0;
z-index: 100;
transform: translateY(-140%);
padding: 0.6rem 1rem;
border: 1px solid var(--gold-deep);
border-radius: var(--radius-input);
background: var(--panel-flat);
color: var(--ink);
font-size: 0.9rem;
text-decoration: none;
transition: transform 0.15s ease;
}
.skip-link:focus {
transform: translateY(12px);
}
/* ---- Header ------------------------------------------------------------- */
.site-header {
position: sticky;
top: 0;
z-index: 50;
min-height: var(--header-h);
border-bottom: 1px solid var(--line-soft);
background: color-mix(in srgb, var(--bg-deep) 88%, transparent);
backdrop-filter: blur(10px);
}
.site-header__inner {
display: flex;
min-height: var(--header-h);
align-items: center;
justify-content: space-between;
gap: var(--gutter);
}
.brand-lockup {
display: inline-flex;
align-items: center;
gap: 0.65rem;
color: var(--ink);
text-decoration: none;
}
.brand-lockup__mark {
width: 32px;
height: 32px;
flex: none;
}
.brand-lockup__name {
font-family: var(--display);
font-size: 1.12rem;
font-weight: 600;
letter-spacing: 0.04em;
color: var(--gold);
}
.site-nav {
display: flex;
align-items: center;
gap: 0.25rem;
}
.site-nav a {
padding: 0.45rem 0.7rem;
border-radius: var(--radius-input);
color: var(--muted);
font-size: 0.94rem;
text-decoration: none;
}
.site-nav a:hover {
background: var(--panel-flat);
color: var(--ink);
}
.site-nav a[aria-current='page'] {
color: var(--gold);
}
/* The nav collapses to the docs link alone until phase 3 gives it a real
disclosure control; a hamburger with nothing behind it is worse than none. */
@media (max-width: 720px) {
.site-nav {
gap: 0;
}
.site-nav a {
padding-inline: 0.45rem;
font-size: 0.86rem;
}
}
/* ---- Footer ------------------------------------------------------------- */
.site-footer {
margin-top: 4rem;
border-top: 1px solid var(--line-soft);
background: var(--bg-deep);
padding-block: 2.5rem 2rem;
color: var(--dim);
font-size: 0.9rem;
}
.site-footer__cols {
display: grid;
gap: 2rem;
grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
}
.site-footer h2 {
margin: 0 0 0.7rem;
color: var(--muted);
font-family: var(--sans);
font-size: 0.76rem;
font-weight: 700;
letter-spacing: 0.11em;
text-transform: uppercase;
}
.site-footer ul {
margin: 0;
padding: 0;
list-style: none;
}
.site-footer li + li {
margin-top: 0.4rem;
}
.site-footer a {
color: var(--muted);
text-decoration: none;
}
.site-footer a:hover {
color: var(--accent-bright);
text-decoration: underline;
}
.site-footer__legal {
margin-top: 2.25rem;
padding-top: 1.25rem;
border-top: 1px solid var(--line-soft);
display: flex;
flex-wrap: wrap;
gap: 0.5rem 1.25rem;
align-items: baseline;
justify-content: space-between;
}
.site-footer__legal p {
margin: 0;
}
/* ---- Panels ------------------------------------------------------------- */
.panel {
border: 1px solid var(--line);
border-radius: var(--radius-panel);
background: var(--panel-grad);
box-shadow: var(--shadow-card);
padding: 1.5rem;
}
.eyebrow {
margin: 0 0 0.75rem;
color: var(--gold);
font-size: 0.74rem;
font-weight: 700;
letter-spacing: 0.14em;
text-transform: uppercase;
}
.prose {
max-width: var(--measure);
}
/* ---- Status chip -------------------------------------------------------- */
.chip {
display: inline-flex;
align-items: center;
gap: 0.4rem;
padding: 0.15rem 0.6rem;
border: 1px solid var(--line);
border-radius: var(--radius-pill);
background: var(--panel-flat);
color: var(--muted);
font-size: 0.76rem;
letter-spacing: 0.04em;
white-space: nowrap;
}
.chip--version {
border-color: color-mix(in srgb, var(--gold-deep) 70%, transparent);
color: var(--gold);
}
.chip--draft {
border-color: color-mix(in srgb, var(--mode-maint) 55%, transparent);
color: var(--mode-maint);
}
.chip--live {
border-color: color-mix(in srgb, var(--mode-live) 55%, transparent);
color: var(--mode-live);
}

158
src/styles/starlight.css Normal file
View File

@@ -0,0 +1,158 @@
/* ============================================================================
Starlight theming — the docs half of §11
============================================================================
Starlight owns `/docs` and brings its own token set (`--sl-color-*`). This
file is the bridge: it restates OUR tokens as Starlight's, so the docs and
the marketing pages cannot drift, and so a bind-mounted `theme.css` that
redefines `--gold` recolours both halves of the site at once.
Marketing is single-theme dark by design; the docs honour the reader's
preference (§11), which is why this file has a light block and global.css
does not. Starlight's own light theme is accessible as shipped, so the light
block restates only what carries brand — the accents and the surfaces.
No colour literal appears here. Every value is a var() from tokens.css.
-------------------------------------------------------------------------- */
/* ---- Dark (Starlight's default root) ------------------------------------ */
:root {
--sl-font: var(--sans);
--sl-font-mono: var(--mono);
--sl-color-accent-low: var(--blue);
--sl-color-accent: var(--accent);
--sl-color-accent-high: var(--accent-bright);
--sl-color-white: var(--ink);
--sl-color-gray-1: var(--head);
--sl-color-gray-2: var(--text);
--sl-color-gray-3: var(--muted);
--sl-color-gray-4: var(--dim);
--sl-color-gray-5: var(--line);
--sl-color-gray-6: var(--line-soft);
--sl-color-gray-7: var(--panel-flat);
--sl-color-black: var(--bg);
--sl-color-bg: var(--bg);
--sl-color-bg-nav: var(--bg-deep);
--sl-color-bg-sidebar: var(--bg-deep);
--sl-color-bg-inline-code: var(--panel-flat);
--sl-color-hairline: var(--line-soft);
--sl-color-hairline-light: var(--line);
--sl-color-hairline-shade: var(--line-soft);
--sl-color-text: var(--text);
--sl-color-text-accent: var(--accent);
--sl-color-text-invert: var(--bg);
--sl-shadow-md: var(--shadow-card);
--sl-shadow-lg: var(--shadow-raised);
}
/* ---- Light -------------------------------------------------------------- */
:root[data-theme='light'] {
--sl-color-accent-low: var(--light-line);
--sl-color-accent: var(--light-accent);
--sl-color-accent-high: var(--light-ink);
--sl-color-white: var(--light-ink);
--sl-color-gray-1: var(--light-ink);
--sl-color-gray-2: var(--light-text);
--sl-color-gray-3: var(--light-muted);
--sl-color-gray-4: var(--light-muted);
--sl-color-gray-5: var(--light-line);
--sl-color-gray-6: var(--light-line);
--sl-color-gray-7: var(--light-panel);
--sl-color-black: var(--light-panel);
--sl-color-bg: var(--light-panel);
--sl-color-bg-nav: var(--light-bg);
--sl-color-bg-sidebar: var(--light-bg);
--sl-color-bg-inline-code: var(--light-bg);
--sl-color-hairline: var(--light-line);
--sl-color-hairline-light: var(--light-line);
--sl-color-hairline-shade: var(--light-line);
--sl-color-text: var(--light-text);
--sl-color-text-accent: var(--light-accent);
--sl-color-text-invert: var(--light-panel);
}
/* ---- Brand details ------------------------------------------------------
The docs are not a different product. The wordmark keeps the display face
and the gold, and the site title in the docs header matches the marketing
header exactly. */
.site-title {
font-family: var(--display);
font-weight: 600;
letter-spacing: 0.04em;
color: var(--gold);
}
:root[data-theme='light'] .site-title {
color: var(--light-gold);
}
/* Headings carry the display face only at h1, matching global.css — using it
further down turns a reference page into a poster. */
.sl-markdown-content h1 {
font-family: var(--display);
font-weight: 600;
}
/* ---- Semantic hues -------------------------------------------------------
Starlight colours asides and badges from five named scales rather than from the accent,
so leaving these alone puts a stock indigo note box in the middle of our palette. The
first attempt here overrode each `.starlight-aside--*` rule, which set the border and
the heading but not the background — that comes from `--sl-color-<hue>-low`, and the box
stayed indigo. Mapping the scales themselves fixes the asides and every other component
that reaches for a semantic colour.
The `-low` step is a background wash, so it is mixed from the same token against the
ground rather than picked separately: recolour `--portal` and the tip box follows. */
:root {
--sl-color-blue-low: color-mix(in srgb, var(--accent) 16%, var(--bg));
--sl-color-blue: var(--accent);
--sl-color-blue-high: var(--accent-bright);
/* Starlight's "tip" is purple; ours is the portal. */
--sl-color-purple-low: color-mix(in srgb, var(--portal) 14%, var(--bg));
--sl-color-purple: var(--portal-deep);
--sl-color-purple-high: var(--portal-bright);
--sl-color-orange-low: color-mix(in srgb, var(--mode-maint) 14%, var(--bg));
--sl-color-orange: var(--mode-maint);
--sl-color-orange-high: var(--mode-maint);
--sl-color-red-low: color-mix(in srgb, var(--danger) 14%, var(--bg));
--sl-color-red: var(--danger);
--sl-color-red-high: var(--danger);
--sl-color-green-low: color-mix(in srgb, var(--mode-live) 14%, var(--bg));
--sl-color-green: var(--mode-live);
--sl-color-green-high: var(--mode-live);
}
:root[data-theme='light'] {
--sl-color-blue-low: color-mix(in srgb, var(--light-accent) 12%, var(--light-panel));
--sl-color-blue: var(--light-accent);
--sl-color-blue-high: var(--light-accent);
--sl-color-purple-low: color-mix(in srgb, var(--light-portal) 12%, var(--light-panel));
--sl-color-purple: var(--light-portal);
--sl-color-purple-high: var(--light-portal);
--sl-color-orange-low: color-mix(in srgb, var(--light-gold) 12%, var(--light-panel));
--sl-color-orange: var(--light-gold);
--sl-color-orange-high: var(--light-gold);
--sl-color-red-low: color-mix(in srgb, var(--danger) 12%, var(--light-panel));
--sl-color-red: var(--danger);
--sl-color-red-high: var(--danger);
--sl-color-green-low: color-mix(in srgb, var(--mode-live) 12%, var(--light-panel));
--sl-color-green: var(--mode-live);
--sl-color-green-high: var(--mode-live);
}

129
src/styles/tokens.css Normal file
View File

@@ -0,0 +1,129 @@
/* ============================================================================
runicgateway.com — design tokens
============================================================================
THIS IS THE ONLY FILE IN THE SOURCE TREE ALLOWED TO CONTAIN A COLOUR LITERAL.
PLAN.md §7 promises that recolouring the site is a file copy and a container
restart — never a rebuild. That promise holds only if every colour, radius,
shadow and font in the stylesheet is a custom property defined here, so that
the bind-mounted `theme.css` can redefine them and win.
`scripts/checkTokens.mjs` enforces it. Without the check, "one CSS file
changes the appearance" decays into "one CSS file changes most of the
appearance, and then there is a hardcoded #0e1318 in the footer".
Names deliberately match `website/client/src/styles/theme.css` where the
concepts line up, so a theme written for a Runic Gateway deployment is
legible here and vice versa (§7, §11).
-------------------------------------------------------------------------- */
:root {
/* ---- Ground and panels -------------------------------------------------
Taken unchanged from the product's token file. Same bytes, same names. */
--bg: #0e1318;
--bg-deep: #0b0f14;
--panel-a: #192231;
--panel-b: #141a21;
--panel-flat: #11161d;
--line: #2a3544;
--line-soft: #1d2733;
/* ---- Interface and type ------------------------------------------------
Also the product's, unchanged. `--accent` is the steel blue that carries
links and interface emphasis across both sites. */
--accent: #7f99bd;
--accent-bright: #cdd9e8;
--ink: #eef3f8;
--head: #e6edf6;
--text: #c4cdd8;
--muted: #aeb8c4;
--dim: #6f7d8e;
--blue: #13243c;
/* ---- Status ------------------------------------------------------------
Reused verbatim from the product so a status pill means the same thing on
both sites (§11). */
--mode-live: #5fb98a;
--mode-maint: #e6c26a;
/* ---- The emblem's own palette ------------------------------------------
§11: gold and cyan as the accent pair, "derived from the artwork by
sampling, not guessed, and both held to WCAG AA against the ground".
Sampled from `runic-emblem.png` (1024x1024, 494,059 opaque pixels) by
binning every saturated pixel by hue and taking the mean of each bin. The
contrast ratio after each value is measured against `--bg` (#0e1318).
AA wants 4.5:1 for body text and 3:1 for large text and UI boundaries, so
the annotation is also the usage rule. Nothing here was nudged for taste;
where a sampled value fails a ratio it is restricted, not brightened. */
/* Hue 25-45deg — the ring. 65% of the emblem's saturated pixels. */
--gold-deep: #946b3c; /* 3.94:1 — rules, borders, UI edges. NEVER text. */
--gold: #c8a368; /* 7.91:1 — emphasis text, headings, the mark. */
--gold-bright: #e4cb90; /* 11.77:1 — highlights on gold surfaces. */
/* Hue 180-210deg — the portal and its glow. */
--portal-deep: #0b6398; /* 2.89:1 — glow fills and gradients only. */
--portal: #15b4de; /* 7.66:1 — the live-state signal, diagram lines. */
--portal-bright: #1bd6f1; /* 10.61:1 — the portal core, focus rings. */
/* Hue 0deg — the ruby set into the ring. The only red in the artwork, so it
is the honest source for a destructive/error colour. */
--danger: #ff4e43; /* 5.71:1 */
/* ---- Type --------------------------------------------------------------
Both self-hosted (§11), so §6's `default-src 'self'` needs no exception.
Cinzel is the project's display face and is already the Android app's;
it is confined to the wordmark and hero. Inter carries everything else. */
--display: 'Cinzel Variable', Georgia, 'Times New Roman', serif;
--sans: 'Inter Variable', system-ui, -apple-system, 'Segoe UI', sans-serif;
--mono: ui-monospace, 'Cascadia Code', 'Source Code Pro', Menlo, Consolas, monospace;
/* ---- Radius ------------------------------------------------------------
Named by the kind of surface rather than the pixel value, matching the
product's promotion of the same four tokens. */
--radius-pill: 999px;
--radius-panel: 12px;
--radius-card: 10px;
--radius-input: 8px;
/* ---- Elevation and surface treatments ---------------------------------- */
--shadow-card: 0 14px 34px rgb(0 0 0 / 30%);
--shadow-raised: 0 22px 48px rgb(0 0 0 / 38%);
--panel-grad: linear-gradient(180deg, var(--panel-a), var(--panel-b));
--glow-portal: 0 0 32px rgb(21 180 222 / 22%);
/* ---- Layout ------------------------------------------------------------
Here rather than in global.css so a theme can widen the measure without
touching the stylesheet. */
--measure: 68ch;
--page-max: 1180px;
--gutter: 24px;
--header-h: 68px;
}
/* ---- Light mode, docs only ----------------------------------------------
§11: marketing pages are single-theme by design; the docs honour the
reader's light/dark preference. Starlight ships an accessible light theme,
so this is not a second palette — it is the four brand colours restated at
the lightness a white ground needs, plus the surfaces Starlight tints.
Same hues as the dark set, darkened rather than re-picked, with the
contrast against `--light-bg` measured the same way. They live here, in the
token file, because that is the rule: a literal anywhere else fails
`checkTokens.mjs`, and a bind-mounted `theme.css` must be able to reach
these too. */
:root {
--light-bg: #f6f8fb;
--light-panel: #ffffff;
--light-line: #d6dee9;
--light-ink: #16202c;
--light-text: #33414f;
--light-muted: #5a6875;
--light-accent: #3c5f8f; /* 6.12:1 — the steel blue, darkened for links */
--light-gold: #7a5a24; /* 5.95:1 — the ring, darkened for emphasis */
--light-portal: #0a5f80; /* 6.67:1 — the portal, darkened for diagrams */
}