@usefragments/ui 1.6.0 → 1.7.0

package/src/components/Popover/Popover.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Popover",
-  "description": "Rich content overlay anchored to a trigger element. Use for forms, detailed information, or interactive content that should stay in context.",
-  "category": "feedback",
-  "tags": [
-    "popover",
-    "overlay",
-    "dropdown",
-    "floating",
-    "contextual"
-  ],
+  "description": "Anchors interactive content to a trigger without blocking the page.",
+  "category": "overlays",
+  "tags": ["popover", "overlay", "dropdown", "floating", "contextual"],
   "status": "stable",
   "sourcePath": "src/components/Popover/index.tsx",
   "exportName": "Popover",
@@ -51,24 +45,23 @@
   },
   "usage": {
     "when": [
-      "Inline editing forms",
-      "Rich preview content",
-      "Filter panels",
-      "Date/color pickers",
-      "Content that needs more space than a tooltip"
+      "Editing a value in place",
+      "Previews richer than a line of text",
+      "Filter and picker panels",
+      "Content that outgrows a tooltip"
     ],
     "whenNot": [
-      "Simple hints (use Tooltip)",
-      "Action lists (use Menu)",
-      "Blocking user interaction (use Dialog)",
-      "System notifications (use Toast or Alert)"
+      "A short hint (use Tooltip)",
+      "A list of actions (use Menu)",
+      "Anything that must block the page (use Dialog)",
+      "Feedback the user does not act on (use Toast or Alert)"
     ],
     "guidelines": [
-      "Keep popover content focused and minimal",
-      "Include a clear way to close (X button or action buttons)",
-      "Position to avoid covering important content",
-      "Use arrow to visually connect popover to trigger",
-      "Popover.Trigger and Popover.Close support asChild for links/router-link components (single valid element child required)"
+      "One job per panel",
+      "Always give the user a visible way out",
+      "Pick a side that does not cover what the user just clicked",
+      "Add the arrow when the trigger is not obvious",
+      "asChild on Trigger and Close needs a single element child"
     ],
     "accessibility": [
       "Focus is moved to popover content on open",
@@ -79,27 +72,27 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Basic popover with content",
+      "description": "Title, body, and a close control.",
       "code": "<Popover>\n  <Popover.Trigger asChild>\n    <Button variant=\"secondary\">Open Popover</Button>\n  </Popover.Trigger>\n  <Popover.Content>\n    <Popover.Close />\n    <Popover.Title>Popover Title</Popover.Title>\n    <Popover.Description>\n      This is a popover with some content. It can contain text, forms, or other elements.\n    </Popover.Description>\n  </Popover.Content>\n</Popover>"
     },
     {
       "name": "With Form",
-      "description": "Popover containing a form",
+      "description": "Enough room to edit a value in place.",
       "code": "<Popover>\n  <Popover.Trigger asChild>\n    <Button variant=\"secondary\">Edit Name</Button>\n  </Popover.Trigger>\n  <Popover.Content size=\"sm\">\n    <Popover.Close />\n    <Popover.Title>Edit Name</Popover.Title>\n    <Popover.Body>\n      <Input label=\"Display Name\" placeholder=\"Enter name\" />\n    </Popover.Body>\n    <Popover.Footer>\n      <Popover.Close asChild>\n        <Button variant=\"secondary\" size=\"sm\">Cancel</Button>\n      </Popover.Close>\n      <Button variant=\"primary\" size=\"sm\">Save</Button>\n    </Popover.Footer>\n  </Popover.Content>\n</Popover>"
     },
     {
       "name": "With Arrow",
-      "description": "Popover with pointing arrow",
+      "description": "The arrow ties the panel back to its trigger.",
       "code": "<Popover>\n  <Popover.Trigger asChild>\n    <Button variant=\"secondary\">Info</Button>\n  </Popover.Trigger>\n  <Popover.Content arrow>\n    <Popover.Title>Quick Tip</Popover.Title>\n    <Popover.Description>\n      This popover has an arrow pointing to its trigger element.\n    </Popover.Description>\n  </Popover.Content>\n</Popover>"
     },
     {
       "name": "Positions",
-      "description": "Popover on different sides",
+      "description": "Flips to the opposite side when space runs out.",
       "code": "<div style={{ display: 'flex', gap: '16px', padding: '60px' }}>\n  <Popover>\n    <Popover.Trigger asChild>\n      <Button variant=\"secondary\">Top</Button>\n    </Popover.Trigger>\n    <Popover.Content side=\"top\" size=\"sm\">\n      <Popover.Description>Popover on top</Popover.Description>\n    </Popover.Content>\n  </Popover>\n  <Popover>\n    <Popover.Trigger asChild>\n      <Button variant=\"secondary\">Bottom</Button>\n    </Popover.Trigger>\n    <Popover.Content side=\"bottom\" size=\"sm\">\n      <Popover.Description>Popover on bottom</Popover.Description>\n    </Popover.Content>\n  </Popover>\n</div>"
     },
     {
       "name": "Link Trigger",
-      "description": "Use asChild with a non-button trigger element",
+      "description": "asChild lets a link open it.",
       "code": "<Popover>\n  <Popover.Trigger asChild>\n    <a href=\"#popover-help\">Open help</a>\n  </Popover.Trigger>\n  <Popover.Content size=\"sm\">\n    <Popover.Description>Popover trigger can be an anchor when using asChild.</Popover.Description>\n  </Popover.Content>\n</Popover>"
     }
   ],
