npm - @fragments-sdk/viewer - Versions diffs - 0.2.1 - Mend

@fragments-sdk/viewer 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (141) hide show

package/LICENSE +84 -0
package/index.html +28 -0
package/package.json +71 -0
package/src/__tests__/a11y-fixes.test.ts +358 -0
package/src/__tests__/jsx-parser.test.ts +502 -0
package/src/__tests__/render-utils.test.ts +232 -0
package/src/__tests__/style-utils.test.ts +404 -0
package/src/app/index.ts +1 -0
package/src/assets/fragments-logo.ts +4 -0
package/src/assets/fragments_logo.png +0 -0
package/src/components/AccessibilityPanel.tsx +1457 -0
package/src/components/ActionCapture.tsx +172 -0
package/src/components/ActionsPanel.tsx +332 -0
package/src/components/AllVariantsPreview.tsx +78 -0
package/src/components/App.tsx +604 -0
package/src/components/BottomPanel.tsx +288 -0
package/src/components/CodePanel.naming.test.tsx +59 -0
package/src/components/CodePanel.tsx +118 -0
package/src/components/CommandPalette.tsx +392 -0
package/src/components/ComponentDocView.tsx +164 -0
package/src/components/ComponentGraph.tsx +380 -0
package/src/components/ComponentHeader.tsx +88 -0
package/src/components/ContractPanel.tsx +241 -0
package/src/components/DeviceMockup.tsx +156 -0
package/src/components/EmptyVariantMessage.tsx +54 -0
package/src/components/ErrorBoundary.tsx +97 -0
package/src/components/FigmaEmbed.tsx +238 -0
package/src/components/FragmentEditor.tsx +525 -0
package/src/components/FragmentRenderer.tsx +61 -0
package/src/components/HeaderSearch.tsx +24 -0
package/src/components/HealthDashboard.tsx +441 -0
package/src/components/HmrStatusIndicator.tsx +61 -0
package/src/components/Icons.tsx +479 -0
package/src/components/InteractionsPanel.tsx +757 -0
package/src/components/IsolatedPreviewFrame.tsx +390 -0
package/src/components/IsolatedRender.tsx +113 -0
package/src/components/KeyboardShortcutsHelp.tsx +53 -0
package/src/components/LandingPage.tsx +420 -0
package/src/components/Layout.tsx +27 -0
package/src/components/LeftSidebar.tsx +472 -0
package/src/components/LoadErrorMessage.tsx +102 -0
package/src/components/MultiViewportPreview.tsx +527 -0
package/src/components/NoVariantsMessage.tsx +59 -0
package/src/components/PanelShell.tsx +161 -0
package/src/components/PerformancePanel.tsx +304 -0
package/src/components/PreviewArea.tsx +254 -0
package/src/components/PreviewAside.tsx +168 -0
package/src/components/PreviewFrameHost.tsx +304 -0
package/src/components/PreviewToolbar.tsx +80 -0
package/src/components/PropsEditor.tsx +506 -0
package/src/components/PropsTable.tsx +111 -0
package/src/components/RelationsSection.tsx +88 -0
package/src/components/ResizablePanel.tsx +271 -0
package/src/components/RightSidebar.tsx +102 -0
package/src/components/RuntimeToolsRegistrar.tsx +17 -0
package/src/components/ScreenshotButton.tsx +90 -0
package/src/components/ShadowPreview.tsx +204 -0
package/src/components/Sidebar.tsx +169 -0
package/src/components/SkeletonLoader.tsx +161 -0
package/src/components/ThemeProvider.tsx +42 -0
package/src/components/Toast.tsx +3 -0
package/src/components/TokenStylePanel.tsx +699 -0
package/src/components/TopToolbar.tsx +159 -0
package/src/components/Untitled +1 -0
package/src/components/UsageSection.tsx +95 -0
package/src/components/VariantMatrix.tsx +391 -0
package/src/components/VariantRenderer.tsx +131 -0
package/src/components/VariantTabs.tsx +40 -0
package/src/components/ViewerHeader.tsx +69 -0
package/src/components/ViewerStateSync.tsx +52 -0
package/src/components/ViewportSelector.tsx +172 -0
package/src/components/WebMCPDevTools.tsx +503 -0
package/src/components/WebMCPIntegration.tsx +47 -0
package/src/components/WebMCPStatusIndicator.tsx +60 -0
package/src/components/_future/CreatePage.tsx +835 -0
package/src/components/viewer-utils.ts +16 -0
package/src/composition-renderer.ts +381 -0
package/src/constants/index.ts +1 -0
package/src/constants/ui.ts +166 -0
package/src/entry.tsx +335 -0
package/src/hooks/index.ts +2 -0
package/src/hooks/useA11yCache.ts +383 -0
package/src/hooks/useA11yService.ts +364 -0
package/src/hooks/useActions.ts +138 -0
package/src/hooks/useAppState.ts +147 -0
package/src/hooks/useCompiledFragments.ts +42 -0
package/src/hooks/useFigmaIntegration.ts +132 -0
package/src/hooks/useHmrStatus.ts +109 -0
package/src/hooks/useKeyboardShortcuts.ts +270 -0
package/src/hooks/usePreviewBridge.ts +347 -0
package/src/hooks/useScrollSpy.ts +78 -0
package/src/hooks/useShadowStyles.ts +221 -0
package/src/hooks/useUrlState.ts +318 -0
package/src/hooks/useViewSettings.ts +111 -0
package/src/intelligence/healthReport.ts +505 -0
package/src/intelligence/styleDrift.ts +340 -0
package/src/intelligence/usageScanner.ts +309 -0
package/src/jsx-parser.ts +486 -0
package/src/preview-frame-entry.tsx +25 -0
package/src/preview-frame.html +148 -0
package/src/render-template.html +68 -0
package/src/render-utils.ts +311 -0
package/src/shared/ComponentDocContent.module.scss +10 -0
package/src/shared/ComponentDocContent.module.scss.d.ts +2 -0
package/src/shared/ComponentDocContent.tsx +274 -0
package/src/shared/DocsHeaderBar.tsx +129 -0
package/src/shared/DocsPageAsideHost.tsx +89 -0
package/src/shared/DocsPageShell.tsx +124 -0
package/src/shared/DocsSearchCommand.tsx +99 -0
package/src/shared/DocsSidebarNav.tsx +66 -0
package/src/shared/PropsTable.module.scss +68 -0
package/src/shared/PropsTable.module.scss.d.ts +2 -0
package/src/shared/PropsTable.tsx +76 -0
package/src/shared/VariantPreviewCard.module.scss +114 -0
package/src/shared/VariantPreviewCard.module.scss.d.ts +2 -0
package/src/shared/VariantPreviewCard.tsx +137 -0
package/src/shared/docs-data/index.ts +32 -0
package/src/shared/docs-data/mcp-configs.ts +72 -0
package/src/shared/docs-data/palettes.ts +75 -0
package/src/shared/docs-data/setup-examples.ts +55 -0
package/src/shared/docs-layout.scss +28 -0
package/src/shared/docs-layout.scss.d.ts +2 -0
package/src/shared/index.ts +34 -0
package/src/shared/types.ts +53 -0
package/src/style-utils.ts +414 -0
package/src/styles/globals.css +278 -0
package/src/types/a11y.ts +197 -0
package/src/utils/a11y-fixes.ts +509 -0
package/src/utils/actionExport.ts +372 -0
package/src/utils/colorSchemes.ts +201 -0
package/src/utils/contrast.ts +246 -0
package/src/utils/detectRelationships.ts +256 -0
package/src/webmcp/__tests__/analytics.test.ts +108 -0
package/src/webmcp/analytics.ts +165 -0
package/src/webmcp/index.ts +3 -0
package/src/webmcp/posthog-bridge.ts +39 -0
package/src/webmcp/runtime-tools.ts +152 -0
package/src/webmcp/scan-utils.ts +135 -0
package/src/webmcp/use-tool-analytics.ts +69 -0
package/src/webmcp/viewer-state.ts +45 -0
package/tsconfig.json +20 -0

