Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

docs: Add design-system component relationship chart (#17608)

Ben Bachem2dff8645594d
diff --git a/knip.jsonc b/knip.jsonc
index d7624fcd05..96f3722edc 100644
--- a/knip.jsonc
+++ b/knip.jsonc
@@ -39,13 +39,15 @@
],
},
"web": {
+ // Components imported by MDX documentation, which Knip does not trace.
+ "entry": [".storybook/docs/**/*.tsx"],
"ignoreFiles": [
// Standalone benchmark invoked directly with Node rather than imported by the application.
"src/features/traces/components/AdvancedJsonViewer/lazy/benchByteJsonIndex.ts",
"src/__tests__/mocks/**",
],
// Include runtime JavaScript modules such as src/env.mjs in dependency analysis.
- "project": ["src/**/*.{ts,tsx,mjs}"],
+ "project": ["src/**/*.{ts,tsx,mjs}", ".storybook/docs/*.{ts,tsx}"],
"ignoreDependencies": [
// Tailwind loads this plugin from an @plugin directive in globals.css.
"@tailwindcss/forms",
diff --git a/web/.storybook/docs.css b/web/.storybook/docs.css
index 3d5ec9caa6..ba62f921f0 100644
--- a/web/.storybook/docs.css
+++ b/web/.storybook/docs.css
@@ -36,6 +36,45 @@
overflow-wrap: break-word;
}
+.sbdocs.sbdocs-content:has(.component-relationship-graph) {
+ display: flex;
+ height: 100vh;
+ max-width: none;
+ flex-direction: column;
+ overflow: hidden;
+ padding: var(--docs-space-6);
+}
+
+.component-relationship-node--component {
+ fill: hsl(var(--chart-1) / 0.16);
+ stroke: hsl(var(--chart-1));
+}
+
+.component-relationship-node--function {
+ fill: hsl(var(--chart-2) / 0.16);
+ stroke: hsl(var(--chart-2));
+}
+
+.component-relationship-node--internal {
+ fill: hsl(var(--chart-4) / 0.16);
+ stroke: hsl(var(--chart-4));
+}
+
+.component-relationship-key--component {
+ background: hsl(var(--chart-1) / 0.16);
+ border-color: hsl(var(--chart-1));
+}
+
+.component-relationship-key--function {
+ background: hsl(var(--chart-2) / 0.16);
+ border-color: hsl(var(--chart-2));
+}
+
+.component-relationship-key--internal {
+ background: hsl(var(--chart-4) / 0.16);
+ border-color: hsl(var(--chart-4));
+}
+
.sbdocs.sbdocs-content .docblock-source {
max-width: 52rem;
margin-top: 0;
diff --git a/web/.storybook/docs/ComponentRelationshipGraph.tsx b/web/.storybook/docs/ComponentRelationshipGraph.tsx
new file mode 100644
index 0000000000..39ec4b9fcd
--- /dev/null
+++ b/web/.storybook/docs/ComponentRelationshipGraph.tsx
@@ -0,0 +1,329 @@
+import { select } from "d3-selection";
+import { zoom, zoomIdentity } from "d3-zoom";
+import type { ElkNode } from "elkjs";
+import ELK from "elkjs/lib/elk.bundled.js";
+import { useEffect, useMemo, useRef, useState } from "react";
+
+import { Button } from "@/src/components/design-system/Button/Button";
+
+import { buildComponentRelationshipGraph } from "./componentRelationshipData";
+
+const sourceModules = import.meta.glob(
+ "../../src/components/design-system/**/*.{ts,tsx}",
+ {
+ query: "?raw",
+ import: "default",
+ eager: true,
+ },
+) as Record<string, string>;
+
+const NODE_WIDTH = 190;
+const NODE_HEIGHT = 42;
+const PADDING = 40;
+
+type Layout = {
+ width: number;
+ height: number;
+ nodes: {
+ id: string;
+ label: string;
+ kind: "component" | "function" | "internal";
+ group: string | null;
+ x: number;
+ y: number;
+ }[];
+ edges: { id: string; path: string }[];
+ groupAreas: {
+ label: string;
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+ }[];
+};
+
+const NODE_CLASSES = {
+ component: "component-relationship-node--component",
+ function: "component-relationship-node--function",
+ internal: "component-relationship-node--internal",
+} as const;
+
+const graph = buildComponentRelationshipGraph(sourceModules);
+
+async function layoutGraph() {
+ const elk = new ELK();
+ const groupedNodes = new Map<string, typeof graph.nodes>();
+ for (const node of graph.nodes) {
+ if (node.group === null) continue;
+ groupedNodes.set(node.group, [
+ ...(groupedNodes.get(node.group) ?? []),
+ node,
+ ]);
+ }
+ const groupedNodeIds = new Set(
+ [...groupedNodes.values()].flat().map((node) => node.id),
+ );
+ const rootNodes = graph.nodes.filter((node) => !groupedNodeIds.has(node.id));
+ const leafNode = (id: string): ElkNode => ({
+ id,
+ width: NODE_WIDTH,
+ height: NODE_HEIGHT,
+ });
+ const elkGraph: ElkNode = {
+ id: "root",
+ layoutOptions: {
+ "elk.algorithm": "layered",
+ "elk.aspectRatio": "0.35",
+ "elk.direction": "RIGHT",
+ "elk.edgeRouting": "ORTHOGONAL",
+ "elk.hierarchyHandling": "INCLUDE_CHILDREN",
+ "elk.layered.spacing.nodeNodeBetweenLayers": "120",
+ "elk.spacing.nodeNode": "32",
+ "elk.spacing.componentComponent": "64",
+ "elk.layered.crossingMinimization.strategy": "LAYER_SWEEP",
+ "elk.layered.nodePlacement.strategy": "BRANDES_KOEPF",
+ "elk.padding": `[top=${PADDING},left=${PADDING},bottom=${PADDING},right=${PADDING}]`,
+ },
+ children: [
+ ...rootNodes.map((node) => leafNode(node.id)),
+ ...[...groupedNodes.entries()].map(([group, nodes]) => ({
+ id: `group:${group}`,
+ layoutOptions: {
+ "elk.algorithm": "layered",
+ "elk.aspectRatio": "0.35",
+ "elk.direction": "RIGHT",
+ "elk.edgeRouting": "ORTHOGONAL",
+ "elk.spacing.nodeNode": "24",
+ "elk.padding": "[top=40,left=24,bottom=24,right=24]",
+ },
+ children: nodes.map((node) => leafNode(node.id)),
+ })),
+ ],
+ edges: graph.edges.map((edge) => ({
+ id: edge.id,
+ sources: [edge.source],
+ targets: [edge.target],
+ })),
+ };
+ const result = await elk.layout(elkGraph);
+ const graphNodes = new Map(graph.nodes.map((node) => [node.id, node]));
+ const nodes: Layout["nodes"] = [];
+ const groupAreas: Layout["groupAreas"] = [];
+
+ for (const node of result.children ?? []) {
+ if (!node.id.startsWith("group:")) {
+ const graphNode = graphNodes.get(node.id);
+ if (!graphNode) continue;
+ nodes.push({
+ ...graphNode,
+ x: node.x ?? 0,
+ y: node.y ?? 0,
+ });
+ continue;
+ }
+
+ const x = node.x ?? 0;
+ const y = node.y ?? 0;
+ groupAreas.push({
+ label: node.id.slice("group:".length),
+ x,
+ y,
+ width: node.width ?? 0,
+ height: node.height ?? 0,
+ });
+ for (const child of node.children ?? []) {
+ const graphNode = graphNodes.get(child.id);
+ if (!graphNode) continue;
+ nodes.push({
+ ...graphNode,
+ x: x + (child.x ?? 0),
+ y: y + (child.y ?? 0),
+ });
+ }
+ }
+
+ const groupOffsets = new Map(
+ (result.children ?? [])
+ .filter((node) => node.id.startsWith("group:"))
+ .map((node) => [node.id, { x: node.x ?? 0, y: node.y ?? 0 }]),
+ );
+ const edges = (result.edges ?? []).flatMap((edge) => {
+ const section = edge.sections?.[0];
+ if (!section) return [];
+ const offset = edge.container
+ ? (groupOffsets.get(edge.container) ?? { x: 0, y: 0 })
+ : { x: 0, y: 0 };
+ const points = [
+ section.startPoint,
+ ...(section.bendPoints ?? []),
+ section.endPoint,
+ ];
+ return [
+ {
+ id: edge.id,
+ path: points
+ .map(
+ (point, index) =>
+ `${index === 0 ? "M" : "L"}${point.x + offset.x},${point.y + offset.y}`,
+ )
+ .join(" "),
+ },
+ ];
+ });
+
+ return {
+ width: result.width ?? 1,
+ height: result.height ?? 1,
+ nodes,
+ edges,
+ groupAreas,
+ } satisfies Layout;
+}
+
+export function ComponentRelationshipGraph() {
+ const [layout, setLayout] = useState<Layout>();
+ const svgRef = useRef<SVGSVGElement>(null);
+ const contentRef = useRef<SVGGElement>(null);
+ const zoomBehavior = useMemo(
+ () =>
+ zoom<SVGSVGElement, unknown>()
+ .scaleExtent([0.25, 8])
+ .on("zoom", (event) => {
+ contentRef.current?.setAttribute("transform", event.transform);
+ }),
+ [],
+ );
+
+ useEffect(() => {
+ let active = true;
+ layoutGraph().then((nextLayout) => {
+ if (active) setLayout(nextLayout);
+ });
+ return () => {
+ active = false;
+ };
+ }, []);
+
+ useEffect(() => {
+ const svg = svgRef.current;
+ if (!svg) return;
+ select(svg).call(zoomBehavior);
+ return () => {
+ select(svg).on(".zoom", null);
+ };
+ }, [layout, zoomBehavior]);
+
+ const resetZoom = () => {
+ if (!svgRef.current) return;
+ select(svgRef.current).call(zoomBehavior.transform, zoomIdentity);
+ };
+
+ return (
+ <div className="component-relationship-graph flex min-h-0 flex-1 flex-col gap-3">
+ <div className="text-muted-foreground flex flex-wrap items-center justify-between gap-2 text-xs">
+ <div className="flex flex-wrap items-center gap-3">
+ <span>
+ {graph.nodes.length} nodes · {graph.edges.length} imports · arrows
+ point toward dependencies
+ </span>
+ <span className="flex items-center gap-1.5">
+ <span className="component-relationship-key--component size-2.5 rounded-sm border" />
+ Component
+ </span>
+ <span className="flex items-center gap-1.5">
+ <span className="component-relationship-key--function size-2.5 rounded-sm border" />
+ Function
+ </span>
+ <span className="flex items-center gap-1.5">
+ <span className="component-relationship-key--internal size-2.5 rounded-sm border" />
+ Internal component
+ </span>
+ </div>
+ <Button text="Reset view" variant="secondary" onClick={resetZoom} />
+ </div>
+ <div className="bg-background min-h-0 flex-1 overflow-hidden rounded-md border">
+ {layout ? (
+ <svg
+ ref={svgRef}
+ className="size-full cursor-grab active:cursor-grabbing"
+ viewBox={`0 0 ${layout.width} ${layout.height}`}
+ aria-label="Design-system component import graph"
+ >
+ <defs>
+ <marker
+ id="dependency-arrow"
+ viewBox="0 0 10 10"
+ refX="9"
+ refY="5"
+ markerWidth="6"
+ markerHeight="6"
+ orient="auto-start-reverse"
+ >
+ <path
+ d="M 0 0 L 10 5 L 0 10 z"
+ className="fill-muted-foreground"
+ />
+ </marker>
+ </defs>
+ <g ref={contentRef}>
+ {layout.groupAreas.map((area) => (
+ <g key={area.label}>
+ <rect
+ x={area.x}
+ y={area.y}
+ width={area.width}
+ height={area.height}
+ rx="8"
+ className="fill-muted/30 stroke-border stroke-dashed"
+ />
+ <text
+ x={area.x + 12}
+ y={area.y + 20}
+ className="fill-muted-foreground text-[10px] font-medium tracking-wide uppercase"
+ >
+ {area.label}
+ </text>
+ </g>
+ ))}
+ {layout.edges.map((edge) => (
+ <path
+ key={edge.id}
+ d={edge.path}
+ fill="none"
+ markerEnd="url(#dependency-arrow)"
+ className="stroke-muted-foreground/50"
+ />
+ ))}
+ {layout.nodes.map((node) => (
+ <g key={node.id} transform={`translate(${node.x} ${node.y})`}>
+ <rect
+ width={NODE_WIDTH}
+ height={NODE_HEIGHT}
+ rx="6"
+ className={NODE_CLASSES[node.kind]}
+ />
+ <text
+ x={NODE_WIDTH / 2}
+ y={NODE_HEIGHT / 2}
+ dominantBaseline="middle"
+ textAnchor="middle"
+ className="fill-foreground text-[11px] font-medium"
+ >
+ {node.label}
+ </text>
+ </g>
+ ))}
+ </g>
+ </svg>
+ ) : (
+ <div className="text-muted-foreground flex size-full items-center justify-center text-sm">
+ Laying out component graph…
+ </div>
+ )}
+ </div>
+ <p className="text-muted-foreground text-xs">
+ Drag to pan and scroll to zoom.
+ </p>
+ </div>
+ );
+}
diff --git a/web/.storybook/docs/ComponentRelationships.mdx b/web/.storybook/docs/ComponentRelationships.mdx
new file mode 100644
index 0000000000..7c15093be8
--- /dev/null
+++ b/web/.storybook/docs/ComponentRelationships.mdx
@@ -0,0 +1,10 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+import { ComponentRelationshipGraph } from "./ComponentRelationshipGraph";
+
+<Meta title="Component Relationships" />
+
+# Component Relationships
+
+This graph shows imports between components in the design system.
+
+<ComponentRelationshipGraph />
diff --git a/web/.storybook/docs/componentRelationshipData.test.ts b/web/.storybook/docs/componentRelationshipData.test.ts
new file mode 100644
index 0000000000..c171c962c9
--- /dev/null
+++ b/web/.storybook/docs/componentRelationshipData.test.ts
@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+
+import { buildComponentRelationshipGraph } from "./componentRelationshipData";
+
+describe("buildComponentRelationshipGraph", () => {
+ it("builds component-level edges from alias and relative imports", () => {
+ const graph = buildComponentRelationshipGraph({
+ "../../src/components/design-system/Button/Button.tsx": "export {}",
+ "../../src/components/design-system/Dialog/Dialog.tsx":
+ 'import { Button } from "@/src/components/design-system/Button/Button";',
+ "../../src/components/design-system/Form/Form.tsx":
+ 'export { Dialog } from "../Dialog/Dialog";',
+ "../../src/components/design-system/Form/Form.stories.tsx":
+ 'import { Checkbox } from "../Checkbox/Checkbox";',
+ });
+
+ expect(graph).toEqual({
+ nodes: [
+ {
+ id: "Button",
+ label: "Button",
+ kind: "component",
+ group: null,
+ },
+ {
+ id: "Dialog",
+ label: "Dialog",
+ kind: "component",
+ group: null,
+ },
+ { id: "Form", label: "Form", kind: "component", group: null },
+ ],
+ edges: [
+ { id: "Dialog->Button", source: "Dialog", target: "Button" },
+ { id: "Form->Dialog", source: "Form", target: "Dialog" },
+ ],
+ });
+ });
+
+ it("keeps nested design-system areas readable", () => {
+ const graph = buildComponentRelationshipGraph({
+ "../../src/components/design-system/table/columns/createTextTableColumn.tsx":
+ 'import { EmptyValue } from "../components/EmptyValue/EmptyValue";',
+ "../../src/components/design-system/table/components/EmptyValue/EmptyValue.tsx":
+ "export {};",
+ "../../src/components/design-system/internal/InputControl/InputControl.tsx":
+ "export {};",
+ });
+
+ expect(graph.nodes.map(({ id }) => id)).toEqual([
+ "Internal / InputControl",
+ "Table / createTextTableColumn",
+ "Table / EmptyValue",
+ ]);
+ expect(graph.nodes.map(({ kind }) => kind)).toEqual([
+ "internal",
+ "function",
+ "component",
+ ]);
+ expect(graph.edges).toEqual([
+ {
+ id: "Table / createTextTableColumn->Table / EmptyValue",
+ source: "Table / createTextTableColumn",
+ target: "Table / EmptyValue",
+ },
+ ]);
+ });
+
+ it("excludes imports that leave the design-system directory", () => {
+ const graph = buildComponentRelationshipGraph({
+ "../../src/components/design-system/Button/Button.tsx":
+ 'import { Dialog } from "../../Dialog/Dialog";',
+ "../../src/components/design-system/Dialog/Dialog.tsx": "export {};",
+ });
+
+ expect(graph.edges).toEqual([]);
+ });
+
+ it("groups new lowercase top-level directories automatically", () => {
+ const graph = buildComponentRelationshipGraph({
+ "../../src/components/design-system/utilities/formatLabel.ts":
+ "export {};",
+ });
+
+ expect(graph.nodes[0]).toMatchObject({
+ id: "Utilities / formatLabel",
+ group: "Utilities",
+ });
+ });
+});
diff --git a/web/.storybook/docs/componentRelationshipData.ts b/web/.storybook/docs/componentRelationshipData.ts
new file mode 100644
index 0000000000..a9b5f3bad3
--- /dev/null
+++ b/web/.storybook/docs/componentRelationshipData.ts
@@ -0,0 +1,147 @@
+export type ComponentRelationshipGraph = {
+ nodes: {
+ id: string;
+ label: string;
+ kind: "component" | "function" | "internal";
+ group: string | null;
+ }[];
+ edges: { id: string; source: string; target: string }[];
+};
+
+const DESIGN_SYSTEM_PATH = "/src/components/design-system/";
+const DESIGN_SYSTEM_ALIAS = "@/src/components/design-system/";
+const SOURCE_FILE_PATTERN = /\.(?:ts|tsx)$/;
+const NON_COMPONENT_FILE_PATTERN =
+ /\.(?:stories|clienttest|servertest|test|spec)\.(?:ts|tsx)$/;
+const STATIC_IMPORT_PATTERN =
+ /(?:import|export)\s+(?:type\s+)?(?:[^;"']*?\s+from\s+)?["']([^"']+)["']/g;
+
+function normalizePath(path: string) {
+ const segments: string[] = [];
+ for (const segment of path.split("/")) {
+ if (segment === "" || segment === ".") continue;
+ if (segment === "..") {
+ segments.pop();
+ continue;
+ }
+ segments.push(segment);
+ }
+ return segments.join("/");
+}
+
+function relativeDesignSystemPath(path: string) {
+ const normalized = `/${normalizePath(path)}`;
+ const markerIndex = normalized.indexOf(DESIGN_SYSTEM_PATH);
+ if (markerIndex === -1) return null;
+ return normalized.slice(markerIndex + DESIGN_SYSTEM_PATH.length);
+}
+
+function componentId(path: string) {
+ const [area, ...segments] = path.split("/");
+ if (!area) return null;
+ if (/^[A-Z]/.test(area)) return area;
+ const group = `${area.charAt(0).toUpperCase()}${area.slice(1)}`;
+ const subject =
+ segments.find((segment) => /^[A-Z]/.test(segment)) ?? segments.at(-1);
+ if (!subject) return group;
+ return `${group} / ${subject.replace(SOURCE_FILE_PATTERN, "")}`;
+}
+
+function nodeGroup(path: string) {
+ const area = path.split("/")[0];
+ if (!area || /^[A-Z]/.test(area)) return null;
+ return `${area.charAt(0).toUpperCase()}${area.slice(1)}`;
+}
+
+function nodeKind(path: string) {
+ if (path.startsWith("internal/")) return "internal" as const;
+ if (path.startsWith("factories/") || path.startsWith("table/columns/")) {
+ return "function" as const;
+ }
+ return "component" as const;
+}
+
+function resolveImport(importer: string, specifier: string) {
+ if (specifier.startsWith(DESIGN_SYSTEM_ALIAS)) {
+ return specifier.slice(DESIGN_SYSTEM_ALIAS.length);
+ }
+ if (!specifier.startsWith(".")) return null;
+ const segments = importer.split("/").slice(0, -1);
+ for (const segment of specifier.split("/")) {
+ if (segment === "" || segment === ".") continue;
+ if (segment === "..") {
+ if (segments.length === 0) return null;
+ segments.pop();
+ continue;
+ }
+ segments.push(segment);
+ }
+ return segments.join("/");
+}
+
+export function buildComponentRelationshipGraph(
+ sourceModules: Record<string, string>,
+): ComponentRelationshipGraph {
+ const modules = Object.entries(sourceModules).flatMap(([path, source]) => {
+ const relativePath = relativeDesignSystemPath(path);
+ if (
+ relativePath === null ||
+ !SOURCE_FILE_PATTERN.test(relativePath) ||
+ NON_COMPONENT_FILE_PATTERN.test(relativePath)
+ ) {
+ return [];
+ }
+ const id = componentId(relativePath);
+ return id === null
+ ? []
+ : [
+ {
+ id,
+ group: nodeGroup(relativePath),
+ kind: nodeKind(relativePath),
+ path: relativePath,
+ source,
+ },
+ ];
+ });
+
+ const nodeDetails = new Map(
+ modules.map(({ id, kind, group }) => [id, { kind, group }]),
+ );
+ const nodeIds = new Set(nodeDetails.keys());
+ const edgePairs = new Set<string>();
+
+ for (const sourceModule of modules) {
+ for (const match of sourceModule.source.matchAll(STATIC_IMPORT_PATTERN)) {
+ const importedPath = resolveImport(sourceModule.path, match[1]);
+ if (importedPath === null) continue;
+ const target = componentId(importedPath);
+ if (target === null || target === sourceModule.id || !nodeIds.has(target))
+ continue;
+ edgePairs.add(JSON.stringify([sourceModule.id, target]));
+ }
+ }
+
+ const nodes = [...nodeIds]
+ .sort((left, right) => left.localeCompare(right))
+ .map((id) => ({
+ id,
+ label: id,
+ kind: nodeDetails.get(id)?.kind ?? "component",
+ group: nodeDetails.get(id)?.group ?? null,
+ }));
+ const edges = [...edgePairs]
+ .map((pair) => JSON.parse(pair) as [string, string])
+ .sort(([leftSource, leftTarget], [rightSource, rightTarget]) =>
+ `${leftSource}\0${leftTarget}`.localeCompare(
+ `${rightSource}\0${rightTarget}`,
+ ),
+ )
+ .map(([source, target]) => ({
+ id: `${source}->${target}`,
+ source,
+ target,
+ }));
+
+ return { nodes, edges };
+}
diff --git a/web/playwright.config.ts b/web/playwright.config.ts
index dc4d044419..3bda799baa 100644
--- a/web/playwright.config.ts
+++ b/web/playwright.config.ts
@@ -1,6 +1,7 @@
import { defineConfig } from "@playwright/test";
export default defineConfig({
+ testDir: "./src/__e2e__",
timeout: 180000, // test timeout 180s (3 minutes)
expect: {
timeout: 60000, // assertion timeout 60s (increased for CI)