Best-practice baseline: keyboard access, metadata, working carousel, repo hygiene

[tatangharyadi]

Best-practice baseline for the site, done before adding games so the foundation
is clean first.

Measured result

Lighthouse, mobile, navigation mode:

Category	Before	After
Accessibility	82	100
Best Practices	100	100
SEO	100	100
Agentic Browsing	50	100
Failed audits	4	0

Images: 956K to 103K. The 100s hold in both colour schemes — audited
separately under light and dark.

The one that mattered

The hero tab radios and the mobile menu checkbox used display: none, which
removes an element from the tab order and the accessibility tree. I confirmed
in the live DOM that 0 of 3 tab inputs were focusable, so the My Services
and For Recruiters panels could not be opened by keyboard and their text was
never announced by a screen reader. On a site whose stated audience is
recruiters, that was the top issue. Both now use a visually-hidden pattern with
a visible focus ring on the label.

Carousel

The .casestudy--container.next animations were dead — the JS never added the
class, and no rule covered the item moving into the centre slot. Cards jumped
while their text animated, which is why it read as half-broken. Added
fromItem1/2/3 keyframes covering both directions and wired them up. The
controller also no longer relies on next/prev being undeclared globals that
only resolved because <button id="next"> becomes window.next.

Colour: Catppuccin Latte and Mocha

The site is now themed with Catppuccin — Latte in
light mode, Mocha in dark, selected by prefers-color-scheme. Every rule
goes through a semantic token (--bg, --bg-alt, --bg-chrome, --text,
--text-muted, --accent, --accent-text, …); no rule names a palette colour,
so a flavour swap touches two :root blocks and nothing else. Hex values come
from upstream catppuccin/palette, not transcribed by hand. DESIGN.md
documents the whole system.

Two findings shaped the result and are worth flagging:

Catppuccin Latte's entire cyan family is unusable as text. Against Latte's
page background: sky 2.47:1, sapphire 2.78:1, teal 3.31:1, blue 4.34:1 —
only mauve clears 4.5:1, and only on that one surface. sky fails even the
3:1 non-text floor, so there is no font size at which it becomes legal, and a
sky focus ring would be illegible. --accent-text is therefore #026389,
Latte sky deepened to 60% lightness with hue and saturation preserved — 5.90 /
5.48 / 5.04:1 on the three surfaces. It is the only non-palette value in the
system, and it is also every focus ring, so it must not be "corrected" back to
sky. --accent (true sky) is restricted to aria-hidden decoration.

The bands are visibly quieter than before, in both schemes. The old design
framed near-white sections with a near-black navy nav — about 15:1.
Catppuccin's crust/mantle/base triad is built for gently stacked surfaces,
not separate zones, and sits close together either way: crust vs base is
1.17:1 in Latte and 1.14:1 in Mocha; mantle vs base 1.09 and 1.07. Dark
mode does not rescue it — Mocha is marginally flatter. Tone alone cannot
separate the nav from the content, so nav, .techstack and the mobile
slide-out each carry a 1px --border hairline on the content-facing edge. For
the slide-out that is not optional: at mantle over base its links otherwise
appear to float on the page rather than sit in a menu. The net composition is
calmer and more layered than the original. That is inherent to the palette, not
a defect — but it is a real change in how the page reads, and the thing here
most likely to want a second opinion.

Everything else

Accessible names on the icon links; aria-hidden on 322 decorative glyphs;
<main> landmark; WCAG AA contrast on the active tab (plus bold, so selection
is not colour-only); prefers-reduced-motion guard. Open Graph / Twitter card /
canonical / favicon / JSON-LD — the link previewed as a blank card before.
Poppins via preconnect instead of an @import chain. Deleted dead CSS
(.portfolio*, .more-btn, the .casestudy-item single-dash typo rule) and
fixed nth-child(3) reading --casestudy-item1-filter. 100vh to 100dvh.
.gitignore plus untracking three committed .DS_Store files, LICENSE,
404.html, robots.txt, sitemap.xml, and real documentation (below).

.nojekyll is the one that unblocks the game work — Pages runs a legacy
Jekyll build here, which silently drops directories starting with _, exactly
what Godot/Unity/bundler exports emit.

Documentation

README had grown into three audiences at once, so it is split across four
documents, plus a one-line pointer:

• ARCHITECTURE.md (new) — how the site is built: the no-build-step
  rationale, file layout, the design tokens and their non-colour constraints, the
  CSS-only tab and sidebar patterns, how the carousel animates backwards out of
  the slot each item vacated, the breakpoint ladder, and the .nojekyll / Pages
  limits.

