@usefragments/ui 1.6.0 → 2.0.0

package/src/components/Loading/Loading.contract.json

@@ -1,22 +1,15 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Loading",
-  "description": "Versatile loading indicator with multiple variants for showing progress or waiting states",
+  "description": "Signals that something is happening when you cannot say how long it will take.",
   "category": "feedback",
-  "tags": [
-    "loading",
-    "spinner",
-    "progress",
-    "feedback",
-    "indicator",
-    "async"
-  ],
+  "tags": ["loading", "spinner", "progress", "feedback", "indicator", "async"],
   "status": "stable",
   "sourcePath": "src/components/Loading/index.tsx",
   "exportName": "Loading",
   "propsSummary": [
     "size: sm|md|lg|xl (default: md)",
-    "variant: spinner|dots|pulse (default: spinner)",
+    "kind: spinner|dots|pulse (default: spinner)",
     "label: string (default: Loading...)",
     "centered: boolean (default: false)",
     "fill: boolean (default: false)",
@@ -29,23 +22,14 @@
       "description": "Size of the loading indicator",
       "default": "md",
       "required": false,
-      "values": [
-        "sm",
-        "md",
-        "lg",
-        "xl"
-      ]
+      "values": ["sm", "md", "lg", "xl"]
     },
-    "variant": {
+    "kind": {
       "type": "enum",
-      "description": "Visual style of the loading animation",
+      "description": "Which animation plays",
       "default": "spinner",
       "required": false,
-      "values": [
-        "spinner",
-        "dots",
-        "pulse"
-      ]
+      "values": ["spinner", "dots", "pulse"]
     },
     "label": {
       "type": "string",
@@ -73,90 +57,82 @@
     },
     "color": {
       "type": "enum",
-      "description": "Color variant - accent uses theme color, current inherits text color",
+      "description": "Colour. accent uses the theme accent, current inherits the surrounding text colour",
       "default": "accent",
       "required": false,
-      "values": [
-        "accent",
-        "current",
-        "muted"
-      ]
+      "values": ["accent", "current", "muted"]
     }
   },
   "usage": {
     "when": [
-      "Indicating content is being fetched or processed",
-      "Showing a pending state while waiting for an async operation",
-      "Displaying loading state for buttons, forms, or page sections",
-      "Full-screen loading during initial app/page load"
+      "Fetching or processing content",
+      "Waiting on an async action to come back",
+      "Buttons, forms, and page sections mid-request",
+      "The first paint of an app or page"
     ],
     "whenNot": [
-      "For showing determinate progress - use Progress component instead",
-      "For showing skeleton placeholders - use Skeleton component instead",
-      "For AI-specific thinking states - use ThinkingIndicator instead"
+      "You know the percentage — use Progress",
+      "You know the page shape — use Skeleton",
+      "AI reasoning states — use ThinkingIndicator"
     ],
     "guidelines": [
-      "Use spinner variant for general loading states",
-      "Use dots variant for chat/messaging contexts",
-      "Use pulse variant for subtle, ambient loading",
-      "Always provide a meaningful label for screen readers",
-      "Consider using Loading.Screen for initial page loads",
-      "Use Loading.Inline when loading indicator should flow with text"
+      "spinner for general waits",
+      "dots for chat and messaging",
+      "pulse for quiet ambient waiting",
+      "Always pass a label describing what is loading",
+      "Loading.Screen for first page load, Loading.Inline to sit inside a sentence"
     ],
     "accessibility": [
-      "Component uses role=\"status\" and aria-live=\"polite\"",
-      "Always provide descriptive label prop for screen readers",
-      "Animations respect prefers-reduced-motion preference"
+      "Announced through role=\"status\" with aria-live=\"polite\"",
+      "label is what a screen reader reads — make it specific",
+      "Animation stops for prefers-reduced-motion"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Default spinner loading indicator",
-      "code": "<Loading />"
+      "description": "Spinner at medium size, accent coloured.",
+      "code": "<Loading label=\"Loading content\" />"
     },
     {
       "name": "Sizes",
-      "description": "Loading indicators in different sizes",
-      "code": "<div style={{ display: 'flex', alignItems: 'center', gap: '24px' }}>\n  <Loading size=\"sm\" />\n  <Loading size=\"md\" />\n  <Loading size=\"lg\" />\n  <Loading size=\"xl\" />\n</div>"
+      "description": "sm inside controls, xl for a whole page.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"lg\" align=\"center\">\n  <Loading size=\"sm\" label=\"Loading\" />\n  <Loading size=\"md\" label=\"Loading\" />\n  <Loading size=\"lg\" label=\"Loading\" />\n  <Loading size=\"xl\" label=\"Loading\" />\n</Stack>"
     },
     {
       "name": "Dots",
-      "description": "Bouncing dots animation",
-      "code": "<Loading variant=\"dots\" />"
+      "description": "Three bouncing dots, at home in a message thread.",
+      "code": "<Loading kind=\"dots\" label=\"Sending message\" />"
     },
     {
       "name": "Pulse",
-      "description": "Pulsing circle animation",
-      "code": "<Loading variant=\"pulse\" />"
+      "description": "One breathing dot for ambient background work.",
+      "code": "<Loading kind=\"pulse\" label=\"Syncing\" />"
     },
     {
       "name": "Colors",
-      "description": "Different color variants",
-      "code": "<div style={{ display: 'flex', alignItems: 'center', gap: '24px' }}>\n  <Loading color=\"accent\" />\n  <Loading color=\"muted\" />\n  <span style={{ color: '#3b82f6' }}>\n    <Loading color=\"current\" />\n  </span>\n</div>"
+      "description": "Accent, muted, or whatever the surrounding text is.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"lg\" align=\"center\">\n  <Loading color=\"accent\" label=\"Loading\" />\n  <Loading color=\"muted\" label=\"Loading\" />\n  <span style={{ color: 'var(--fui-color-info)' }}>\n    <Loading color=\"current\" label=\"Loading\" />\n  </span>\n</Stack>"
     },
     {
       "name": "Inline",
-      "description": "Inline loading indicator that flows with text",
-      "code": "<p style={{ margin: 0 }}>\n  Processing your request <Loading.Inline /> please wait...\n</p>"
+      "description": "Sits on the text baseline mid-sentence.",
+      "code": "<p style={{ margin: 0 }}>\n  Processing your request <Loading.Inline label=\"Processing\" /> please wait…\n</p>"
     },
     {
       "name": "Centered",
-      "description": "Centered in container",
-      "code": "<div style={{ width: '200px', height: '100px', border: '1px dashed #ccc', borderRadius: '8px' }}>\n  <Loading centered fill />\n</div>"
+      "description": "Fills its container and centres in it.",
+      "code": "<div\n  style={{\n    width: '200px',\n    height: '100px',\n    border: '1px dashed var(--fui-border)',\n    borderRadius: 'var(--fui-radius-md)',\n  }}\n>\n  <Loading centered fill label=\"Loading section\" />\n</div>"
     },
     {
       "name": "Screen",
-      "description": "Full-screen loading state with optional label",
-      "code": "<div style={{ position: 'relative', width: '300px', height: '200px', border: '1px solid #ccc', borderRadius: '8px', overflow: 'hidden', transform: 'scale(1)' }}>\n  <Loading.Screen size=\"lg\" label=\"Loading application...\" showLabel />\n</div>"
+      "description": "Covers the surface it sits on and names the wait.",
+      "code": "<div\n  style={{\n    position: 'relative',\n    contain: 'layout',\n    width: '300px',\n    height: '200px',\n    border: '1px solid var(--fui-border)',\n    borderRadius: 'var(--fui-radius-md)',\n    overflow: 'hidden',\n  }}\n>\n  <Loading.Screen size=\"lg\" label=\"Loading application…\" showLabel />\n</div>"
     }
   ],
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Inline",
-      "Screen"
-    ]
+    "subComponents": ["Inline", "Screen"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Loading/Loading.module.scss

@@ -1,4 +1,5 @@
 @use "../../tokens/variables" as *;
+@use "../../tokens/measurements.generated" as measurements;
 @use "../../recipes/representation" as representation;
 @use "../../recipes/typography" as typography;
 
@@ -58,17 +59,17 @@
 }
 
 // ============================================
