refine(web): polish homepage craftsmanship - #2
Merged
Conversation
Adds ProblemSection (apps/web/src/components/marketing/problem-section.tsx) and integrates it immediately after HeroSection on the marketing page — no other section, the Hero, header, footer, docs, or routing touched. Structure follows docs/design-system.md exactly: - H2 "Every new session starts here." + supporting copy, reusing the shared Section/Container wrapper every other homepage section uses (§5, §15 "reuse by default"). - A two-column comparison at `lg:grid-cols-2` (matches the Hero's own breakpoint), stacking to "Without Recall" then "With Recall" on mobile via DOM order — no separate mobile-only markup. - Both comparison columns share one local `ComparisonCard` helper (border, bg-card, p-6, rounded-lg, no shadow, no hover — §7: cards that aren't clickable get no hover state). - "Without Recall": a restrained transcript (speaker label in muted-foreground, message in foreground, plain stacked text) — no chat bubbles, no avatars, no gradients, not styled as a branded chat UI. - "With Recall": a checklist reusing the exact success-checkmark pattern already established in HeroTerminal (§15 consistency), ending in a plain "Context ready." status line. - Closing centered statement below the comparison, in muted-foreground to match the rest of the page's supporting-text convention. Every color is an existing semantic token (foreground, muted-foreground, border, card, success) — no new arbitrary colors, no gradients, no shadows, no animation, no icons beyond the same functional checkmark already in use elsewhere on this page. Visual verification (Playwright, localhost dev server): confirmed at 1440x900 and 390x844, in both light and dark theme — card balance, heading wrap, mobile stacking order (Without Recall first), zero horizontal overflow (scrollWidth === clientWidth at 390px), contrast, and visual consistency with the existing Hero. Validation: `pnpm --filter recall-web lint/typecheck/test/build` and root `pnpm lint/typecheck/test/build` all green (16/16 workspace tasks).
Adds HowRecallWorksSection (apps/web/src/components/marketing/ how-recall-works-section.tsx) and integrates it immediately after ProblemSection on the marketing page. Hero, ProblemSection, header, footer, docs, routing, and copy outside this section are untouched. Structure follows docs/design-system.md exactly: - H2 "How Recall works" + supporting paragraph, using the shared Section wrapper every other homepage section uses (§5, §15 "reuse by default"). - Four equally-sized step cards (Scan Repository / Build Memory / Understand Task / Provide Context), each a plain bordered card (border, bg-card, p-6, rounded-lg, no shadow, no hover — §7: not clickable, so no hover state) containing a mono step numeral (`01`- `04`, matching the numeral convention already established in the page's existing "How it works" section), an h3 title, and a short description. - Cards are connected by a single hairline (`bg-border`) between each pair — vertical when stacked on mobile, horizontal in the row on desktop — implemented as flat flex siblings (not nested per-card wrappers) so all four cards share the exact same `flex-1` sizing rule and stay genuinely equal-width regardless of connector placement. This is a connected-steps flow, not a timeline: no dates, no large illustrations, no icons beyond the existing checkmark style. - A compact terminal block below the steps, visually identical to HeroTerminal's treatment (border, bg-code-background, font-mono, `$`-prefixed command, success-colored checkmarks) but narrower (max-w-xl) to read as a confirmation rather than a second hero. Every color is an existing semantic token (foreground, muted-foreground, border, card, code-background, success) — no new arbitrary colors, no gradients, no shadows, no animation, no illustrations. Note: a separate, pre-existing "How it works" section (3 steps: Scan/ Rank/Generate) already exists further down this same page from the original scaffold. It was left untouched per "do not modify existing copy outside this section" — the two sections now temporarily overlap in subject matter until a later pass consolidates or removes the older scaffold section. Visual verification (Playwright, live dev server): confirmed at 1440x900 and 390x844, in both light and dark theme — equal card widths, connector consistency (vertical on mobile, horizontal on desktop), terminal readability in both themes, zero horizontal overflow (scrollWidth === clientWidth at 390px), and visual consistency with the existing Hero terminal. Validation: `pnpm --filter recall-web lint/typecheck/test/build` and root `pnpm lint/typecheck/test/build` all green (16/16 workspace tasks).
An audit pass over Hero, ProblemSection, and HowRecallWorksSection
against docs/design-system.md, treating the homepage as one connected
narrative rather than three independent sections — no new sections,
no copy changes, no new dependencies.
Findings and fixes:
- HowRecallWorksSection's connector line was centered against the
tallest card's full height (flex `self-center`), so on desktop it
landed at an approximate row-center rather than through the step
numerals it's meant to connect. Pinned it to a fixed offset (24px
card padding + 10px, half of `text-sm`'s exact 20px line-height —
verified against Tailwind's own --text-sm--line-height token) so it
runs precisely through every numeral regardless of how a
description happens to wrap. This is the kind of "disciplined
alignment" the design system explicitly calls for, and it was
previously only approximately correct.
- ProblemSection's two comparison card titles both used identical
foreground weight, giving no typographic signal that "Without
Recall" describes a problem and "With Recall" describes its
resolution. Added a `muted` option to the shared card title (used
only for "Without Recall"), applying an existing token
(muted-foreground) rather than introducing any new color — per
design-system.md §4 rule 3, color hierarchy (not size or decoration)
is exactly how this system is meant to carry that kind of meaning.
- Hero was evaluated and deliberately left unchanged: it already
reads as restrained, typography-led, and correctly hierarchical: an
audit finding no defect is itself a legitimate outcome, not a
missed opportunity.
One idea considered and explicitly rejected: scroll-triggered
fade/slide reveal animations on these sections. docs/design-system.md
§10 forbids this outright ("every section is visible and fully
rendered immediately... not by virtue of an animation permitting it
to appear"), which directly conflicts with looser "progressive
reveal" language elsewhere — the design system document is the
tie-breaker per its own stated authority, so no motion was added
anywhere in this pass.
Validation: `pnpm --filter recall-web lint/typecheck/test/build` and
root `pnpm lint/typecheck/test/build` all green (16/16 workspace
tasks). Visual verification via Playwright was attempted but the
browser bridge was unresponsive for the full session (connects, then
times out) — correctness was instead confirmed via the rendered HTML
output (both new classes present and correct in the live dev-server
markup) and exact CSS math against Tailwind's own token values, not
a guess. Live visual confirmation is still recommended once the
bridge is available.
Implements the approved items from the homepage narrative audit —
removing duplication and diversifying visual language, not adding new
sections, features, or copy.
1. Removed the older scaffold "How it works" (3-step: Scan/Rank/
Generate). It duplicated HowRecallWorksSection's 4-step flow with a
different step count a few sections later on the same page — the
single most credibility-damaging issue found in the audit (an
engineer would read it as unedited). HowRecallWorksSection already
covers this ground with more care; this is pure subtraction.
2. Redesigned "What Recall generates" from a 6-card bordered grid
(FeatureCard, now unused and removed) into a typography-first
definition list: a semantic `<dl>` with `divide-y` hairlines between
rows instead of six repeated `border + rounded-lg + p-6` boxes,
generous per-row spacing (py-6/py-8), and a two-column dt/dd layout
on wider viewports. Same six title/description pairs, same order,
zero new copy — only the container changed. This was the single
most generic-feeling section on the page (a textbook SaaS-grid
pattern); it's the fourth consecutive card grid a scrolling visitor
would otherwise see after Hero/Problem/Workflow.
3. Replaced HowRecallWorksSection's closing terminal block with
MemoryFlow, a borderless data-flow line ("Repository → Architecture
· Conventions · Decisions · Risks · Technical debt → Coding agent"
plus "Context ready.") instead of a second `$ recall context`
terminal. The Hero already demonstrates terminal output; repeating
it two sections later added a second, weaker version of the same
idea rather than a new one. Every label reused verbatim from
existing copy elsewhere on the page (Hero, ProblemSection) — no new
copy introduced. Uses `role="img"` + one descriptive `aria-label`
(same accessible pattern as HeroTerminal), with the visual glyphs
`aria-hidden`.
Net effect: card-count in the Hero-to-comparison-table stretch of the
page drops from 13 bordered boxes to 4 (the two ProblemSection cards
and... nothing else — the step cards were the only bordered element
left in HowRecallWorksSection after this change). No motion added
anywhere; docs/design-system.md §10's ban on scroll-triggered reveal
animations was treated as non-negotiable per its own stated authority.
Validation: `pnpm --filter recall-web lint/typecheck/test/build` and
root `pnpm lint/typecheck/test/build` all green (16/16 workspace
tasks). Playwright's browser bridge was unresponsive for this entire
session (same issue as the prior turn) — correctness was verified via
the live dev server's rendered HTML instead (confirmed zero remaining
occurrences of "How it works", the new `<dl>` markup with all six
features present, and MemoryFlow's exact output). A live visual pass
is still recommended once the bridge reconnects.
…on color buttonVariants carried focus-visible:outline-none with no replacement ring. Because Tailwind v4 compiles utilities into a layer declared after base, that class silently beat the global :focus-visible rule in globals.css, leaving the Hero's primary and secondary CTAs with no visible focus indicator on keyboard navigation — a violation of design-system.md §13. Removing the redundant override lets the existing global ring apply. Also adds the ::selection styling design-system.md §3 specifies but globals.css never implemented (accent at low opacity).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR continues the Recall homepage refinement work after the initial web foundation was merged.
It adds the Problem and Workflow sections, removes duplicated narrative/UI patterns, replaces the generic feature-card grid with a typography-first presentation, simplifies workflow visualization, and fixes two concrete accessibility/design-system issues: the missing visible keyboard focus ring on buttons and the missing text-selection styling.
The objective is to make the homepage feel more like a deliberate engineering product and less like a generic SaaS landing page, without adding new product features or changing Recall CLI behavior.
Related issue
None.
Test plan
pnpm lintpnpm typecheckpnpm testpnpm buildChecklist
{ path, reason }) — not applicable to this web-only PR.recall/,.gitignore, or an explicit output path are written — no Recall CLI write behavior changedpnpm changeset) — not required; this PR only changes the website and does not publishrecall-context