joshuaandClaude Opus 5.5
54ae9c49a1
Built from the kit specs (CLAUDE.md, docs/01-05): question index import, status seals, connections graph, Pagefind search, Scripture margin, and 157 evidence articles (drafts unless published) with sources and verified "Learn more" links. Includes link, owner-notes, a11y and publish scripts. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
60 lines
3.6 KiB
Markdown
60 lines
3.6 KiB
Markdown
# 04 — Build plan
|
||
|
||
Work in order. Finish each phase, run the build, then stop and report what changed and why.
|
||
|
||
## Phase 1 — Scaffold
|
||
|
||
- Create the Astro project in the repo root (TypeScript strict, MDX, sitemap). Keep `CLAUDE.md`, `docs/`, `brand/`, `content/` and `scripts/` as they are.
|
||
- Add `src/site.config.ts` with name "Tested", tagline "Test everything. Hold fast what is good.", placeholder URL.
|
||
- Install fonts via Fontsource; add `tokens.css` and `base.css` from the design system.
|
||
- Add `npm run import`, `npm run icons`, `npm run build` (astro build, then Pagefind), `npm run preview`.
|
||
- Add `.editorconfig` and Prettier (with the Astro plugin) so WebStorm formats consistently.
|
||
|
||
Done when: `npm run dev` shows a blank page using the right fonts and background, and `npm run build` passes.
|
||
|
||
## Phase 2 — Data
|
||
|
||
- Make `scripts/import-index.mjs` work against `content/source/question-index.md` (it's provided; adjust if the export format differs, and report what you changed).
|
||
- Write `src/lib/questions.ts`: typed loaders, `getQuestion(id)`, `getGroup(id)`, `getRelated(q)`, status and domain counts.
|
||
- Validate: every related id resolves, every status is valid, no duplicate ids. The import fails loudly with a list of problems.
|
||
|
||
Done when: import produces all groups and questions, and validation passes or lists exact problems.
|
||
|
||
## Phase 3 — Brand and icons
|
||
|
||
- Copy `brand/*.svg` into place; write `scripts/build-icons.mjs` using `sharp` to output `favicon.ico`, `favicon.svg`, `apple-touch-icon.png`, `icon-192.png`, `icon-512.png` and `og-image.png` into `public/`.
|
||
- Add `site.webmanifest` and all head tags.
|
||
|
||
Done when: the favicon shows in the browser tab in light and dark mode, and the OG image renders at 1200×630.
|
||
|
||
## Phase 4 — Core pages
|
||
|
||
- Layout shell: header with logo and nav, footer, skip link, theme toggle (respects system preference, remembers choice).
|
||
- `StatusSeal`, `QuestionRow`, `ShortAnswer`, `Marginalia` components.
|
||
- Question page, questions list with URL-driven filters, group pages, About page (explains the statuses and domains using `docs/05-content-rules.md`), 404.
|
||
|
||
Done when: every question has a working page, filters work and survive a reload, and pages pass an axe accessibility check with no serious issues.
|
||
|
||
## Phase 5 — Signature visuals
|
||
|
||
- `ArcDiagram` on the home page, rendered as SVG at build time from `graph.ts`, with a small script for hover, focus and click. Arcs draw in once on load; respect reduced motion.
|
||
- `ConnectionsGraph` on `/connections/` with D3, plus the accessible list fallback.
|
||
|
||
Done when: hovering a question on the home page highlights its arcs and shows its title, keyboard users can tab through questions, and the graph runs smoothly on a mid-range phone.
|
||
|
||
## Phase 6 — Search and SEO
|
||
|
||
- Pagefind search in the header and on the home page, styled with the tokens.
|
||
- Meta tags, canonical URLs, JSON-LD `FAQPage`, sitemap, robots.txt.
|
||
- Build-time check that `authorNotes` text never appears in `dist/`.
|
||
|
||
Done when: searching "Enoch" finds the Enoch questions, and Lighthouse scores 95+ for performance, accessibility, best practices and SEO on a question page.
|
||
|
||
## Phase 7 — Articles
|
||
|
||
- Content collection for `src/content/articles/` with a schema matching the article structure in `docs/05-content-rules.md`.
|
||
- Article template rendering the sections with proper headings and a sources list.
|
||
- Create one sample article stub for 7.9 ("Did Jesus rise from the dead?") with section headings and TODO markers only. The owner writes the content.
|
||
|
||
Done when: a question with an MDX file shows the full article; others show the short answer and "Full article coming".
|