Static content review: site + wiki fixes from dual design review

.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 `<picture>`, 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 `<picture>` + `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).
 
@@ -47,12 +49,27 @@ Source repo: https://github.com/foundryside-dev/simic — explore it for the can
 
 **Motion**: essentially none. One 120ms ease-out transition (skip link). `prefers-reduced-motion` kills everything. Do not add animation.
 
-**Dark mode**: not an afterthought — every token is a `light-dark()` pair; diagrams swap variants; print forces light.
+**Dark mode**: not an afterthought — every token is a `light-dark()` pair; diagrams ship as light/dark pairs selected by `<picture>`; print falls back to light.
+
+<!-- CORRECTION (2026-08-09, static-site review M6). The paragraphs above are
+     hand-corrected and now DIVERGE from the upstream SPA export, whose
+     descriptors still assert a three-state toggle on the marketing site. That
+     export is currently unrecoverable (the 33 component/token/ui_kit files
+     were never committed — see the Index warning), so the divergence cannot be
+     resolved by re-syncing today. When the project IS re-exported, re-apply:
+       1. marketing site is TWO-state (system preference only, zero JS);
+          `[data-theme]` is an unreached hook. Only the wiki is three-state.
+       2. diagrams select via <picture> + `media="screen and
+          (prefers-color-scheme: dark)"`, so they cannot follow `[data-theme]`
+          at all, and print falls through to the light variant with no override.
+     Verified against site/style.css and site/*.html on 2026-08-09. -->
+
+
 
 ## 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 +78,49 @@ 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`
+> was therefore four dangling `@import`s loading nothing; it has since been
+> flattened locally (see its provenance header).
+>
+> 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). 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.
+>
+> **⚠ THE GENERATED FILES ARE NOW STALE — a re-sync will REGRESS the site.**
+> `_ds_manifest.json` and `_adherence.oxlintrc.json` are generated output and
+> were deliberately **not** hand-edited, so they still describe the palette as
+> it stood on 2026-08-08, before the static-site review (M2, m6). Three
+> divergences, all verified 2026-08-09:
+>
+> | Token | `site/style.css` (correct) | generated files (stale) |
+> |---|---|---|
+> | `--color-bg-note` dark | hue **175** | hue **195** |
+> | `--color-bg-note-status` dark | hue **85** | hue **75** |
+> | `--color-accent-quiet` | **deleted** (unused; 4.22:1 on `--color-bg`, fails AA) | still declared, and allowlisted at `_adherence.oxlintrc.json:124,192` |
+>
+> Nothing shipped is wrong — the consumed stylesheets (`site/style.css` and the
+> flattened `styles.css`) both carry the corrected values. The hazard is
+> directional: **a `DesignSync` re-sync overwrites these files from upstream and
+> would silently reintroduce all three.** Whoever completes the export must
+> re-apply the two hue corrections and re-delete `--color-accent-quiet`
+> (including both `_adherence.oxlintrc.json` entries) as part of that sync, then
+> diff the manifest's tokens against `site/style.css` before considering it
+> done. This is a recorded deferral, not an oversight.
+
+- `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.

.claude/skills/simic-design/styles.css

@@ -1,4 +1,110 @@
-@import "tokens/colors.css";
-@import "tokens/typography.css";
-@import "tokens/spacing.css";
-@import "tokens/base.css";
+/* ==========================================================================
+   Simic Design System — global entry point
+
+   PROVENANCE. This file is a LOCAL FLATTENING, not the original export. The
+   upstream Claude Design project (namespace SimicDesignSystem_5a908e) split
+   these tokens across tokens/colors.css, tokens/typography.css,
+   tokens/spacing.css and tokens/base.css, and this file was four @import
+   statements pointing at them. Those four files — and 29 others under
+   components/, guidelines/ and ui_kits/ — were never committed (see the
+   warning in readme.md), so the imports resolved to nothing and this
+   stylesheet loaded no rules at all.
+
+   Rather than leave a dead import chain, the token layer is inlined below,
+   lifted verbatim from `site/style.css`, which is and remains the ground
+   truth for every value here. The four tokens/*.css paths are still named in
+   _ds_manifest.json and readme.md's Index on purpose: that is the record of
+   what is missing, and re-exporting the project is the real fix.
+
+   CONSEQUENCE: this file carries TOKENS ONLY. The component rules (Masthead,
+   Note, CanonQuote, Spine, CardGrid, DataTable, Split, Diagram) live in
+   `site/style.css` and were not duplicated here — one copy of a component
+   layer is correct, and a second would drift. To style a real surface, read
+   `site/style.css`.
+
+   Keep in sync with site/style.css. If the two ever disagree, site/style.css
+   wins.
+   ========================================================================== */
+
+:root {
+  color-scheme: light dark;
+
+  /* --- Primitives -------------------------------------------------------
+     Simic reads blue-green. Hue 225 carries structure, hue 175 carries
+     emphasis, hue 85 is the sole warning colour. OKLCH so the light and dark
+     ramps stay perceptually matched. */
+  --ink-050: oklch(0.985 0.004 225);
+  --ink-100: oklch(0.955 0.008 225);
+  --ink-200: oklch(0.905 0.012 225);
+  --ink-300: oklch(0.825 0.016 225);
+  /* ink-500 is the light-mode muted text; kept dark enough that muted text
+     clears WCAG AA (4.5:1) against --color-bg-subtle, not just --color-bg. */
+  --ink-500: oklch(0.495 0.024 225);
+  --ink-700: oklch(0.375 0.030 225);
+  --ink-850: oklch(0.235 0.026 225);
+  --ink-900: oklch(0.185 0.024 225);
+  --ink-950: oklch(0.145 0.020 225);
+
+  --teal-400: oklch(0.780 0.110 175);
+  /* Ramp midpoint. No current consumer — kept so the ramp stays derivable, and
+     because the mark's fixed #0f9b8e sits beside it. Do not use it for text:
+     it measures 4.22:1 on --color-bg, which fails AA. */
+  --teal-600: oklch(0.560 0.105 175);
+  --teal-700: oklch(0.470 0.098 175);
+
+  --amber-400: oklch(0.800 0.105 85);
+  --amber-700: oklch(0.520 0.105 85);
+
+  /* --- Semantic tokens (one declaration each) --------------------------- */
+  --color-bg:          light-dark(var(--ink-050), var(--ink-950));
+  --color-bg-subtle:   light-dark(var(--ink-100), var(--ink-900));
+  --color-bg-code:     light-dark(var(--ink-100), var(--ink-850));
+  /* Tinted callout grounds. Each holds its family's hue on BOTH sides — teal
+     175 for the plain note, amber 85 for the status note — so a callout never
+     drifts off the three-hue palette when the theme flips. */
+  --color-bg-note:     light-dark(oklch(0.965 0.020 175), oklch(0.235 0.030 175));
+  --color-bg-note-status: light-dark(oklch(0.975 0.022 85), oklch(0.235 0.028 85));
+
+  --color-text:        light-dark(var(--ink-900), var(--ink-100));
+  --color-text-muted:  light-dark(var(--ink-500), var(--ink-300));
+  --color-heading:     light-dark(var(--ink-950), var(--ink-050));
+
+  --color-border:      light-dark(var(--ink-200), oklch(0.300 0.020 225));
+  --color-border-firm: light-dark(var(--ink-300), oklch(0.380 0.024 225));
+
+  --color-accent:      light-dark(var(--teal-700), var(--teal-400));
+  --color-warn:        light-dark(var(--amber-700), var(--amber-400));
+
+  --color-link:        var(--color-accent);
+  --color-link-hover:  color-mix(in oklch, var(--color-link) 72%, var(--color-text) 28%);
+
+  /* --- Typography ------------------------------------------------------- */
+  --font-body: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue",
+               Arial, sans-serif;
+  --font-code: ui-monospace, "SFMono-Regular", Menlo, Consolas,
+               "Liberation Mono", monospace;
+
+  --text-h1: clamp(2rem, 1.45rem + 2.6vw, 3.1rem);
+  --text-h2: clamp(1.35rem, 1.18rem + 0.8vw, 1.75rem);
+  --text-h3: clamp(1.08rem, 1.02rem + 0.3vw, 1.22rem);
+
+  /* --- Spacing (8px base) ----------------------------------------------- */
+  --space-1: 0.25rem;
+  --space-2: 0.5rem;
+  --space-3: 1rem;
+  --space-4: 1.5rem;
+  --space-5: 2rem;
+  --space-6: 3rem;
+  --space-7: 4.5rem;
+
+  /* --- Layout ------------------------------------------------------------ */
+  --measure: 46rem;      /* prose column */
+  --page: 62rem;         /* wide elements: tables, diagrams */
+  --radius: 4px;
+}
+
+/* Hook for an explicit reader override. NOTHING SETS data-theme on the
+   marketing site: it ships zero JavaScript and is system-preference-only.
+   Only the MkDocs wiki is three-state. See readme.md § VISUAL FOUNDATIONS. */
+:root[data-theme="light"] { color-scheme: light; }
+:root[data-theme="dark"]  { color-scheme: dark; }