Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/website.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ name: Website

on:
pull_request:
branches: [website]
branches: [website, 'fix/website-*']
push:
branches: [website]
workflow_dispatch:
Expand Down
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,11 +55,11 @@ just verify

vinext 1.0.1 includes `@vercel/og` 1.0.3 with the Satori SVG-escaping fix and the framework's HarfBuzz runtime support. The `satori` override pins `fflate` 0.7.5 to fix its ZIP64 parsing advisory while Satori pins 0.7.3; remove that override once Satori uses a patched release. The lockfile also keeps `@hono/node-server` and `systeminformation` on patched versions within their existing dependency ranges.

The Website GitHub Actions workflow (`.github/workflows/website.yml`) runs the same checks, plus a deploy dry run, on every pull request and push to `website`, without deploying. A second job warns when the recorded documentation is behind `main`. The production check visits every documentation page, validates asset responses and the security headers on pages, redirects and static files, checks that every page carries the share card and that each labelled control's name contains its visible text, and verifies not-found responses and redirects. On Node 24, CI also runs the Playwright Chromium suite (`npm run test:browser`) against the built Worker. It covers journey selection, game completion, search loading and recovery, code copying, keyboard-operated comparison controls, catalogue toggles, and mobile Escape handling. The main checks also run on the declared minimum Node 22.18.0. For local browser checks, run `npx playwright install chromium`, `npm run build`, then `npm run test:browser`; Playwright starts and stops its own local Worker and blocks outside requests.
The Website GitHub Actions workflow (`.github/workflows/website.yml`) runs the same checks, plus a deploy dry run, on every pull request and push to `website`, without deploying. Pull requests stacked on `fix/website-*` branches also run these checks. A second job warns when the recorded documentation is behind `main`. The production check visits every documentation page, validates asset responses and the security headers on pages, redirects and static files, checks raw-head metadata and share cards, checks that each labelled control's name contains its visible text, and verifies not-found responses and redirects. On Node 24, CI also runs the Playwright Chromium suite (`npm run test:browser`) against the built Worker. It covers journey selection, game completion, search loading and recovery, route announcements, code copying, keyboard-operated comparison controls, catalogue toggles, mobile Escape handling, narrow layouts, and the reported catalogue and retro contrast regressions. The main checks also run on the declared minimum Node 22.18.0. For local browser checks, run `npx playwright install chromium`, `npm run build`, then `npm run test:browser`; Playwright starts and stops its own local Worker and blocks outside requests. These checks do not replace testing with screen readers or native browser zoom.

## Documentation source

`README.md` on `main` is the reference source. This branch keeps a recorded copy of it, and of the fxcss version, in `content/source/`. `npm run content` generates and sanitises `content/docs.json` from that copy; it runs automatically before development and production builds. Source hashes and tests detect stale generated content and missing command pages. The build also writes a content-hashed search index under `public/search/` and records its URL in `content/search-index.json`. Documentation navigation receives only page labels; search downloads the index on first focus or input, with a retry control if it fails. Exact phrases rank first, followed by pages containing all query words in any order. Descriptions use the first prose paragraph and end at a word boundary.
`README.md` on `main` is the reference source. This branch keeps a recorded copy of it, and of the fxcss version, in `content/source/`. `npm run content` generates and sanitises `content/docs.json` from that copy; it runs automatically before development and production builds. Source hashes and tests detect stale generated content and missing command pages. The build also writes a content-hashed search index under `public/search/` and records its URL in `content/search-index.json`. Documentation navigation receives only page labels; search downloads the index on first focus or input, with a retry control and the normal page navigation if it fails. Retrying returns keyboard focus to the search field. Exact phrases rank first, followed by pages containing all query words in any order. Descriptions select useful prose or list content, with explicit summaries for reference pages, and end at a word boundary. Metadata resolves before HTML streams so all clients receive it in the document head.

The copy refreshes itself. The Refresh docs workflow (`.github/workflows/refresh-docs.yml`) regenerates it from `main` and pushes it to this branch, and Workers Builds deploys the result. `main`'s Website docs workflow starts it after each release reaches PyPI and after each README change. Before pushing, it:
- skips a version PyPI doesn't serve yet, so the site never advertises an install that fails;
Expand Down Expand Up @@ -115,4 +115,4 @@ The site is prepared for **https://fxcss.com**. `/install.sh` serves the interac

