[chasegrayoffice]

Design pass on the developer site (tempo.xyz/developers) from Chase's 10.09 notes. One commit per change ID; this body maps ID → commit.

Summary

• System (G1–G12):
  • Ports TDS Platform tokens (from tempoxyz/ds@3fd4cf7, by hand, no new dependency).
  • Adds tempo.xyz smooth corners, chevron and color links, animated heading anchors and copy feedback, gray secondary buttons, spacing instead of section rules, full-width tables, TDS Callout/Alert callouts, and docs-local SegmentedControl, Tabs, Badge (outline) and IconButton.
• Home: one product grid with outline badges, chevron titles and links, matched two-line descriptions, a full-width setup SegmentedControl, the agent block on the page, Start with a guide as a 3-up, and Tools & references with color links.
• Guides and sidebar: Get Started hero and setup tiles, more space between Steps, the MCP select's spacing, and the sidebar hierarchy, hover and selected state (desktop and the mobile drawer).
• Nav, search, blog: tempo.xyz nav layout with a search icon button; search dialog at content width with no input ring, an animated height and a lighter scrim; blog as the tempo.xyz Use cases grid with TDS Tabs filters, a featured post without a panel, "Announcements", and full author names.
• Several of these reverse style(docs): apply design review feedback to the home and Get Started pages #966. See FL3 below.

Changes

System

1. G1 0bcdc1e7: docs colors, surfaces, lines and status tones resolve to TDS Core via Platform semantics (ds@3fd4cf7); Platform palette tokens (tertiary, container steps, tones, scrim); radius re-pointed to Platform steps + panel; section spacing token (80/64).
2. G2 69fdb851: tempo.xyz SmoothCorners (native corner-shape, SVG clip fallback with inset focus ring, pill exception), scoped to elements that set --corner-radius; repaints on theme change and rediscovers on resize; shadowed surfaces skip the clip.
3. G3 7728c022: content, zoomable, blog and diagram images get a radius sized to the image.
4. G4 77f67cfc: fill differs from page → no border (code blocks, prompts, inline code, zoom frames, demo panels in dark, MCP explorer output, API overview pane).
5. G5 99bc6c1a, e5f930cc: L1 chevron links (ChevronLink, CSS variant on Vocs cards), L2 color links, shared motion tokens; Agent setup panel and mobile menu get enter/exit.
6. G6 d5fb8a9c: h2–h6 anchors fade, the whole heading is the hit area, copy swaps to a content-primary check for ~1.2s.
7. G7 38f64902, 7be388ac: one copy feedback (cross-fading icons, "Copied", content-primary check) for page actions, home terminal, Agent setup, Vocs code/shell/Copy page for AI, OpenAPI Copy and demo copies.
8. G8 a762b1da, e42765af, 814addc4: secondary buttons = TDS gray fill, no outline (incl. Vocs OpenAPI actions, the MCP Reset and the 404 link); primary stays inverted (incl. MCP Run); smoothed md radius on buttons, lg on header controls.
9. G9 b5ad9328, 2a6394ec: section rules → section spacing on every docs page (incl. API reference), more space above the footer, pager opacity hover; one section token on Home.
10. G10 e0f540ce: tables span exactly the content width and scroll inside their wrapper.
11. G11 d7d62feb: TDS Callout (note/info) and Alert tones (tip/warning/danger/success) for every callout.
12. G12 25133835: docs-local SegmentedControl, Tabs, Badge (outline) and IconButton with DS keyboard behavior.

Home
13. H1 b2734535: one six-tile grid, tier labels removed, outline badges (Primitives ×2, Agents).
14. H2: no change needed (tiles had no hover fill or lift).
15. H3 04327fb9: tile titles are chevron links; their heading anchors are removed.
16. H4 42325f03: sub-links are chevron links, no underline.
17. H5 a661dd2a: six matched descriptions, two lines at 1440 and 1280 (FL4).
18. H6 1f86b874: setup subtitles removed.
19. H7 771463f3: full-width SegmentedControl; scrolls sideways at 390, never wraps.
20. H8 f45bc668: agent block on the page; terminal on the gray panel surface.
21. H9 fdb87d88: Start with a guide as its own 3-up with hairline rules and gray guide buttons.
22. H10 41b39a3d: ampersands, APIs & SDKs as a label, "All APIs & SDKs" link; old anchors kept.
23. H11 1466383d: reference lists use L2 color links.
24. H12: Tools & references anchor follows G6 (verified, no code).
25. d710f818: 24px hit areas for Home's standalone links (QA bar).