@@ -128,27 +121,12 @@
       "Popover.Trigger / Popover.Close asChild support non-button children",
       "Popover.Content side: top|bottom|left|right - position"
     ],
-    "a11yRules": [
-      "A11Y_POPOVER_FOCUS",
-      "A11Y_POPOVER_ESCAPE",
-      "A11Y_TARGET_SIZE_MIN"
-    ]
+    "a11yRules": ["A11Y_POPOVER_FOCUS", "A11Y_POPOVER_ESCAPE", "A11Y_TARGET_SIZE_MIN"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Trigger",
-      "Content",
-      "Close",
-      "Title",
-      "Description",
-      "Body",
-      "Footer"
-    ],
-    "requiredChildren": [
-      "Trigger",
-      "Content"
-    ],
+    "subComponents": ["Trigger", "Content", "Close", "Title", "Description", "Body", "Footer"],
+    "requiredChildren": ["Trigger", "Content"],
     "commonPatterns": [
       "<Popover><Popover.Trigger asChild><Button>Open</Button></Popover.Trigger><Popover.Content><Popover.Close /><Popover.Title>{title}</Popover.Title><Popover.Description>{description}</Popover.Description></Popover.Content></Popover>",
       "<Popover><Popover.Trigger asChild><a href=\"#help\">Open help</a></Popover.Trigger><Popover.Content>...</Popover.Content></Popover>"

package/src/components/Popover/Popover.module.scss

@@ -13,7 +13,7 @@
 
   position: relative;
   opacity: 0;
-  transform: scale(0.95) translateY(-$fui-anim-offset-sm);
+  transform: scale(0.95) translateY(calc(-1 * var(--fui-anim-offset-sm, #{$fui-anim-offset-sm})));
   transform-origin: var(--transform-origin);
   transition:
     opacity var(--fui-transition-fast, $fui-transition-fast),
@@ -26,21 +26,22 @@
 
   &[data-starting-style] {
     opacity: 0;
-    transform: scale(0.95) translateY(-$fui-anim-offset-sm);
+    transform: scale(0.95) translateY(calc(-1 * var(--fui-anim-offset-sm, #{$fui-anim-offset-sm})));
   }
 
   &[data-ending-style] {
     opacity: 0;
-    transform: scale(0.95) translateY($fui-anim-offset-sm);
+    transform: scale(0.95) translateY(var(--fui-anim-offset-sm, #{$fui-anim-offset-sm}));
   }
 
   &[data-side="top"] {
     &[data-starting-style] {
-      transform: scale(0.95) translateY($fui-anim-offset-sm);
+      transform: scale(0.95) translateY(var(--fui-anim-offset-sm, #{$fui-anim-offset-sm}));
     }
 
     &[data-ending-style] {
-      transform: scale(0.95) translateY(-$fui-anim-offset-sm);
+      transform: scale(0.95)
+        translateY(calc(-1 * var(--fui-anim-offset-sm, #{$fui-anim-offset-sm})));
     }
   }
 

package/src/components/Progress/Progress.contract.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Progress",
-  "description": "Visual indicator of task completion or loading state. Available in linear and circular variants.",
+  "description": "Shows how far along a task is, as a bar or a ring.",
   "category": "feedback",
   "tags": ["progress", "loading", "indicator", "percentage", "status"],
   "status": "stable",
@@ -70,56 +70,60 @@
   },
   "usage": {
     "when": [
-      "Showing upload/download progress",
-      "Displaying task completion percentage",
-      "Form completion indicators",
-      "Loading states with known duration"
+      "Upload and download progress",
+      "Percentage of a task finished",
+      "How much of a form is filled in",
+      "Waits where you know the duration"
     ],
     "whenNot": [
-      "Unknown loading duration (use Spinner)",
-      "Step-based progress (use Stepper)",
-      "Status without percentage (use Badge)"
+      "You cannot say how long — use Loading",
+      "Discrete steps — use a stepper",
+      "Status with no number — use Badge"
     ],
     "guidelines": [
-      "Use determinate progress when you know the completion percentage",
-      "Use indeterminate for unknown durations",
-      "Include a label for context when the purpose isnt obvious",
-      "Use appropriate color variants for success/warning/danger states",
-      "Use variant=\"neutral\" with role=\"meter\" for magnitude or distribution values where reaching the maximum is not a success state",
-      "Determinate values are clamped to the min/max range for display"
+      "Pass a value when you know the percentage; pass null when you do not",
+      "Add a label whenever the bar alone leaves the purpose unclear",
+      "success, warning, and danger carry state, not decoration",
+      "variant=\"neutral\" with role=\"meter\" for a magnitude where full is not success",
+      "Values outside min and max are clamped before display"
     ],
     "accessibility": [
-      "Uses role=\"progressbar\" with aria-valuenow",
-      "Accepts role=\"meter\" for scalar measurements within a known range",
-      "Label is associated with the progress bar",
-      "State changes are announced to screen readers"
+      "Reports role=\"progressbar\" with aria-valuenow",
+      "role=\"meter\" is accepted for scalar readings inside a known range",
+      "The label is tied to the bar",
+      "Value changes are announced as they happen"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic progress bar with percentage",
-      "code": "<Progress value={60} label=\"Uploading...\" showValue />"
+      "description": "Determinate bar with its percentage spelled out.",
+      "code": "<Progress value={60} label=\"Uploading…\" showValue />"
     },
     {
       "name": "Variants",
-      "description": "Different color variants for different states",
-      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '300px' }}>\n  <Progress value={75} variant=\"default\" label=\"Processing\" showValue />\n  <Progress value={100} variant=\"success\" label=\"Complete\" showValue />\n  <Progress value={80} variant=\"warning\" label=\"Almost full\" showValue />\n  <Progress value={95} variant=\"danger\" label=\"Storage critical\" showValue />\n</div>"
+      "description": "Colour carries state: normal, done, tight, critical.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"column\" gap=\"md\">\n  <Progress value={75} variant=\"default\" label=\"Processing\" showValue />\n  <Progress value={100} variant=\"success\" label=\"Complete\" showValue />\n  <Progress value={80} variant=\"warning\" label=\"Almost full\" showValue />\n  <Progress value={95} variant=\"danger\" label=\"Storage critical\" showValue />\n</Stack>"
+    },
+    {
+      "name": "Meter",
+      "description": "A reading where hitting the top is not a win.",
+      "code": "<Progress\n  value={42}\n  variant=\"neutral\"\n  role=\"meter\"\n  label=\"Seats used\"\n  showValue\n/>"
     },
     {
       "name": "Sizes",
-      "description": "Different progress bar sizes",
-      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '300px' }}>\n  <Progress value={50} size=\"sm\" label=\"Small\" />\n  <Progress value={50} size=\"md\" label=\"Medium\" />\n  <Progress value={50} size=\"lg\" label=\"Large\" />\n</div>"
+      "description": "Thin for table rows, thick when the bar is the point.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"column\" gap=\"md\">\n  <Progress value={50} size=\"sm\" label=\"Small\" />\n  <Progress value={50} size=\"md\" label=\"Medium\" />\n  <Progress value={50} size=\"lg\" label=\"Large\" />\n</Stack>"
     },
     {
       "name": "Indeterminate",
-      "description": "Loading state with unknown duration",
-      "code": "<Progress value={null} label=\"Loading...\" />"
+      "description": "value={null} sweeps instead of filling.",
+      "code": "<Progress value={null} label=\"Loading…\" />"
     },
     {
       "name": "Circular",
-      "description": "Circular progress indicator",
-      "code": "<div style={{ display: 'flex', gap: '24px', alignItems: 'center' }}>\n  <CircularProgress value={25} size=\"sm\" />\n  <CircularProgress value={50} size=\"md\" showValue />\n  <CircularProgress value={75} size=\"lg\" showValue variant=\"success\" />\n  <CircularProgress value={null} size=\"md\" />\n</div>"
+      "description": "Same value in a ring, for tiles and compact chrome.",
+      "code": "import { CircularProgress } from '@/components/Progress';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"lg\" align=\"center\">\n  <CircularProgress value={25} size=\"sm\" />\n  <CircularProgress value={50} size=\"md\" showValue />\n  <CircularProgress value={75} size=\"lg\" showValue variant=\"success\" />\n  <CircularProgress value={null} size=\"md\" />\n</Stack>"
     }
   ],
   "relations": [

package/src/components/Progress/Progress.module.scss

@@ -90,7 +90,7 @@
 // Indeterminate animation
 .indicatorIndeterminate {
   inline-size: 50%;
-  animation: indeterminate 1.5s ease-in-out infinite;
+  animation: indeterminate var(--fui-duration-pulse, $fui-duration-pulse) ease-in-out infinite;
 }
 
 @keyframes indeterminate {
@@ -147,7 +147,8 @@
 }
 
 .circularIndicatorIndeterminate {
-  animation: circularIndeterminate 1.5s ease-in-out infinite;
+  animation: circularIndeterminate var(--fui-duration-pulse, $fui-duration-pulse) ease-in-out
+    infinite;
 }
 
 @keyframes circularIndeterminate {

package/src/components/Prompt/Prompt.contract.json

@@ -1,16 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Prompt",
-  "description": "Multi-line input with toolbar for AI/chat interfaces",
+  "description": "Collects multi-line input for AI and chat interfaces.",
   "category": "ai",
-  "tags": [
-    "prompt",
-    "chat",
-    "ai",
-    "input",
-    "textarea",
-    "form"
-  ],
+  "tags": ["prompt", "chat", "ai", "input", "textarea", "form"],
   "status": "stable",
   "sourcePath": "src/components/Prompt/index.tsx",
   "exportName": "Prompt",
@@ -106,11 +99,7 @@
       "description": "Visual/positioning variant",
       "default": "default",
       "required": false,
-      "values": [
-        "default",
-        "fixed",
-        "sticky"
-      ]
+      "values": ["default", "fixed", "sticky"]
     },
     "onFiles": {
       "type": "function",
@@ -127,37 +116,30 @@
       "description": "How the card is divided up. \"panel\" keeps the toolbar as a filled footer under a rule; \"seamless\" makes the whole card one writing surface with the controls floating on it.",
       "default": "panel",
       "required": false,
-      "values": [
-        "panel",
-        "seamless"
-      ]
+      "values": ["panel", "seamless"]
     }
   },
   "usage": {
     "when": [
-      "Building chat or AI assistant interfaces",
-      "Need multi-line input with submit action",
-      "Require toolbar with actions like attachments or model selection"
+      "Chat and AI assistant interfaces",
+      "Multi-line input with a submit action",
+      "Toolbars carrying attachments or a model picker"
     ],
     "whenNot": [
-      "Simple single-line text input (use Input)",
-      "Basic multi-line without toolbar (use Textarea)",
-      "Search-only interface (use Input with search variant)"
+      "Single-line text (use Input)",
+      "Multi-line with no toolbar (use Textarea)",
+      "Search-only fields (use Input with the search variant)"
     ],
     "guidelines": [
-      "Always provide an onSubmit handler",
-      "Use loading state during API calls",
-      "Prompt.Textarea forwards native textarea props (autoComplete, inputMode, aria-*, data-*, handlers)",
-      "Prompt.Textarea composes your onChange/onKeyDown handlers with built-in submit and auto-resize behavior",
-      "Use appearance=\"seamless\" for agent composers where the controls should float on the writing surface rather than sit in a footer",
-      "Seamless controls share the dense 32px token scale with body-sized labels and standard glyphs so mixed Prompt.Select, Prompt.Attach and Prompt.Submit rows remain optically aligned",
-      "Seamless secondary controls keep transparent hover and open states so they read as inline tools; only Prompt.Submit carries a persistent filled shape",
-      "Seamless Prompt.Submit mirrors the trailing ink gutter established by Prompt.Attach at the leading edge",
-      "Prompt.Submit uses a neutral inverse surface by default so the primary action stays visible without consuming semantic brand color",
-      "Use Prompt.ModeButton for a setting you toggle and Prompt.Select for one you pick from a list",
-      "Wire onFiles once: the attach button, pasting a screenshot and dropping on the card all go through it",
-      "Render Prompt.Attachments above Prompt.Textarea — attachments are part of the message, not a setting on it",
-      "Consider showing usage/token limits for AI contexts"
+      "Always pass an onSubmit handler",
+      "Set loading while the request is in flight to block duplicate sends",
+      "Prompt.Textarea forwards native textarea props and composes your own handlers",
+      "appearance=\"seamless\" floats the controls on the writing surface instead of a footer",
+      "Seamless secondary controls stay transparent; only Prompt.Submit keeps a filled shape",
+      "Prompt.Submit uses a neutral inverse surface, never semantic brand color",
+      "Prompt.ModeButton toggles a setting; Prompt.Select picks one from a list",
+      "Wire onFiles once — the attach button, paste, and drop all route through it",
+      "Render Prompt.Attachments above Prompt.Textarea; they are part of the message"
     ],
     "accessibility": [
       "Enter submits, Shift+Enter for newline",
@@ -168,32 +150,37 @@
   "examples": [
     {
       "name": "Basic",
-      "description": "Simple prompt with submit button",
+      "description": "A textarea and a submit button, nothing else.",
       "code": "<Prompt onSubmit={(value) => console.log(value)}>\n  <Prompt.Textarea />\n  <Prompt.Toolbar>\n    <Prompt.Actions />\n    <Prompt.Info>\n      <Prompt.Submit />\n    </Prompt.Info>\n  </Prompt.Toolbar>\n</Prompt>"
     },
     {
       "name": "With Actions",
-      "description": "Prompt with attachment and mode buttons",
+      "description": "Attach and mode controls sit to the left of submit.",
       "code": "<Prompt onSubmit={(value) => console.log(value)}>\n  <Prompt.Textarea />\n  <Prompt.Toolbar>\n    <Prompt.Actions>\n      <Prompt.ActionButton aria-label=\"Add attachment\">\n        +\n      </Prompt.ActionButton>\n      <Prompt.ModeButton>Auto</Prompt.ModeButton>\n    </Prompt.Actions>\n    <Prompt.Info>\n      <Prompt.Submit />\n    </Prompt.Info>\n  </Prompt.Toolbar>\n</Prompt>"
     },
     {
       "name": "With Usage",
-      "description": "Shows token usage indicator",
+      "description": "A quota readout sits beside the submit button.",
       "code": "<Prompt onSubmit={(value) => console.log(value)}>\n  <Prompt.Textarea />\n  <Prompt.Toolbar>\n    <Prompt.Actions>\n      <Prompt.ActionButton aria-label=\"Add attachment\">\n        +\n      </Prompt.ActionButton>\n      <Prompt.ModeButton active>Auto</Prompt.ModeButton>\n    </Prompt.Actions>\n    <Prompt.Info>\n      <Prompt.Usage>52% used</Prompt.Usage>\n      <Prompt.Submit />\n    </Prompt.Info>\n  </Prompt.Toolbar>\n</Prompt>"
     },
     {
       "name": "Agent Composer",
-      "description": "Seamless surface with the scope of the run chosen on the toolbar",
+      "description": "Controls float on the writing surface instead of a footer.",
       "code": "<Prompt\n  appearance=\"seamless\"\n  submitOnEnter={false}\n  minRows={3}\n  onSubmit={(value) => console.log(value)}\n>\n  <Prompt.Textarea placeholder=\"What should be true when this is done?\" />\n  <Prompt.Toolbar>\n    <Prompt.Actions>\n      <Prompt.Select\n        aria-label=\"Model\"\n        defaultValue=\"claude-opus-4-8\"\n        options={[{ value: 'claude-opus-4-8', label: 'Opus 4.8' }, { value: 'claude-sonnet-5', label: 'Sonnet 5' }]}\n      />\n      <Prompt.ModeButton>Plan</Prompt.ModeButton>\n    </Prompt.Actions>\n    <Prompt.Info>\n      <Prompt.Submit />\n    </Prompt.Info>\n  </Prompt.Toolbar>\n</Prompt>"
     },
+    {
+      "name": "With Attachments",
+      "description": "Staged files list above the text they belong to.",
+      "code": "<Prompt onSubmit={(value) => console.log(value)}>\n  <Prompt.Attachments\n    items={[\n      { id: '1', name: 'findings-export.csv', size: 20480 },\n      { id: '2', name: 'dashboard.png', size: 153600 },\n    ]}\n    onRemove={(id) => console.log(id)}\n  />\n  <Prompt.Textarea />\n  <Prompt.Toolbar>\n    <Prompt.Actions>\n      <Prompt.ActionButton aria-label=\"Add attachment\">\n        +\n      </Prompt.ActionButton>\n    </Prompt.Actions>\n    <Prompt.Info>\n      <Prompt.Submit />\n    </Prompt.Info>\n  </Prompt.Toolbar>\n</Prompt>"
+    },
     {
       "name": "Loading State",
-      "description": "During API submission",
+      "description": "Input locks and submit spins while the request runs.",
       "code": "<Prompt\n  onSubmit={(value) => console.log(value)}\n  loading\n  defaultValue=\"Tell me about the weather...\"\n>\n  <Prompt.Textarea />\n  <Prompt.Toolbar>\n    <Prompt.Actions>\n      <Prompt.ActionButton aria-label=\"Add attachment\">\n        +\n      </Prompt.ActionButton>\n      <Prompt.ModeButton>Auto</Prompt.ModeButton>\n    </Prompt.Actions>\n    <Prompt.Info>\n      <Prompt.Usage>52% used</Prompt.Usage>\n      <Prompt.Submit />\n    </Prompt.Info>\n  </Prompt.Toolbar>\n</Prompt>"
     },
     {
       "name": "Disabled",
-      "description": "Non-interactive prompt",
+      "description": "Everything dims and stops responding to input.",
       "code": "<Prompt onSubmit={(value) => console.log(value)} disabled>\n  <Prompt.Textarea />\n  <Prompt.Toolbar>\n    <Prompt.Actions>\n      <Prompt.ActionButton aria-label=\"Add attachment\">\n        +\n      </Prompt.ActionButton>\n    </Prompt.Actions>\n    <Prompt.Info>\n      <Prompt.Submit />\n    </Prompt.Info>\n  </Prompt.Toolbar>\n</Prompt>"
     }
   ],
@@ -220,10 +207,7 @@
       "submitOnEnter: boolean - Enter key behavior (default: true)",
       "Prompt.Textarea accepts native textarea props and optional aria-label override"
     ],
-    "a11yRules": [
-      "A11Y_TEXTAREA_LABEL",
-      "A11Y_BUTTON_LABEL"
-    ]
+    "a11yRules": ["A11Y_TEXTAREA_LABEL", "A11Y_BUTTON_LABEL"]
   },
   "ai": {
     "compositionPattern": "compound",

package/src/components/Prompt/Prompt.module.scss

@@ -29,7 +29,7 @@
 
   // Gradient layer (behind everything)
   &::before {
-    inset: -1px;
+    inset: calc(-1 * var(--fui-stroke-hairline, 1px));
     z-index: 0;
     background: conic-gradient(
       from var(--beam-angle, 0deg) at 50% 50%,
@@ -42,14 +42,16 @@
       transparent 75%,
       transparent 100%
     );
-    animation: beam-rotate 4s linear infinite;
+    // Ambient loop: twice the shimmer beat, kept on the token scale.
+    animation: beam-rotate calc(var(--fui-duration-shimmer, #{$fui-duration-shimmer}) * 2) linear
+      infinite;
     opacity: 0.6;
     transition: opacity var(--fui-transition-normal, $fui-transition-normal);
   }
 
   // Mask layer — covers the interior, leaving only the 1px border visible
   &::after {
-    inset: 1px;
+    inset: var(--fui-stroke-hairline, 1px);
     z-index: 1;
     background: var(--fui-bg-elevated, $fui-bg-elevated);
   }
@@ -299,6 +301,8 @@
   @include button-reset;
   @include typography.role("body-compact");
 
+  // button-reset marks pressables select-none; typed text must stay selectable.
+  user-select: text;
   display: block;
   width: 100%;
   min-height: var(--fui-input-height, $fui-input-height);
@@ -361,10 +365,14 @@
   &:hover {
     color: var(--fui-text-primary, $fui-text-primary);
   }
+
+  &:focus-visible {
+    @include focus-ring;
+  }
 }
 
 .tabButtonActive {
-  background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+  background-color: var(--fui-control-selected-bg, $fui-bg-active);
   color: var(--fui-text-primary, $fui-text-primary);
 }
 
@@ -454,7 +462,7 @@
 
 .modeButtonActive {
   color: var(--fui-text-primary, $fui-text-primary);
-  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+  background-color: var(--fui-control-selected-bg, $fui-bg-active);
 }
 
 // ============================================

package/src/components/RadioGroup/RadioGroup.contract.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "RadioGroup",
-  "description": "Single selection from a list of mutually exclusive options",
-  "category": "forms",
+  "description": "Selects one option from a mutually exclusive set.",
+  "category": "inputs",
   "tags": ["form", "radio", "selection", "options"],
   "status": "stable",
   "sourcePath": "src/components/RadioGroup/index.tsx",
@@ -115,63 +115,62 @@
   },
   "usage": {
     "when": [
-      "User must select exactly one option from a small set",
-      "Options are mutually exclusive",
-      "All options should be visible at once",
-      "2-5 options available"
+      "Exactly one answer out of two to five",
+      "Options rule each other out",
+      "Every option should be visible without opening anything"
     ],
     "whenNot": [
-      "Multiple selections allowed (use Checkbox group)",
-      "Many options (use Select)",
-      "Binary on/off choice (use Switch)",
-      "Options need to be searchable (use Combobox)"
+      "Several answers allowed (use a Checkbox group)",
+      "Long lists (use Select)",
+      "A single on/off (use Switch)",
+      "Options need searching (use Combobox)"
     ],
     "guidelines": [
-      "Always have one option pre-selected when possible",
-      "Order options logically (alphabetical, frequency, etc.)",
-      "Keep option labels concise",
-      "Use helperText on RadioGroup.Item for complex options"
+      "Pre-select a sensible default whenever one exists",
+      "Order options predictably: alphabetical, by frequency, or by cost",
+      "Keep labels short",
+      "Put the trade-off in each item's helperText"
     ],
     "accessibility": [
-      "Group must have an accessible label",
-      "Use arrow keys to navigate between options",
-      "Selected option should be clearly indicated"
+      "The group carries its own label",
+      "Arrow keys move between options",
+      "The selected option reads as checked"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic radio group with labels",
+      "description": "Three options stacked, the first already chosen.",
       "code": "<RadioGroup defaultValue=\"option1\" label=\"Select an option\">\n  <RadioGroup.Item value=\"option1\" label=\"Option 1\" />\n  <RadioGroup.Item value=\"option2\" label=\"Option 2\" />\n  <RadioGroup.Item value=\"option3\" label=\"Option 3\" />\n</RadioGroup>"
     },
     {
       "name": "With Helper Text",
-      "description": "Radio items with additional context",
+      "description": "Each option carries the trade-off under its label.",
       "code": "<RadioGroup defaultValue=\"standard\" label=\"Shipping Method\">\n  <RadioGroup.Item\n    value=\"standard\"\n    label=\"Standard\"\n    helperText=\"5-7 business days\"\n  />\n  <RadioGroup.Item\n    value=\"express\"\n    label=\"Express\"\n    helperText=\"2-3 business days\"\n  />\n  <RadioGroup.Item\n    value=\"overnight\"\n    label=\"Overnight\"\n    helperText=\"Next business day\"\n  />\n</RadioGroup>"
     },
     {
       "name": "Horizontal",
-      "description": "Side-by-side layout",
+      "description": "One row — good for short labels like sizes.",
       "code": "<RadioGroup orientation=\"horizontal\" defaultValue=\"small\" label=\"Size\">\n  <RadioGroup.Item value=\"small\" label=\"S\" />\n  <RadioGroup.Item value=\"medium\" label=\"M\" />\n  <RadioGroup.Item value=\"large\" label=\"L\" />\n  <RadioGroup.Item value=\"xlarge\" label=\"XL\" />\n</RadioGroup>"
     },
     {
       "name": "With Group Helper Text",
-      "description": "Group-level helper text",
+      "description": "One note under the whole group instead of per option.",
       "code": "<RadioGroup defaultValue=\"standard\" label=\"Plan\" helperText=\"You can change your plan at any time\">\n  <RadioGroup.Item value=\"free\" label=\"Free\" />\n  <RadioGroup.Item value=\"standard\" label=\"Standard\" />\n  <RadioGroup.Item value=\"pro\" label=\"Pro\" />\n</RadioGroup>"
     },
     {
       "name": "With Error",
-      "description": "Validation error state (string shows error message)",
+      "description": "Passing a string to error tints the group and prints the reason.",
       "code": "<RadioGroup label=\"Required selection\" error=\"Please select an option\">\n  <RadioGroup.Item value=\"a\" label=\"Option A\" />\n  <RadioGroup.Item value=\"b\" label=\"Option B\" />\n</RadioGroup>"
     },
     {
       "name": "Disabled",
-      "description": "Non-interactive state",
+      "description": "The choice stays visible but nothing can change it.",
       "code": "<RadioGroup disabled defaultValue=\"locked\" label=\"Locked selection\">\n  <RadioGroup.Item value=\"locked\" label=\"This is locked\" />\n  <RadioGroup.Item value=\"other\" label=\"Cannot select\" />\n</RadioGroup>"
     },
     {
       "name": "Styling Targets",
-      "description": "Use explicit class names for wrapper/group/item styling hooks",
+      "description": "Named class hooks for the wrapper, the group, and each item.",
       "code": "<RadioGroup\n  defaultValue=\"a\"\n  label=\"Display mode\"\n  wrapperClassName=\"demo-radio-wrapper\"\n  groupClassName=\"demo-radio-group\"\n>\n  <RadioGroup.Item value=\"a\" label=\"Compact\" controlClassName=\"demo-radio-control\" contentClassName=\"demo-radio-content\" />\n  <RadioGroup.Item value=\"b\" label=\"Comfortable\" />\n</RadioGroup>"
     }
   ],