Mushroom Alien Games — Website Build Brief

Version 01.2608.0003 (WIP) For: Claude Code. Read DESIGN_SYSTEM.md and SITE_ARCHITECTURE.md first — this doc is the task list against them. © 2026 Willem van Wyk

Environment

• Repo: /opt/mushroomaliengames — one repo, tracks origin/main on GitHub (MushroomAlien/mushroomaliengames). All build work happens on the redesign branch; main stays exactly as currently deployed until Willem reviews and merges it himself.
• Reference docs: /opt/mushroomaliengames/documents/, on the redesign branch — this file, DESIGN_SYSTEM.md, SITE_ARCHITECTURE.md, VERSIONING_REFERENCE.md, and Website_Handover_01.2608.0001.md all live there.
• Flag: an earlier version of this document described a separate working copy directory (/opt/www.mushroomaliengames), with its own bootstrap steps (git init, no remote). That setup was retired and consolidated into this single repo on 2026-08-26. The old directory is archived as /opt/www.mushroomaliengames.bak-2026-08-26, pending deletion once confirmed unneeded.
• Preview locally before treating anything as done: bundle install && bundle exec jekyll serve, check http://localhost:4000.
• Merging redesign into main and pushing to GitHub is a separate, later step Willem does once he’s reviewed the branch as a whole. Not part of any phase below.

Working method

One phase at a time. Each phase has a Definition of Done. Stop at the end of a phase rather than rolling into the next — this is a multi-session build, and each phase should leave the site in a working, previewable state, not mid-refactor.

Constraints that apply to every phase:

• Static Jekyll only, no build tooling beyond what GitHub Pages runs natively
• No parallax, WebGL, scroll-jacking, autoplay
• Mobile-first; Core Web Vitals matter more than any single visual flourish
• UK spelling, no em dashes or en dashes — checked programmatically, not just by eye
• Don’t invent final marketing/pitch copy. Placeholder copy is fine and should be visibly marked as placeholder (an HTML comment or a [DRAFT COPY] label) — Willem writes final pitch copy himself
• Every new page or component gets checked against DESIGN_SYSTEM.md’s colour/contrast table before being called done, not just eyeballed

Phase 1 — Foundation (Layer 1)

Scope: the site-wide design system, applied to Home, Games index, and Updates index. Salt & Stone page is untouched in this phase — still on the old navy/gold system, that’s Phase 2.

1. Implement colour tokens, typography, and spacing scale from DESIGN_SYSTEM.md in assets/css/main.css.
2. Copy mag_colour.svg into assets/img/brand/, wire into header and footer.
3. Build the header include: full header on load, sticky minimal bar with one CTA on scroll.
4. Build the footer include: version stamp motif reinstated, format per DESIGN_SYSTEM.md, value sourced from _config.yml.
5. Build the reusable field-guide component set: .fig-label, .caption, hr.hairline, .panel.
6. Apply all of the above to Home, Games index, Updates index. This phase is visual/structural — homepage copy can stay close to current, not a copy rewrite.
7. Spot-check against DESIGN_SYSTEM.md’s contrast table before calling this phase done.

Definition of Done: Home, Games index, and Updates index render in the new system with a consistent header/footer/typography across all three. jekyll serve builds clean, no console errors, checked at a mobile viewport.

Phase 2 — Salt & Stone page (Layer 2)

Scope: the one game with real content right now. Apply the ochre/rust Layer 2 per SITE_ARCHITECTURE.md’s theming mechanism.

1. Create assets/css/games/salt-and-stone.css with a scoped accent override (ochre/rust). Don’t pick the exact hex silently — flag the chosen value back to Willem for approval before it ships.
2. Wire custom_css into _games/salt-and-stone.md front matter.
3. The existing hand-drawn SVG illustration (settlement grid, salting) stays in place as a placeholder — restyle the page chrome around it, don’t discard it.
4. Rebuild the flip-card widget include against the new Phase 1 component set.
5. Page keeps Layer 1 typography/structure (header, footer, field-guide apparatus) — only the accent and game-specific illustration/texture shift.

Definition of Done: Salt & Stone page reads as visually distinct from the rest of the site (its own colour layer) while still unmistakably part of the same site (same header, footer, type, apparatus). Compare side-by-side with Home to confirm Layer 2 didn’t leak into Layer 1 or vice versa.

Phase 3 — Press kit

