@usefragments/ui 1.6.0 → 2.0.0

package/src/components/CodeBlock/index.tsx

@@ -6,8 +6,10 @@ import { useState, useCallback, useEffect, useMemo } from "react";
 // Lazy-loaded dependency (shiki)
 // ============================================
 
+type ShikiThemeInput = string | typeof import("./css-variables-theme").FUI_CSS_VARIABLES_THEME;
+
 let _codeToHtml:
-  | ((code: string, options: { lang: string; theme: string }) => Promise<string>)
+  | ((code: string, options: { lang: string; theme: ShikiThemeInput }) => Promise<string>)
   | null = null;
 let _shikiLoadPromise: Promise<void> | null = null;
 let _shikiFailed = false;
@@ -27,8 +29,12 @@ async function loadShikiDeps() {
   }
   await _shikiLoadPromise;
 }
-import { TabsRoot, TabsList, Tab, TabsPanel } from "../Tabs";
+import { Button } from "../Button";
+import { IconButton } from "../IconButton";
+import { TabsRoot, TabsList, Tab, TabsPanel, type TabsVariant } from "../Tabs";
+import { FUI_CSS_VARIABLES_THEME } from "./css-variables-theme";
 import styles from "./CodeBlock.module.scss";
+import { isDevelopmentBuild, isProductionBuild } from "../../utils/env";
 
 export type CodeBlockLanguage =
   | "tsx"
@@ -76,6 +82,7 @@ const LANGUAGE_ALIASES: Partial<Record<CodeBlockLanguage, string>> = {
 
 /** Available syntax highlighting themes */
 export type CodeBlockTheme =
+  | "css-variables"
   | "synthwave-84"
   | "github-dark"
   | "github-light"
@@ -95,7 +102,7 @@ export interface CodeBlockProps extends React.HTMLAttributes<HTMLDivElement> {
   code: string;
   /** Programming language for syntax highlighting */
   language?: CodeBlockLanguage;
-  /** Syntax highlighting theme */
+  /** Syntax highlighting theme. Default follows `--fui-code-token-*` via shiki css-variables. */
   theme?: CodeBlockTheme;
   /** Show copy button */
   showCopy?: boolean;
@@ -125,6 +132,12 @@ export interface CodeBlockProps extends React.HTMLAttributes<HTMLDivElement> {
   defaultCollapsed?: boolean;
   /** Number of lines to show when collapsed */
   collapsedLines?: number;
+  /**
+   * Collapse control copy. `lines` keeps “Show N more lines” / “Show less”
+   * (docs prose). `expand` is one right-aligned Expand / Collapse control
+   * for preview+code capsules.
+   */
+  collapseAction?: "lines" | "expand";
   /** Compact mode with reduced padding */
   compact?: boolean;
   /** Show a persistent copy button (always visible, uses Button component) */
@@ -547,14 +560,22 @@ function processShikiHtml(html: string, options: ProcessOptions): string {
     const lineClass = lineClasses.join(" ");
     const diffMarker = isAdded ? "+" : isRemoved ? "-" : " ";
 
-    if (showLineNumbers || hasDiff) {
-      const lineNumHtml = showLineNumbers
-        ? `<span class="line-number">${displayLineNum}</span>`
+    const lineNumHtml =
+      showLineNumbers || hasDiff
+        ? `${showLineNumbers ? `<span class="line-number">${displayLineNum}</span>` : ""}${
+            hasDiff ? `<span class="diff-marker">${diffMarker}</span>` : ""
+          }`
         : "";
-      const diffMarkerHtml = hasDiff ? `<span class="diff-marker">${diffMarker}</span>` : "";
-      return `<span class="${lineClass}">${lineNumHtml}${diffMarkerHtml}${line}</span>`;
+
+    // Shiki already wraps each row in <span class="line">; merge into that span
+    // instead of nesting a second .line (which breaks the inline-block row layout).
+    if (/^<span class="line([^"]*)">/.test(line)) {
+      return line.replace(
+        /^<span class="line([^"]*)">/,
+        `<span class="${lineClass}$1">${lineNumHtml}`
+      );
     }
-    return `<span class="${lineClass}">${line}</span>`;
+    return `<span class="${lineClass}">${lineNumHtml}${line}</span>`;
   });
 
   // Reconstruct the HTML
