docs: redraw the architecture overview as a themed SVG component - #1181
Open
teallarson wants to merge 4 commits into
Open
docs: redraw the architecture overview as a themed SVG component#1181teallarson wants to merge 4 commits into
teallarson wants to merge 4 commits into
Conversation
The About Arcade diagram was a pair of 3112x1741 PNGs, one per theme. It blurred at zoom, its labels were invisible to search and translation, and editing it meant round-tripping through whatever tool drew it. Replace both with one hand-placed SVG component. It follows the active theme from design-system tokens instead of shipping a second asset, scales cleanly, and keeps every label as selectable text with a screen-reader description. Labels move to sentence case per STYLEGUIDE.md, and "IDPs, & Entitlement Servers" loses its stray comma. The topology, the arrow directions, and the box set are unchanged. Mermaid was tried first and rejected: dagre put Local to the right of Platform, floated the governance boxes into dead space, and its light theme renders yellow and lavender with no way to brand it that survives a theme switch. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
teallarson
marked this pull request as ready for review
September 4, 2026 19:51
Give the About Arcade diagram a collapsible prose summary so agents and markdown export get explicit topology without relying on SVG geometry. Co-authored-by: Cursor <cursoragent@cursor.com>
Drop the decorative underline and render Local and Platform in brand-accent semibold instead. Co-authored-by: Cursor <cursoragent@cursor.com>
Use semibold foreground with letter-spacing so Local and Platform read as section headers without competing with MCP and consumer accent elements. Co-authored-by: Cursor <cursoragent@cursor.com>
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.
Diagram in the preview env: https://docs-git-teallarson-nicer-diagram-arcade-ai.vercel.app/en/get-started/about-arcade#how-arcade-solves-this
What
BEFORE:
AFTER:
The architecture diagram on About Arcade was a pair of 3112×1741 PNGs, one per theme. Replaced with a single hand-placed SVG component.
Why
The PNGs blurred at zoom, their labels were invisible to search and translation, and editing them meant round-tripping through whatever tool drew them — plus keeping two files in sync.
The component follows the active theme from design-system tokens (
--brand-accent,--card,--border,--muted-foreground) instead of shipping a second asset, scales cleanly to any width, and keeps every label as selectable text with a<desc>summary for screen readers. On narrow screens the figure scrolls horizontally rather than shrinking the type into illegibility.What changed in the diagram itself
Nothing structural. Same boxes, same topology, same arrow directions (including the bidirectional links the original used).
Labels moved to sentence case per
STYLEGUIDE.md, andIDPs, & Entitlement Serverslost its stray comma:On mermaid
Tried it first, since Nextra already ships
@theguild/remark-mermaidand the glossary uses it. Rejected after two tuning passes: dagre placed Local to the right of Platform, floated the governance boxes into a dead column, and clipped the bottom arrows through the container border. Its light theme renders yellow and lavender, and the only fix — an%%{init}%%theme block — pins one theme and breaks the other, since Nextra picksdark/defaultat render time.Mermaid is right for the glossary's three-node graphs. Here the layout is the information.
Checks
pnpm build— compiled successfullypnpm lint/tsc --noEmit— cleanpnpm test— 873 passed, 2 skipped🤖 Generated with Claude Code
Note
Low Risk
Docs-only UI change on a single page; no runtime, auth, or API behavior is affected.
Overview
About Arcade no longer uses separate light/dark PNG architecture images. The page now renders a new
ArchitectureDiagramReact component: a hand-placed SVG that uses theme tokens, stays sharp at zoom, and exposes selectable labels plus SVGtitle/descfor accessibility.The figure keeps the same Local vs Platform topology and connector semantics as before. Copy on the diagram shifts to sentence case and fixes a few labels (e.g. IdPs wording). A collapsible Architecture summary under the figure mirrors the diagram in prose and links operators to
/operate/deploy/architecture.On narrow viewports the diagram scrolls horizontally (
min-w-[720px]) instead of shrinking text.Reviewed by Cursor Bugbot for commit d924567. Bugbot is set up for automated code reviews on this repo. Configure here.