The site runs as the Cloudflare Worker `fxcss-website`, configured in `vite.config.ts`; the `deploy` script attaches the `fxcss.com` and `www.fxcss.com` custom domains. `npm run build` writes `dist/server/index.js`, `dist/client/` and the generated `dist/server/wrangler.json`, and `npm run deploy` publishes them. Production scripts require the generated Worker configuration. The public installer must work without a browser session or a sign-in redirect. Do not serve the development server publicly.

The tab favicon uses the existing lightweight SVG, independently of the recorded source icon. The catalogue capture script normalises older toolkit output to `aria-pressed` toggle buttons after each recapture.
The tab favicon uses the existing lightweight SVG, independently of the recorded source icon. After each catalogue recapture, `scripts/prepare_catalogue.py` applies the website's document structure, language, landmarks, toggle semantics and contrast fixes without changing captured images. It fails if the toolkit's generated structure has changed unexpectedly. The captured directory is an auxiliary reference marked `noindex,follow`; `/docs/catalogue` remains its indexable documentation page.
55 changes: 13 additions & 42 deletions app/components/comparison.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,6 @@ import {
useRef,
useState,
type CSSProperties,
type KeyboardEvent,
type PointerEvent,
} from 'react';
import Image from 'next/image';
Expand Down Expand Up @@ -190,37 +189,19 @@ export function Comparison({
}
function startDrag(event: PointerEvent<HTMLDivElement>) {
if (!event.isPrimary || event.button !== 0) return;
// Keep the range focused instead of letting the drag surface take focus.
event.preventDefault();
setAutoplay(false);
event.currentTarget.focus({ preventScroll: true });
figure.current
?.querySelector<HTMLInputElement>('.compare-control input[type="range"]')
?.focus({ preventScroll: true });
event.currentTarget.setPointerCapture(event.pointerId);
positionFromPointer(event);
}
function endDrag(event: PointerEvent<HTMLDivElement>) {
if (event.currentTarget.hasPointerCapture(event.pointerId))
event.currentTarget.releasePointerCapture(event.pointerId);
}
function handleKey(event: KeyboardEvent<HTMLDivElement>) {
const step = event.shiftKey ? 10 : 1;
const changes: Record<string, number> = {
ArrowLeft: -step,
ArrowDown: -step,
ArrowRight: step,
ArrowUp: step,
PageDown: -10,
PageUp: 10,
};
if (event.key !== 'Home' && event.key !== 'End' && !(event.key in changes))
return;
event.preventDefault();
setAutoplay(false);
updatePosition(
event.key === 'Home'
? 0
: event.key === 'End'
? 100
: Math.round(currentPosition.current) + changes[event.key],
);
}
return (
<figure className="comparison-figure" ref={figure}>
<Tabs
Expand All @@ -241,27 +222,16 @@ export function Comparison({
<TabsTrigger value="diff">Changed pixels</TabsTrigger>
</TabsList>
</div>
<TabsContent value="compare">
<TabsContent value="compare" tabIndex={-1}>
<div className="compare-labels">
<span>Before · {shown.change.before}</span>
<span>After · {shown.change.after}</span>
</div>
{/* The image surface captures dragging across its full area and supplies slider keyboard semantics. */}
{/* eslint-disable jsx-a11y/prefer-tag-over-role */}
{/* Pointer dragging and the range below share one value. Keep the
images outside the slider role so their descriptions remain available. */}
<div
className="compare-image"
style={{ '--split': `${position[0]}%` } as CSSProperties}
role="slider"
tabIndex={0}
aria-label="Image comparison"
aria-describedby={hintId}
aria-valuemin={0}
aria-valuemax={100}
aria-valuenow={position[0]}
aria-valuetext={`${Math.round(position[0])}% before`}
aria-orientation="horizontal"
onFocus={() => setAutoplay(false)}
onKeyDown={handleKey}
onPointerEnter={() => setHovered(true)}
onPointerLeave={() => setHovered(false)}
onPointerDown={startDrag}
Expand Down Expand Up @@ -300,9 +270,8 @@ export function Comparison({
<span>‹ ›</span>
</span>
</div>
{/* eslint-enable jsx-a11y/prefer-tag-over-role */}
<div className="compare-interaction">
<span id={hintId}>Drag the image to compare</span>
<span id={hintId}>Drag the image or use the slider to reveal the before capture</span>
{!reducedMotion && (
<Button
variant="ghost"
Expand All @@ -327,9 +296,11 @@ export function Comparison({
onPointerLeave={() => setHovered(false)}
onPointerDownCapture={() => setAutoplay(false)}
>
<span id={controlId}>Reveal before</span>
<span id={controlId}>Image comparison</span>
<Slider
aria-labelledby={controlId}
aria-describedby={hintId}
format={{ style: 'unit', unit: 'percent' }}
value={position}
onValueChange={(value) => {
setAutoplay(false);
Expand Down Expand Up @@ -375,7 +346,7 @@ export function Comparison({
aria-pressed={zoomed}
>
{zoomed ? <ZoomOut size={15} /> : <ZoomIn size={15} />}{' '}
{zoomed ? 'Full toolbar' : 'Zoom into the tab'}
Zoom into the tab
</Button>
<span>
<strong>{percentage}%</strong> of the full capture changed
Expand Down
11 changes: 7 additions & 4 deletions app/components/docs-navigation.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -127,8 +127,11 @@ function DocsNavigation({
? `${matches.length} matching ${matches.length === 1 ? 'page' : 'pages'}`
: 'No matching pages. Try a command or a shorter phrase.'}
</output>
{searchStatus === 'error' && <button onClick={loadSearch}>Retry search</button>}
{searching ? (
{searchStatus === 'error' && <button onClick={() => {
loadSearch();
searchField.current?.focus();
}}>Retry search</button>}
{searching && searchStatus !== 'error' ? (
<div className="docs-search-results">
{secret && <div className="search-secret">
{secret === 'coffee' ? <><strong>☕ Secret brew unlocked.</strong><button onClick={() => revealSecret('coffee')}>Brew another #c0ffee</button></> : secret === 'retro' && retroDestination ? <><strong>◷ Destination: {retroDestinations[retroDestination].label}, {retroDestinations[retroDestination].year}.</strong><button onClick={() => revealSecret('retro', retroDestination)}>Start the time machine</button><span>Switch desktops or return to the present above.</span></> : <><strong>A challenger appears.</strong><Link href="/important" onClick={onNavigate}>Enter the specificity boss battle ↗</Link></>}
Expand All @@ -154,7 +157,7 @@ function DocsNavigation({
<div className="command-navigation">
{groups.map((group) => (
<section className="nav-group" key={group}>
<h2>{group}</h2>
<p className="nav-group-label">{group}</p>
{pages
.filter((p) => p.chapter === group)
.map((p) => (
Expand Down Expand Up @@ -236,7 +239,7 @@ export function DocsFrame({
};
return (
<div className="guide-layout" data-slot="sidebar-wrapper">
<aside className="guide-sidebar" data-slot="sidebar">
<aside className="guide-sidebar" data-slot="sidebar" aria-label="Documentation navigation">
<div className="desktop-docs-nav">
<DocsNavigation {...navigation} />
</div>
Expand Down
6 changes: 3 additions & 3 deletions app/components/easter-eggs.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -42,15 +42,15 @@ export function EasterEggs({ children }: { children: ReactNode }) {
const destination = retro ? retroDestinations[retro] : null;
const minimise = useCallback(() => {
setMinimised(true);
requestAnimationFrame(() => document.querySelector<HTMLButtonElement>('[data-retro-restore]')?.focus({ preventScroll: true }));
requestAnimationFrame(() => document.querySelector<HTMLButtonElement>('[data-retro-restore]')?.focus());
}, []);
const restore = useCallback(() => {
setMinimised(false);
requestAnimationFrame(() => timeBar.current?.querySelector<HTMLButtonElement>('[aria-pressed="true"]')?.focus({ preventScroll: true }));
requestAnimationFrame(() => timeBar.current?.querySelector<HTMLButtonElement>('[aria-pressed="true"]')?.focus());
}, []);
const close = useCallback(() => {
setRetro(null);
requestAnimationFrame(() => document.querySelector<HTMLAnchorElement>('.site-header .brand')?.focus({ preventScroll: true }));
requestAnimationFrame(() => document.querySelector<HTMLAnchorElement>('.site-header .brand')?.focus());
}, [setRetro]);
const brewCoffee = useCallback(() => {
setCoffee((count) => count + 1);
Expand Down
36 changes: 36 additions & 0 deletions app/components/route-announcer.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
'use client';

import { useEffect, useRef, useState } from 'react';
import { usePathname } from 'next/navigation';

export function RouteAnnouncer() {
const pathname = usePathname();
const previousPath = useRef(pathname);
const [announcement, setAnnouncement] = useState('');

useEffect(() => {
if (pathname === previousPath.current) return;
previousPath.current = pathname;

// Navigation and metadata can commit separately. Wait for the DOM, and
// observe later title changes without moving focus out of the navigation.
let frame = 0;
const announce = () => {
cancelAnimationFrame(frame);
frame = requestAnimationFrame(() => setAnnouncement(document.title));
};
const observer = new MutationObserver(announce);
observer.observe(document.head, {
childList: true,
subtree: true,
characterData: true,
});
announce();
return () => {
cancelAnimationFrame(frame);
observer.disconnect();
};
}, [pathname]);

return <output className="sr-only" aria-label="Page navigation" aria-live="polite" aria-atomic="true">{announcement}</output>;
}
6 changes: 3 additions & 3 deletions app/components/specificity-battle.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ export function SpecificityBattle() {
<span><Swords size={17} /> CASCADE ARENA</span>
<span>{complete ? 'All rounds complete' : `Round ${roundIndex + 1} of ${battleRounds.length}`}</span>
</div>
<div className="battle-progress" aria-label={`${complete ? battleRounds.length : roundIndex} of ${battleRounds.length} rounds completed`}>
<div className="battle-progress" aria-hidden="true">
{battleRounds.map((item, index) => <span key={item.title} className={index < answers.length ? 'done' : index === roundIndex && !complete ? 'current' : ''} />)}
</div>
{complete ? (
Expand All @@ -79,7 +79,7 @@ export function SpecificityBattle() {
</div>
<p className="battle-prompt">Both declarations match this button. Which colour will the browser use?</p>
<pre className="battle-markup"><code>{round.markup}</code></pre>
<div className="battle-preview" aria-label={answered ? `Browser result: ${round.rules[winner].colorName}` : 'Browser result hidden until you answer'}>
<div className="battle-preview">
{answered ? <CascadePreview round={round} /> : <span className="battle-preview-tab">Firefox <span aria-hidden="true">?</span></span>}
<span>{answered ? `The browser chose ${round.rules[winner].colorName}.` : 'Make your prediction to reveal the result.'}</span>
</div>
Expand All @@ -105,7 +105,7 @@ export function SpecificityBattle() {
{answered ? <button className="button primary" onClick={advance}>{roundIndex === battleRounds.length - 1 ? 'Claim victory' : 'Next battle'} <ArrowRight size={16} /></button> : <button className="battle-hint-button" onClick={() => setHint(!hint)} aria-expanded={hint} aria-controls="battle-hint"><Lightbulb size={16} />{hint ? 'Hide hint' : 'A little help?'}</button>}
<span>{score} correct so far</span>
</div>
{!answered && hint && <p className="battle-hint" id="battle-hint">{round.hint}</p>}
{!answered && <p className="battle-hint" id="battle-hint" hidden={!hint}>{round.hint}</p>}
</div>
)}
<div className="battle-footnote">
Expand Down
20 changes: 8 additions & 12 deletions app/docs/[slug]/page.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -33,11 +33,11 @@ export default async function DocumentationPage({ params }: { params: Promise<{
return (
<>
<main id="main" className="guide-article">
<div className="breadcrumbs">
<nav className="breadcrumbs" aria-label="Breadcrumb">
<Link href="/docs">Documentation</Link>
<span>/</span>
<span aria-hidden="true">/</span>
{page.group === "command" ? "Command reference" : "Guides"}
</div>
</nav>
<span className="eyebrow">
{page.group === "command" ? "COMMAND REFERENCE" : "THE FIELD GUIDE"}
</span>
Expand All @@ -59,7 +59,7 @@ export default async function DocumentationPage({ params }: { params: Promise<{
{slug === "catalogue" && (
<a
className="button primary"
href="/catalogue/index.html"
href="/catalogue/"
target="_blank"
rel="noreferrer"
>
Expand All @@ -76,17 +76,13 @@ export default async function DocumentationPage({ params }: { params: Promise<{
)}
</div>
</main>
<aside className="guide-toc" aria-label="On this page">
<span>ON THIS PAGE</span>
{page.headings.length ? (
page.headings.map((h) => (
<aside className="guide-toc" aria-label={page.headings.length ? "On this page and help" : "Documentation help"}>
{page.headings.length > 0 && <span>ON THIS PAGE</span>}
{page.headings.map((h) => (
<a href={`#${h.id}`} key={h.id}>
{h.text}
</a>
))
) : (
<a href="#main">{page.title}</a>
)}
))}
<div>
<strong>Need a hand?</strong>
<p>
Expand Down
Loading
Loading