Site improvements: SEO, accessibility, decoupling & design tokens

[HumbleBee14]

Site-wide improvements from a four-part audit (SEO, accessibility, code decoupling, design consistency). Everything is committed in reviewable chunks; type-check, 47 unit tests, and a production build all pass, and the changes were spot-verified in a preview build in both light and dark themes.

The site was already well-built — these are refinements, not rebuilds. Weighted toward SEO (the stated priority) and decoupling/export-readiness (for a possible future host/backend migration).

1. Accessibility & the writer flow (9a4f8dc)

• Dark-mode contrast fix (P0): white-on-accent was ~2.3:1 on the salmon dark accent. Active topic tab, .btn-primary:hover, and the playground live-tag now use var(--paper) (matching the convention other accent buttons already used). Verified in dark mode: dark text on salmon (~8:1).
• Site-wide :focus-visible ring for links/buttons/form controls; restored a keyboard ring on the /write Title/Summary inputs; aria-labels on those inputs.
• theme-color meta now tracks the resolved data-theme (it was keyed to prefers-color-scheme, but the site theme is data-theme + localStorage, so browser chrome could mismatch the page).
• Writer onboarding: intro leads with email (the realistic path for non-coders) and no longer links "pull request" to /pulls (which can't accept a submission); a post-download panel now explains what the .zip is and how to send it. Empty drafts no longer trigger the restore banner.

2. Decoupling & taxonomy (31ffc1e)

• Centralized GitHub identity: SITE.org/repo/repoUrl/issuesUrl/pullsUrl/discussionsUrl derived from one constant; replaced ~10 hardcoded github.com/MLSysDev URLs across the site; deduped SITE.github/SOCIALS.github and the two Twitter encodings. (The /write repoUrl also now points at the repo, not the org — fixing the guide link and the ZIP "fork" instruction.)
• Taxonomy single source of truth: post topicId is validated with z.enum(TOPIC_IDS) (a typo now fails the build); display names derive from topicName(id) everywhere instead of the denormalized topic frontmatter string, which had drifted (e.g. "Inference" vs canonical "Inference & Serving").
• Added an optional updated date to the post schema (feeds dateModified + sitemap lastmod).

3. SEO (dfa0cdf)

• URL consistency: trailingSlash: 'never' so canonicals, internal links, and the sitemap all agree (they were split before). /search is now noindex + excluded from the sitemap.
• New indexable surface: /tags/[tag] archive pages for every post tag (keyword-targeted titles, CollectionPage + BreadcrumbList JSON-LD) plus a /tags index; article-byline tags link to them; footer surfaces /tags.
• Structured data: BreadcrumbList on posts/topics/tags/authors/tools; ProfilePage + Person on author pages; Article authors gained a url.
• Metadata: retargeted homepage + topic titles/descriptions to core ML-systems keywords (dropped the doubled phrasing); trimmed over-long descriptions and enriched thin ones (about/contact/authors); og:image:alt + twitter:site sitewide; article:modified_time/section/tag on posts; added the missing about/search/authors OG page images.

4. Performance & IA (f8148a1)

• Global prefers-reduced-motion block (was only on /about).
• HeroFigure hydrates client:visible instead of client:load.
• KaTeX CSS scoped to the article page + /write editor instead of the global sheet — non-math pages drop ~23KB (verified: 0 KaTeX font refs on the homepage, present on articles).
• Zero-article topics hidden and no longer generated (no thin pages in the sitemap); footer "Most read" (a duplicate of /blog) → "Tags"; "Read the style guide" anchors to #style-guide; blog empty-state copy is correct under the all-view.

5. Design tokens (5a7a4df)

• Added --radius-* and --shadow-hover scales (pure additions; the /tags pages use the pill token).

---

Deliberately deferred (recommended follow-ups)

These are real audit findings I did not land here because they carry visual-regression risk best reviewed with diffs, or are larger features:

• Design-system consolidation — the card recipe is hand-copied ~5× (about/contact/authors/community/playground) and the mono-pill "chip" pattern exists in ~7 variants under 4 names; About/Contact use blog-h1 while other pages use page-h1. Extract shared .card/.card--interactive, a .chip base, and PageHeader/IconLinkCard, then adopt the new --radius-* tokens. Low-risk but touches many pages — worth reviewing visually.
• Article table of contents — feasible with the headings already returned by render(); a strong lever for a learning site.
• Self-host fonts (drop the Google Fonts third-party round-trip; @fontsource already installed for OG) + fallback-metric CLS tuning.
• Centralized content-access layer (getPublishedPosts/getPostsWithAuthors + a COLLECTIONS const) — the draft filter is duplicated across ~12 pages; consolidating it is the seam you'd re-point at a backend/API on a future migration.
• SearchModal focus-trap + listbox/aria-activedescendant semantics.

Notes

• The trailing-slash change makes all emitted signals consistent (no-slash). If the host (Cloudflare Pages) serves a different canonical form, a redirect rule may be worth confirming — but the signals now agree, which is the important part.
• License: separately, LICENSE/README were updated (all content © respective author; MIT/code split removed) per your call.

[cloudflare-workers-and-pages]

Deploying mlsystems with    Cloudflare Pages

Latest commit:	8af2fab
Status:	✅  Deploy successful!
Preview URL:	https://37944ff1.mlsystems.pages.dev
Branch Preview URL:	https://feature-ui-audit-batch-1.mlsystems.pages.dev

View logs