@usefragments/ui 1.6.0 → 2.0.0

package/src/components/Chip/Chip.contract.json

@@ -1,15 +1,15 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Chip",
-  "description": "Interactive pill-shaped element for filtering, selecting, and tagging. Supports single and multi-select via Chip.Group.",
-  "category": "forms",
+  "description": "Pill control for filtering, multi-select, and removable tags.",
+  "category": "inputs",
   "tags": ["chip", "tag", "filter", "selection", "multi-select", "action"],
   "status": "stable",
   "sourcePath": "src/components/Chip/index.tsx",
   "exportName": "Chip",
   "propsSummary": [
     "children: node (required)",
-    "variant: filled|outlined|outline|soft (default: filled)",
+    "variant: solid|outline|soft (default: solid)",
     "size: xs|sm|md|lg (default: xs)",
     "selected: boolean (default: false)",
     "icon: node",
@@ -27,10 +27,10 @@
     },
     "variant": {
       "type": "enum",
-      "description": "Visual style variant",
-      "default": "filled",
+      "description": "Chrome family. solid is the tinted pill; outline is hairline-bordered; soft is info-tinted for a suggestion",
+      "default": "solid",
       "required": false,
-      "values": ["filled", "outlined", "outline", "soft"]
+      "values": ["solid", "outline", "soft"]
     },
     "size": {
       "type": "enum",
@@ -79,77 +79,70 @@
   },
   "usage": {
     "when": [
-      "Filtering content by categories or tags",
-      "Multi-select scenarios like choosing interests or skills",
-      "Toggling options in a compact pill-shaped control",
-      "Displaying removable user-applied filters"
+      "Filtering a list by tag or category",
+      "Multi-select from a compact set",
+      "Showing filters the user can dismiss"
     ],
     "whenNot": [
-      "Display-only status labels (use Badge)",
-      "Navigation between views (use Tabs)",
-      "Binary on/off state (use Switch)",
-      "Primary call-to-action (use Button)"
+      "Read-only status — use Badge",
+      "Switching views — use Tabs",
+      "On/off state — use Switch",
+      "A main call to action — use Button"
     ],
     "guidelines": [
-      "Keep chip labels short (1-3 words)",
-      "Use Chip.Group for multi-select sets with shared state",
-      "Keep the default micro size for filters and tags; opt into a larger size only when the surrounding control track requires it",
-      "Use onRemove only when users should be able to dismiss the chip",
-      "Pair avatar chips with user-related selections (assignees, reviewers)",
-      "Provide an explicit value on Chip when using non-string/custom JSX children inside Chip.Group"
+      "One to three words per chip",
+      "Chip.Group when chips share selection state",
+      "Keep xs for filters and tags; size up only to match a taller control track",
+      "onRemove only when the chip is genuinely dismissible",
+      "Pass an explicit value when children are custom JSX"
     ],
     "accessibility": [
-      "Chips are buttons and use aria-pressed for selection state",
-      "Chip.Group is a grouping wrapper; add role/aria-label when needed for assistive context",
-      "Remove buttons include descriptive aria-label with chip text",
-      "Disabled chips are properly excluded from interaction"
+      "Chips are buttons; selection is reported via aria-pressed",
+      "Add role and aria-label to Chip.Group when the set needs a name",
+      "Remove buttons carry the chip text in their aria-label",
+      "Disabled chips are skipped by keyboard and pointer"
     ]
   },
   "examples": [
     {
-      "name": "Default",
-      "description": "Basic filled chip",
-      "code": "<Chip>Default</Chip>"
+      "name": "Variants",
+      "description": "Tinted, hairline, and accent-soft chrome.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Chip variant=\"solid\">Solid</Chip>\n  <Chip variant=\"outline\">Outline</Chip>\n  <Chip variant=\"soft\">Soft</Chip>\n</Stack>"
     },
     {
-      "name": "Outline",
-      "description": "Chip with border using the \"outline\" alias for \"outlined\"",
-      "code": "<div style={{ display: 'flex', gap: '8px' }}>\n  <Chip variant=\"outline\">Outline</Chip>\n  <Chip variant=\"outline\" selected>Outline Selected</Chip>\n</div>"
+      "name": "Sizes",
+      "description": "xs for filter rows; larger sizes match taller field tracks.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" align=\"center\" wrap>\n  <Chip variant=\"outline\" size=\"xs\">Extra small</Chip>\n  <Chip variant=\"outline\" size=\"sm\">Small</Chip>\n  <Chip variant=\"outline\" size=\"md\">Medium</Chip>\n  <Chip variant=\"outline\" size=\"lg\">Large</Chip>\n</Stack>"
     },
     {
       "name": "Selected",
-      "description": "Chip in selected state across variants",
-      "code": "<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Chip selected>Filled</Chip>\n  <Chip variant=\"outlined\" selected>Outlined</Chip>\n  <Chip variant=\"soft\" selected>Soft</Chip>\n</Stack>"
+      "description": "All three variants share one selection treatment.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Chip selected>Solid</Chip>\n  <Chip variant=\"outline\" selected>Outline</Chip>\n  <Chip variant=\"soft\" selected>Soft</Chip>\n</Stack>"
     },
     {
       "name": "With Avatar",
-      "description": "Chip with a leading avatar image",
+      "description": "Leading face, for people-shaped selections.",
       "code": "<Chip avatar={<img src=\"https://i.pravatar.cc/32?u=chip\" alt=\"\" />}>\n  Jane Doe\n</Chip>"
     },
     {
       "name": "With Remove",
-      "description": "Removable chip with dismiss button",
-      "code": "<div style={{ display: 'flex', gap: '8px' }}>\n  <Chip onRemove={() => {}}>React</Chip>\n  <Chip onRemove={() => {}}>TypeScript</Chip>\n  <Chip onRemove={() => {}}>SCSS</Chip>\n</div>"
-    },
-    {
-      "name": "Selected Removable",
-      "description": "Selected removable chips retain the shared selection treatment across variants",
-      "code": "<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Chip selected onRemove={() => {}}>Filled</Chip>\n  <Chip variant=\"outlined\" selected onRemove={() => {}}>Outlined</Chip>\n  <Chip variant=\"soft\" selected onRemove={() => {}}>Soft</Chip>\n</Stack>"
+      "description": "Trailing dismiss button clears the tag.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Chip variant=\"outline\" onRemove={() => {}}>React</Chip>\n  <Chip variant=\"outline\" selected onRemove={() => {}}>TypeScript</Chip>\n  <Chip variant=\"soft\" onRemove={() => {}}>SCSS</Chip>\n</Stack>"
     },
     {
       "name": "Chip Group",
-      "description": "Multi-select chip set with shared state",
+      "description": "Selection state is held by the group, not each chip.",
       "code": "<Chip.Group defaultValue={['react']}>\n  <Chip value=\"react\">React</Chip>\n  <Chip value=\"vue\">Vue</Chip>\n  <Chip value=\"angular\">Angular</Chip>\n  <Chip value=\"svelte\">Svelte</Chip>\n</Chip.Group>"
     },
     {
       "name": "Chip Group with Custom Labels",
-      "description": "Use explicit values when chip labels are custom JSX",
+      "description": "Custom JSX children need an explicit value.",
       "code": "<Chip.Group aria-label=\"Assignees\">\n  <Chip value=\"jane\">\n    <span>Jane Doe</span>\n  </Chip>\n  <Chip value=\"sam\">\n    <span>Sam Lee</span>\n  </Chip>\n</Chip.Group>"
     },
     {
       "name": "Disabled",
-      "description": "Chip in disabled state",
-      "code": "<div style={{ display: 'flex', gap: '8px' }}>\n  <Chip disabled>Disabled</Chip>\n  <Chip disabled selected>Disabled Selected</Chip>\n</div>"
+      "description": "Dimmed and unreachable, selected or not.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Chip variant=\"outline\" disabled>Disabled</Chip>\n  <Chip variant=\"outline\" disabled selected>Disabled selected</Chip>\n</Stack>"
     }
   ],
   "relations": [
@@ -172,7 +165,7 @@
   "contract": {
     "propsSummary": [
       "children: ReactNode - chip label (required)",
-      "variant: filled|outlined|outline|soft - visual style",
+      "variant: solid|outline|soft - chrome family",
       "size: xs|sm|md|lg - chip size (xs by default)",
       "selected: boolean - selection state",
       "icon/avatar: ReactNode - leading visual",

package/src/components/Chip/Chip.module.scss

@@ -1,5 +1,6 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../tokens/measurements.generated" as measurements;
 @use "../../recipes/action";
 @use "../../recipes/layout";
 
@@ -13,7 +14,8 @@
 
   &:active:not(:disabled) {
     background-color: var(--fui-field-selection-bg-hover, $fui-bg-hover);
-    box-shadow: inset 0 0 0 1px var(--fui-field-selection-border, $fui-border-strong);
+    box-shadow: inset 0 0 0 var(--fui-stroke-hairline, #{$fui-stroke-hairline})
+      var(--fui-field-selection-border, $fui-border-strong);
   }
 }
 
@@ -24,12 +26,11 @@
 
   border-radius: var(--fui-radius-full, $fui-radius-full);
   white-space: nowrap;
-  user-select: none;
 }
 
 .withRemove {
-  border-top-right-radius: 0;
-  border-bottom-right-radius: 0;
+  border-start-end-radius: var(--fui-radius-none, #{$fui-radius-none});
+  border-end-end-radius: var(--fui-radius-none, #{$fui-radius-none});
 }
 
 // Sizes
@@ -49,8 +50,8 @@
   @include action.size("lg");
 }
 
-// Variants
-.filled {
+// Variants — chrome only
+.solid {
   background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
   color: var(--fui-text-primary, $fui-text-primary);
 
@@ -67,10 +68,10 @@
   }
 }
 
-.outlined {
+.outline {
   background-color: transparent;
   color: var(--fui-text-primary, $fui-text-primary);
-  border: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
+  border: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid var(--fui-border, $fui-border);
 
   &:hover:not(:disabled) {
     background-color: var(--fui-bg-hover, $fui-bg-hover);
@@ -110,23 +111,23 @@
   align-items: center;
 
   img {
-    width: var(--fui-icon-md, $fui-icon-md);
-    height: var(--fui-icon-md, $fui-icon-md);
+    inline-size: var(--fui-icon-md, $fui-icon-md);
+    block-size: var(--fui-icon-md, $fui-icon-md);
     border-radius: var(--fui-radius-full, $fui-radius-full);
     object-fit: cover;
   }
 
   .xs & {
     img {
-      width: var(--fui-icon-sm, $fui-icon-sm);
-      height: var(--fui-icon-sm, $fui-icon-sm);
+      inline-size: var(--fui-icon-sm, $fui-icon-sm);
+      block-size: var(--fui-icon-sm, $fui-icon-sm);
     }
   }
 
   .sm & {
     img {
-      width: var(--fui-icon-sm, $fui-icon-sm);
-      height: var(--fui-icon-sm, $fui-icon-sm);
+      inline-size: var(--fui-icon-sm, $fui-icon-sm);
+      block-size: var(--fui-icon-sm, $fui-icon-sm);
     }
   }
 }
@@ -149,13 +150,13 @@
   @include action.base;
 
   color: var(--fui-text-secondary, $fui-text-secondary);
-  border-top-right-radius: var(--fui-radius-full, $fui-radius-full);
-  border-bottom-right-radius: var(--fui-radius-full, $fui-radius-full);
-  border-top-left-radius: 0;
-  border-bottom-left-radius: 0;
+  border-start-end-radius: var(--fui-radius-full, $fui-radius-full);
+  border-end-end-radius: var(--fui-radius-full, $fui-radius-full);
+  border-start-start-radius: var(--fui-radius-none, #{$fui-radius-none});
+  border-end-start-radius: var(--fui-radius-none, #{$fui-radius-none});
   background-color: transparent;
-  border: var(--fui-stroke-hairline, 1px) solid transparent;
-  border-left-color: var(--fui-border, $fui-border);
+  border: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid transparent;
+  border-inline-start-color: var(--fui-border, $fui-border);
 
   .removableChip[data-size="xs"] & {
     @include action.icon-only("micro");
@@ -180,7 +181,7 @@
 
 // Match remove button visuals to chip variant/state so the compound control
 // remains visually coherent across seeds/themes.
-.filled + .remove {
+.solid + .remove {
   background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
 
   &:hover:not(:disabled) {
@@ -192,7 +193,7 @@
   }
 }
 
-.outlined + .remove {
+.outline + .remove {
   background-color: transparent;
 
   &:hover:not(:disabled) {
@@ -219,7 +220,7 @@
 
 .selected + .remove {
   @include selected-surface;
-  border-left-color: transparent;
+  border-inline-start-color: transparent;
 }
 
 // Chip.Group

package/src/components/Chip/index.tsx

@@ -2,17 +2,24 @@
 
 import * as React from "react";
 import styles from "./Chip.module.scss";
+import { isProductionBuild } from "../../utils/env";
 
 /**
  * Chip for selections, filters, and tags. Use with Chip.Group for multi-select.
  * @see https://usefragments.com/components/chip
  */
+export type ChipVariant = "solid" | "outline" | "soft";
+
 export interface ChipProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
   children: React.ReactNode;
-  /** Visual style variant. `"outline"` is an alias for `"outlined"`.
-   * @default "filled"
+  /** Chrome family.
+   *
+   * - `solid` (default): tinted pill for filters and tags.
+   * - `outline`: hairline-bordered, transparent.
+   * - `soft`: info-tinted, for a chip that carries a suggestion.
+   * @default "solid"
    * @see https://usefragments.com/components/chip#variants */
-  variant?: "filled" | "outlined" | "outline" | "soft";
+  variant?: ChipVariant;
   /** Chip size.
    * @default "xs" */
   size?: "xs" | "sm" | "md" | "lg";
@@ -44,7 +51,7 @@ export interface ChipGroupProps extends Omit<
 const ChipBase = React.forwardRef<HTMLButtonElement, ChipProps>(function Chip(
   {
     children,
-    variant: variantProp = "filled",
+    variant = "solid",
     size: sizeProp,
     selected = false,
     disabled = false,
@@ -59,8 +66,6 @@ const ChipBase = React.forwardRef<HTMLButtonElement, ChipProps>(function Chip(
   ref
 ) {
   const size = sizeProp ?? "xs";
-  // Resolve alias: "outline" → "outlined"
-  const variant = variantProp === "outline" ? "outlined" : variantProp;
 
   const classes = [
     styles.chip,
@@ -165,7 +170,7 @@ function ChipGroupInner(
           if (child.props.value != null) return child.props.value;
           if (typeof child.props.children === "string") return child.props.children;
           if (child.key != null) return String(child.key);
-          if (process.env.NODE_ENV !== "production") {
+          if (!isProductionBuild()) {
             // Non-string labels need an explicit value to avoid unstable group selection keys.
             console.warn(
               "Chip.Group: Chips with non-string children should provide a `value` prop."

package/src/components/CodeBlock/CodeBlock.contract.json

@@ -1,16 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "CodeBlock",
-  "description": "Syntax-highlighted code display with copy functionality, theming, diff view, and collapsible sections",
+  "description": "Shows code with syntax colors, a copy button, and diff or collapse when you need them.",
   "category": "display",
-  "tags": [
-    "code",
-    "syntax",
-    "highlighting",
-    "documentation",
-    "developer",
-    "diff"
-  ],
+  "tags": ["code", "syntax", "highlighting", "documentation", "developer", "diff"],
   "status": "stable",
   "dependencies": [
     {
@@ -24,7 +17,7 @@
   "propsSummary": [
     "code: string (required)",
     "language: tsx|typescript|ts|javascript|js|jsx|bash|shell|css|scss|sass|json|html|xml|markdown|md|yaml|yml|python|py|ruby|go|rust|java|kotlin|swift|c|cpp|csharp|php|sql|graphql|diff|plaintext|text (default: tsx)",
-    "theme: synthwave-84|github-dark|github-light|one-dark-pro|dracula|nord|monokai|vitesse-dark|vitesse-light|min-dark|min-light (default: one-dark-pro)",
+    "theme: css-variables|synthwave-84|github-dark|github-light|one-dark-pro|dracula|nord|monokai|vitesse-dark|vitesse-light|min-dark|min-light (default: css-variables)",
     "showCopy: boolean (default: true)",
     "title: string",
     "filename: string",
@@ -96,10 +89,11 @@
     },
     "theme": {
       "type": "enum",
-      "description": "Syntax highlighting theme",
-      "default": "one-dark-pro",
+      "description": "Syntax highlighting theme. css-variables maps spans onto --fui-code-token-* so both themes stay readable.",
+      "default": "css-variables",
       "required": false,
       "values": [
+        "css-variables",
         "synthwave-84",
         "github-dark",
         "github-light",
@@ -190,6 +184,12 @@
       "default": "5",
       "required": false
     },
+    "collapseAction": {
+      "type": "\"lines\" | \"expand\"",
+      "description": "Collapse control copy: line-count bar, or a single Expand / Collapse control",
+      "default": "lines",
+      "required": false
+    },
     "compact": {
       "type": "boolean",
       "description": "Compact mode with reduced padding",
@@ -207,11 +207,7 @@
       "description": "Where to place the copy button when not using persistentCopy",
       "default": "auto",
       "required": false,
-      "values": [
-        "auto",
-        "header",
-        "overlay"
-      ]
+      "values": ["auto", "header", "overlay"]
     },
     "bg": {
       "type": "string",
@@ -226,118 +222,97 @@
   },
   "usage": {
     "when": [
-      "Displaying code examples in documentation",
-      "Showing installation commands",
-      "Presenting configuration snippets",
-      "Teaching programming concepts",
-      "Showing code diffs or changes",
-      "Displaying long code files with collapse functionality"
+      "Code examples inside prose or docs",
+      "Install and config snippets",
+      "Showing what changed, as a diff"
     ],
     "whenNot": [
-      "User-editable code (use code editor)",
-      "Very short inline code (use <code> element)",
-      "Non-code content (use Text or Card)"
+      "The user needs to edit it (use an editor)",
+      "A couple of words inline (use a code element)"
     ],
     "guidelines": [
-      "Always specify the correct language for accurate highlighting",
-      "Use filename prop to show source file name in header bar",
-      "Use copyPlacement=\"auto\" to render copy in overlay mode when no filename is provided",
-      "Use title prop for external labels above the code block",
-      "Enable line numbers for longer code samples",
-      "Use highlightLines to draw attention to key lines",
-      "Use addedLines/removedLines for diff highlighting",
-      "Set maxHeight for very long code blocks to prevent layout issues",
-      "Use collapsible for code samples that users may want to skim",
-      "Choose a theme that matches your documentation style",
-      "Keep code examples concise and focused",
-      "Use CodeBlock.Tabbed for multi-language snippets; tabs support controlled value/onValueChange and explicit tab values"
+      "Set language every time — wrong highlighting is worse than none",
+      "filename for a real file, title for a label, caption for the aside",
+      "Line numbers earn their keep once you need to point at a line",
+      "highlightLines for emphasis; addedLines and removedLines for diffs",
+      "maxHeight or collapsible keeps a long file from swallowing the page",
+      "CodeBlock.Tabbed groups the same snippet across languages"
     ],
     "accessibility": [
-      "Code is presented in a semantic pre/code structure",
-      "Copy button has appropriate aria-label",
-      "Keyboard accessible copy functionality",
-      "Collapse button has aria-expanded state"
+      "Renders as semantic pre and code",
+      "The copy button is labelled and keyboard reachable",
+      "The collapse toggle reports aria-expanded"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic code block with syntax highlighting",
+      "description": "Pass code and language; highlighting and copy come free.",
       "code": "<CodeBlock code={`import { Button } from '@usefragments/ui';\n\nfunction App() {\n  return <Button>Click me</Button>;\n}`} language=\"tsx\" />"
     },
     {
       "name": "With Filename",
-      "description": "Code block with filename in header bar",
+      "description": "A header bar names the source file and holds the copy button.",
       "code": "<CodeBlock filename=\"app.tsx\" code={`import { Button, Card } from '@usefragments/ui';\n\nfunction App() {\n  return (\n    <Card>\n      <Card.Header>Welcome</Card.Header>\n      <Card.Content>\n        <Button>Get Started</Button>\n      </Card.Content>\n    </Card>\n  );\n}`} language=\"tsx\" />"
     },
     {
       "name": "With Title",
-      "description": "Code block with external title label",
+      "description": "A label above the block, outside the code surface.",
       "code": "<CodeBlock title=\"Installation\" code=\"npm install @usefragments/ui\" language=\"bash\" />"
     },
     {
       "name": "With Caption",
-      "description": "Code block with footer caption",
+      "description": "A footer line for the aside that does not belong in the code.",
       "code": "<CodeBlock\n  code={`const API_URL = process.env.NEXT_PUBLIC_API_URL;`}\n  language=\"typescript\"\n  caption=\"Environment variables must be prefixed with NEXT_PUBLIC_ to be available in the browser.\"\n/>"
     },
     {
       "name": "With Line Numbers",
-      "description": "Shows line numbers for reference",
+      "description": "Turn these on once a snippet is long enough to point at.",
       "code": "<CodeBlock code={`const greeting = \"Hello\";\nconst name = \"World\";\nconsole.log(\\`\\${greeting}, \\${name}!\\`);`} language=\"typescript\" showLineNumbers />"
     },
     {
       "name": "Custom Start Line",
-      "description": "Shows code excerpt starting from a specific line number",
+      "description": "Numbering starts where the excerpt actually starts in the file.",
       "code": "<CodeBlock\n  code={`  return (\n    <button onClick={() => setCount(c => c + 1)}>\n      Count: {count}\n    </button>\n  );\n}`}\n  language=\"tsx\"\n  showLineNumbers\n  startLineNumber={15}\n  caption=\"Lines 15-20 from Counter.tsx\"\n/>"
     },
     {
       "name": "With Highlighted Lines",
-      "description": "Emphasizes specific lines of code",
+      "description": "Marks the lines the prose is talking about.",
       "code": "<CodeBlock code={`import { useState } from 'react';\n\nfunction Counter() {\n  const [count, setCount] = useState(0);\n\n  return (\n    <button onClick={() => setCount(c => c + 1)}>\n      Count: {count}\n    </button>\n  );\n}`} language=\"tsx\" showLineNumbers highlightLines={[4, '7-9']} />"
     },
     {
       "name": "Diff View",
-      "description": "Shows added and removed lines in a diff-like format",
+      "description": "Added and removed lines, side by side with the rest.",
       "code": "<CodeBlock\n  code={`import { useState } from 'react';\nimport { useCallback } from 'react';\n\nfunction Counter() {\n  const [count, setCount] = useState(0);\n  const increment = () => setCount(c => c + 1);\n  const increment = useCallback(() => setCount(c => c + 1), []);\n\n  return <button onClick={increment}>Count: {count}</button>;\n}`}\n  language=\"tsx\"\n  showLineNumbers\n  removedLines={[6]}\n  addedLines={[2, 7]}\n/>"
     },
     {
-      "name": "GitHub Dark Theme",
-      "description": "Using the GitHub Dark theme",
+      "name": "Custom Theme",
+      "description": "Any Shiki theme works — pass its name to theme.",
       "code": "<CodeBlock\n  code={`async function fetchUser(id: string) {\n  const response = await fetch(\\`/api/users/\\${id}\\`);\n  return response.json();\n}`}\n  language=\"typescript\"\n  theme=\"github-dark\"\n/>"
     },
-    {
-      "name": "GitHub Light Theme",
-      "description": "Using the GitHub Light theme for light backgrounds",
-      "code": "<CodeBlock\n  code={`def fibonacci(n):\n    if n <= 1:\n        return n\n    return fibonacci(n - 1) + fibonacci(n - 2)`}\n  language=\"python\"\n  theme=\"github-light\"\n/>"
-    },
-    {
-      "name": "Dracula Theme",
-      "description": "Using the popular Dracula theme",
-      "code": "<CodeBlock\n  code={`fn main() {\n    println!(\"Hello, Rust!\");\n}`}\n  language=\"rust\"\n  theme=\"dracula\"\n/>"
-    },
     {
       "name": "Word Wrap",
-      "description": "Long lines wrap instead of scrolling horizontally",
+      "description": "Long lines break instead of scrolling sideways.",
       "code": "<CodeBlock\n  code={`const longString = \"This is a very long string that would normally cause horizontal scrolling, but with word wrap enabled it will break to the next line instead.\";`}\n  language=\"typescript\"\n  wordWrap\n/>"
     },
     {
       "name": "Max Height with Scroll",
-      "description": "Constrains height with scrollable content",
+      "description": "Caps the height so one snippet cannot own the page.",
       "code": "<CodeBlock\n  code={`// This code block has a maximum height\nfunction processItems(items: string[]) {\n  const results = [];\n  for (const item of items) {\n    if (item.startsWith('_')) {\n      continue;\n    }\n    const processed = item.trim().toLowerCase();\n    if (processed.length > 0) {\n      results.push(processed);\n    }\n  }\n  return results;\n}\n\nexport default processItems;`}\n  language=\"typescript\"\n  maxHeight={150}\n  showLineNumbers\n/>"
     },
     {
       "name": "Collapsible",
-      "description": "Long code that can be expanded/collapsed",
+      "description": "Shows the opening lines and hides the rest behind a toggle.",
       "code": "<CodeBlock\n  code={`import React, { useState, useEffect } from 'react';\n\ninterface User {\n  id: string;\n  name: string;\n  email: string;\n  avatar?: string;\n}\n\nexport function UserProfile({ userId }: { userId: string }) {\n  const [user, setUser] = useState<User | null>(null);\n  const [loading, setLoading] = useState(true);\n  const [error, setError] = useState<string | null>(null);\n\n  useEffect(() => {\n    async function fetchUser() {\n      try {\n        setLoading(true);\n        const response = await fetch(\\`/api/users/\\${userId}\\`);\n        if (!response.ok) throw new Error('Failed to fetch');\n        const data = await response.json();\n        setUser(data);\n      } catch (err) {\n        setError(err instanceof Error ? err.message : 'Unknown error');\n      } finally {\n        setLoading(false);\n      }\n    }\n    fetchUser();\n  }, [userId]);\n\n  if (loading) return <div>Loading...</div>;\n  if (error) return <div>Error: {error}</div>;\n  if (!user) return null;\n\n  return (\n    <div>\n      <h1>{user.name}</h1>\n      <p>{user.email}</p>\n    </div>\n  );\n}`}\n  language=\"tsx\"\n  showLineNumbers\n  collapsible\n  defaultCollapsed\n  collapsedLines={8}\n/>"
     },
     {
       "name": "JSON",
-      "description": "Configuration file example",
+      "description": "Config files highlight the same way source does.",
       "code": "<CodeBlock title=\"package.json\" code={`{\n  \"name\": \"my-app\",\n  \"dependencies\": {\n    \"@usefragments/ui\": \"^0.3.0\"\n  }\n}`} language=\"json\" />"
     },
     {
       "name": "Without Copy Button",
-      "description": "Minimal display without copy functionality",
+      "description": "Drop the copy button when the snippet is not meant to be reused.",
       "code": "<CodeBlock code=\"const simple = true;\" language=\"typescript\" showCopy={false} />"
     }
   ],
@@ -357,7 +332,7 @@
     "propsSummary": [
       "code: string - required code content",
       "language: tsx|typescript|javascript|jsx|bash|shell|css|scss|sass|json|html|xml|markdown|md|yaml|yml|python|py|ruby|go|rust|java|kotlin|swift|c|cpp|csharp|php|sql|graphql|diff|plaintext",
-      "theme: synthwave-84|github-dark|github-light|one-dark-pro|dracula|nord|monokai|vitesse-dark|vitesse-light|min-dark|min-light (default: one-dark-pro)",
+      "theme: css-variables|synthwave-84|github-dark|github-light|one-dark-pro|dracula|nord|monokai|vitesse-dark|vitesse-light|min-dark|min-light (default: css-variables)",
       "showCopy: boolean (default: true)",
       "copyPlacement: auto|header|overlay (default: auto)",
       "title: string - optional external label",
@@ -373,18 +348,13 @@
       "collapsible: boolean (default: false)",
       "defaultCollapsed: boolean (default: false)",
       "collapsedLines: number (default: 5)",
-      "CodeBlock.Tabbed: tabs[] plus optional defaultTab/value/onValueChange for multi-language snippets"
+      "CodeBlock.Tabbed: tabs[] plus optional defaultTab/value/onValueChange for multi-language snippets; collapsible/defaultCollapsed/collapsedLines forward to every panel"
     ],
-    "a11yRules": [
-      "A11Y_CODE_SEMANTIC",
-      "A11Y_BTN_LABEL"
-    ]
+    "a11yRules": ["A11Y_CODE_SEMANTIC", "A11Y_BTN_LABEL"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Tabbed"
-    ]
+    "subComponents": ["Tabbed"]
   },
   "provenance": {
     "source": "migrated",