package/src/render-template.html ADDED Viewed

@@ -0,0 +1,68 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Fragments Render</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap"
+      rel="stylesheet"
+    />
+    <style>
+      /* Reset and base styles for isolated rendering */
+      *, *::before, *::after {
+        box-sizing: border-box;
+      }
+      html, body {
+        margin: 0;
+        padding: 0;
+        font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+        -webkit-font-smoothing: antialiased;
+        -moz-osx-font-smoothing: grayscale;
+      }
+      body {
+        background: #ffffff;
+        min-height: 100vh;
+      }
+      #render-root {
+        padding: 16px;
+        display: inline-block;
+      }
+      /* Signal that rendering is complete */
+      #render-root.ready {
+        /* Used by Playwright to know when to capture */
+      }
+      /* Error display */
+      .render-error {
+        padding: 16px;
+        background: #fef2f2;
+        border: 1px solid #fecaca;
+        border-radius: 8px;
+        color: #dc2626;
+        font-size: 14px;
+      }
+      .render-error pre {
+        margin: 8px 0 0;
+        padding: 8px;
+        background: #fff;
+        border-radius: 4px;
+        overflow-x: auto;
+        font-size: 12px;
+        font-family: 'JetBrains Mono', monospace;
+      }
+    </style>
+    <!-- PROJECT_STYLES_PLACEHOLDER -->
+  </head>
+  <body>
+    <div id="render-root"></div>
+    <!-- RENDER_SCRIPT_PLACEHOLDER -->
+  </body>
+</html>

