refactor(website): even columns, symmetric margins, and centred arrows in the architecture diagram

Measured the geometry and fixed what it found: the adapters-to-agents
gap was 48 against 64 elsewhere, the drawing sat 24px off centre (64
left, 40 right), the users arrow was 28px above the two card centres it
joins, the LangSmith rows started 12px above the LangGraph rows beside
them, and the People card's content floated at the top of a 392px card.

Columns are now 64 apart with 48px margins on all four sides, every
arrow is 64 long and lands on the centre of the card it enters, the
paired cards share their row positions, and the People block is centred
where its arrow leaves. The spec asserts each of those, so they cannot
drift back.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: blove

apps/website/src/components/landing/EnterpriseArchitecture.tsx

@@ -287,7 +287,7 @@ function CardView({ card }: { card: Card }) {
         <Icon
           name={card.icon.name}
           x={card.x + CARD_PAD}
-          y={card.y + 32}
+          y={card.y + 32 + (card.contentDy ?? 0)}
           size={44}
           bg={card.icon.bg}
           fg={card.icon.fg}
@@ -315,7 +315,11 @@ function CardView({ card }: { card: Card }) {
           </text>
         </a>
       ) : card.icon ? (
-        <text className="arch-title" x={card.x + CARD_PAD} y={card.y + 116}>
+        <text
+          className="arch-title"
+          x={card.x + CARD_PAD}
+          y={card.y + 116 + (card.contentDy ?? 0)}
+        >
           {card.title}
         </text>
       ) : (

apps/website/src/lib/architecture-diagram.spec.ts

@@ -3,6 +3,7 @@ import { resolve } from 'node:path';
 import { describe, expect, it } from 'vitest';
 import {
   ARROWS,
+  STRIP_CHIP_H,
   CARDS,
   CARD_GAP,
   CARD_PAD,
@@ -74,19 +75,60 @@ describe('architecture diagram geometry', () => {
     expect(card('ag-ui-servers').y).toBe(bottom.y);
   });
 
-  it('draws every arrow from one card edge to the next card edge, on a grid row', () => {
+  it('lands every arrow on the vertical centre of the card it enters, at one length', () => {
+    const lengths = new Set<number>();
     for (const a of ARROWS) {
-      expect(onGrid(a.y), `arrow y ${a.y}`).toBe(true);
       const from = CARDS.find(
         (c) => c.x + c.width === a.x1 && a.y > c.y && a.y < c.y + c.height
       );
-      const to = CARDS.find(
-        (c) => c.x === a.x2 && a.y > c.y && a.y < c.y + c.height
-      );
+      const to = CARDS.find((c) => c.x === a.x2);
       expect(from, `arrow at ${a.x1} leaves a card`).toBeDefined();
       expect(to, `arrow at ${a.x2} enters a card`).toBeDefined();
-      expect(a.y).toBeGreaterThan(from!.y);
-      expect(a.y).toBeLessThan(from!.y + from!.height);
+      const enters = CARDS.filter(
+        (c) => c.x === a.x2 && a.y > c.y && a.y < c.y + c.height
+      )[0];
+      expect(a.y, `arrow into ${enters?.id}`).toBe(
+        enters!.y + enters!.height / 2
+      );
+      lengths.add(a.x2 - a.x1);
+    }
+    expect([...lengths], 'every arrow is the same length').toHaveLength(1);
+  });
+
+  it('spaces the columns evenly and centres the drawing in the view', () => {
+    const xs = [...new Set(CARDS.map((c) => c.x))].sort((a, b) => a - b);
+    const gaps = xs.slice(1).map((x, i) => {
+      const right = Math.max(
+        ...CARDS.filter((c) => c.x === xs[i]).map((c) => c.x + c.width)
+      );
+      return x - right;
+    });
+    expect([...new Set(gaps)], `column gaps ${gaps}`).toHaveLength(1);
+    expect(onGrid(gaps[0])).toBe(true);
+    const left = xs[0];
+    const right = VIEW.width - Math.max(...CARDS.map((c) => c.x + c.width));
+    expect(right, 'left and right margins match').toBe(left);
+    expect(
+      VIEW.height - (MODEL_STRIP.chipY + STRIP_CHIP_H),
+      'bottom margin matches the sides'
+    ).toBe(left);
+    expect(MODEL_STRIP.x, 'the strip starts at the first column').toBe(left);
+  });
+
+  it('aligns the rows of side-by-side cards', () => {
+    const firstItemY = (id: string) => {
+      const r = card(id).rows.find((row) => row.kind === 'items');
+      return r && r.kind === 'items' ? r.y : null;
+    };
+    expect(firstItemY('langsmith')).toBe(firstItemY('langgraph-sdk'));
+    expect(firstItemY('ag-ui-servers')).toBe(firstItemY('ag-ui'));
+    // Both rows of the stack share their tops and bottoms across the columns.
+    for (const [a, b] of [
+      ['langgraph-sdk', 'langsmith'],
+      ['ag-ui', 'ag-ui-servers'],
+    ] as const) {
+      expect(card(b).y).toBe(card(a).y);
+      expect(card(b).height).toBe(card(a).height);
     }
   });
 

apps/website/src/lib/architecture-diagram.ts

@@ -14,7 +14,7 @@
  * of a role, never as integrations the library claims.
  */
 
-export const VIEW = { width: 1280, height: 624 } as const;
+export const VIEW = { width: 1280, height: 640 } as const;
 export const GRID = 8;
 export const MAJOR = 40;
 export const CARD_GAP = 40;
@@ -122,6 +122,8 @@ export interface Card {
     readonly bg: string;
     readonly fg: string;
   };
+  /** Pushes an icon card's icon and title down, to centre a short card's content. */
+  readonly contentDy?: number;
   /** Right-aligned tag on the card's first line. */
   readonly tag?: string;
   readonly highlight?: boolean;
@@ -145,30 +147,33 @@ export interface StripChip {
 }
 
 export const COLUMNS: readonly ColumnLabel[] = [
-  { x: 64, label: 'YOUR USERS' },
-  { x: 304, label: 'YOUR ANGULAR APPLICATION' },
-  { x: 776, label: 'ADAPTERS' },
-  { x: 1024, label: 'YOUR AGENTS' },
+  { x: 48, label: 'YOUR USERS' },
+  { x: 288, label: 'YOUR ANGULAR APPLICATION' },
+  { x: 744, label: 'ADAPTERS' },
+  { x: 1008, label: 'YOUR AGENTS' },
 ];
 export const COLUMN_LABEL_Y = 72;
 
 export const CARDS: readonly Card[] = [
   {
     id: 'users',
-    x: 64,
+    x: 48,
     y: 104,
     width: 176,
     height: 392,
     title: 'People',
     href: '/docs/chat/getting-started/introduction',
     icon: { name: 'users', bg: '#fff3e0', fg: '#c2410c' },
-    rows: [{ kind: 'text', y: 248, text: 'web · mobile' }],
+    // The column's single node: its block is centred on the card, where its
+    // outgoing arrow leaves.
+    contentDy: 104,
+    rows: [{ kind: 'text', y: 352, text: 'web · mobile' }],
   },
   {
     id: 'threadplane',
-    x: 304,
+    x: 288,
     y: 104,
-    width: 408,
+    width: 392,
     height: 392,
     title: 'Threadplane',
     href: '/docs/chat/getting-started/introduction',
@@ -202,8 +207,8 @@ export const CARDS: readonly Card[] = [
           },
         ],
       },
-      { kind: 'badge', x: 540, y: 224, mark: 'google', label: 'A2UI' },
-      { kind: 'badge', x: 540, y: 272, mark: 'vercel', label: 'json-render' },
+      { kind: 'badge', x: 524, y: 224, mark: 'google', label: 'A2UI' },
+      { kind: 'badge', x: 524, y: 272, mark: 'vercel', label: 'json-render' },
       {
         kind: 'mono',
         y: 470,
@@ -213,7 +218,7 @@ export const CARDS: readonly Card[] = [
   },
   {
     id: 'langgraph-sdk',
-    x: 776,
+    x: 744,
     y: 104,
     width: 200,
     height: 208,
@@ -238,7 +243,7 @@ export const CARDS: readonly Card[] = [
   },
   {
     id: 'ag-ui',
-    x: 776,
+    x: 744,
     y: 352,
     width: 200,
     height: 144,
@@ -247,39 +252,39 @@ export const CARDS: readonly Card[] = [
     href: '/docs/ag-ui/getting-started/introduction',
     mark: 'agui',
     rows: [
-      { kind: 'items', y: 460, step: 32, items: ['events · tools · state'] },
+      { kind: 'items', y: 468, step: 32, items: ['events · tools · state'] },
     ],
   },
   {
     id: 'langsmith',
-    x: 1024,
+    x: 1008,
     y: 104,
-    width: 216,
+    width: 224,
     height: 208,
     title: 'LangSmith',
     href: '/docs/langgraph/guides/deployment',
     mark: 'langchain',
     rows: [
       {
         kind: 'items',
-        y: 200,
+        y: 212,
         step: 32,
         items: ['deploy · observe', 'traces · evals', 'or self-hosted'],
       },
     ],
   },
   {
     id: 'ag-ui-servers',
-    x: 1024,
+    x: 1008,
     y: 352,
-    width: 216,
+    width: 224,
     height: 144,
     title: 'AG-UI servers',
     href: '/docs/runtimes/getting-started/introduction',
     rows: [
       {
         kind: 'marks',
-        y: 400,
+        y: 408,
         marks: ['crewai', 'mastra', 'microsoft', 'bedrock', 'pydantic'],
         size: 30,
         step: 34,
@@ -294,25 +299,26 @@ export const CARDS: readonly Card[] = [
   },
 ];
 
+/** Each arrow lands on the vertical centre of the card it enters. */
 export const ARROWS: readonly Arrow[] = [
-  { x1: 240, x2: 304, y: 272 },
-  { x1: 712, x2: 776, y: 208 },
-  { x1: 712, x2: 776, y: 424 },
-  { x1: 976, x2: 1024, y: 208 },
-  { x1: 976, x2: 1024, y: 424 },
+  { x1: 224, x2: 288, y: 300 },
+  { x1: 680, x2: 744, y: 208 },
+  { x1: 680, x2: 744, y: 424 },
+  { x1: 944, x2: 1008, y: 208 },
+  { x1: 944, x2: 1008, y: 424 },
 ];
 /** The two-line caption between the adapter arrows. */
 export const CONTRACT_CAPTION = {
-  x: 744,
+  x: 712,
   y: 306,
   lines: ['one Agent', 'contract'],
 } as const;
 
 export const MODEL_STRIP = {
   label: 'ANY MODEL',
-  labelY: 540,
+  labelY: 524,
   chipY: 556,
-  x: 64,
+  x: 48,
   chips: [
     { mark: 'openai', label: 'OpenAI' },
     { mark: 'anthropic', label: 'Anthropic' },