Skip to content

Redesign landing page and reskin docs (Iris/Cloud design system) - #455

Draft
em3s wants to merge 27 commits into
mainfrom
feature/site-redesign
Draft

Redesign landing page and reskin docs (Iris/Cloud design system)#455
em3s wants to merge 27 commits into
mainfrom
feature/site-redesign

Conversation

@em3s

@em3s em3s commented Jul 22, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Important

Blocked by #281 (Adopt SlateDB) — do not merge until it is complete. The redesigned landing presents SlateDB as part of the storage story (trust band, architecture drawing, hero annotations), so this PR should ship only after the SlateDB integration lands.

Summary

Full redesign of the website: a bespoke marketing landing, an Iris/Cloud reskin of the Starlight docs, a signature "drafting language" visual system, and a quality pass covering accessibility, SEO, performance, and template-leftover cleanup. 76 files changed, +2,625 / −5,483.

Landing (website/src/pages/index.astro + components/landing/)

  • Hero — editorial headline (Cormorant / Manrope / JetBrains Mono) with a signature illustration: the interaction graph drawn in a blueprint annotation style — serif-labelled nodes, directed edges, a leader note (version / props), corner ticks, and a Fig. 01 caption. Hidden below 1080px.
  • Drafting language across sections — a shared .fig-cap system numbers the drawings: hero (Fig. 01), live demo graph (Fig. 02), architecture (Fig. 03), so the page reads as one annotated drawing set.
  • Interactive demo — the CLI console runs get / scan / count presets against an in-memory edge set and highlights the matching edges in the graph panel. Preset rows are styled as executable buttons (run indicator, hover elevation). Console output is announced via role="log" + aria-live.
  • CLI otter banner — the real CLI welcome art, rendering fixed: 9px / line-height 1.1 (render-tested; larger values dash the frame and split the figlet rows), a one-column alignment bug in the wordmark's bottom row corrected, and the box-drawing frame replaced by a gold CSS border (the Google Fonts mono subset lacks U+2500–257F, so frame glyphs fell back to a wider system font and jutted ~2px).
  • Trust band — production statement plus fact chips (Apache-2.0 · REST · CDC · HBase / SlateDB). Nav GitHub button shows a live star count (client-side, fails silently) on both landing and docs.
  • Structure — the landing is split into HeroArt / DemoSection / ArchDiagram components plus assets/landing-page.css; index.astro is 518 lines.

Docs reskin

  • Iris/Cloud Starlight overrides in assets/landing.css; Cormorant headings, mono sidebar labels, minimal callouts, unified footer.
  • Chrome matches the landing: same wordmark (otter mark restored into both logo SVGs, scaled into the 26px nav band), same round theme toggle (Lucide Moon/Sun SVGs — the previous ☾/☀ glyphs rendered as emoji through the docs font stack), same GitHub star pill.
  • Favicon now tracks the chosen theme on docs pages (it read a localStorage key nothing wrote).