package/src/render-utils.ts ADDED Viewed

@@ -0,0 +1,311 @@
+/**
+ * Render utilities for AI preview endpoint.
+ * Generates code to render design system components in isolation.
+ */
+export interface RenderRequest {
+  /** Component name (e.g., "Button", "Card") */
+  component: string;
+  /** Props to pass to the component */
+  props?: Record<string, unknown>;
+  /** Variant name to render (uses variant's render function) */
+  variant?: string;
+  /** Viewport dimensions */
+  viewport?: {
+    width: number;
+    height: number;
+  };
+}
+export interface FragmentInfo {
+  name: string;
+  path: string;
+}
+/**
+ * Serialize a value to JavaScript code string.
+ * Handles strings, numbers, booleans, null, undefined, arrays, and objects.
+ */
+export function serializeValue(value: unknown): string {
+  if (value === null) return "null";
+  if (value === undefined) return "undefined";
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number") return String(value);
+  if (typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) {
+    return `[${value.map(serializeValue).join(", ")}]`;
+  }
+  if (typeof value === "object") {
+    const entries = Object.entries(value)
+      .map(([k, v]) => `${JSON.stringify(k)}: ${serializeValue(v)}`)
+      .join(", ");
+    return `{${entries}}`;
+  }
+  // Functions and other types - skip
+  return "undefined";
+}
+/**
+ * Serialize props object to JSX attribute string.
+ * Example: { variant: "primary", disabled: true } -> variant="primary" disabled={true}
+ */
+export function serializePropsToJsx(props: Record<string, unknown>): string {
+  return Object.entries(props)
+    .filter(([_, v]) => v !== undefined)
+    .map(([key, value]) => {
+      if (typeof value === "string") {
+        return `${key}=${JSON.stringify(value)}`;
+      }
+      return `${key}={${serializeValue(value)}}`;
+    })
+    .join(" ");
+}
+/**
+ * Find a fragment by component name.
+ * Returns the fragment info if found, null otherwise.
+ */
+export function findFragmentByName(
+  componentName: string,
+  fragments: Array<{ path: string; fragment: { meta: { name: string } } }>
+): FragmentInfo | null {
+  const match = fragments.find(
+    (s) => s.fragment.meta.name.toLowerCase() === componentName.toLowerCase()
+  );
+  if (!match) return null;
+  return {
+    name: match.fragment.meta.name,
+    path: match.path,
+  };
+}
+/**
+ * Get list of available component names from loaded fragments.
+ */
+export function getAvailableComponents(
+  fragments: Array<{ fragment: { meta: { name: string } } }>
+): string[] {
+  return fragments.map((s) => s.fragment.meta.name).sort();
+}
+/**
+ * Generate the render script that will be injected into the template.
+ * This script imports the component and renders it with the given props.
+ */
+export function generateRenderScript(
+  fragmentPath: string,
+  componentName: string,
+  props: Record<string, unknown> = {}
+): string {
+  const propsJsx = serializePropsToJsx(props);
+  const propsString = propsJsx ? ` ${propsJsx}` : "";
+  // Handle children prop specially - render as content between tags
+  const hasChildren = "children" in props && props.children !== undefined;
+  const childrenContent = hasChildren ? String(props.children) : "";
+  const propsWithoutChildren = { ...props };
+  delete propsWithoutChildren.children;
+  const propsJsxNoChildren = serializePropsToJsx(propsWithoutChildren);
+  const propsStringNoChildren = propsJsxNoChildren ? ` ${propsJsxNoChildren}` : "";
+  return `
+import React from "react";
+import { createRoot } from "react-dom/client";
+// Import the fragment to get the component
+async function render() {
+  const root = document.getElementById("render-root");
+  try {
+    // Dynamic import of the fragment file
+    const fragmentModule = await import("${fragmentPath}");
+    const fragment = fragmentModule.default;
+    if (!fragment || !fragment.component) {
+      throw new Error("Fragment does not export a component");
+    }
+    const Component = fragment.component;
+    // Create React root and render
+    const reactRoot = createRoot(root);
+    ${
+      hasChildren
+        ? `reactRoot.render(React.createElement(Component, ${JSON.stringify(propsWithoutChildren)}, ${JSON.stringify(childrenContent)}));`
+        : `reactRoot.render(React.createElement(Component, ${JSON.stringify(props)}));`
+    }
+    // Signal that rendering is complete
+    // Wait a frame for React to flush
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        root.classList.add("ready");
+        window.__RENDER_READY__ = true;
+      });
+    });
+  } catch (error) {
+    console.error("Render error:", error);
+    root.innerHTML = \`
+      <div class="render-error">
+        <strong>Render Error</strong>
+        <pre>\${error.message}</pre>
+      </div>
+    \`;
+    root.classList.add("ready");
+    window.__RENDER_READY__ = true;
+    window.__RENDER_ERROR__ = error.message;
+  }
+}
+render();
+`;
+}
+/**
+ * Generate a render script that renders a specific variant by name.
+ * The variant lookup happens in the browser using the fragment's variants array.
+ */
+export function generateVariantRenderScript(
+  fragmentPath: string,
+  componentName: string,
+  variantName: string
+): string {
+  const variantNameLower = JSON.stringify(variantName.toLowerCase());
+  return `
+import React from "react";
+import { createRoot } from "react-dom/client";
+async function render() {
+  const root = document.getElementById("render-root");
+  try {
+    const fragmentModule = await import("${fragmentPath}");
+    const fragment = fragmentModule.default;
+    if (!fragment || !fragment.variants || fragment.variants.length === 0) {
+      throw new Error("Fragment has no variants");
+    }
+    const variant = fragment.variants.find(
+      v => v.name.toLowerCase() === ${variantNameLower}
+    );
+    if (!variant) {
+      const available = fragment.variants.map(v => v.name).join(", ");
+      throw new Error("Variant '" + ${JSON.stringify(variantName)} + "' not found. Available: " + available);
+    }
+    const element = variant.render();
+    const reactRoot = createRoot(root);
+    reactRoot.render(element);
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        root.classList.add("ready");
+        window.__RENDER_READY__ = true;
+      });
+    });
+  } catch (error) {
+    console.error("Render error:", error);
+    root.innerHTML = \`
+      <div class="render-error">
+        <strong>Render Error</strong>
+        <pre>\${error.message}</pre>
+      </div>
+    \`;
+    root.classList.add("ready");
+    window.__RENDER_READY__ = true;
+    window.__RENDER_ERROR__ = error.message;
+  }
+}
+render();
+`;
+}
+/**
+ * Generate a render script that also runs axe-core for accessibility auditing.
+ * When variantName is provided, renders that specific variant; otherwise renders
+ * the component with empty props.
+ */
+export function generateA11yRenderScript(
+  fragmentPath: string,
+  componentName: string,
+  variantName?: string
+): string {
+  const variantLookup = variantName
+    ? `
+    const variant = fragment.variants?.find(
+      v => v.name.toLowerCase() === ${JSON.stringify(variantName.toLowerCase())}
+    );
+    if (!variant) {
+      throw new Error("Variant '${variantName}' not found");
+    }
+    element = variant.render();`
+    : `
+    element = React.createElement(fragment.component, {});`;
+  return `
+import React from "react";
+import { createRoot } from "react-dom/client";
+import axe from "axe-core";
+async function render() {
+  const root = document.getElementById("render-root");
+  try {
+    const fragmentModule = await import("${fragmentPath}");
+    const fragment = fragmentModule.default;
+    if (!fragment || !fragment.component) {
+      throw new Error("Fragment does not export a component");
+    }
+    let element;
+    ${variantLookup}
+    const reactRoot = createRoot(root);
+    reactRoot.render(element);
+    // Wait for React to flush rendering
+    await new Promise(resolve => {
+      requestAnimationFrame(() => {
+        requestAnimationFrame(resolve);
+      });
+    });
+    // Additional settle time for CSS/animations
+    await new Promise(resolve => setTimeout(resolve, 100));
+    // Run axe-core accessibility audit
+    const results = await axe.run('#render-root', {
+      runOnly: {
+        type: 'tag',
+        values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'best-practice'],
+      },
+    });
+    window.__AXE_RESULTS__ = results;
+    window.__RENDER_READY__ = true;
+  } catch (error) {
+    console.error("A11y audit error:", error);
+    window.__AXE_ERROR__ = error.message;
+    window.__RENDER_READY__ = true;
+  }
+}
+render();
+`;
+}
+/**
+ * Generate a virtual module ID for a render request.
+ * This creates a unique ID that Vite can resolve.
+ */
+export function generateRenderModuleId(componentName: string, requestId: string): string {
+  return `virtual:fragments-render-${componentName}-${requestId}`;
+}