Get Started, Quickstart, Build with AI
26. GS1 3beb15f0: lede 400px, content primary, tighter hero spacing.
27. GS2–GS5, GS7: covered by G8, G5, G9 and G6 (verified).
28. GS6 30b46f9f: setup tiles outlined (page fill + hairline), card radius, small gray link buttons that wrap.
29. QS1, QS3, QS4: covered by G8, G7 and G9 (verified).
30. QS2 1a3c4dc7: later Steps start 48px below the previous one (shared Steps styling).
31. AI1 ef0066d5: MCP tool select uses TDS NativeSelect spacing (style-only, #960).
32. AI2: covered by G10 (verified).

Sidebar
33. SB1 f38ebde8: the current page has no hover change.
34. SB2 b3a9c833, 014d21d1: single-section title in secondary ("On this page" style); group labels in secondary (tertiary failed WCAG AA, so Chase chose secondary); entries and collapsible groups primary.
35. SB3 01ad34d3: hover one radius step rounder, smoothed, with enter/exit motion.
36. 54431fa7: SB1–SB3 in the mobile sidebar drawer.

Nav, search, blog
37. N1 e8f5ee6c: tempo.xyz nav layout (logo, Docs/Blog centered, Agent setup + search IconButton); inline search field removed; ⌘K kept on docs and blog.
38. S1 2cf91cad: no focus ring on the open search input.
39. S2 40030b95: dialog at the docs content width, smoothed panel radius; dark dialog on neutral 088.
40. S3 c36b6921: dialog height animates to its results (instant under reduced motion).
41. S4 a1748773: lighter TDS scrim (strong in dark), no blur.
42. BL1 288163c1: "Announcements" label; slug unchanged.
43. BL2 ad32d77b: full names with commas (FL4).
44. BL3 224e1872: article list as the tempo.xyz Use cases grid (3/2/1), chevron titles, smoothed images.
45. BL4 fdb6eb0c: filters as TDS Tabs.
46. BL5 88e63366: featured post without a panel, hairline rule, larger headline.
47. BL6: no change needed (spot-checked).

Follow-ups from Chase's review (10.09 evening)
49. GS6 f2a6b802: every setup link button (DocsLinkCards) ends in a chevron that nudges on hover or focus.
50. H8/H9 7ceca514: Build with your agent in an outlined tile like the Accounts setup tiles, with the install link on the Connect Tempo docs row. In Start with a guide, the guide names are column headings, the buttons read "Get started", and Find your starting point sits on the section heading row.
51. G11 c27011da: the alert indicator is a smoothed 8px square centered on the first line; callout text uses the B2 20px line.
52. b9a1ece6: docs and blog article body text uses TDS B1 (16/22, 0.12px tracking).

Test
48. No budget change. The /docs/protocol/transactions HTML budget stays at main's 225 kB; the merged branch builds that page at 220,148 bytes.

Merge with main (10.18)

• Copy controls use the shared CopyButton from fix: preserve copy button widths with a shared component #992, with the G7 cross-fading icon passed in.
• Blog cards and the featured post link through blogPostHref from fix: repair docs asset routes and canonical blog links #1018.
• Home keeps the "Tempo API" label from Clarify Tempo API overview for search #1017.

Flags

FL1 View Markdown 404 (not fixed here)

• Repro: https://tempo.xyz/developers/get-started → Ask AI → View as Markdown. This opens https://tempo.xyz/assets/md/get-started.md, which returns 404. https://tempo.xyz/developers/assets/md/get-started.md returns 200.
• Cause:
  • Vocs AskAi calls window.open('/assets/md/<path>.md'), which is root-relative and drops the /developers mount (I confirmed this with Playwright on production).
  • tempo.xyz doesn't proxy /assets/md/*.
  • The docs' own page tools go through publicAssetPath() and work.
  • fix(docs): preserve developers mount in generated links #967 covers server-generated links, not this client window.open.
• Fix options:
  • a tempo.xyz rewrite /assets/md/:path* → the docs deployment
  • extend patches/vocs@2.8.5.patch (this changes the lockfile hash, so I held it)

FL2 TDS discrepancies

• Button radius. TDS Button/IconButton use full (pill or circle). The notes ask for "a little rounder" with smooth corners, and smoothing skips pills. I used Platform 2xs (8px, docs radius.md) smoothed on buttons, icon buttons and header controls. Switching to pills is one token change.
• Page background. TDS background.primary is #F5F5F5 / #000. Light pages stay white; otherwise every page turns gray. Panels use neutral 004 / 092 so their fills differ from the page in both themes (G4). The dark page moves from #0c0c0c to #000.
• Motion. Platform components have no hover states or transitions. Per the notes, fills and colors fade (200ms enter / 150ms exit, tempo.xyz easing).
• Callout/Alert type. TDS Alert is 12px. Docs callouts hold prose, so both stay at 14/20.
• SegmentedControl.
  • TDS fixes three items at 354px. The home chooser has five, spans the full width and scrolls sideways at 390.
  • In dark mode the TDS selected fill (#141414) is darker than the track (white 12%), which reads as inverted. I kept the TDS pair.
• Scrim. TDS scrim.regular (16% black in both themes) barely shows on the black dark page. scrim.strong (32%) is the TDS option if needed.
• Unchanged colors. Prose body color keeps today's 70% foreground rather than Platform content.secondary (56%).
• Radius scale. Re-pointed to Platform steps: md 6→8, lg 8→12, xl 12→16, plus panel 24. Demo surfaces that use these are slightly rounder.

FL3 #966 reversals (cc @snario, Tanishq)

• (1, 8) Contrast-panel hairlines. Already removed upstream in fix(docs): mobile sweep, broken partner logos, and panel borders #968. Panels stay borderless where their fill differs from the page. GS6 gives Set up your project tiles the outline (page fill + hairline), per G4.
• (4) Outlined secondary page actions become the TDS gray fill (G8).
• (2) Guide-row arrow nudge is replaced by the H9 3-up with gray buttons.
• (9) Home tier labels are removed. The labels move into the tiles as outline badges (H1).

FL4 Copy changes

• H5 tile descriptions (each is two lines at 1440 and 1280, measured):

Tile	Old	New
Earn	Build earning balances with stablecoin vaults.	Let customers deposit into stablecoin vaults, track earnings, and withdraw.
Routes	Move stablecoins between Tempo and other networks.	Move stablecoins between Tempo and other networks, and accept deposits.
Zones	Keep stablecoin balances in a private ledger.	Keep stablecoin balances and transactions private inside a Tempo Zone.
Accounts	Create accounts, send payments, and control who can use them.	Create accounts, send and receive payments, and control who can use them.
Tempo EVM	Build wallets, issue stablecoins, and deploy Solidity contracts.	Build wallets, issue stablecoins, and deploy Solidity contracts on Tempo.
Machine Payments	Pay for APIs and accept payments from software and agents.	Pay for APIs from code or the CLI, and accept payments from agents.

• H10: "Tools & references", "Protocol & infrastructure" and "APIs & partners", plus a new "All APIs & SDKs" link. The old anchor ids are kept.
• H9: all three guide buttons read "Get started"; the guide names move into column headings. Each button's accessible name still carries the guide, e.g. "Get started: Send your first payment".
• BL1: "Product announcements" → "Announcements"; the post tag reads "Announcement". The slug is unchanged.
• BL2 names:
  • "Liam & Varun" → "Liam Horne, Varun". Liam Horne is the only Liam in git history, and he published the Zones guides the same day.
  • Varun's last name isn't in any repo source and is left as is. Please supply it.
  • "Parv Ahuja / Brendan Ryan" → "Parv Ahuja, Brendan Ryan".
• Partners sidebar: "ECOSYSTEM" / "INFRA" → "Ecosystem" / "Infrastructure". Sidebar labels no longer render in uppercase.

FL5 Assumptions

• H6: Codex and Claude Code keep their install link; the other agents keep their instruction line. The Markdown export still includes the agent sentence.
• H7: at 390 the five items (456px) don't fit, so the control scrolls sideways. It never wraps, and the selected item scrolls into view.
• H9: "All setup options" and "Find your starting point" are both L1 chevron links. All Home section headings now share one style.
• H10: the three group labels keep their heading anchors; only the tile titles lose theirs.
• SB2:
  • The first top-level sidebar header is the title, in secondary color. Later and nested headers are group labels in tertiary.
  • On the Accounts sidebar, "Accounts" is the first header, so it renders as the title.
  • Tertiary failed WCAG AA at sidebar size (2.85:1 light, 3.66:1 dark), so group labels use secondary (4.95:1 / 6.49:1), per Chase.
• GS1: scoped to Get Started.
• GS6: DocsLinkCards is shared, so the outline tiles and small buttons also apply on Tools, Network, Development, Accounts and Getting funds.
• QS2: steps 2+ start 48px below the previous step. The first step keeps 24px.
• G11: note/info → Callout; tip → Alert tip (blue); warning, danger and success → Alert tones.
• S2: "standard max width" = the docs article max width (84ch + content padding = 986px).
• S3: the height animation needs a small client component (SearchDialogMotion) that binds a measured CSS variable. CSS can't animate a content-driven height.
• One search implementation: blog search opens the same Vocs dialog. marketing/_components/SearchDialog is only used by marketing pages, which are out of scope.
• BL3: images sit above the copy (no card fill to bottom-align the art); thumbnails use object-fit: cover. Columns: 3 at ≥1024, 2 at 640–1023, 1 below.
• BL4: the tabs are TDS small (32px). They wrap to two rows at 390. The mobile hit-area assertion is now ≥32px.
• BL5: "one type step larger" = 32 → 40px on desktop, 26 → 28px on mobile.
• Terminal demos keep their own terminal theming (they count as runnable examples).
• Unchanged. Vocs-owned controls keep their markup; the edits there are style-only.

Suggestions (not implemented), GS8

1. One name for the page: "Get Started" in the tab, "Start building" in the sidebar, "Build on Tempo" as the H1 and "Get Started with Tempo" as the SEO title. Use "Get started" for all.
2. Make the quickstart the primary action, with a "Send a test payment" button (and "Get testnet funds") instead of a prose line under three page-action buttons.
3. Add a Zones tile to Choose what to build, with an outline "Limited preview" badge.
4. Move the floating Ask AI input. At 1440 it overlaps the Charge for APIs tile by about 22px.
5. Strip the 15 empty legacy <span id> anchors from the Markdown export (Copy for agent and View Markdown).

Validation

• Local gate after the main merge: check:types, Biome on the 58 touched files, vitest 1222/1222, build, check:markdown and check:anchors (467 links) pass.
• Local gate (10.13 head): check:types, check:styles (in build), oxlint, biome on the 58 touched TS/JSON files, check:markdown, check:anchors (444 links) and build:site all pass. vitest: 1181/1181.
• Targeted e2e against the production build: 153 passed, 18 skipped, 0 failed. Suites: developers-homepage, docs-workspace, blog, sidebar-scroll, zyzz-styles, document-semantics, outline-anchors, openapi-layout, seo-head, production-mount, inline-api-guides. Updated tests: badge radius (6→8px), the home 3-up layout, chooser radios, blog tab hit area.
• Screenshots: 13 pages × 1440/1024/768/390 × light/dark, plus search empty and with results. Pages: Home, Get Started, Quickstart, Build with AI, Stablecoins, Use cases, Earn, Accounts, protocol RPC, API reference, Blog, a blog article, 404.
• Interactions checked:
  • L1/L2 hover and focus-visible, with no layout shift
  • G6 anchor fade, heading hit area and the 1.2s check
  • G7 copy swaps
  • SegmentedControl and Tabs keyboard behavior
  • ⌘K on docs and blog
  • search grow and shrink
  • Agent setup panel and mobile menu enter/exit
  • reduced motion
  • WebKit SVG fallback, including theme repaint and outline badges
• Adversarial review pass: 1 blocker and 6 majors found and fixed: OpenAPI controls covered by the anchor hit area, dark search edge, WebKit theme repaint, WebKit badge corners, sidebar contrast and hierarchy, dark demo borders. Minors fixed or listed in Flags.
• Vercel preview: https://tempo-docs-git-chase-site-31-developers-design-tempoxyz.vercel.app (Vercel SSO). I checked the 13-page list at 1440 light and 390 dark: all 200, the 404 returns 404, no page errors.

Tracking

• Linear: https://linear.app/tempoxyz/issue/SITE-31/developers-design-pass-home-get-started-guides-nav-search-blog
• Builds on feat: use Tempo JetBrains Mono for docs code #952 (Tempo JetBrains Mono, merged) and rebases cleanly on fix(docs): mobile sweep, broken partner logos, and panel borders #968 and Add the Routes API demo and supported routes table #965.

🤖 Generated with Claude Code

[claude]

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

Beyond the inline findings, I checked two other spots. The markdown-output.ts change is safe: no MDX page under src/pages still uses the removed bold-title-plus-span guide-card pattern, and all three HomeGuideButton uses in index.mdx pass a guide label, so the missing-label throw can't fire. The comma split for author bylines in seo.ts matches the two bylines that were rewritten.

Extended reasoning...

Inline findings were already posted for this large styling refresh. This note covers only the logic changes outside them (Markdown link rendering and JSON-LD author splitting), which I checked and found unaffected.

[claude]

🟡 (optional) Firefox and Safari users on docs pages with long sidebars may see jank on load and on every window-resize frame. This cost does not exist on the base branch. update() removes data-smooth-corners and then reads getComputedStyle(element).width, so each smoothed element forces its own style and layout pass. flush() runs that once per pending element. Fix: in flush(), first strip the attribute from every pending element, then read all metrics, then write all results, so a frame costs one forced recalc instead of N. Resizing re-queues every known element via discover(document.body).

Why this was flagged

SmoothCorners is mounted in DocsHeader (src/components/DocsHeader.tsx:851) on every docs and blog page, so a sidebar with tens to hundreds of links is tracked. In update() (src/components/SmoothCorners.tsx:20-40) each element has its attribute removed (a write), then has getComputedStyle and its used width/height read (a read that forces style and layout). In the SVG path that browsers without corner-shape take (Firefox, Safari), dropping the attribute also flips position back from relative to static via [data-smooth-corners="svg"][data-smooth-static]. That dirties layout, so the next read forces a reflow. flush() (line 97) calls update() in a loop over pending, which gives N forced reflows per frame. The rAF-throttled resize handler (line 147) calls discover(document.body) again, and that re-queues every known element (line 119), so each resize frame repeats the whole thrash. The base branch has no such runtime. No batching or other safeguard prevents it.

Verification: flush() (SmoothCorners.tsx:97) calls update(element) per pending element, which writes (line 20), reads layout (lines 21, 41-42), then writes again (lines 71, 76-92). In src/styles/smoothCorners.ts:27-29 the SVG attribute sets position: relative, so each element dirties layout. This is new in this diff.

[chasegrayoffice]

Leaving this for a follow-up so this PR stays a style pass: batching the reads and writes in flush() changes the clip timing, which needs its own WebKit and Firefox check.

[claude]

I reviewed the latest push and found no new bugs. This is still a large restyle across the docs site and blog, so a human look would still be worthwhile.

What was reviewed:

• Commit 98c7382. The global docs focus ring now skips only elements marked data-tds-control, which only SegmentedControl.tsx and Tabs.tsx set, so Vocs role="tab" buttons get the ring again.
• The 24px hit-area rule now sits in tempoDocsHome, the wrapper that contains the guide, product, reference and agent-block links.
• The SmoothCorners.tsx flush() loop hasn't changed since the earlier inline comment.

Extended reasoning...

The PR touches 61 files (+2783/-1003): design tokens, global styles, new UI components (SmoothCorners, Tabs, SegmentedControl, copy feedback), the docs home and blog layouts, the Markdown output renderer and e2e tests. It touches no auth, crypto or data-exposure code. The newest commit changes four files to address two of the three earlier inline comments. I deferred because the change is very large and full of design decisions that a human should weigh.

Still open from earlier reviews (1):

• Unresolved: 1 minor or pre-existing.