• DESIGN.md (new) — the visual system: the two flavours, the semantic token
  table, the accent rule and why #026389 exists, every contrast figure and the
  tightest margins, and what was deliberately left out (no theme toggle, no
  other flavours). Written to the DESIGN.md
  format — machine-readable
  tokens in front matter (18 colours, 9 typography levels, 20 components, every
  hex verified against css/style.css) plus rationale prose, on the canonical
  section order. npx @google/design.md lint DESIGN.md reports 0 errors, 0
  warnings, and it exports to valid W3C DTCG and a Tailwind theme. That lint is
  a one-off command, not a dependency — there is still no package.json.

  The format has no light/dark axis, which is the one real friction point.
  Latte and Mocha are therefore carried as two flat token sets (mocha-* for the
  dark half) with a -dark component variant each. That is deliberate rather
  than merely expedient: because every Mocha pair is reachable through a
  component, the linter's WCAG check runs over the dark flavour too — verified by
  breaking hero-tab-dark and watching the rule fire. The inline
  { light, dark } shape the maintainer has endorsed upstream
  (#13,
  #128) errors in the
  released alpha, so the file documents it as the shape to collapse to once it
  ships rather than adopting it early.

• AGENTS.md (new) — the operational half: local dev, how to verify a change,
  and the things that look like bugs but are load-bearing. Two of those were not
  written down anywhere before: the fromItem* keyframes deliberately having no
  to block, and void carousel.offsetWidth being a reflow rather than dead
  code.

• CLAUDE.md (new) — one line, @AGENTS.md, so there is a single source
  rather than two that drift.

• README.md — trimmed to a visitor-facing overview plus pointers.

Also fixed a stale lead-in that said "Two patterns" above a three-bullet list.

Verification

Served locally and checked in Chrome: 3/3 tab inputs focusable, mobile menu
opens from the keyboard, both slide directions animate the correct elements and
unlock afterwards, reduced-motion path cuts instantly without locking the
buttons, no console errors, HTML tag structure balanced, no duplicate ids.

For the colour work: 20 foreground/background pairs × 2 flavours checked against
per-pair floors (4.5:1 text, 3:1 large text and non-text indicators) — 0
failures; runtime computed values confirmed to match the documented table in
both schemes; no stale token or stray hex left anywhere in css/ or *.html;
Lighthouse re-run under each scheme.

Worth a second look

• MIT LICENSE — I picked a common default. Change or drop it if you'd rather
  not license the code.
• The band contrast change described above. It is the most visible
  consequence of adopting Catppuccin and it applies in both light and dark.
• --accent-text is not a Catppuccin colour. #026389 is a derived value.
  It is defensible (no Latte cyan works as text) but it is a deviation from the
  palette, and mauve was the only in-palette alternative — rejected because it
  still fails in the nav at 4.09:1 and shifts the brand hue to purple.
• Body text colour is now Latte subtext1 / Mocha subtext0. This affects
  the hero subtitle and all three tab panels, so it is a visible change, not just
  a token tweak. (The earlier #5c6370 body colour and #006d94 accent from
  this branch are both superseded by the palette.)
• Slide duration is now uniformly 700ms (was 500ms for one of the two
  animations) so JS has a single value to read.
• og-card.jpg is the profile photo padded onto the old dark brand colour.
  It no longer matches the palette; a purpose-designed 1200x630 card in
  Catppuccin would be better.
• No in-page theme toggle — prefers-color-scheme only. A toggle needs JS,
  localStorage and an inline blocking script to avoid a flash of the wrong
  theme; deliberate omission, easy to add later.

CI

.github/workflows/ci.yml runs on every PR. It is not a build — there is still no
build step, no package.json and no lockfile, and the checkers are stdlib Python
plus one pinned npx one-off. It checks only what duplication or prose makes
silent:

Check	Catches
scripts/check_palette.py	drift between the four copies of the palette
scripts/check_repo.py	a deleted .nojekyll; a page missing from sitemap.xml
npx @google/design.md lint	DESIGN.md falling off 0 errors / 0 warnings
node --check js/script.js	a syntax error shipping a dead carousel

The palette check is the one that earns its keep. The Catppuccin values are
written out in css/style.css (source of truth), 404.html's inline subset,
DESIGN.md's front matter under semantic names, and the theme-color meta pair in
each page. Every duplication is justified; none was enforced. Editing one and not
the others produced no error and no visual break in whichever scheme you happened
to be testing — the single most likely silent regression in this repo, and the one
thing here a reviewer could not reasonably be expected to catch.

Two details worth flagging. The design.md linter exits 0 on warnings, so the
workflow gates on its JSON summary rather than the exit code — an errors-only gate
would have let CI permit exactly the state AGENTS.md forbids. And each check was
verified to fail on a deliberately broken tree, not merely to pass on a clean
one: a check never observed failing is not yet a check.

This reverses a line I had written in ARCHITECTURE.md ("There is no CI…"). That
prose is now replaced with why there is one and what it deliberately does not
cover — CI cannot tab through a page, operate the carousel from the keyboard, or
run Lighthouse per scheme. AGENTS.md remains the authority and now marks which of
its eight steps are automated, with an explicit note that green CI does not mean a
change is verified.