@@ -565,7 +586,7 @@ const CodeBlockBase = React.forwardRef<HTMLDivElement, CodeBlockProps>(function
   {
     code,
     language = "tsx",
-    theme = "one-dark-pro",
+    theme = "css-variables",
     showCopy = true,
     title,
     filename,
@@ -580,6 +601,7 @@ const CodeBlockBase = React.forwardRef<HTMLDivElement, CodeBlockProps>(function
     collapsible = false,
     defaultCollapsed = false,
     collapsedLines = 5,
+    collapseAction = "lines",
     compact = false,
     persistentCopy = false,
     copyPlacement = "auto",
@@ -591,7 +613,10 @@ const CodeBlockBase = React.forwardRef<HTMLDivElement, CodeBlockProps>(function
   ref
 ) {
   const [copied, setCopied] = useState(false);
-  const [highlight, setHighlight] = useState<{ html: string; loading: boolean }>({ html: '', loading: true });
+  const [highlight, setHighlight] = useState<{ html: string; loading: boolean }>({
+    html: "",
+    loading: true,
+  });
   const [isCollapsed, setIsCollapsed] = useState(defaultCollapsed);
 
   const trimmedCode = useMemo(() => normalizeCode(code, language), [code, language]);
@@ -624,7 +649,7 @@ const CodeBlockBase = React.forwardRef<HTMLDivElement, CodeBlockProps>(function
       const fallbackHtml = `<pre class="shiki"><code>${escapeHtml(visibleCode)}</code></pre>`;
 
       if (_shikiFailed || !_codeToHtml) {
-        if (_shikiFailed && process.env.NODE_ENV === "development") {
+        if (_shikiFailed && isDevelopmentBuild()) {
           console.warn(
             "[@usefragments/ui] CodeBlock: shiki is not installed. " +
               "Install it with: npm install shiki"
@@ -635,7 +660,9 @@ const CodeBlockBase = React.forwardRef<HTMLDivElement, CodeBlockProps>(function
 
       try {
         const resolvedLang = LANGUAGE_ALIASES[language] || language;
-        const html = await _codeToHtml(visibleCode, { lang: resolvedLang, theme });
+        const shikiTheme: ShikiThemeInput =
+          theme === "css-variables" ? FUI_CSS_VARIABLES_THEME : theme;
+        const html = await _codeToHtml(visibleCode, { lang: resolvedLang, theme: shikiTheme });
         return processShikiHtml(html, {
           showLineNumbers,
           startLineNumber,
@@ -644,7 +671,7 @@ const CodeBlockBase = React.forwardRef<HTMLDivElement, CodeBlockProps>(function
           removedLines: removedSet,
         });
       } catch (err) {
-        if (process.env.NODE_ENV !== "production") {
+        if (!isProductionBuild()) {
           console.error("Syntax highlighting failed:", err);
         }
         return fallbackHtml;
@@ -679,7 +706,7 @@ const CodeBlockBase = React.forwardRef<HTMLDivElement, CodeBlockProps>(function
       setTimeout(() => setCopied(false), 2000);
       onCopy?.();
     } catch (err) {
-      if (process.env.NODE_ENV !== "production") {
+      if (!isProductionBuild()) {
         console.error("Failed to copy:", err);
       }
     }
@@ -714,15 +741,20 @@ const CodeBlockBase = React.forwardRef<HTMLDivElement, CodeBlockProps>(function
     : undefined;
 
   return (
-    <div ref={ref} {...htmlProps} className={classNames} data-theme="dark">
-      {title && <div className={styles.title}>{title}</div>}
-      <div className={wrapperClasses} style={wrapperStyle}>
+    <div ref={ref} {...htmlProps} className={classNames} data-slot="code-block">
+      {title && (
+        <div className={styles.title} data-slot="code-block-title">
+          {title}
+        </div>
+      )}
+      <div className={wrapperClasses} style={wrapperStyle} data-slot="code-block-frame">
         {shouldRenderHeader && (
           <div className={styles.header}>
             <span className={styles.filename}>{filename ?? ""}</span>
             {shouldShowHeaderCopy && (
-              <button
-                type="button"
+              <IconButton
+                variant="ghost"
+                size="sm"
                 onClick={handleCopy}
                 className={`${styles.copyButton} ${copied ? styles.copied : ""}`}
                 aria-label={copied ? "Copied!" : "Copy code"}
@@ -732,19 +764,20 @@ const CodeBlockBase = React.forwardRef<HTMLDivElement, CodeBlockProps>(function
                 ) : (
                   <CopyIcon className={styles.icon} />
                 )}
-              </button>
+              </IconButton>
             )}
           </div>
         )}
         {shouldShowOverlayCopy && (
-          <button
-            type="button"
+          <IconButton
+            variant="ghost"
+            size="sm"
             onClick={handleCopy}
             className={`${styles.copyButton} ${styles.copyOverlay} ${copied ? styles.copied : ""}`}
             aria-label={copied ? "Copied!" : "Copy code"}
           >
             {copied ? <CheckIcon className={styles.icon} /> : <CopyIcon className={styles.icon} />}
-          </button>
+          </IconButton>
         )}
         {highlight.loading ? (
           <div className={styles.loading} style={codeContainerStyle}>
@@ -760,24 +793,33 @@ const CodeBlockBase = React.forwardRef<HTMLDivElement, CodeBlockProps>(function
           />
         )}
         {persistentCopy && (
-          <button
-            type="button"
+          <IconButton
+            variant="ghost"
+            size="sm"
             onClick={handleCopy}
             className={`${styles.persistentCopy} ${styles.copyButton} ${styles.copyOverlay} ${copied ? styles.copied : ""}`}
             aria-label={copied ? "Copied!" : "Copy code"}
           >
             {copied ? <CheckIcon className={styles.icon} /> : <CopyIcon className={styles.icon} />}
-          </button>
+          </IconButton>
         )}
         {shouldShowCollapse && (
-          <button
-            type="button"
+          <Button
+            variant="ghost"
+            size="sm"
+            fullWidth
             onClick={toggleCollapsed}
-            className={styles.collapseButton}
+            className={
+              collapseAction === "expand"
+                ? `${styles.collapseButton} ${styles.collapseExpand}`
+                : styles.collapseButton
+            }
             aria-expanded={!isCollapsed}
             aria-label={isCollapsed ? "Expand code" : "Collapse code"}
           >
-            {isCollapsed ? (
+            {collapseAction === "expand" ? (
+              <span>{isCollapsed ? "Expand" : "Collapse"}</span>
+            ) : isCollapsed ? (
               <>
                 <ChevronDownIcon className={styles.icon} />
                 <span>Show {totalLines - collapsedLines} more lines</span>
@@ -788,7 +830,7 @@ const CodeBlockBase = React.forwardRef<HTMLDivElement, CodeBlockProps>(function
                 <span>Show less</span>
               </>
             )}
-          </button>
+          </Button>
         )}
       </div>
       {caption && <div className={styles.caption}>{caption}</div>}
@@ -828,12 +870,20 @@ export interface TabbedCodeBlockProps {
   showLineNumbers?: boolean;
   /** Syntax highlighting theme (applies to all tabs) */
   theme?: CodeBlockTheme;
-  /** Tab list visual style */
-  tabsVariant?: "underline" | "pills";
+  /** Tab list chrome: `soft` (default) is the filled rail, `ghost` the underline strip. */
+  tabsVariant?: TabsVariant;
   /** Enable word wrapping for long lines */
   wordWrap?: boolean;
   /** Maximum height in pixels (enables scrolling) */
   maxHeight?: number;
+  /** Allow collapsing/expanding each tab's code (forwarded to every panel) */
+  collapsible?: boolean;
+  /** Initial collapsed state (only applies when collapsible is true) */
+  defaultCollapsed?: boolean;
+  /** Number of lines to show when collapsed */
+  collapsedLines?: number;
+  /** Forwarded to every panel (see CodeBlock `collapseAction`) */
+  collapseAction?: "lines" | "expand";
   /** Additional class name */
   className?: string;
   /** Callback fired when a tab's copy button is clicked. Receives the tab label. */
@@ -849,9 +899,13 @@ function TabbedCodeBlock({
   copyPlacement = "auto",
   showLineNumbers = false,
   theme,
-  tabsVariant = "pills",
+  tabsVariant = "soft",
   wordWrap,
   maxHeight,
+  collapsible,
+  defaultCollapsed,
+  collapsedLines,
+  collapseAction,
   className,
   onCopy,
 }: TabbedCodeBlockProps) {
@@ -864,28 +918,37 @@ function TabbedCodeBlock({
           {tabs.map((tab, index) => {
             const tabValue = tab.value ?? tab.label;
             return (
-            <Tab key={`${tabValue}-${index}`} value={tabValue}>
-              {tab.label}
-            </Tab>
+              <Tab key={`${tabValue}-${index}`} value={tabValue}>
+                {tab.label}
+              </Tab>
             );
           })}
         </TabsList>
         {tabs.map((tab, index) => {
           const tabValue = tab.value ?? tab.label;
           return (
-          <TabsPanel key={`${tabValue}-panel-${index}`} value={tabValue} flush className={styles.tabbedPanel}>
-            <CodeBlockBase
-              code={tab.code}
-              language={tab.language}
-              theme={theme}
-              showCopy={showCopy}
-              copyPlacement={copyPlacement}
-              showLineNumbers={showLineNumbers}
-              wordWrap={wordWrap}
-              maxHeight={maxHeight}
-              onCopy={onCopy ? () => onCopy(tab.label) : undefined}
-            />
-          </TabsPanel>
+            <TabsPanel
+              key={`${tabValue}-panel-${index}`}
+              value={tabValue}
+              flush
+              className={styles.tabbedPanel}
+            >
+              <CodeBlockBase
+                code={tab.code}
+                language={tab.language}
+                theme={theme}
+                showCopy={showCopy}
+                copyPlacement={copyPlacement}
+                showLineNumbers={showLineNumbers}
+                wordWrap={wordWrap}
+                maxHeight={maxHeight}
+                collapsible={collapsible}
+                defaultCollapsed={defaultCollapsed}
+                collapsedLines={collapsedLines}
+                collapseAction={collapseAction}
+                onCopy={onCopy ? () => onCopy(tab.label) : undefined}
+              />
+            </TabsPanel>
           );
         })}
       </TabsRoot>

package/src/components/Collapsible/Collapsible.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Collapsible",
-  "description": "An interactive component that expands/collapses to show or hide content",
+  "description": "Shows or hides one region of content behind a trigger.",
   "category": "layout",
-  "tags": [
-    "collapsible",
-    "expandable",
-    "accordion",
-    "disclosure",
-    "toggle"
-  ],
+  "tags": ["collapsible", "expandable", "accordion", "disclosure", "toggle"],
   "status": "stable",
   "sourcePath": "src/components/Collapsible/index.tsx",
   "exportName": "Collapsible",
@@ -51,22 +45,21 @@
   },
   "usage": {
     "when": [
-      "Showing/hiding additional content on demand",
-      "Building accordions or expandable sections",
-      "Collapsible navigation sections",
-      "FAQ sections with expandable answers",
-      "Settings panels with grouped options"
+      "Detail most readers do not need",
+      "Optional or advanced settings",
+      "Navigation sections that fold away",
+      "Building a disclosure the other components do not cover"
     ],
     "whenNot": [
-      "Single item disclosure (use Accordion instead)",
-      "Navigation menus with complex interactions (use Menu)",
-      "Modal or overlay content (use Dialog or Popover)"
+      "Several sections that should coordinate (use Accordion)",
+      "Content that must overlay the page (use Dialog or Popover)",
+      "Action lists (use Menu)"
     ],
     "guidelines": [
-      "Use clear trigger labels that indicate expandable content",
-      "Consider defaultOpen for primary content users often need",
-      "Keep trigger text concise but descriptive",
-      "Use chevron icons consistently to indicate collapsible state"
+      "The trigger should say what opens, not 'click here'",
+      "defaultOpen for content most users want on arrival",
+      "Keep the trigger to a short phrase",
+      "Keep the chevron direction consistent across the page"
     ],
     "accessibility": [
       "Trigger must have aria-expanded to indicate state",
@@ -78,32 +71,32 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Basic collapsible with trigger and content",
+      "description": "Starts closed and opens on click.",
       "code": "<Collapsible>\n  <Collapsible.Trigger>Click to expand</Collapsible.Trigger>\n  <Collapsible.Content>\n    <p>This content is hidden by default and revealed when the trigger is clicked.</p>\n  </Collapsible.Content>\n</Collapsible>"
     },
     {
       "name": "Default Open",
-      "description": "Collapsible that starts in the expanded state",
+      "description": "Starts open for content most users want.",
       "code": "<Collapsible defaultOpen>\n  <Collapsible.Trigger>Section Title</Collapsible.Trigger>\n  <Collapsible.Content>\n    <p>This content is visible by default. Click the trigger to collapse.</p>\n  </Collapsible.Content>\n</Collapsible>"
     },
     {
       "name": "Chevron Start",
-      "description": "Collapsible with chevron icon on the left",
+      "description": "Marker leads the label instead of trailing it.",
       "code": "<Collapsible>\n  <Collapsible.Trigger chevronPosition=\"start\">Navigation</Collapsible.Trigger>\n  <Collapsible.Content>\n    <ul style={{ margin: 0, paddingLeft: '1.5rem' }}>\n      <li>Dashboard</li>\n      <li>Settings</li>\n      <li>Profile</li>\n    </ul>\n  </Collapsible.Content>\n</Collapsible>"
     },
     {
       "name": "No Chevron",
-      "description": "Collapsible without chevron indicator",
+      "description": "Bare trigger when the surrounding layout signals enough.",
       "code": "<Collapsible>\n  <Collapsible.Trigger showChevron={false}>Show more details</Collapsible.Trigger>\n  <Collapsible.Content>\n    <p>Hidden details that appear when triggered.</p>\n  </Collapsible.Content>\n</Collapsible>"
     },
     {
       "name": "Disabled",
-      "description": "Collapsible in disabled state",
+      "description": "Locked shut and skipped by the keyboard.",
       "code": "<Collapsible disabled>\n  <Collapsible.Trigger>Cannot toggle (disabled)</Collapsible.Trigger>\n  <Collapsible.Content>\n    <p>This content cannot be shown because the collapsible is disabled.</p>\n  </Collapsible.Content>\n</Collapsible>"
     },
     {
       "name": "Multiple Sections",
-      "description": "Multiple independent collapsible sections",
+      "description": "Independent regions that ignore each other.",
       "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '4px' }}>\n  <Collapsible defaultOpen>\n    <Collapsible.Trigger>Getting Started</Collapsible.Trigger>\n    <Collapsible.Content>\n      <p>Introduction and setup instructions.</p>\n    </Collapsible.Content>\n  </Collapsible>\n  <Collapsible>\n    <Collapsible.Trigger>Advanced Usage</Collapsible.Trigger>\n    <Collapsible.Content>\n      <p>Advanced configuration options.</p>\n    </Collapsible.Content>\n  </Collapsible>\n  <Collapsible>\n    <Collapsible.Trigger>API Reference</Collapsible.Trigger>\n    <Collapsible.Content>\n      <p>Complete API documentation.</p>\n    </Collapsible.Content>\n  </Collapsible>\n</div>"
     }
   ],
@@ -131,19 +124,11 @@
       "onOpenChange: (open: boolean) => void - state change callback",
       "disabled: boolean - prevents interaction"
     ],
-    "a11yRules": [
-      "A11Y_EXPANDED_STATE",
-      "A11Y_REGION_LABEL",
-      "A11Y_KEYBOARD_NAV"
-    ]
+    "a11yRules": ["A11Y_EXPANDED_STATE", "A11Y_REGION_LABEL", "A11Y_KEYBOARD_NAV"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root",
-      "Trigger",
-      "Content"
-    ]
+    "subComponents": ["Root", "Trigger", "Content"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Collapsible/Collapsible.module.scss

@@ -25,11 +25,6 @@
   &:focus-visible {
     @include focus-ring;
   }
-
-  &:disabled {
-    opacity: 0.5;
-    cursor: not-allowed;
-  }
 }
 
 .triggerContent {
@@ -72,8 +67,7 @@
 }
 
 .disabled .trigger {
-  opacity: 0.5;
-  cursor: not-allowed;
+  @include disabled-state;
 }
 
 @media (prefers-reduced-motion: reduce) {

package/src/components/ColorPicker/ColorPicker.contract.json

@@ -1,16 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "ColorPicker",
-  "description": "Color selection control with hex input and visual picker. Displays a swatch that opens a full color picker on click.",
-  "category": "forms",
-  "tags": [
-    "color",
-    "picker",
-    "input",
-    "hex",
-    "swatch",
-    "theme"
-  ],
+  "description": "Selects a color through a visual picker and hexadecimal input.",
+  "category": "inputs",
+  "tags": ["color", "picker", "input", "hex", "swatch", "theme"],
   "status": "stable",
   "dependencies": [
     {
@@ -88,11 +81,7 @@
       "description": "Size variant",
       "default": "md",
       "required": false,
-      "values": [
-        "sm",
-        "md",
-        "lg"
-      ]
+      "values": ["sm", "md", "lg"]
     },
     "showInput": {
       "type": "boolean",
@@ -103,68 +92,67 @@
   },
   "usage": {
     "when": [
-      "Theme customization interfaces",
-      "Brand color selection",
-      "Design tool color inputs",
-      "User preference settings for colors"
+      "Theme and brand customisation",
+      "Any colour the user must pick freely",
+      "Design tool inputs"
     ],
     "whenNot": [
-      "Predefined color options only (use RadioGroup with swatches)",
-      "Simple color display without editing (use a colored Badge)",
-      "Color indication only (use semantic color tokens)"
+      "A fixed palette (use RadioGroup with swatches)",
+      "Showing a colour without editing it (use a tinted Badge)",
+      "Status colour that should come from a token"
     ],
     "guidelines": [
-      "Always provide a label to describe what the color is for",
-      "Use helperText to explain color usage or constraints",
-      "Consider providing color presets alongside the picker for common choices",
-      "Validate hex format (#RRGGBB) on input"
+      "Label says what the colour is for",
+      "Use helperText for constraints, such as contrast rules",
+      "Offer presets next to the picker for the common choices",
+      "Validate the hex as #RRGGBB before accepting it"
     ],
     "accessibility": [
-      "Label is associated with the color input",
-      "Swatch button has appropriate aria-label",
-      "Color picker popup is keyboard accessible",
-      "Hex input allows direct text entry"
+      "Label is tied to the hex input",
+      "The swatch button carries its own aria-label",
+      "The picker popup is reachable from the keyboard",
+      "Users can type a hex instead of dragging"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic color picker with label",
+      "description": "Swatch opens the picker; the hex field accepts typing.",
       "code": "<ColorPicker\n  label=\"Brand Color\"\n  defaultValue=\"#3b82f6\"\n/>"
     },
     {
       "name": "With Helper Text",
-      "description": "Color picker with helper text",
+      "description": "Supporting line says where the colour will be used.",
       "code": "<ColorPicker\n  label=\"Primary Color\"\n  defaultValue=\"#10b981\"\n  helperText=\"This color will be used for buttons and links\"\n/>"
     },
     {
       "name": "Controlled",
-      "description": "Controlled color picker that logs changes",
+      "description": "The parent owns the value and sees every change.",
       "code": "<ControlledColorPickerDemo />"
     },
     {
       "name": "Multiple Pickers",
-      "description": "Multiple color pickers for theme configuration",
+      "description": "A stacked set reads as one palette.",
       "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '240px' }}>\n  <ColorPicker label=\"Primary\" defaultValue=\"#3b82f6\" />\n  <ColorPicker label=\"Success\" defaultValue=\"#22c55e\" />\n  <ColorPicker label=\"Warning\" defaultValue=\"#f59e0b\" />\n  <ColorPicker label=\"Danger\" defaultValue=\"#ef4444\" />\n</div>"
     },
     {
       "name": "Compact",
-      "description": "Small size with swatch only (no input)",
+      "description": "showInput={false} drops the hex field, leaving a swatch row.",
       "code": "<div style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>\n  <ColorPicker defaultValue=\"#ef4444\" size=\"sm\" showInput={false} />\n  <ColorPicker defaultValue=\"#f59e0b\" size=\"sm\" showInput={false} />\n  <ColorPicker defaultValue=\"#22c55e\" size=\"sm\" showInput={false} />\n  <ColorPicker defaultValue=\"#3b82f6\" size=\"sm\" showInput={false} />\n</div>"
     },
     {
       "name": "Sizes",
-      "description": "Different size variants",
+      "description": "Three swatch sizes: sm, md, lg.",
       "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '240px' }}>\n  <ColorPicker label=\"Small\" defaultValue=\"#3b82f6\" size=\"sm\" />\n  <ColorPicker label=\"Medium (default)\" defaultValue=\"#3b82f6\" size=\"md\" />\n  <ColorPicker label=\"Large\" defaultValue=\"#3b82f6\" size=\"lg\" />\n</div>"
     },
     {
       "name": "Error State",
-      "description": "Color picker with error styling",
-      "code": "<ColorPicker\n  label=\"Brand Color\"\n  defaultValue=\"#000000\"\n  error\n  helperText=\"Please select a valid brand color\"\n/>"
+      "description": "Red border on the hex field, and the reason below it.",
+      "code": "<ColorPicker\n  label=\"Brand Color\"\n  defaultValue=\"#7c3aed\"\n  error\n  helperText=\"This color fails contrast against the page background\"\n/>"
     },
     {
       "name": "Disabled",
-      "description": "Disabled color picker",
+      "description": "Swatch will not open and the hex field will not accept typing.",
       "code": "<ColorPicker\n  label=\"Locked Color\"\n  defaultValue=\"#64748b\"\n  helperText=\"This color cannot be changed\"\n  disabled\n/>"
     }
   ],
@@ -198,18 +186,11 @@
       "size: sm|md|lg - size variant",
       "showInput: boolean - show hex input field"
     ],
-    "a11yRules": [
-      "A11Y_LABEL_REQUIRED",
-      "A11Y_FOCUS_VISIBLE",
-      "A11Y_TARGET_SIZE_MIN"
-    ]
+    "a11yRules": ["A11Y_LABEL_REQUIRED", "A11Y_FOCUS_VISIBLE", "A11Y_TARGET_SIZE_MIN"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root",
-      "preload"
-    ]
+    "subComponents": ["Root", "preload"]
   },
   "provenance": {
     "source": "migrated",