Quality pass

  • Accessibility — WCAG AA contrast fixes on both surfaces (--accent-text per theme, darker light-mode muted; measured 3.76:1 → 8.43:1 for dark-mode accent text); <main> landmark + skip link; prefers-reduced-motion support; site-wide :focus-visible; axe scan of landing/docs/stories in both themes: 0 violations.
  • SEO — landing gains canonical, full OG/Twitter set, descriptive <title>; robots.txt moved from src/assets/ (never deployed) to public/ with the correct sitemap host.
  • Performance — the 20 social-media-guide PNGs (~4.4 MB) now go through the Astro image pipeline (WebP, dimensions, lazy).
  • Template leftovers removed — the Netlify _redirects copied from the Starlight showcase (it would proxy /ph/* to a third-party site if ever hosted on Netlify), ~5,200 lines of unused showcase components (theme-designer/, testimonials, youtube grids…), the markdoc grammar pipeline, six unused npm dependencies; package renamed to actionbase-website.
  • Test harness repaired — the axe suite's sitemap rewrite still pointed at starlight.astro.build and playwright.config.ts invoked pnpm in an npm repo; both fixed so npm test actually runs.

How to Test

cd website
npm run build      # 41 pages, internal links valid
npm run preview    # inspect / (landing) and any docs page, e.g. /quick-start/
npm test           # axe accessibility suite over the sitemap

Toggle light/dark on both surfaces — the choice (and favicon) persists across them. On the landing, click the demo presets (get / scan / count) and Reset; check the architecture section on a narrow viewport (scrolls sideways instead of shrinking).

AI Assistance

  • This PR was written largely with AI assistance.
    • Tool / model: Claude Code (Fable 5)

em3s and others added 10 commits July 23, 2026 00:29
@em3s @claude
feat(website): redesign landing and reskin docs (Iris/Cloud)
ea19497 
Recreate the Iris/Cloud design handoff in the live Astro + Starlight site.
Design system only — all copy follows the current repo.

- Landing: standalone src/pages/index.astro with a guided, keyboard-free live
  console and write/read architecture paths converging on a shared storage
  backend. Live GitHub star count; theme synced via the starlight-theme key.
  Replaces the old Starlight splash index.mdx.
- Docs reskin (structure unchanged): Starlight CSS custom-property overrides
  for Iris/Cloud, Space Grotesk / Manrope / JetBrains Mono fonts, a dark
  Expressive Code theme, and consistent header/footer/theme-toggle chrome.
- HANDOFF.md (temporary) with decisions and remaining work.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@em3s @claude
feat(website): refine landing console and engine cards
dbc18e0 
- CLI console: title now "actionbase cli"; colour the banner to match the
  real CLI (white otter, gold frame/heart/labels/wordmark) instead of a flat
  gold; fix scroll so the whole stack (banner included) scrolls up as commands
  run — the term body is a plain block scroll container pinned to the bottom
  (a flex column was squashing the banner instead of overflowing).
- Terminal frame: thinner, muted so it no longer overpowers the console.
- Engine cards: vertical stripes only (no grid crosslines, no gradient wash).
- "The engine" section retitled "Under the hood"; drop the roman-numeral
  card ordinals.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@em3s @claude
feat(website): lock the landing console from user scroll/drag
7d5dcc1 
Make the term body overflow:hidden (was auto) so the wheel and drag no longer
move it, and user-select:none so text can't be drag-selected. The JS still
scrolls it programmatically after each command, pinning the view to the bottom
so a click jumps there and stays put.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@em3s @claude
feat(website): rework hero into a 2×2 demo and use the wordmark logo
8151592 
- Hero is now a 2×2 grid — copy | console over graph | run controls — so the
  space reads full instead of a lone column. The mascot is dropped from the
  hero; the interactive edge-state graph reacts to each console step (get/scan/
  count highlight the relevant edges/nodes, count shows a badge).
- Copy: value-prop headline "Precomputed at write time, served as simple
  lookups" over the GitHub-description subline.
- The three demo cells (console, graph, controls) share one .panel frame
  (surf-soft fill, line-soft border, equal padding) so they read as a set;
  drop the loud indigo console frame and the unused --glass token.
- Logo: crop the shared SVG viewBox to the "actionbase" wordmark (otter off),
  and size the docs header logo to match the landing nav (26px).
- Section retitled "Under the hood" → "Features"; drop its subtitle.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@em3s @claude
feat(website): restructure the landing into a demo-led flow
7955ece 
- Move the interactive console/graph out of the hero into a dedicated
  "Interactive demo" section (renamed from "Try it" to signal it's a
  simulation), below the trust band and Features.
- Section order is now Features → Interactive demo → Architecture → Quick
  start → CTA. Architecture is promoted to a top-level section (h2), and the
  CTA reads "Start building".
- Hero is copy-only: a two-line value-prop headline over the one-line GitHub
  description.
- Demo controls become two tabs — Supported (get/scan/count, runnable in any
  order, clicked step stays active) and Coming soon (agg + two topk shapes
  from #369 + multihop, disabled with a TBD tag). Each command shows a short
  description; on mobile the tabs collapse and the upcoming queries render as
  a plain list.
- Console and graph share the panel row height; the console content is
  absolutely positioned so running commands never grows the cell. Graph is
  modernized (thin edges, open-chevron arrows, "likes" labels, count numbers
  the matched edges 1..n).
- Nav/docs logo is the otter-less "actionbase" wordmark.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@em3s @claude
feat(website): realistic demo console, graph redesign, unified chrome
a0f6f2a 
Landing:
- Console output now mirrors the real CLI for get/scan/count — request line,
  200 response, aligned result table and timing, with the
  actionbase(likes:likes)> prompt; the banner leading is fixed to a 2:1 cell so
  the otter art connects; a Reset control sits by the section title.
- Graph reskinned to the handoff: dotted board, card nodes that glow when
  active, marching-ants dashed active edges (no arrowheads), "likes" labels;
  count still numbers the matched edges.
- Architecture is now a connected SVG (Client → Actionbase → write Kafka / read
  request → one storage backend → CDC Kafka), no broken connectors.
- Features cards regain 01–06 ordinals; header GitHub is a round icon button
  sized/placed to match the theme toggle.

Docs (Starlight):
- GitHub moves from a text nav link to a round social icon next to the toggle
  (divider removed, icon centered); header background matches the page.
- Footer bar spans content + on-this-page rail (not the nav) as one band; the
  content↔rail vertical divider is dropped.
- Active sidebar item and the Main/Stories switcher drop the rounded pill for a
  flat accent underline / left bar.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@em3s @claude
feat(website): elegant heading font + neutral active states
28293cb 
- Swap the heading typeface from Space Grotesk to Cormorant (a slim, classical
  serif) across the landing and docs; drop Space Grotesk from the font loads.
- Docs active states go neutral (no accent purple, no rounded pill): the active
  sidebar item gets a flat grey fill with strong dark text (no left bar), and
  the Main/Stories switcher keeps just a dark underline with no fill.
- Docs footer bar spans content + on-this-page rail but no longer covers the
  nav menu (right-side bleed only).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@em3s @claude
fix(website): make the active docs sidebar highlight visible
2dfee17 
Bump the active item fill from gray-6 to gray-5 so the neutral highlight reads
against the white page instead of nearly disappearing.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@em3s @claude
feat(website): merge docs sidebar and polish chrome
6eee966 
- Merge Main/Stories into one sidebar: drop the multiSidebar plugin,
  flatten all groups to the root with `collapsed: true`, and make
  Stories a top-level group.
- Match the standalone Community link to the root group-label type
  (mono/uppercase) and shrink sub-item links to 0.8125rem.
- Make prev/next cards transparent so they sit on the page gradient
  instead of a near-white nav surface; tint only on hover.
- Stop over-scroll bounce (`overscroll-behavior: none`) and give <html>
  a solid background colour so dragging never flashes white.
- Unify header background with the page gradient, drop the h1 divider,
  and remove dead multiSidebar CSS.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@em3s @claude
fix(website): unify Stories page chrome and reorder sidebar
77df1df 
- Move Community below Stories so it sits last in the sidebar.
- Drop `tableOfContents: false` from the Stories overview: it was the
  only page without a right-sidebar column, which let the main pane grow
  full-width, shifted the content column right, and pushed the full-bleed
  footer past the viewport. Restoring the TOC column makes its layout and
  footer identical to every other doc.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@em3s
em3s force-pushed the feature/site-redesign branch from 7ad6d1b to 46fe428 Compare July 23, 2026 11:30
@em3s
Make Actionbase easier to evaluate and use across screen sizes
aa0bb6a 
Constraint: Preserve the existing product language and interactive CLI behavior while applying the reviewed UI improvements in one cohesive change.
Rejected: Replacing the original production proof band | The existing concise statement was explicitly preferred.
Confidence: high
Scope-risk: moderate
Directive: Keep mobile demo controls before visualization and guard full-bleed docs footer rules behind desktop breakpoints.
Tested: npm run typecheck; npm run build; Playwright desktop/mobile screenshots and 390px overflow, copy, and demo interaction checks
Not-tested: Physical touch-device and Safari visual regression
@em3s
em3s force-pushed the feature/site-redesign branch from 46fe428 to aa0bb6a Compare July 23, 2026 11:35
em3s and others added 16 commits July 23, 2026 20:39
@em3s @claude
chore(website): drop handoff doc and dead star-count script
baa8fee 
- Remove HANDOFF.md: a temporary session-bootstrap note (marked
  "remove before merge"), not site content.
- Remove the GitHub star-count script from Head.astro: it targeted
  `.nav-external`, which no longer renders now that the docs header uses
  the Starlight social icon — the script early-returned as dead code
  (its api.github.com fetch never fired) and was inconsistent with the
  landing, where the star count was already removed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@em3s @claude
fix(website): clean deploy leftovers from the Starlight template
6c28435 
- delete public/_redirects: it proxied /ph/* to a third-party site and
  redirected paths that do not exist here; GitHub Pages ignores it today,
  but it would activate on a Netlify move
- move robots.txt from src/assets (never deployed) to public/ and point
  its Sitemap line at actionbase.io instead of starlight.astro.build
- fix _headers cache rule: max-age=0 + immutable was self-defeating

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@em3s @claude
fix(website): sync docs favicon with the chosen theme
b2e4240 
Head.astro keyed off localStorage.theme, a key nothing writes (both
toggles persist to starlight-theme), so the docs favicon only followed
the OS preference. Key it off html[data-theme] and a theme-change event
instead, and dispatch that event from the docs toggle like the landing
toggle already does.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@em3s @claude
fix(website): meet WCAG AA contrast on landing and docs
7851578 
- add --accent-text/--accent-text-hover per theme; raw --accent measured
  3.76:1 on the dark page bg and 4.42:1 on light as small text
- switch small accent text (links, demo reset, graph labels, card
  numbers, arch annotations, step numbers) to the new tokens
- darken light-theme muted #6f7389 -> #61657c (4.28:1 -> 5.25:1), both
  on the landing and the docs skin
- button text to pure white (#f5f6ff on accent was 4.49:1)
- underline in-paragraph quickstart links (color-only distinction)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@em3s @claude
feat(website): complete landing SEO/social metadata
3b85e58 
The bespoke landing head only carried og:image; docs pages get the full
set from Starlight. Add canonical, sitemap link, og:title/description/
url/type/site_name, twitter:card, and expand the one-word <title> into
the descriptive pattern search results and shares actually surface.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@em3s @claude
feat(website): landing accessibility basics
5ca376d 
- wrap page content in a <main> landmark and add a skip link
- announce demo console output via role=log + aria-live=polite
- replace the half-implemented ARIA tabs (tablist/tab/aria-selected
  without panels or arrow keys) with plain toggle buttons + aria-pressed
- stop infinite cursor-blink and edge-dash animations under
  prefers-reduced-motion
- site-wide :focus-visible outline
- copy buttons restore their per-step label after the copied state

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@em3s @claude
fix(website): repair the a11y test harness
0f05066 
The suite was copied from the Starlight docs repo and could never run
here: the sitemap rewrite stripped https://starlight.astro.build (our
site is actionbase.io), producing invalid URLs, the i18n exclude list
referenced Starlight-only slugs, and playwright.config/linkcheck
invoked pnpm in an npm repo.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@em3s @claude
perf(website): route social-media guide images through the image pipe…
14a9569 
…line

The 20 guide PNGs (~4.4 MB) lived in public/ and were referenced by
absolute path, bypassing Astro's image service — no WebP, no
dimensions (CLS), no lazy loading. Moving them to src/assets and
referencing them relatively gets all three for free from the existing
sharp dependency.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@em3s @claude
feat(website): restore the otter in the wordmark logo, unify theme to…
9fc60e9 
…ggles

The otter mark was still in both logo SVGs — the redesign only cropped
it out via the viewBox. Re-expand the viewBox and scale the otter to
1.22x the wordmark cap height, optically centered, so the lockup fits
the existing 26px nav band.

Also replace the ☾/☀ glyph in both theme toggles with Lucide Moon/Sun
SVGs swapped via CSS on html[data-theme]: the docs header's font stack
let the glyphs fall back to Apple Color Emoji, rendering a filled disc
that didn't match the landing. Docs toggle also drops its bg-nav fill
to match the landing's transparent ring.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@em3s @claude
feat(website): hero graph motif in the site's drafting language
649c3e7 
Adopt the signature visual direction (blueprint annotation language at
editorial density): the hero's empty right column gets an interaction-
graph illustration — serif-labelled nodes, swept directed edges, a
'likes' chip — annotated with drafting marks: corner ticks, a leader
note (version/props), a construction ring on the hot item, and a
'Fig. 01' caption.

The same caption system extends to the demo graph panel (Fig. 02) and
the architecture diagram (Fig. 03) via a shared .fig-cap style, so the
landing reads as one annotated drawing set. Art hides below 1080px.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@em3s @claude
feat(website): trust-signal band + star count; fix CLI banner rendering
651f35b 
- replace the #hashtag band with drafting-style fact chips
  (Apache-2.0 / REST · CDC / HBase · SlateDB)
- GitHub nav button becomes a pill with a live star count on both the
  landing and docs headers (client-side fetch, fails silently)
- CLI otter banner: bottom figlet row was one column right of the rest
  (verified by column math); bump 6.5px -> 9px and set line-height 1.1
  — render-tested 1.0/1.1/1.2/1.35/1.5: 1.1 keeps the frame verticals
  connected and the wordmark rows cohesive

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@em3s @claude
fix(website): draw the CLI banner frame with CSS, not box-drawing chars
b87c373 
The Google Fonts JetBrains Mono subset lacks U+2500-257F, so the frame
glyphs fell back to the system mono whose advance is ~0.34% wider —
measured 541.86px vs 540.05px per line, making the corners jut out ~2px
past the art rows. A gold CSS border with rounded corners reproduces
the CLI frame pixel-exactly.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@em3s @claude
feat(website): preset-button affordance + legible mobile architecture
9473ca3 
- demo preset rows get radius, a run indicator, and hover elevation so
  they read as executable buttons before the first click
- below 700px the architecture panel scrolls sideways at full text size
  (min-width 620px) instead of scaling the SVG into illegibility

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@em3s @claude
chore(website): remove Starlight-showcase dead code
e94e6e0 
All copied from the Starlight docs site and referenced by nothing here
(import graph verified):

- 16 components + the theme-designer/ directory (25 files)
- i18n content collection whose only key fed the dead component-preview
- unreferenced hero.svg / hero.webp
- markdoc grammar pipeline (grammars/, npm script, shiki config) — no
  doc uses markdoc fences
- unused deps: js-yaml, @lorenzo_lewis/starlight-utils, culori,
  @astro-community/astro-embed-youtube (+ their @types)
- rename the package starlight-docs -> actionbase-website

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@em3s @claude
refactor(website): split the landing monolith
f85e7ad 
index.astro had grown past 2,100 lines (project cap: 800). Extract the
self-contained pieces, no behavior change (render, axe, and demo
interaction verified identical):

- components/landing/HeroArt.astro — the Fig. 01 hero illustration
- components/landing/DemoSection.astro — console + graph markup and
  its banner/preset data (the driving script stays with the page)
- components/landing/ArchDiagram.astro — the Fig. 03 drawing
- assets/landing-page.css — the global style block, imported by the page
- drop the unused writeNode/readNode constants

index.astro is now 518 lines: head, chrome, copy sections, and scripts.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@em3s @claude
fix(website): drop the underline under the docs star count
124dd78 
Starlight underlines header anchors; the GitHub pill had no text until
the star count was added, so the inherited decoration only now became
visible.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@em3s