Scope: minimal /press/ page per SITE_ARCHITECTURE.md’s content plan. Ships with placeholders, not blocked on missing assets — there isn’t much real content for this page yet.

1. New page /press/: factsheet sidebar component (title, developer, player count, playtime, genre, status, one-line pitch).
2. Sell sheet PDF download slot — placeholder state if the file doesn’t exist yet at build time.
3. Photo grid slot (3-4 images) — placeholder state if press photos don’t exist yet.
4. ZIP download mechanism — build the packaging/link structure now, contents populate later.
5. Contact block: mushroomalien+contact@pm.me.
6. Point the Phase 1 sticky-header CTA at /press/.

Definition of Done: page is live and structurally complete, degrades gracefully with placeholders where content is genuinely missing, and doesn’t look broken or unfinished to a publisher who lands on it today.

Phase 4 — Content and polish pass

Scope: everything that depends on content that doesn’t exist yet at the time of Phases 1-3. Revisit this phase whenever new content lands — it isn’t a one-time pass.

1. Real dev-log post in _posts/.
2. SEO basics: meta descriptions, Open Graph tags/images, sitemap.xml, favicon (needs the badge-only crop flagged as missing in DESIGN_SYSTEM.md’s asset inventory).
3. Swap the Salt & Stone placeholder SVG for real photography once the shoot happens, per DESIGN_SYSTEM.md’s photography direction.
4. Populate the press kit’s sell sheet PDF and photo grid once those exist.
5. Full-site link and build check before this is considered ready to port to the live repo.

Definition of Done: no visible placeholders remain, /press/ is fully populated, and the redesign branch is ready for Willem to review for merging into main.

After Phase 4

Merging redesign into main and pushing to GitHub is a manual step Willem does, or asks for help with, once the branch has been reviewed. Not part of this brief.

Phase 1 Amendment — dark background revision (2026-08-27)

Scope: DESIGN_SYSTEM.md was revised to v0003 (figure/ground inversion — --teal becomes the primary page background, renamed --ink; --substrate becomes primary text-on-dark). This re-opens Phase 1’s own Definition of Done rather than starting a new phase, per DESIGN_SYSTEM.md v0003’s own recommendation. Full change detail and the selector-by-selector reclassification table are in devlog.md’s 2026-08-27 entry — this section checks that work against this session’s specific Acceptance criteria.

Acceptance criteria for this amendment:

1. Every pre-existing var(--teal)/var(--teal-faded) usage in main.css individually reclassified against the v0003 role table (page-background vs .panel context), not blind-renamed — Met. Two selectors (.caption, .update-tag) turned out to be shared between both contexts and needed a scoped .panel override added to resolve correctly.
2. Home, Games index, Updates index, and the site header/footer render on the new --ink background with correct contrast throughout, no dark-on-dark or invisible text — Met, verified by cascade-tracing the rendered HTML/CSS output against the reclassification table, not by browser screenshot (no browser automation in this container — same limitation noted in every prior session). Willem’s own preview pass is still the real check.
3. Header wordmark visibly larger, exact size flagged rather than picked silently — Met: 1.4rem desktop (from 1.05rem), 1.1rem at ≤420px (from 0.85rem). Sticky-bar mini-mark confirmed not to scale as a side effect (it carries no wordmark text at all).
4. Salt & Stone’s page body unchanged, header/footer only — Met, confirmed legacy-game.css uses an entirely separate token namespace with no overlap with the renamed tokens.

Additional work this amendment surfaced, beyond the original ask: the header/sticky/footer logo assets’ primary fill (#06373C) was byte-identical to the new --ink background — a real defect, not the “check on preview” risk it was flagged as going in. Resolved by adding light-fill duplicates (mag_badge-light.svg, mag_colour-light.svg) after confirming the SVG’s internal detail lines are negative-space cutouts rather than separate paths, so a single fill swap was sufficient. This also completes the “single-colour variants” row in DESIGN_SYSTEM.md’s asset inventory, previously listed as missing.

Still open going into Phase 2: the .field-texture hairline grid’s star-chart read on the new dark background, and the teal-faded-on-.panel tightest-margin pairing (4.55:1, flagged since the padding-fix session) — both need Willem’s visual gut-check on preview, not further code changes assumed. legacy-game.css’s pre-existing .hero/.wrap padding-shorthand collision on the Salt & Stone page (flagged in the 2026-08-27 padding-fix devlog entry) also remains untouched, per Phase 1’s scope boundary.