From 6435f076e28407f199f559873cc7e26755d53b0f Mon Sep 17 00:00:00 2001
From: John Morrissey <544926+tachyon-beep@users.noreply.github.com>
Date: Sun, 9 Aug 2026 08:08:15 +1000
Subject: [PATCH 1/6] site: implement static-content review fixes (site stream)
Linkified citation spine into /design/, OG/Twitter/canonical metadata +
social card, status-note honesty + as-of date, token fixes (bg-note-status,
hue drift), theme swap, a11y fixes (tabindex, target size,
en-GB, permalinks), 404/robots/sitemap, favicon consolidation, deploy
gates (html-validate + offline linkcheck), design-skill safe subset.
Co-Authored-By: Claude Fable 5
---
.claude/skills/simic-design/readme.md | 37 ++++++---
.github/workflows/deploy-site.yml | 25 ++++++
site/404.html | 91 ++++++++++++++++++++
site/architecture.html | 96 +++++++++++++---------
site/assets/mark.svg | 1 +
site/assets/social-card.png | Bin 0 -> 62763 bytes
site/assets/social-card.src.html | 97 ++++++++++++++++++++++
site/index.html | 105 +++++++++++++++---------
site/lineage.html | 71 ++++++++++------
site/robots.txt | 10 +++
site/sitemap.xml | 29 +++++++
site/style.css | 114 ++++++++++++++++++++------
tools/ci/linkcheck.py | 71 ++++++++++++++++
13 files changed, 607 insertions(+), 140 deletions(-)
create mode 100644 site/404.html
create mode 100644 site/assets/mark.svg
create mode 100644 site/assets/social-card.png
create mode 100644 site/assets/social-card.src.html
create mode 100644 site/robots.txt
create mode 100644 site/sitemap.xml
create mode 100755 tools/ci/linkcheck.py
diff --git a/.claude/skills/simic-design/readme.md b/.claude/skills/simic-design/readme.md
index 25cc025..f1c71fe 100644
--- a/.claude/skills/simic-design/readme.md
+++ b/.claude/skills/simic-design/readme.md
@@ -31,13 +31,15 @@ Source repo: https://github.com/foundryside-dev/simic — explore it for the can
## VISUAL FOUNDATIONS
-**Color**: OKLCH throughout. Blue-green world: hue 225 ("ink") carries all structure — backgrounds, text, borders; hue 175 (teal) carries emphasis — links, accents, active nav, callout spines; hue 85 (amber) is the sole warning color. Both themes come from one palette via `light-dark()`; `color-scheme: light dark` follows the OS, `[data-theme]` overrides. Max 2 background colors per page (`--color-bg`, `--color-bg-subtle`), plus tinted note backgrounds. Never pure black/white.
+**Color**: OKLCH throughout. Blue-green world: hue 225 ("ink") carries all structure — backgrounds, text, borders; hue 175 (teal) carries emphasis — links, accents, active nav, callout spines; hue 85 (amber) is the sole warning color. A callout holds its family's hue on both sides of `light-dark()` — never let the dark side drift off-hue. Both themes come from one palette via `light-dark()`. Max 2 background colors per page (`--color-bg`, `--color-bg-subtle`), plus the two tinted note grounds (`--color-bg-note`, `--color-bg-note-status`). Never pure black/white.
+
+**Theme model — two-state, not three.** The marketing site follows the OS via `color-scheme: light dark` and **has no toggle**: it ships zero JavaScript, so nothing ever sets `data-theme`. The `:root[data-theme]` rules in `site/style.css` are an unreached hook, kept for a future toggle; the diagrams cannot follow them at all (they select via ``, resolved by the layout engine). Only the **wiki** is three-state — MkDocs Material supplies its own toggle. Do not describe the marketing site as having a theme switcher.
**Type**: system stacks only, on purpose (zero third-party requests — a privacy stance, not an omission). Body `system-ui…`; code/labels `ui-monospace…`. Mono is the brand's display voice: the wordmark, taglines, note labels, invariant chips, table `name` cells are all mono. Fluid heading sizes via `clamp()`. Base 1rem/1.65. h1 tracking -0.02em; mono labels tracked out (+0.04–0.08em) and often uppercase at ~0.78rem.
**Spacing/layout**: 8px-base scale (`--space-1..7` = 4/8/16/24/32/48/72px). Two widths: prose `--measure` 46rem, wide blocks (tables, diagrams, grids) `--page` 62rem. Prose is narrow by default; wide elements opt out.
-**Backgrounds**: flat solid colors only. No gradients, no textures, no imagery, no photography. The only "images" are pre-rendered Mermaid diagram SVGs, shipped in light+dark pairs and swapped with the color tokens.
+**Backgrounds**: flat solid colors only. No gradients, no textures, no imagery, no photography. The only "images" are pre-rendered Mermaid diagram SVGs, shipped in light+dark pairs and selected by `` + `media="screen and (prefers-color-scheme: dark)"` — one variant fetched, and print falls through to the light one. The single exception is `site/assets/social-card.png`, a 1200×630 Open Graph card rendered from `social-card.src.html`; it is a fixed dark artefact and does not track the viewer's theme.
**Borders & radius**: 1px hairline `--color-border` everywhere (h2 top rules, table rows, cards, code); `--color-border-firm` for firmer edges. Radius `4px` (3px on inline code, 2px on focus rings). Callouts and quotes use a 3px left spine (teal = note/canon, amber = status, neutral = plain quote).
@@ -52,7 +54,7 @@ Source repo: https://github.com/foundryside-dev/simic — explore it for the can
## ICONOGRAPHY
There is **no icon system**. The site ships zero icon fonts, zero icon SVG sets. The complete iconography:
-- **The mark**: a teal diamond (`assets/mark.svg`, `#0f9b8e`), used as favicon and rendered as the `◈` character before the wordmark (`.wordmark::before`, colored accent). This is the closest thing to a logo — there is no wordmark image; the wordmark is live text in mono.
+- **The mark**: a teal diamond, used as favicon and rendered as the `◈` character before the wordmark (`.wordmark::before`, colored accent). This is the closest thing to a logo — there is no wordmark image; the wordmark is live text in mono. One file, two deployed copies kept byte-identical: `site/assets/mark.svg` (marketing) and `tools/wiki/assets/mark.svg` (wiki logo + favicon). Its `#0f9b8e` is a fixed hex, not a token — a favicon cannot use `light-dark()` — and sits between `--teal-600` and `--teal-400`; do not introduce a fourth teal to match it.
- **Unicode as UI glyphs**: `◈` (wordmark), `→` (forward links "Read the architecture →"), `›` (breadcrumbs), `·` (footer separators).
- **Diagrams**: pre-rendered Mermaid SVGs in `assets/diagrams/` (light/dark pairs) — the only illustrations in the brand.
- The wiki (Material theme) uses Material Design icons only for chrome (theme toggle, GitHub link, permalinks); content uses none.
@@ -61,13 +63,28 @@ Do not introduce icon sets, emoji, or drawn illustrations. When an icon urge str
## Index
-- `styles.css` — global entry (imports everything below)
-- `tokens/` — `colors.css`, `typography.css`, `spacing.css`, `base.css`
-- `assets/` — `mark.svg`, `diagrams/` (6 Mermaid SVGs, light/dark pairs)
-- `guidelines/` — foundation specimen cards
-- `components/site/` — Masthead, SiteFooter, PageHead, Note, CanonQuote, Spine, CardGrid, DataTable, Split, Diagram (the full inventory `site/style.css` defines — nothing invented)
-- `ui_kits/website/` — recreation of the overview page
-- `ui_kits/wiki/` — recreation of a design-docs wiki page (MkDocs Material)
+> **⚠ INCOMPLETE EXPORT — read before using this skill.** Only the eight
+> metadata files were committed (`6e74997`). The 33 files listed below under
+> `tokens/`, `components/`, `guidelines/` and `ui_kits/` are **absent from this
+> directory** and are not gitignored — they were never committed. `styles.css`
+> is therefore four dangling `@import`s and loads nothing.
+>
+> Until the export is completed, **treat `site/style.css` in the repo as the
+> token source of truth** (it always was — see the note above) and read
+> `_ds_manifest.json` for the resolved token values, which it carries inline.
+> Do not hand-author replacements for the files below: they exist in the
+> upstream Claude Design project `SimicDesignSystem_5a908e` and re-exporting or
+> pulling them (`DesignSync`) is the fix. Do not edit this Index to match the
+> disk either — the gap is the record of what is missing.
+
+- `styles.css` — global entry (imports everything below) — **present but inert**
+- `tokens/` — `colors.css`, `typography.css`, `spacing.css`, `base.css` — **missing**
+- `assets/` — `mark.svg`, `diagrams/` (6 Mermaid SVGs, light/dark pairs) — **missing** (both live in the repo: `site/assets/mark.svg`, `site/assets/diagrams/`)
+- `guidelines/` — foundation specimen cards (14 files) — **missing**
+- `components/{content,data,navigation}/` — Masthead, SiteFooter, PageHead, Note, CanonQuote, Spine, CardGrid, DataTable, Split, Diagram (the full inventory `site/style.css` defines — nothing invented) — **missing**
+- `ui_kits/website/` — recreation of the overview page — **missing**
+- `ui_kits/wiki/` — recreation of a design-docs wiki page (MkDocs Material) — **missing**
+- `_ds_manifest.json` — component/token index; the only complete record of the palette in this directory
- `SKILL.md` — agent skill entry point
**Intentional additions**: none. The component list is exactly the class inventory of `site/style.css`. The wiki surface is stock MkDocs Material (teal/teal, `font: false`) — recreated as a UI kit screen, not as components.
diff --git a/.github/workflows/deploy-site.yml b/.github/workflows/deploy-site.yml
index 1e11433..1a1208d 100644
--- a/.github/workflows/deploy-site.yml
+++ b/.github/workflows/deploy-site.yml
@@ -25,6 +25,9 @@ on:
- 'docs/design/**'
- 'docs/adr/**'
- 'tools/wiki/**'
+ # The pre-upload gates: a change to either must re-run against the
+ # current site, not wait for the next content edit to notice it.
+ - 'tools/ci/**'
- '.github/workflows/deploy-site.yml'
workflow_dispatch:
@@ -110,6 +113,28 @@ jobs:
echo " root pages: $(find _pages -maxdepth 1 -name '*.html' | wc -l)"
echo " wiki pages: $(find _pages/design -name '*.html' | wc -l)"
+ - name: Validate the hand-written pages
+ # The wiki half is gated by `mkdocs build --strict` above; this is the
+ # equivalent gate for site/, which is hand-written and had none. Scoped
+ # to the ROOT pages on purpose — the generated Material output is the
+ # upstream theme's business, not ours, and linting it here would fail
+ # the deploy on markup we do not author.
+ run: npx --yes html-validate '_pages/*.html'
+
+ - name: Check internal links and fragments
+ # Offline: every href/src in the root pages must resolve to a file in
+ # the artifact, and every #fragment to a real id on the target page.
+ # External URLs are listed, never fetched — a deploy must not fail
+ # because GitHub rate-limited us.
+ #
+ # This exists because the marketing pages deep-link into the generated
+ # wiki (/design/02-constitution/#53-the-canonical-sentence). Those slugs
+ # are derived from chapter headings, so rewording a heading silently
+ # breaks a citation on the other half of the site. That is precisely the
+ # class of break --strict catches within the wiki and nothing caught
+ # across the seam.
+ run: python3 tools/ci/linkcheck.py _pages
+
- name: Upload Pages artifact
uses: actions/upload-pages-artifact@v3
with:
diff --git a/site/404.html b/site/404.html
new file mode 100644
index 0000000..07e68d4
--- /dev/null
+++ b/site/404.html
@@ -0,0 +1,91 @@
+
+
+
+
+
+Page not found — Simic
+
+
+
+
+
+
+
+Skip to content
+
+
+
+ Nothing is published at that address. The site is small enough to list
+ exhaustively, so one of the links below is almost certainly what you
+ wanted.
+
+ If you followed a link from the design-docs wiki or from
+ the repository and
+ landed here, that is a broken cross-reference worth reporting as an issue.
+
This page is a digest. The canonical text is
- docs/design/02-constitution.md (naming constitution and the
- 45 invariants) and docs/design/04-architecture.md (system
- context, planes, control hierarchy) in
- the repository.
+ 02-constitution.md
+ (naming constitution and the 45 invariants) and
+ 04-architecture.md
+ (system context, planes, control hierarchy), published in full at
+ /design/ and versioned in
+ the repository.
-
Actors have verbs. Infrastructure has prepositions.
+
Actors have verbs. Infrastructure has prepositions.#
The locked convention distinguishes agents from
@@ -68,7 +84,7 @@
Actors have verbs. Infrastructure has prepositions.
happen.
-
+
The three infrastructure domains
@@ -102,7 +118,7 @@
Actors have verbs. Infrastructure has prepositions.
-
+
The eleven agent domains
@@ -139,12 +155,13 @@
Actors have verbs. Infrastructure has prepositions.
Because each domain owns a verb, the narrative grammar doubles as a cheap
@@ -302,7 +323,7 @@
The sentence test
Healthy
-
Nissa published the same TelemetryEnvelope
+
Nissa published the same TelemetryEnvelope
to Narset and Momir.
Narset issued a GrowthIntent for Region A
under Tamiyo's envelope.
@@ -317,7 +338,7 @@
Healthy
Triggers review
-
Narset forwarded a captioned telemetry
+
Narset forwarded a captioned telemetry
summary to Momir.
Narset requested an attention-like topology.
Nissa recommended a wide bottleneck.
@@ -333,12 +354,13 @@
Triggers review
The full catalogue of smells — observation to likely cause — is in
- docs/design/03-principles.md, Appendix A. The sentence test
+ 03-principles.md
+ § Appendix A. The sentence test
is not a proof; it is an intentionally cheap first filter, backed by Leyline
contracts and authority tests that do the real enforcement.