feat(website): scaffold aimx.email homepage and mdBook guide#121
Conversation
Adds a static site served from `/` (homepage) and `/book/` (user guide). The homepage expands the existing aimx.email "coming soon" page with a mascot hero, Quick start, 6-feature rundown, and deep links to the repo and book. The book/ markdown already existed; this adds SUMMARY.md plus a branding-compliant mdBook theme (palette, typography, chrome) layered on the built-in light/coal slots. Palette, typography, and voice follow docs/branding.md §2, §3, §5.2, §5.3.
uzyn
left a comment
uzyn
left a comment
There was a problem hiding this comment.
Changes Overview
Adds a website/ sibling directory that builds a static site with / (homepage) and /book/ (an mdBook render of the existing book/ markdown). Homepage is a single index.html expanded from the prior aimx.email coming-soon page: mascot hero, alpha · pre-v1 status pulse, what-it-is prose, quick-start block, six-feature rundown, deep links, and the "dig" detail block. mdBook is wired via three layered CSS files (styles/palette.css, styles/typography.css, styles/chrome.css) and a theme/head.hbs that injects Google Fonts — no custom index.hbs. book/SUMMARY.md is added so mdBook can build from the existing chapter files without moving them.
Scope Alignment
Scope is delivered. Every bullet in the PR description is present in the diff: homepage sections, alpha · pre-v1 eyebrow, /book/ render, branding-compliant theme layered on default slots, exactly one <em> on the homepage. The test plan in the PR description is a checklist of seven items, all still unchecked — no evidence the author actually ran through them in a browser. That's a verification gap, not a scope gap.
Potential Bugs
Non-blocker
1. styles/chrome.css:10-20, 22-27 — dead selectors; book pages silently lose the brand radial accents.
mdBook applies the theme class to <html> (confirmed: <html lang="en" class="light sidebar-visible">), not <body>. The ruleset at lines 10–20 targets body.aimx, body.light, body.navy, body.rust, body.coal, body.ayu { background-image: radial-gradient(...) } and never matches anything. Same issue at lines 22–27 for body.aimx-dark. Net effect: the radial copper ambient that branding §2.5 calls for on long-form surfaces is present on the homepage but absent on every book page. That's a visible brand-compliance miss across the entire guide surface, not a cosmetic one-liner. Fix: change the selectors to html.light, html.rust, html.ayu { ... } and html.coal, html.navy { ... }, matching what styles/palette.css already does. The html.aimx/html.aimx-dark fallback selectors should also be removed — palette.css never sets those classes either, so they're dead.
2. styles/palette.css:6-8 — color-scheme hardcoded to light; dark theme never reaches browser UI.
:root { color-scheme: light; } is set globally and never overridden. Inside the html.coal, html.navy block at line 107, --color-scheme: dark is declared as a custom property, which the browser ignores — it's not the color-scheme CSS property. When a reader picks the Coal theme, the chrome.css custom scrollbar covers most of the gap, but native form controls (the search input's caret and selection colors, the theme popup's system menu behaviors) will still render in light-mode styling on the dark palette. Fix: drop the custom-property lines and add color-scheme: dark; as a real property inside the html.coal, html.navy { ... } block (and color-scheme: light; inside the light block).
3. website/public/index.html:368, 381, 392, 404 — section headings are <div class="section-label"> rather than <h2>.
Document outline on the homepage is currently: <h1> (hero), then four sections each labelled by a <div>. Screen readers and outline-extractors see a single h1-only page with no sub-structure. Branding.md doesn't prescribe HTML semantics explicitly but §5.2 describes these as "sections", and a real landing page should expose them to the document outline. Fix: promote each .section-label to <h2 class="section-label"> (no visual-styling change needed beyond adjusting margins, since the class already controls typography).
4. website/public/index.html:23 — Google Fonts <link> is missing rel="stylesheet".
Line 23 is <link href="https://fonts.googleapis.com/css2?..." rel="stylesheet"> — actually reading again, rel="stylesheet" IS present. Disregard.
5. website/public/index.html:407 — external GitHub link has rel="noopener" but no target="_blank".
Since the link opens in the same tab, noopener is a no-op. Either drop the rel (no harm) or add target="_blank" rel="noopener noreferrer" if the intent was a new tab. Minor — not load-bearing either way.
6. website/public/robots.txt:4 — references sitemap.xml that doesn't exist.
Crawlers will hit a 404. Either remove the Sitemap: line or generate a sitemap as part of the build. Low impact, but producing a 404-on-every-crawl is easy to avoid.
Security Issues
None identified. The site is entirely static, has no forms, no inline event handlers, no innerHTML injection surface. The only third-party resources are Google Fonts (documented in the PR as a deliberate choice with self-hosting tracked as a future asset gap).
One note: the PR description calls out eval-free status implicitly by being HTML+CSS only. The only JS running on book pages is mdBook's default bundled JS (elasticlunr search, highlight.js, clipboard). No new JS was introduced by this PR.
Test Coverage
No automated tests — this is expected for a static marketing/docs site. The author's PR description provides a seven-item manual test plan, but every item is unchecked. For a visual-only change I wouldn't block on this, but the implementer's own earlier summary admits "I haven't visually inspected the pages in a browser — this session has no GUI." That's worth running through before merging:
- Radial gradient presence on
/book/<any>.html— would have caught bug #1 above. - Dark mode switch via the "Coal" theme picker option — would confirm palette flipping and flush out bug #2.
- Keyboard-only nav through the homepage (tab order, focus rings) — untested, and the custom
border-bottom: 1px solid accentlink styling may or may not present a visible focus indicator. prefers-reduced-motion: reduce(the author already handles.fadeand the status pulse, but worth confirming in a browser that throws the media query).
Code Quality
Makefile:10—cp -R public/. dist/silently ships whatever happens to be inpublic/on the builder's disk.public/assets/is created at Makefile line 9 as an empty dir; if a local developer has stray files inpublic/assets/(not in git), they get published. Low risk, but thecp -R public/. dist/copies anything present, not just tracked files. Tightening would mean either a manifest orgit archive-style copy. Non-blocker for a solo project.website/README.md:67— "governed bydocs/branding.mdin the parent project" is ambiguous. The aimx repo's.gitignoreexcludes/docs/entirely; a new contributor cloning the repo has no way to finddocs/branding.md. Either commit the branding doc (or a copy) into the repo or make the README explicit that it lives outside the public tree.- Mascot deep-link on the homepage is via absolute URL (
/assets/aimx-pigeon.svg), which ties the homepage to being served at the site root. Fine foraimx.emailbut will break any sub-path preview deploys (Cloudflare Pages preview subdomains use root, so this is fine in practice — flag for awareness only). - Fonts request includes IBM Plex Sans weight 600, but branding.md §2.2 specifies weights 400 and 500 only. The homepage uses 600 for
<strong>inside feature bullets. Either the branding doc should be extended or the homepage should drop to 500 for strong. Small divergence.
Summary and Recommended Actions
Overall verdict: Needs minor fixes. No blockers, but the radial-gradient selector bug (issue #1) silently removes a brand motif from every book page and should be fixed before merge; it's a one-character change per selector and would have been caught by a 30-second browser check.
Blockers: none.
Non-blockers (recommended before merge):
styles/chrome.css— changebody.*selectors tohtml.*so radial accents actually render on book pages.styles/palette.css— setcolor-schemeas a real CSS property per theme, not a custom property.website/public/index.html— promote.section-labeldivs to<h2>for document outline.
Nice-to-haves (track, don't block):
- Run the seven-item test plan in a real browser and tick the boxes, or remove the checklist.
robots.txtsitemap reference points at nothing.- Drop unused
rel="noopener"on the same-tab GitHub link, or make ittarget="_blank". - Remove dead
html.aimx/html.aimx-darkfallback selectors fromchrome.css. - Reconcile the IBM Plex Sans 600 weight against branding.md §2.2 (either update the doc or drop to 500).
- Clarify where
docs/branding.mdactually lives for contributors cloning from a fresh checkout.
Review fixes: - chrome.css: radial-gradient selectors target html.* not body.*, so book pages actually pick up the brand accent backdrop - palette.css: set color-scheme as a real CSS property per theme, not a custom property (dark mode now reaches native browser UI) - index.html: section labels are <h2>, not <div>, for document outline - Drop IBM Plex Sans 600 weight (not in branding §2.2); strong tags use 500 everywhere - robots.txt: remove reference to sitemap.xml that does not exist Design tweaks: - Top-left logo is lowercase "aimx" with font-variant-caps: small-caps - Homepage CTAs: "Read the book" and "Get the code"
Homepage:
- Two CTA buttons sit directly after the pitch ("Read the book",
"Get the code") — the book button is primary (filled ink),
code is secondary (outlined); code opens in a new tab.
- Top-right status eyebrow is replaced by a three-item nav:
home / book / code. The "// alpha" line in the dig block still
signals project stage.
- Wordmark is now a link back to /.
- Redundant "Go deeper" section removed; the header nav and the
hero CTAs cover navigation.
Book:
- scripts/nav.js wraps the mdBook menu-title in a link to /
and injects the same home/book/code nav into the menu bar.
- Matching styles added to chrome.css; external "code" opens
in a new tab, home/book stay in-tab.
Page <title>, og:title, and twitter:title all used uppercase "AIMX" which showed up in the browser tab and link previews. Branding §2.3 reserves uppercase AIMX for the logo wordmark; prose/metadata uses lowercase aimx.
Adds .github/workflows/site.yml: - On pull_request touching website/**, book/**, or the mascot: build-only validation (catches regressions before merge). - On push to main with the same paths (and on manual dispatch): build, write a CNAME for aimx.email, and deploy via the GitHub Pages action pair (configure-pages + upload-pages-artifact + deploy-pages). mdBook is installed through peaceiris/actions-mdbook. - Concurrency is scoped to the deploy job only, so PR builds do not queue behind a running deploy. README updated to point contributors at the workflow.
aimx targets Linux servers only; macOS is not a supported deployment target. The matrix also accounted for most of the UDS-timing flakes on the integration tests.
1 participant
Summary
website/— a static site with/(homepage) and/book/(mdBook render of the existingbook/markdown). Build:cd website && make build→website/dist/.aimx.email"coming soon" page with the mechanical-pigeon hero,alpha · pre-v1status eyebrow, "What it is" prose, Quick start block, six-feature rundown, and deep links to the repo and guide.book/SUMMARY.mdso mdBook can render the user guide without touching the existing chapter files (GitHub links likebook/faq.mdkeep resolving).website/styles/(palette, typography, chrome) layered on mdBook's built-inlight/coaltheme slots. No customindex.hbs— the default theme picker still works; Light / Rust / Ayu render the aimx light palette, Coal / Navy render the aimx dark palette.docs/branding.md§2, §3, §5.2, §5.3. Homepage ships with exactly one<em>(the one-italic-beat rule) and no forbidden superlatives.Out of scope (still open per branding.md §6)
Test plan
cd website && make build—dist/index.html,dist/book/index.html, anddist/book/faq.htmlexistmake serve— homepage athttp://localhost:8000/renders with paper grain, radial copper accents, mascot, alpha eyebrowhttp://localhost:8000/book/— sidebar navigable; code blocks have a 2px copper left border and no background fill; tables have no row stripes/book/https://github.com/uzyn/aimxprefers-reduced-motion: reduce(no fade-in, no pulsing status dot)