A calm place to write long-form, and publish it to the open social web.
skypress.blog/
Merge branch 'playful-error-pages' into trunk
author
Jeremy Herve
date
(Jun 9, 2026, 7:09 PM +0200)
commit
f8083077
f80830772283255af999ea5d700b095ee7f1773a
parent
1ce5a577
1ce5a5778457279eba73b2cfedf203e3bdd9430e
+865
-243
+98
docs/specs/sp12-error-pages.md
+98
docs/specs/sp12-error-pages.md
···
1
+
# SP12 — Playful error pages (404 / 500)
2
+
3
+
- **Status:** Built
4
+
- **Depends on:** SP4 (public renderer), SP6 (brand), SP10 (publication URL model)
5
+
- **Decisions:** none new (reuses 0007 read-through renderer, 0009 Cloudflare deploy)
6
+
7
+
## Goal
8
+
9
+
Replace the bare `new Response('Not found', { status: 404 })` plain-text responses on the
10
+
reader routes with a **good-looking, playful** error page that stays on brand, and add the
11
+
two error pages SkyPress is missing entirely: a global **404** for unmatched URLs and a
12
+
**500** for server-side failures (e.g. a PDS fetch that throws).
13
+
14
+
The visual concept is **"Below the horizon"**: SkyPress's warm paper/ink/**sun** palette with
15
+
a setting sun dipping under a thin horizon line and a couple of distant birds. One scene,
16
+
copy that adapts to what went wrong, and a single **Back to homepage** button.
17
+
18
+
## Scope
19
+
20
+
Five situations, all rendered by the same scene:
21
+
22
+
| Kind | HTTP | Triggered from |
23
+
| ------------------------ | ---- | --------------------------------------------------------- |
24
+
| `writer-not-found` | 404 | `resolveAuthor(handle)` returns null (all 3 reader routes)|
25
+
| `publication-not-found` | 404 | `resolveReaderPublication` returns null |
26
+
| `article-not-found` | 404 | record missing, or `record.value.site` ≠ this publication |
27
+
| `not-found` | 404 | unmatched URL (global `404.astro`) + malformed params |
28
+
| `server-error` | 500 | any route throws (auto-rendered `500.astro`) |
29
+
30
+
## Copy (the content model)
31
+
32
+
No em dashes, plain natural wording. Eyebrow is a mono kicker; headline uses the display
33
+
face. All five share the single **Back to homepage** button.
34
+
35
+
- **`writer-not-found`** — eyebrow `404 · no one by that name`,
36
+
heading `No writer at @{handle}`,
37
+
sub `Nobody on the network goes by that handle yet. It might have a typo.`
38
+
- **`publication-not-found`** — eyebrow `404 · publication not found`,
39
+
heading `No publication by that name`,
40
+
sub `@{handle} hasn't published anything under "{slug}".`
41
+
- **`article-not-found`** — eyebrow `404 · story not found`,
42
+
heading `This story set below the horizon`,
43
+
sub `It's no longer part of {publicationName}. It may have been unpublished or moved.`
44
+
- **`not-found`** — eyebrow `404 · off the map`,
45
+
heading `This page set below the horizon`,
46
+
sub `There's nothing to read at this address.`
47
+
- **`server-error`** — eyebrow `500 · overcast`,
48
+
heading `The sky's a bit cloudy right now`,
49
+
sub `Something went wrong on our end. Give it a moment, then try again.`
50
+
51
+
## Modules
52
+
53
+
- `src/lib/reader/errors.ts` — **pure, dependency-free** source of truth. A function
54
+
`errorScene(kind, context?)` returns `{ status, eyebrow, heading, subline }`. Context is
55
+
the interpolation values (`handle`, `slug`, `publicationName`). All copy lives here, so it
56
+
is edited in one place and is fully unit-testable. No `@wordpress`, no network.
57
+
- `src/components/ErrorScene.astro` — the visual. Props are exactly the four
58
+
`errorScene()` fields. Renders inside `Base` (masthead + `Logo`). Self-contained `<style>`
59
+
for the horizon scene. **No `@wordpress/*` imports** (AGENTS.md #3 — this is a read path).
60
+
- `src/pages/404.astro` — `prerender = true`. Static generic 404 for unmatched URLs;
61
+
renders `ErrorScene` with `errorScene('not-found')`.
62
+
- `src/pages/500.astro` — `prerender = true`. Astro auto-renders this when a route throws,
63
+
so no per-route try/catch is needed; renders `errorScene('server-error')`.
64
+
65
+
## Wiring the reader routes
66
+
67
+
In each of `src/pages/[author]/index.astro`, `[author]/[slug]/index.astro`, and
68
+
`[author]/[slug]/[rkey].astro`, replace every early `return new Response('…', { status })`
69
+
with: build the matching `errorScene(...)` props, set `Astro.response.status = props.status`,
70
+
and render `<ErrorScene {...props} />` from the template instead of the normal content
71
+
(`{ error ? <ErrorScene {...error} /> : <…normal…> }`). The real 404 status is preserved for
72
+
crawlers; the page is now a rendered HTML body, not plain text.
73
+
74
+
## Look & accessibility
75
+
76
+
- Reuses brand tokens from `global.css` (`--paper`, `--ink`, `--sun`, `--sun-tint`, `.btn`,
77
+
`.eyebrow`). Light + dark first-class: a dark-mode sky-gradient variant via
78
+
`@media (prefers-color-scheme: dark)`.
79
+
- Setting-sun has a slow glow animation, disabled under `@media (prefers-reduced-motion)`.
80
+
- Decorative sun/birds/horizon are `aria-hidden`. Single `<h1>` carries the heading. The
81
+
status is conveyed in visible text, not colour alone. The button is a real `<a href="/">`.
82
+
- Every error page emits `<meta name="robots" content="noindex">` so the playful copy is
83
+
never indexed, and opts out of social/canonical tags (`socialMeta={false}` on `Base`).
84
+
85
+
## Tests (TDD — copy is test-locked)
86
+
87
+
- `errors.test.ts` — for each kind: correct `status` (404 vs 500), correct eyebrow/heading,
88
+
context interpolation (`handle`, `slug`, `publicationName` land in the strings), and a
89
+
guard asserting **no em dash (`—`)** appears in any produced string.
90
+
- Reader-route `.meta.test.ts` files already exist; extend the relevant ones to assert an
91
+
error case sets a 404 status and renders the scene rather than plain text.
92
+
93
+
## Out of scope
94
+
95
+
- Per-situation CTAs beyond "Back to homepage" (deliberately one button — decided in design).
96
+
- Search / "did you mean" suggestions on 404.
97
+
- Illustrated/animated art beyond the CSS horizon scene (no image assets).
98
+
- Localisation of error copy (English only for v1, consistent with the rest of the reader).
+133
src/components/ErrorScene.astro
+133
src/components/ErrorScene.astro
···
1
+
---
2
+
import Base from '../layouts/Base.astro';
3
+
import Logo from './Logo.astro';
4
+
5
+
interface Props {
6
+
eyebrow: string;
7
+
heading: string;
8
+
subline: string;
9
+
}
10
+
const { eyebrow, heading, subline } = Astro.props;
11
+
---
12
+
13
+
<Base title={`${ heading } · SkyPress`} socialMeta={false}>
14
+
<Fragment slot="head">
15
+
<meta name="robots" content="noindex" />
16
+
</Fragment>
17
+
18
+
<header class="err-mast">
19
+
<a href="/"><Logo /></a>
20
+
</header>
21
+
22
+
<main class="err">
23
+
<div class="err__sky" aria-hidden="true">
24
+
<span class="err__birds">︶ ︶</span>
25
+
<span class="err__sun"></span>
26
+
<span class="err__horizon"></span>
27
+
</div>
28
+
<div class="err__body">
29
+
<p class="eyebrow">{eyebrow}</p>
30
+
<h1 class="err__heading">{heading}</h1>
31
+
<p class="err__sub">{subline}</p>
32
+
<a class="btn btn--primary" href="/">Back to homepage</a>
33
+
</div>
34
+
</main>
35
+
</Base>
36
+
37
+
<style>
38
+
.err-mast {
39
+
padding: 1.5rem clamp(1.25rem, 5vw, 4rem);
40
+
}
41
+
.err-mast a {
42
+
text-decoration: none;
43
+
}
44
+
.err {
45
+
position: relative;
46
+
min-height: calc(100vh - 6rem);
47
+
display: flex;
48
+
flex-direction: column;
49
+
align-items: center;
50
+
justify-content: flex-end;
51
+
text-align: center;
52
+
padding: 0 1.5rem clamp(3rem, 12vh, 7rem);
53
+
overflow: hidden;
54
+
/* Light sky: warm dawn at the top, a hard-ish stop forms the horizon band. */
55
+
background: linear-gradient(180deg, #fff4df 0%, #fcdfb8 33%, var(--paper) 33%);
56
+
}
57
+
.err__sky {
58
+
position: absolute;
59
+
inset: 0;
60
+
z-index: 0;
61
+
}
62
+
.err__sun {
63
+
position: absolute;
64
+
top: clamp(4rem, 16vh, 9rem);
65
+
left: 50%;
66
+
width: clamp(72px, 14vw, 104px);
67
+
height: clamp(72px, 14vw, 104px);
68
+
transform: translateX(-50%);
69
+
border-radius: 50%;
70
+
background: radial-gradient(circle at 50% 38%, #f8b850, var(--sun));
71
+
box-shadow: 0 0 46px 10px rgba(232, 146, 12, 0.3);
72
+
animation: err-glow 4.5s ease-in-out infinite;
73
+
}
74
+
@keyframes err-glow {
75
+
0%, 100% {
76
+
box-shadow: 0 0 46px 10px rgba(232, 146, 12, 0.3);
77
+
}
78
+
50% {
79
+
box-shadow: 0 0 66px 18px rgba(232, 146, 12, 0.42);
80
+
}
81
+
}
82
+
@media (prefers-reduced-motion: reduce) {
83
+
.err__sun {
84
+
animation: none;
85
+
}
86
+
}
87
+
.err__horizon {
88
+
position: absolute;
89
+
top: 33%;
90
+
left: 0;
91
+
right: 0;
92
+
height: 1px;
93
+
background: linear-gradient(
94
+
90deg,
95
+
transparent,
96
+
var(--line-strong) 18%,
97
+
var(--line-strong) 82%,
98
+
transparent
99
+
);
100
+
}
101
+
.err__birds {
102
+
position: absolute;
103
+
top: clamp(3rem, 11vh, 6rem);
104
+
left: 0;
105
+
right: 0;
106
+
text-align: center;
107
+
color: var(--sun-strong);
108
+
opacity: 0.5;
109
+
letter-spacing: 0.6em;
110
+
font-size: 0.9rem;
111
+
}
112
+
.err__body {
113
+
position: relative;
114
+
z-index: 1;
115
+
max-width: 36ch;
116
+
}
117
+
.err__heading {
118
+
font-size: clamp(2rem, 6vw, 2.9rem);
119
+
line-height: 1.04;
120
+
margin: 0.6rem 0 0;
121
+
}
122
+
.err__sub {
123
+
color: var(--ink-soft);
124
+
font-size: 1.05rem;
125
+
line-height: 1.55;
126
+
margin: 0.9rem 0 1.6rem;
127
+
}
128
+
@media (prefers-color-scheme: dark) {
129
+
.err {
130
+
background: linear-gradient(180deg, #2a1f12 0%, #3a2a14 33%, var(--paper) 33%);
131
+
}
132
+
}
133
+
</style>
+43
src/components/ErrorScene.meta.test.ts
+43
src/components/ErrorScene.meta.test.ts
···
1
+
/**
2
+
* Source-level guard for the shared error scene. Page/component rendering through
3
+
* astro/container isn't viable in this jsdom-pinned suite (see Base.meta.test.ts),
4
+
* so we pin the wiring at the source level.
5
+
*/
6
+
import { readFileSync } from 'node:fs';
7
+
import { dirname, join } from 'node:path';
8
+
import { fileURLToPath } from 'node:url';
9
+
import { describe, expect, it } from 'vitest';
10
+
11
+
const here = dirname( fileURLToPath( import.meta.url ) );
12
+
const component = readFileSync( join( here, './ErrorScene.astro' ), 'utf8' );
13
+
14
+
describe( 'ErrorScene component', () => {
15
+
it( 'renders inside Base and opts out of social meta', () => {
16
+
expect( component ).toMatch( /import Base from '[^']*layouts\/Base.astro'/ );
17
+
expect( component ).toMatch( /socialMeta=\{false\}/ );
18
+
} );
19
+
20
+
it( 'marks the page noindex so playful copy is never indexed', () => {
21
+
expect( component ).toMatch(
22
+
/<meta\s+name="robots"\s+content="noindex"\s*\/?>/
23
+
);
24
+
} );
25
+
26
+
it( 'renders the eyebrow, heading and subline props', () => {
27
+
expect( component ).toMatch( /\{eyebrow\}/ );
28
+
expect( component ).toMatch( /\{heading\}/ );
29
+
expect( component ).toMatch( /\{subline\}/ );
30
+
} );
31
+
32
+
it( 'provides a single Back to homepage link to the site root', () => {
33
+
expect( component ).toMatch( /href="\/"[^>]*>\s*Back to homepage/ );
34
+
} );
35
+
36
+
it( 'disables the sun-glow animation under reduced motion', () => {
37
+
expect( component ).toMatch( /prefers-reduced-motion/ );
38
+
} );
39
+
40
+
it( 'is dependency-free (no @wordpress imports on the read path)', () => {
41
+
expect( component ).not.toMatch( /@wordpress\// );
42
+
} );
43
+
} );
+64
src/lib/reader/errors.test.ts
+64
src/lib/reader/errors.test.ts
···
1
+
import { describe, expect, it } from 'vitest';
2
+
import { errorScene, type ErrorKind } from './errors';
3
+
4
+
const ALL_KINDS: ErrorKind[] = [
5
+
'writer-not-found',
6
+
'publication-not-found',
7
+
'article-not-found',
8
+
'not-found',
9
+
'server-error',
10
+
];
11
+
12
+
describe( 'errorScene', () => {
13
+
it( 'returns 404 for every not-found kind and 500 for server-error', () => {
14
+
expect( errorScene( 'writer-not-found' ).status ).toBe( 404 );
15
+
expect( errorScene( 'publication-not-found' ).status ).toBe( 404 );
16
+
expect( errorScene( 'article-not-found' ).status ).toBe( 404 );
17
+
expect( errorScene( 'not-found' ).status ).toBe( 404 );
18
+
expect( errorScene( 'server-error' ).status ).toBe( 500 );
19
+
} );
20
+
21
+
it( 'interpolates the handle into the writer-not-found copy', () => {
22
+
const scene = errorScene( 'writer-not-found', { handle: 'jeherve.com' } );
23
+
expect( scene.heading ).toBe( 'No writer at @jeherve.com' );
24
+
} );
25
+
26
+
it( 'interpolates handle + slug into the publication-not-found copy', () => {
27
+
const scene = errorScene( 'publication-not-found', {
28
+
handle: 'jeherve.com',
29
+
slug: 'tribulations',
30
+
} );
31
+
expect( scene.subline ).toContain( '@jeherve.com' );
32
+
expect( scene.subline ).toContain( 'tribulations' );
33
+
} );
34
+
35
+
it( 'interpolates the publication name into the article-not-found copy', () => {
36
+
const scene = errorScene( 'article-not-found', {
37
+
publicationName: 'Tribulations of a Software Engineer',
38
+
} );
39
+
expect( scene.subline ).toContain( 'Tribulations of a Software Engineer' );
40
+
} );
41
+
42
+
it( 'falls back gracefully when the article publication name is missing', () => {
43
+
const scene = errorScene( 'article-not-found' );
44
+
expect( scene.subline ).toContain( 'this publication' );
45
+
} );
46
+
47
+
it( 'keeps the horizon metaphor for the generic not-found heading', () => {
48
+
expect( errorScene( 'not-found' ).heading ).toBe(
49
+
'This page set below the horizon'
50
+
);
51
+
} );
52
+
53
+
it( 'never emits an em dash in any copy field (house rule)', () => {
54
+
for ( const kind of ALL_KINDS ) {
55
+
const scene = errorScene( kind, {
56
+
handle: 'x',
57
+
slug: 'y',
58
+
publicationName: 'Z',
59
+
} );
60
+
const text = `${ scene.eyebrow }${ scene.heading }${ scene.subline }`;
61
+
expect( text ).not.toContain( '—' ); // em dash
62
+
}
63
+
} );
64
+
} );
+72
src/lib/reader/errors.ts
+72
src/lib/reader/errors.ts
···
1
+
/**
2
+
* Source of truth for reader error-page copy + HTTP status (SP12).
3
+
*
4
+
* Pure and dependency-free (no @wordpress, no network) so it can run on the read
5
+
* path (AGENTS.md #3) and be unit-tested directly. Copy avoids em dashes by house
6
+
* rule; the eyebrow uses a middle-dot kicker in SkyPress's editorial voice.
7
+
*/
8
+
export type ErrorKind =
9
+
| 'writer-not-found'
10
+
| 'publication-not-found'
11
+
| 'article-not-found'
12
+
| 'not-found'
13
+
| 'server-error';
14
+
15
+
export interface ErrorContext {
16
+
handle?: string;
17
+
slug?: string;
18
+
publicationName?: string;
19
+
}
20
+
21
+
export interface ErrorSceneCopy {
22
+
status: number;
23
+
eyebrow: string;
24
+
heading: string;
25
+
subline: string;
26
+
}
27
+
28
+
export function errorScene(
29
+
kind: ErrorKind,
30
+
context: ErrorContext = {}
31
+
): ErrorSceneCopy {
32
+
switch ( kind ) {
33
+
case 'writer-not-found':
34
+
return {
35
+
status: 404,
36
+
eyebrow: '404 · no one by that name',
37
+
heading: `No writer at @${ context.handle ?? '' }`,
38
+
subline:
39
+
'Nobody on the network goes by that handle yet. It might have a typo.',
40
+
};
41
+
case 'publication-not-found':
42
+
return {
43
+
status: 404,
44
+
eyebrow: '404 · publication not found',
45
+
heading: 'No publication by that name',
46
+
subline: `@${ context.handle ?? '' } hasn't published anything under "${ context.slug ?? '' }".`,
47
+
};
48
+
case 'article-not-found':
49
+
return {
50
+
status: 404,
51
+
eyebrow: '404 · story not found',
52
+
heading: 'This story set below the horizon',
53
+
subline: `It's no longer part of ${ context.publicationName ?? 'this publication' }. It may have been unpublished or moved.`,
54
+
};
55
+
case 'server-error':
56
+
return {
57
+
status: 500,
58
+
eyebrow: '500 · overcast',
59
+
heading: "The sky's a bit cloudy right now",
60
+
subline:
61
+
'Something went wrong on our end. Give it a moment, then try again.',
62
+
};
63
+
case 'not-found':
64
+
default:
65
+
return {
66
+
status: 404,
67
+
eyebrow: '404 · off the map',
68
+
heading: 'This page set below the horizon',
69
+
subline: "There's nothing to read at this address.",
70
+
};
71
+
}
72
+
}
+12
src/pages/404.astro
+12
src/pages/404.astro
···
1
+
---
2
+
import ErrorScene from '../components/ErrorScene.astro';
3
+
import { errorScene } from '../lib/reader/errors';
4
+
5
+
// Generic, data-free: prerender to a static 404.html the adapter serves for
6
+
// any unmatched URL.
7
+
export const prerender = true;
8
+
9
+
const scene = errorScene( 'not-found' );
10
+
---
11
+
12
+
<ErrorScene eyebrow={scene.eyebrow} heading={scene.heading} subline={scene.subline} />
+19
src/pages/404.meta.test.ts
+19
src/pages/404.meta.test.ts
···
1
+
import { readFileSync } from 'node:fs';
2
+
import { dirname, join } from 'node:path';
3
+
import { fileURLToPath } from 'node:url';
4
+
import { describe, expect, it } from 'vitest';
5
+
6
+
const here = dirname( fileURLToPath( import.meta.url ) );
7
+
const page = readFileSync( join( here, './404.astro' ), 'utf8' );
8
+
9
+
describe( 'global 404 page', () => {
10
+
it( 'is prerendered (static, no per-request data)', () => {
11
+
expect( page ).toMatch( /export const prerender = true/ );
12
+
} );
13
+
14
+
it( 'renders ErrorScene with the generic not-found copy', () => {
15
+
expect( page ).toMatch( /import ErrorScene from '[^']*components\/ErrorScene.astro'/ );
16
+
expect( page ).toMatch( /errorScene\(\s*'not-found'\s*\)/ );
17
+
expect( page ).toMatch( /<ErrorScene/ );
18
+
} );
19
+
} );
+12
src/pages/500.astro
+12
src/pages/500.astro
···
1
+
---
2
+
import ErrorScene from '../components/ErrorScene.astro';
3
+
import { errorScene } from '../lib/reader/errors';
4
+
5
+
// Astro auto-renders this page when an SSR route throws (e.g. a PDS fetch fails),
6
+
// so no per-route try/catch is needed. Static copy, so prerender it.
7
+
export const prerender = true;
8
+
9
+
const scene = errorScene( 'server-error' );
10
+
---
11
+
12
+
<ErrorScene eyebrow={scene.eyebrow} heading={scene.heading} subline={scene.subline} />
+19
src/pages/500.meta.test.ts
+19
src/pages/500.meta.test.ts
···
1
+
import { readFileSync } from 'node:fs';
2
+
import { dirname, join } from 'node:path';
3
+
import { fileURLToPath } from 'node:url';
4
+
import { describe, expect, it } from 'vitest';
5
+
6
+
const here = dirname( fileURLToPath( import.meta.url ) );
7
+
const page = readFileSync( join( here, './500.astro' ), 'utf8' );
8
+
9
+
describe( 'global 500 page', () => {
10
+
it( 'is prerendered (static, no per-request data)', () => {
11
+
expect( page ).toMatch( /export const prerender = true/ );
12
+
} );
13
+
14
+
it( 'renders ErrorScene with the server-error copy', () => {
15
+
expect( page ).toMatch( /import ErrorScene from '[^']*components\/ErrorScene.astro'/ );
16
+
expect( page ).toMatch( /errorScene\(\s*'server-error'\s*\)/ );
17
+
expect( page ).toMatch( /<ErrorScene/ );
18
+
} );
19
+
} );