-// Spinner Variant
+// Spinner kind
 // ============================================
 
 .spinnerIcon {
   inline-size: 100%;
   block-size: 100%;
-  animation: spin 0.8s linear infinite;
+  animation: spin var(--fui-duration-spin, $fui-duration-spin) linear infinite;
 
   @media (prefers-reduced-motion: reduce) {
     animation: none;
-    opacity: 0.7;
+    opacity: var(--fui-opacity-muted, #{$fui-opacity-muted});
   }
 }
 
@@ -82,10 +83,13 @@
 }
 
 // ============================================
-// Dots Variant
+// Dots kind
 // ============================================
 
-.dots {
+// `.dots`/`.pulse` on the root are kind hooks only — sizing lives on the
+// inner track. Sharing one class between root and track let the track's
+// 100% × 100% override the root's fixed activity footprint (rendered 0 × 0).
+.dotsTrack {
   display: flex;
   align-items: center;
   justify-content: space-between;
@@ -98,23 +102,23 @@
   block-size: 25%;
   border-radius: var(--fui-radius-full, $fui-radius-full);
   background-color: currentColor;
-  animation: bounce 1.4s ease-in-out infinite;
+  animation: bounce var(--fui-duration-pulse, $fui-duration-pulse) ease-in-out infinite;
 
   &:nth-child(1) {
-    animation-delay: 0s;
+    animation-delay: var(--fui-raw-space-0, #{measurements.raw-space(0)});
   }
 
   &:nth-child(2) {
-    animation-delay: 0.2s;
+    animation-delay: calc(var(--fui-duration-pulse, #{$fui-duration-pulse}) / 8);
   }
 
   &:nth-child(3) {
-    animation-delay: 0.4s;
+    animation-delay: calc(var(--fui-duration-pulse, #{$fui-duration-pulse}) / 4);
   }
 
   @media (prefers-reduced-motion: reduce) {
     animation: none;
-    opacity: 0.6;
+    opacity: var(--fui-opacity-muted, #{$fui-opacity-muted});
   }
 }
 
@@ -123,7 +127,7 @@
   60%,
   100% {
     transform: translateY(0);
-    opacity: 0.4;
+    opacity: var(--fui-opacity-disabled, #{$fui-opacity-disabled});
   }
   30% {
     transform: translateY(-30%);
@@ -132,10 +136,10 @@
 }
 
 // ============================================
-// Pulse Variant
+// Pulse kind
 // ============================================
 
-.pulse {
+.pulseTrack {
   position: relative;
   inline-size: 100%;
   block-size: 100%;
@@ -146,22 +150,22 @@
 
 .pulseRing {
   position: absolute;
-  width: 100%;
-  height: 100%;
+  inline-size: 100%;
+  block-size: 100%;
   border-radius: var(--fui-radius-full, $fui-radius-full);
   background-color: currentColor;
-  opacity: 0.3;
-  animation: pulseRing 1.5s ease-out infinite;
+  opacity: var(--fui-opacity-faint, #{$fui-opacity-faint});
+  animation: pulseRing var(--fui-duration-pulse, $fui-duration-pulse) ease-out infinite;
 
   @media (prefers-reduced-motion: reduce) {
     animation: none;
-    opacity: 0.2;
+    opacity: var(--fui-opacity-faint, #{$fui-opacity-faint});
   }
 }
 
 .pulseDot {
-  width: 50%;
-  height: 50%;
+  inline-size: 50%;
+  block-size: 50%;
   border-radius: var(--fui-radius-full, $fui-radius-full);
   background-color: currentColor;
   z-index: 1;
@@ -170,7 +174,7 @@
 @keyframes pulseRing {
   0% {
     transform: scale(0.5);
-    opacity: 0.5;
+    opacity: var(--fui-opacity-faint, #{$fui-opacity-faint});
   }
   100% {
     transform: scale(1.5);
@@ -189,7 +193,7 @@
   align-items: center;
   justify-content: center;
   background-color: var(--fui-backdrop, $fui-backdrop);
-  z-index: 50;
+  z-index: var(--fui-overlay-layer-backdrop, #{$fui-overlay-layer-backdrop});
 }
 
 .overlay {
@@ -197,7 +201,7 @@
 }
 
 // ============================================
-// Inline Variant
+// Inline
 // ============================================
 
 .inline {
@@ -206,23 +210,25 @@
   vertical-align: middle;
 }
 
+// The inline spinner scales with the surrounding text, so its box is an em
+// measure rather than a glyph step; the md icon is the fallback.
 .inline-sm {
-  --inline-size: 0.875em; // Relative to surrounding text
+  --_loading-inline-size: 0.875em;
 }
 
 .inline-md {
-  --inline-size: 1.125em;
+  --_loading-inline-size: 1.125em;
 }
 
 .inlineSpinner {
-  width: var(--inline-size);
-  height: var(--inline-size);
-  animation: spin 0.8s linear infinite;
+  inline-size: var(--_loading-inline-size, var(--fui-icon-md, #{$fui-icon-md}));
+  block-size: var(--_loading-inline-size, var(--fui-icon-md, #{$fui-icon-md}));
+  animation: spin var(--fui-duration-spin, $fui-duration-spin) linear infinite;
   color: currentColor;
 
   @media (prefers-reduced-motion: reduce) {
     animation: none;
-    opacity: 0.7;
+    opacity: var(--fui-opacity-muted, #{$fui-opacity-muted});
   }
 }
 
@@ -237,9 +243,9 @@
   flex-direction: column;
   align-items: center;
   justify-content: center;
-  gap: var(--fui-raw-space-12, 12px);
+  gap: var(--fui-raw-space-12, #{measurements.raw-space(12)});
   background-color: var(--fui-bg-primary, $fui-bg-primary);
-  z-index: 100;
+  z-index: var(--fui-overlay-layer-modal, #{$fui-overlay-layer-modal});
 }
 
 .screenLabel {

package/src/components/Loading/index.tsx

@@ -8,13 +8,14 @@ import styles from "./Loading.module.scss";
 // ============================================
 
 export type LoadingSize = "sm" | "md" | "lg" | "xl";
-export type LoadingVariant = "spinner" | "dots" | "pulse";
+export type LoadingKind = "spinner" | "dots" | "pulse";
 
 export interface LoadingProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Size of the loading indicator */
   size?: LoadingSize;
-  /** Visual style of the loading indicator */
-  variant?: LoadingVariant;
+  /** Which animation plays. Not chrome, so it is `kind`, not `variant`.
+   * @default "spinner" */
+  kind?: LoadingKind;
   /** Accessible label for screen readers */
   label?: string;
   /** Whether to center the loading indicator in its container */
@@ -23,7 +24,7 @@ export interface LoadingProps extends React.HTMLAttributes<HTMLDivElement> {
   fill?: boolean;
   /** Whether to show the loading indicator with a backdrop overlay */
   overlay?: boolean;
-  /** Color variant - uses accent color by default, 'current' inherits text color */
+  /** Colour. `accent` by default; `current` inherits the surrounding text colour */
   color?: "accent" | "current" | "muted";
 }
 
@@ -37,8 +38,8 @@ export interface LoadingInlineProps extends React.HTMLAttributes<HTMLSpanElement
 export interface LoadingScreenProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Loading indicator size */
   size?: LoadingSize;
-  /** Loading indicator variant */
-  variant?: LoadingVariant;
+  /** Which animation plays */
+  kind?: LoadingKind;
   /** Optional label text to display */
   label?: string;
   /** Whether to show the label text visually */
@@ -93,7 +94,7 @@ function PulseAnimation({ className }: { className?: string }) {
 const LoadingRoot = React.forwardRef<HTMLDivElement, LoadingProps>(function LoadingRoot(
   {
     size = "md",
-    variant = "spinner",
+    kind = "spinner",
     label = "Loading...",
     centered = false,
     fill = false,
@@ -107,7 +108,7 @@ const LoadingRoot = React.forwardRef<HTMLDivElement, LoadingProps>(function Load
   const classes = [
     styles.loading,
     styles[size],
-    styles[variant],
+    styles[kind],
     styles[`color-${color}`],
     centered && styles.centered,
     fill && styles.fill,
@@ -118,10 +119,10 @@ const LoadingRoot = React.forwardRef<HTMLDivElement, LoadingProps>(function Load
     .join(" ");
 
   const animation =
-    variant === "dots" ? (
-      <DotsAnimation className={styles.dots} />
-    ) : variant === "pulse" ? (
-      <PulseAnimation className={styles.pulse} />
+    kind === "dots" ? (
+      <DotsAnimation className={styles.dotsTrack} />
+    ) : kind === "pulse" ? (
+      <PulseAnimation className={styles.pulseTrack} />
     ) : (
       <SpinnerIcon className={styles.spinnerIcon} />
     );
@@ -171,7 +172,7 @@ function LoadingInline({
 
 function LoadingScreen({
   size = "lg",
-  variant = "spinner",
+  kind = "spinner",
   label = "Loading...",
   showLabel = false,
   className,
@@ -181,7 +182,7 @@ function LoadingScreen({
 
   return (
     <div className={classes} role="status" aria-label={label} aria-live="polite" {...htmlProps}>
-      <LoadingRoot size={size} variant={variant} label={label} />
+      <LoadingRoot size={size} kind={kind} label={label} />
       {showLabel && <span className={styles.screenLabel}>{label}</span>}
     </div>
   );

package/src/components/Main/Main.contract.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Main",
-  "description": "Canonical page composition owning gutter, measure, and vertical rhythm.",
+  "description": "Owns a page's gutters, reading measure, and vertical rhythm.",
   "category": "layout",
   "tags": ["main", "page", "layout", "compound"],
   "status": "stable",
@@ -45,11 +45,19 @@
     }
   },
   "usage": {
-    "when": ["Composing a page header, description, content, and footer"],
-    "whenNot": ["Application shell navigation (use AppShell)"],
+    "when": [
+      "Laying out a page's header, description, content, and footer",
+      "Giving a page one consistent gutter and measure"
+    ],
+    "whenNot": [
+      "Shell-level navigation chrome (use AppShell)",
+      "Arbitrary spacing inside a component (use Stack or Box)"
+    ],
     "guidelines": [
-      "Use one Main gutter owner per page",
-      "Compose page regions with Main.Header, Main.Description, Main.Content, and Main.Footer"
+      "One Main per page owns the gutters — do not nest them",
+      "measure=\"narrow\" caps content for reading; \"full\" uses the whole canvas",
+      "Compose regions with Main.Header, Main.Description, Main.Content, Main.Footer",
+      "Main.Description caps itself at 68ch regardless of measure"
     ],
     "accessibility": [
       "Use the default main element unless an existing shell already owns the main landmark"
@@ -58,13 +66,13 @@
   "examples": [
     {
       "name": "Full Measure",
-      "description": "Page composition that uses the full available canvas",
-      "code": "<Main measure=\"full\">\n  <Main.Header>Page statement</Main.Header>\n  <Main.Description>Supporting page context.</Main.Description>\n  <Main.Content>Page content</Main.Content>\n  <Main.Footer>Page actions</Main.Footer>\n</Main>"
+      "description": "Content fills the canvas, inset only by the page gutter.",
+      "code": "import { Box } from '@/components/Box';\nimport { Main } from '@/components/Main';\n\n<Box width=\"100%\" border rounded=\"md\">\n  <Main measure=\"full\">\n    <Main.Header>Findings</Main.Header>\n    <Main.Description>\n      Every governance finding raised against this repository, newest first.\n    </Main.Description>\n    <Main.Content>\n      Content stretches edge to edge, inset only by the page gutter.\n    </Main.Content>\n    <Main.Footer>Export report</Main.Footer>\n  </Main>\n</Box>"
     },
     {
       "name": "Narrow Measure",
-      "description": "Readable page composition constrained to the canonical 800px measure",
-      "code": "<Main measure=\"narrow\">\n  <Main.Header>Settings</Main.Header>\n  <Main.Description>Manage the workspace contract.</Main.Description>\n  <Main.Content>Settings content</Main.Content>\n  <Main.Footer>Save changes</Main.Footer>\n</Main>"
+      "description": "Caps content at the reading measure and centres it on wide screens.",
+      "code": "import { Box } from '@/components/Box';\nimport { Main } from '@/components/Main';\n\n<Box width=\"100%\" border rounded=\"md\">\n  <Main measure=\"narrow\">\n    <Main.Header>Settings</Main.Header>\n    <Main.Description>\n      Manage the workspace contract, canonical components, and token files.\n    </Main.Description>\n    <Main.Content>\n      Content is capped at the reading measure and centred, so long prose stays\n      comfortable to read on wide displays.\n    </Main.Content>\n    <Main.Footer>Save changes</Main.Footer>\n  </Main>\n</Box>"
     }
   ],
   "ai": {

package/src/components/Markdown/Markdown.contract.json

@@ -1,16 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Markdown",
-  "description": "Renders markdown strings as styled prose using react-markdown and remark-gfm. Supports headings, lists, tables, code blocks, blockquotes, and more.",
+  "description": "Turns a Markdown string into styled headings, lists, tables, code, and quotes.",
   "category": "display",
-  "tags": [
-    "markdown",
-    "prose",
-    "content",
-    "text",
-    "ai",
-    "chat"
-  ],
+  "tags": ["markdown", "prose", "content", "text", "ai", "chat"],
   "status": "stable",
   "dependencies": [
     {
@@ -26,11 +19,7 @@
   ],
   "sourcePath": "src/components/Markdown/index.tsx",
   "exportName": "Markdown",
-  "propsSummary": [
-    "content: string (required)",
-    "components: object",
-    "className: string"
-  ],
+  "propsSummary": ["content: string (required)", "components: object", "className: string"],
   "props": {
     "content": {
       "type": "string",
@@ -50,50 +39,45 @@
   },
   "usage": {
     "when": [
-      "Rendering AI/LLM response content",
-      "Displaying user-authored markdown text",
-      "Showing documentation or readme content",
-      "Rich text display without a WYSIWYG editor"
+      "Rendering an LLM reply",
+      "Showing text a user wrote in Markdown",
+      "Docs or readme content inside the app"
     ],
     "whenNot": [
-      "Plain text without formatting (use Text)",
-      "Editing markdown (use a markdown editor component)",
-      "Rendering trusted HTML directly (use dangerouslySetInnerHTML)"
+      "The string has no formatting (use Text)",
+      "The user needs to edit it (use an editor)"
     ],
     "guidelines": [
-      "Install react-markdown and remark-gfm as peer dependencies",
-      "Use the components prop to override default element rendering",
-      "Content is sanitized by react-markdown by default",
-      "The parser is loaded on demand, so the first render on a page is the plain-text fallback and parsed output arrives a tick later; call Markdown.preload() at startup to skip that frame",
-      "Falls back to plain text paragraphs if react-markdown is not installed",
-      "Standard div props (id, style, aria-*, data-*) are forwarded to the Markdown wrapper"
+      "react-markdown and remark-gfm are peer dependencies — install both",
+      "The parser loads on demand, so the first frame is plain text; call Markdown.preload() at startup to skip it",
+      "Without react-markdown installed it degrades to plain paragraphs",
+      "components overrides how any element renders",
+      "react-markdown sanitises the content for you"
     ],
     "accessibility": [
-      "Rendered HTML follows semantic structure (headings, lists, tables)",
-      "Links are rendered as proper anchor elements",
-      "Images include alt text from markdown syntax",
-      "Tables use proper th/td structure for screen readers"
+      "Output is real headings, lists, and tables",
+      "Links render as anchors, images keep their alt text"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic markdown with headings, paragraphs, inline code, lists, and blockquote",
+      "description": "Headings, emphasis, lists, and quotes all pick up the type scale.",
       "code": "<Markdown content={`# Hello World\n\nThis is a paragraph with **bold text** and *italic text*.\n\nHere is some \\`inline code\\` within a sentence.\n\n- First item\n- Second item\n- Third item\n\n> A blockquote for emphasis.\n`} />"
     },
     {
       "name": "GFM Table",
-      "description": "GitHub Flavored Markdown with tables and task lists",
+      "description": "remark-gfm adds tables and checkbox items on top of the basics.",
       "code": "<Markdown content={`## Data Overview\n\n| Feature    | Status    | Priority |\n|------------|-----------|----------|\n| Markdown   | Done      | High     |\n| Tables     | Done      | Medium   |\n| Task Lists | Planned   | Low      |\n\nNotes:\n- [x] Support GFM tables\n- [x] Support task lists\n- [ ] Syntax highlighting\n`} />"
     },
     {
       "name": "Code Block",
-      "description": "Markdown with fenced code blocks and inline code",
-      "code": "<Markdown content={`## Code Example\\n\\nHere is a JavaScript function:\\n\\n```js\\nfunction greet(name) {\\n  return \\`Hello, ${name}!\\`;\\n}\\n```\\n\\nAnd some inline code: \\`const x = 42;\\``} />"
+      "description": "Fenced blocks get the same code surface as CodeBlock.",
+      "code": "<Markdown content={`## Code Example\n\nHere is a JavaScript function:\n\n```js\nfunction greet(name) {\n  return 'Hello, ' + name;\n}\n```\n\nAnd some inline code: \\`const x = 42;\\``} />"
     },
     {
       "name": "Mixed Content",
-      "description": "Complex markdown mixing headings, lists, tables, blockquotes, and task lists",
+      "description": "A realistic document — the worst case worth checking.",
       "code": "<Markdown content={`# Project Update\n\n## Summary\n\nThe project is progressing well. Here are the **key highlights**:\n\n1. Completed the *design system* components\n2. Added markdown rendering support\n3. Integrated with the documentation site\n\n### Performance Metrics\n\n| Metric      | Before | After |\n|-------------|--------|-------|\n| Bundle Size | 142kb  | 98kb  |\n| Load Time   | 1.2s   | 0.8s  |\n| Lighthouse  | 72     | 95    |\n\n> These improvements were achieved through tree-shaking and code splitting.\n\n### Next Steps\n\n- [ ] Add syntax highlighting\n- [ ] Support custom themes\n- [x] GFM table support\n`} />"
     }
   ],
@@ -121,16 +105,11 @@
       "className: string - Additional CSS class",
       "Forwards standard HTML div attributes to the wrapper element"
     ],
-    "a11yRules": [
-      "A11Y_SEMANTIC_HTML"
-    ]
+    "a11yRules": ["A11Y_SEMANTIC_HTML"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root",
-      "preload"
-    ]
+    "subComponents": ["Root", "preload"]
   },
   "provenance": {
     "source": "migrated",