package/src/shared/ComponentDocContent.module.scss ADDED Viewed

@@ -0,0 +1,10 @@
+.accessibilityList {
+  margin: 0.5rem 0 0;
+  padding-left: 1.125rem;
+  font-size: 0.8125rem;
+  line-height: 1.6;
+  li {
+    margin-bottom: 0.25rem;
+  }
+}

package/src/shared/ComponentDocContent.module.scss.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ declare const styles: Record<string, string>;
2	+ export default styles;

package/src/shared/ComponentDocContent.tsx ADDED Viewed

@@ -0,0 +1,274 @@
+'use client';
+import type { ReactNode } from 'react';
+import {
+  Badge,
+  Box,
+  Card,
+  CardBody,
+  Grid,
+  ListRoot,
+  ListItem,
+  Stack,
+  Text,
+  Alert,
+  AlertIcon,
+  AlertBody,
+  AlertTitle,
+  AlertContent,
+  CodeBlock,
+  Link,
+} from '@fragments-sdk/ui';
+import type { DocProp } from './types';
+import { PropsTable } from './PropsTable';
+import styles from './ComponentDocContent.module.scss';
+/** Normalize PascalCase to lowercase with spaces: "AppSwitcher" → "app switcher" */
+function pascalToLowerSpaced(name: string): string {
+  return name.replace(/([A-Z])/g, ' $1').trim().toLowerCase();
+}
+/** Detect auto-generated placeholder descriptions like "ActionMenu component" */
+function isGenericDescription(name: string, description: string): boolean {
+  const lower = description.toLowerCase().trim();
+  const nameLower = name.toLowerCase();
+  const nameSpaced = pascalToLowerSpaced(name);
+  return (
+    lower === `${nameLower} component` ||
+    lower === `${nameSpaced} component` ||
+    lower === `${nameLower} component.` ||
+    lower === `${nameSpaced} component.` ||
+    (lower.startsWith('interactive ') && lower.endsWith(' element for triggering actions')) ||
+    (lower.startsWith('form ') && lower.endsWith(' for user input')) ||
+    (lower.startsWith('container ') && lower.endsWith(' for grouping content'))
+  );
+}
+/** Detect placeholder usage items like "Use X for its intended purpose" */
+function isGenericUsageItem(item: string): boolean {
+  const lower = item.toLowerCase().trim();
+  return (
+    (lower.startsWith('use ') && lower.endsWith(' for its intended purpose')) ||
+    lower === 'when a more specific component is available' ||
+    lower.startsWith('todo:')
+  );
+}
+/** Check if any real (non-placeholder) usage content exists */
+function hasRealUsageContent(usage: { when: string[]; whenNot: string[]; guidelines: string[]; accessibility: string[] }): boolean {
+  const allItems = [...usage.when, ...usage.whenNot, ...usage.guidelines, ...usage.accessibility];
+  return allItems.length > 0 && allItems.some(item => !isGenericUsageItem(item));
+}
+/** Filter out generic placeholder items from usage lists */
+function filterRealItems(items: string[]): string[] {
+  return items.filter(item => !isGenericUsageItem(item));
+}
+interface StandardReference {
+  id: string;
+  title: string;
+  url: string;
+}
+export interface ComponentDocContentProps {
+  name: string;
+  description: string;
+  componentId: string;
+  props: Record<string, DocProp>;
+  variants: Array<{ name: string; description?: string; code?: string }>;
+  usage: {
+    when: string[];
+    whenNot: string[];
+    guidelines: string[];
+    accessibility: string[];
+  };
+  relations: Array<{ component: string; relationship: string; note?: string }>;
+  dependencies?: Array<{ name: string }>;
+  standards?: StandardReference[];
+  /** Custom package name for the import path (e.g. '@payroc/react'). Defaults to '@fragments-sdk/ui'. */
+  packageName?: string;
+  /** Render a variant example (framework-specific). */
+  renderVariant: (variant: { name: string; description?: string; code?: string }, index: number) => ReactNode;
+  /** Render a related-component link (framework-specific). If omitted, renders plain text. */
+  renderRelatedLink?: (component: string, relationship: string, note: string | undefined, key: string) => ReactNode;
+}
+export function ComponentDocContent({
+  name,
+  description,
+  componentId,
+  props,
+  variants,
+  usage,
+  relations,
+  packageName,
+  dependencies,
+  standards,
+  renderVariant,
+  renderRelatedLink,
+}: ComponentDocContentProps) {
+  return (
+    <Stack gap="xl">
+      <Box as="header">
+        <Stack gap="sm">
+          <Text as="h1" size="2xl" weight="semibold">{name}</Text>
+          {!isGenericDescription(name, description) && (
+            <Text as="p" color="secondary">{description}</Text>
+          )}
+        </Stack>
+      </Box>
+      <Box as="section">
+        <Stack gap="md">
+          <Text as="h2" id="setup" size="xl" weight="semibold">Setup</Text>
+          <CodeBlock
+            code={`import { ${componentId} } from '${packageName || '@fragments-sdk/ui'}';`}
+            language="tsx"
+          />
+          {dependencies && dependencies.length > 0 && (
+            <Stack gap="sm">
+              <Text as="h3" size="base" weight="semibold">Dependencies</Text>
+              <Text size="sm" color="secondary">
+                This component requires additional packages:
+              </Text>
+              <CodeBlock
+                code={`npm install ${dependencies.map((d) => d.name).join(' ')}`}
+                language="bash"
+              />
+            </Stack>
+          )}
+        </Stack>
+      </Box>
+      {variants.length > 0 && (
+        <Box as="section">
+          <Stack gap="md">
+            <Text as="h2" id="examples" size="xl" weight="semibold">Examples</Text>
+            {variants.map((variant, index) => renderVariant(variant, index))}
+          </Stack>
+        </Box>
+      )}
+      {Object.keys(props).length > 0 && (
+        <Box as="section">
+          <Stack gap="md">
+            <Text as="h2" id="props" size="xl" weight="semibold">Props</Text>
+            <PropsTable props={props} />
+          </Stack>
+        </Box>
+      )}
+      {hasRealUsageContent(usage) && (
+      <Box as="section">
+        <Stack gap="md">
+          <Text as="h2" id="usage-guidelines" size="xl" weight="semibold">Usage Guidelines</Text>
+          <Grid columns={{ base: 1, md: 2 }} gap="md">
+            {filterRealItems(usage.when).length > 0 && (
+              <Box background="secondary" rounded="md" padding="md">
+                <Stack gap="sm">
+                  <Text as="h3" id="when-to-use" size="base" weight="semibold">When to use</Text>
+                  <ListRoot variant="disc" gap="xs">
+                    {filterRealItems(usage.when).map((item, i) => (
+                      <ListItem key={i}>{item}</ListItem>
+                    ))}
+                  </ListRoot>
+                </Stack>
+              </Box>
+            )}
+            {filterRealItems(usage.whenNot).length > 0 && (
+              <Box background="secondary" rounded="md" padding="md">
+                <Stack gap="sm">
+                  <Text as="h3" id="when-not-to-use" size="base" weight="semibold">When not to use</Text>
+                  <ListRoot variant="disc" gap="xs">
+                    {filterRealItems(usage.whenNot).map((item, i) => (
+                      <ListItem key={i}>{item}</ListItem>
+                    ))}
+                  </ListRoot>
+                </Stack>
+              </Box>
+            )}
+          </Grid>
+          {filterRealItems(usage.guidelines).length > 0 && (
+            <Stack gap="sm">
+              <Text as="h3" id="best-practices" size="base" weight="semibold">Best practices</Text>
+              <ListRoot variant="disc" gap="xs">
+                {filterRealItems(usage.guidelines).map((item, i) => (
+                  <ListItem key={i}>{item}</ListItem>
+                ))}
+              </ListRoot>
+            </Stack>
+          )}
+          {usage.accessibility.length > 0 && (
+            <Alert severity="info">
+              <AlertIcon />
+              <AlertBody>
+                <AlertTitle>Accessibility</AlertTitle>
+                <AlertContent>
+                  <ul className={styles.accessibilityList}>
+                    {usage.accessibility.map((item, i) => (
+                      <li key={i}>{item}</li>
+                    ))}
+                  </ul>
+                </AlertContent>
+              </AlertBody>
+            </Alert>
+          )}
+        </Stack>
+      </Box>
+      )}
+      {standards && standards.length > 0 && (
+        <Box as="section">
+          <Stack gap="sm">
+            <Text as="h2" id="standards" size="xl" weight="semibold">Standards References</Text>
+            <ListRoot variant="disc" gap="xs">
+              {standards.map((standard) => (
+                <ListItem key={standard.id}>
+                  <Link href={standard.url} target="_blank" rel="noreferrer">
+                    {standard.title}
+                  </Link>
+                </ListItem>
+              ))}
+            </ListRoot>
+          </Stack>
+        </Box>
+      )}
+      {relations.length > 0 && (
+        <Box as="section">
+          <Stack gap="md">
+            <Text as="h2" id="related-components" size="xl" weight="semibold">Related Components</Text>
+            <Grid columns="auto" minChildWidth="220px" gap="sm">
+              {relations.map((relation) => {
+                const key = `${relation.component}-${relation.relationship}`;
+                if (renderRelatedLink) {
+                  return renderRelatedLink(relation.component, relation.relationship, relation.note, key);
+                }
+                return (
+                  <Card key={key} variant="outlined">
+                    <CardBody>
+                      <Stack gap="xs">
+                        <Stack direction="row" align="center" justify="between">
+                          <Text weight="semibold">{relation.component}</Text>
+                          <Badge size="sm">{relation.relationship}</Badge>
+                        </Stack>
+                        {relation.note && <Text size="sm" color="secondary">{relation.note}</Text>}
+                      </Stack>
+                    </CardBody>
+                  </Card>
+                );
+              })}
+            </Grid>
+          </Stack>
+        </Box>
+      )}
+    </Stack>
+  );
+}