@usefragments/ui 1.5.4 → 1.7.0

package/src/components/Link/Link.contract.json

@@ -1,22 +1,16 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Link",
-  "description": "Styled anchor element for navigation. Supports internal and external links with consistent visual treatment.",
+  "description": "Navigates somewhere else, inline or in chrome, with real link semantics.",
   "category": "navigation",
-  "tags": [
-    "link",
-    "anchor",
-    "navigation",
-    "href",
-    "url"
-  ],
+  "tags": ["link", "anchor", "navigation", "href", "url"],
   "status": "stable",
   "sourcePath": "src/components/Link/index.tsx",
   "exportName": "Link",
   "propsSummary": [
     "children: node (required)",
     "variant: default|subtle|muted (default: default)",
-    "underline: always|hover|none (default: hover)",
+    "underline: always|hover|none|dotted (default: hover)",
     "external: boolean (default: false)",
     "asChild: boolean (default: false)",
     "className: string",
@@ -35,22 +29,14 @@
       "description": "Visual style variant",
       "default": "default",
       "required": false,
-      "values": [
-        "default",
-        "subtle",
-        "muted"
-      ]
+      "values": ["default", "subtle", "muted"]
     },
     "underline": {
       "type": "enum",
       "description": "Underline behavior",
       "default": "hover",
       "required": false,
-      "values": [
-        "always",
-        "hover",
-        "none"
-      ]
+      "values": ["always", "hover", "none", "dotted"]
     },
     "external": {
       "type": "boolean",
@@ -87,56 +73,55 @@
   },
   "usage": {
     "when": [
-      "Inline text links within paragraphs",
-      "Navigation links in footers or sidebars",
-      "\"Forgot password?\" or \"Sign up\" links in forms",
-      "External links to documentation or resources"
+      "Inline links inside body text",
+      "Footer and sidebar navigation",
+      "\"Forgot password?\" and \"Sign up\" in forms",
+      "Pointing out to docs or external resources"
     ],
     "whenNot": [
-      "Primary call-to-action (use Button instead)",
-      "Navigation tabs (use Tabs component)",
-      "Menu items in dropdowns (use Menu component)",
-      "Cards that link to detail pages should still use real link semantics (Link or anchor inside Card)"
+      "A main call to action — use Button",
+      "Switching views in place — use Tabs",
+      "Dropdown items — use Menu"
     ],
     "guidelines": [
-      "Link text should describe the destination, not \"click here\"",
-      "Use external prop for links that open in new tabs",
-      "Use subtle variant for secondary/contextual links",
-      "Ensure links are distinguishable from regular text",
-      "When using asChild, Link composes event handlers with the child instead of overwriting them"
+      "Name the destination; never \"click here\"",
+      "external sets target and rel — add your own \"opens in a new tab\" cue",
+      "subtle and muted for secondary and contextual links",
+      "Links must stay distinguishable from surrounding text",
+      "asChild composes handlers with the child rather than replacing them"
     ],
     "accessibility": [
-      "Link text must be descriptive of the destination",
-      "External links should indicate they open in new window",
-      "Links must have visible focus indicators",
-      "Avoid using links that look like buttons without button semantics"
+      "The link text alone should make sense out of context",
+      "Say when a link opens a new window",
+      "Focus ring must stay visible",
+      "A link that looks like a button still needs link semantics"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Standard link with hover underline",
+      "description": "Accent text that underlines on hover.",
       "code": "<Link href=\"#\">Learn more about our services</Link>"
     },
     {
       "name": "Variants",
-      "description": "Visual style options",
-      "code": "<div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>\n  <Link href=\"#\" variant=\"default\">Default</Link>\n  <Link href=\"#\" variant=\"subtle\">Subtle</Link>\n  <Link href=\"#\" variant=\"muted\">Muted</Link>\n</div>"
+      "description": "Accent, then quieter, then quietest.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"md\" align=\"center\" wrap>\n  <Link href=\"#\" variant=\"default\">Default</Link>\n  <Link href=\"#\" variant=\"subtle\">Subtle</Link>\n  <Link href=\"#\" variant=\"muted\">Muted</Link>\n</Stack>"
     },
     {
       "name": "Underline Styles",
-      "description": "Different underline behaviors",
-      "code": "<div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>\n  <Link href=\"#\" underline=\"always\">Always underlined</Link>\n  <Link href=\"#\" underline=\"hover\">Underline on hover</Link>\n  <Link href=\"#\" underline=\"none\">No underline</Link>\n</div>"
+      "description": "Four rules for when the line shows.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"md\" align=\"center\" wrap>\n  <Link href=\"#\" underline=\"always\">Always underlined</Link>\n  <Link href=\"#\" underline=\"hover\">Underline on hover</Link>\n  <Link href=\"#\" underline=\"dotted\">Dotted underline</Link>\n  <Link href=\"#\" underline=\"none\">No underline</Link>\n</Stack>"
     },
     {
       "name": "External Link",
-      "description": "Link that opens in new tab",
+      "description": "Sets target and rel; you still supply the visible cue.",
       "code": "<Link href=\"https://example.com\" external>\n  View documentation ↗\n</Link>"
     },
     {
       "name": "As Child (Polymorphic)",
-      "description": "Renders as a custom element while applying Link styles and composing handlers. Useful with Next.js Link for client-side navigation.",
-      "code": "<Link asChild variant=\"subtle\" onClick={() => {}}>\n  <button type=\"button\" onClick={() => alert('Navigated!')}>\n    Polymorphic link as button\n  </button>\n</Link>"
+      "description": "Paints Link styling onto a router link and keeps both click handlers.",
+      "code": "<Link asChild variant=\"subtle\" onClick={() => {}}>\n  <a href=\"#pricing\" onClick={() => {}}>\n    Client-side navigation\n  </a>\n</Link>"
     }
   ],
   "relations": [
@@ -156,20 +141,15 @@
       "children: ReactNode - link text (required)",
       "href: string - destination URL",
       "variant: default|subtle|muted - visual style",
-      "underline: always|hover|none - underline behavior",
+      "underline: always|hover|none|dotted - underline behavior",
       "external: boolean - opens in new tab",
       "asChild: boolean - polymorphic child rendering with merged styles and composed event handlers"
     ],
-    "a11yRules": [
-      "A11Y_LINK_TEXT",
-      "A11Y_LINK_FOCUS"
-    ]
+    "a11yRules": ["A11Y_LINK_TEXT", "A11Y_LINK_FOCUS"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root"
-    ]
+    "subComponents": ["Root"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Link/Link.module.scss

@@ -1,15 +1,14 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+@use "../../recipes/action";
+@use "../../recipes/prose";
 
 .link {
   @include interactive-base;
+  @include action.inline;
+  @include prose.link;
 
   display: inline;
-  font-family: inherit;
-  font-size: inherit;
-  font-weight: inherit;
-  line-height: inherit;
-  text-decoration: none;
   cursor: pointer;
   border-radius: var(--fui-radius-sm, $fui-radius-sm);
 
@@ -20,10 +19,10 @@
 
 // Variants
 .default {
-  color: var(--fui-color-accent, $fui-color-accent);
+  color: var(--fui-link-color, var(--fui-link-ink, #{$fui-link-ink}));
 
   &:hover {
-    color: var(--fui-color-accent-hover, $fui-color-accent-hover);
+    color: var(--fui-link-color-hover, var(--fui-link-ink, #{$fui-link-ink}));
   }
 }
 
@@ -46,15 +45,32 @@
 // Underline styles
 .underline-always {
   text-decoration: underline;
-  text-underline-offset: 2px;
+  text-decoration-style: var(--fui-link-underline-style, solid);
+  text-underline-offset: 0.2em;
 }
 
 .underline-hover {
-  text-decoration: none;
+  text-decoration-line: var(--fui-link-underline-line, none);
+  text-decoration-style: var(--fui-link-underline-style, solid);
+  text-underline-offset: 0.2em;
+  text-decoration-color: color-mix(in srgb, currentColor 55%, transparent);
+
+  &:hover {
+    text-decoration-line: underline;
+    text-decoration-style: var(--fui-link-underline-style, solid);
+    text-decoration-color: currentColor;
+    text-underline-offset: 0.2em;
+  }
+}
+
+.underline-dotted {
+  text-decoration: underline dotted;
+  text-underline-offset: 0.2em;
+  text-decoration-thickness: from-font;
+  text-decoration-color: color-mix(in srgb, currentColor 55%, transparent);
 
   &:hover {
-    text-decoration: underline;
-    text-underline-offset: 2px;
+    text-decoration-color: currentColor;
   }
 }
 

package/src/components/Link/index.tsx

@@ -18,7 +18,7 @@ export interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement>
   /** Visual variant */
   variant?: 'default' | 'subtle' | 'muted';
   /** Underline style */
-  underline?: 'always' | 'hover' | 'none';
+  underline?: 'always' | 'hover' | 'none' | 'dotted';
   /** Open in new tab (adds rel="noopener noreferrer") */
   external?: boolean;
   /**

package/src/components/List/List.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "List",
-  "description": "Compound component for rendering ordered or unordered lists with consistent styling. Supports bullet, numbered, and icon-prefixed items.",
+  "description": "Stacks items down the page with evenly spaced bullets, numbers, or icons.",
   "category": "display",
-  "tags": [
-    "list",
-    "items",
-    "bullet",
-    "ordered",
-    "unordered"
-  ],
+  "tags": ["list", "items", "bullet", "ordered", "unordered"],
   "status": "stable",
   "sourcePath": "src/components/List/index.tsx",
   "exportName": "List",
@@ -31,35 +25,21 @@
       "description": "List type",
       "default": "ul",
       "required": false,
-      "values": [
-        "ul",
-        "ol"
-      ]
+      "values": ["ul", "ol"]
     },
     "variant": {
       "type": "enum",
       "description": "List style variant",
       "default": "disc",
       "required": false,
-      "values": [
-        "none",
-        "disc",
-        "decimal",
-        "icon"
-      ]
+      "values": ["none", "disc", "decimal", "icon"]
     },
     "gap": {
       "type": "enum",
       "description": "Spacing between items",
       "default": "sm",
       "required": false,
-      "values": [
-        "none",
-        "xs",
-        "sm",
-        "md",
-        "lg"
-      ]
+      "values": ["none", "xs", "sm", "md", "lg"]
     },
     "style": {
       "type": "object",
@@ -69,49 +49,45 @@
   },
   "usage": {
     "when": [
-      "Feature lists with checkmarks or icons",
-      "Ordered steps or instructions",
-      "Navigation lists in sidebars",
-      "Pricing plan feature comparisons"
+      "Steps, instructions, or anything with an order",
+      "Feature and benefit lists",
+      "Plain stacks of links in a sidebar"
     ],
     "whenNot": [
-      "Interactive selection lists (use Menu or Select)",
-      "Data tables with columns (use Table)",
-      "Cards in a grid (use Grid with Card)",
-      "Navigation tabs (use Tabs)"
+      "Items are pickable (use Menu or Select)",
+      "Items have columns (use Table)",
+      "Items need their own surface (use Card in a Grid)"
     ],
     "guidelines": [
-      "Use as=\"ol\" for sequential or numbered content",
-      "Use variant=\"icon\" with meaningful icons for feature lists",
-      "Keep list items concise and parallel in structure",
-      "Use consistent icons within a single list"
+      "Order matters? Use as=\"ol\" so the numbers are real",
+      "Keep one icon meaning per list — mixing icons reads as noise",
+      "Write items in parallel grammar; scanning depends on it",
+      "Stop nesting at two levels"
     ],
     "accessibility": [
-      "Use semantic list elements (ul, ol) for screen reader support",
-      "List items are automatically announced with count",
-      "Icons are decorative; ensure text conveys meaning",
-      "Avoid deeply nested lists (3+ levels)"
+      "Real ul/ol markup means screen readers announce the item count",
+      "Icons are decorative — the text has to carry the meaning"
     ]
   },
   "examples": [
     {
       "name": "Bullet List",
-      "description": "Default unordered list with bullets",
+      "description": "The default marker — reach for it when order does not matter.",
       "code": "<List variant=\"disc\">\n  <List.Item>First item</List.Item>\n  <List.Item>Second item</List.Item>\n  <List.Item>Third item</List.Item>\n</List>"
     },
     {
       "name": "Numbered List",
-      "description": "Ordered list with numbers",
+      "description": "as=\"ol\" makes the sequence real, not just visual.",
       "code": "<List as=\"ol\" variant=\"decimal\">\n  <List.Item>Create your account</List.Item>\n  <List.Item>Configure your settings</List.Item>\n  <List.Item>Start building</List.Item>\n</List>"
     },
     {
       "name": "Icon List",
-      "description": "List with custom icons per item",
+      "description": "Each item takes its own icon — checkmarks sell a feature list.",
       "code": "<List variant=\"icon\">\n  <List.Item icon={<Check weight=\"bold\" color=\"var(--fui-color-success)\" />}>\n    Unlimited projects\n  </List.Item>\n  <List.Item icon={<Check weight=\"bold\" color=\"var(--fui-color-success)\" />}>\n    Priority support\n  </List.Item>\n  <List.Item icon={<Check weight=\"bold\" color=\"var(--fui-color-success)\" />}>\n    Advanced analytics\n  </List.Item>\n</List>"
     },
     {
       "name": "No Style",
-      "description": "Plain list without markers",
+      "description": "No markers, wider gap — the shape for stacked nav links.",
       "code": "<List variant=\"none\" gap=\"md\">\n  <List.Item>Dashboard</List.Item>\n  <List.Item>Settings</List.Item>\n  <List.Item>Profile</List.Item>\n</List>"
     }
   ],
@@ -134,16 +110,11 @@
       "variant: none|disc|decimal|icon - list style",
       "gap: none|xs|sm|md|lg - item spacing"
     ],
-    "a11yRules": [
-      "A11Y_LIST_SEMANTIC",
-      "A11Y_LIST_NESTING"
-    ]
+    "a11yRules": ["A11Y_LIST_SEMANTIC", "A11Y_LIST_NESTING"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Item"
-    ]
+    "subComponents": ["Item"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/List/List.module.scss

@@ -1,50 +1,48 @@
-@use '../../tokens/variables' as *;
+@use "../../tokens/variables" as *;
+@use "../../recipes/layout" as layout;
+@use "../../recipes/prose" as prose;
 
 .list {
   margin: 0;
   padding: 0;
-  display: flex;
-  flex-direction: column;
 }
 
 // Variants
 .none {
-  list-style: none;
+  @include prose.list("none");
 }
 
 .disc {
-  list-style: disc;
-  padding-left: var(--fui-space-2, $fui-space-2);
+  @include prose.list("disc");
 }
 
 .decimal {
-  list-style: decimal;
-  padding-left: var(--fui-space-2, $fui-space-2);
+  @include prose.list("decimal");
 }
 
 .icon {
-  list-style: none;
+  @include prose.list("icon");
 }
 
 // Gap variants
 .gap-none {
-  gap: 0;
+  row-gap: layout.gap("none");
 }
 
 .gap-xs {
-  gap: var(--fui-space-1, $fui-space-1);
+  row-gap: layout.gap("xs");
 }
 
 .gap-sm {
-  gap: var(--fui-space-2, $fui-space-2);
+  row-gap: layout.gap("sm");
 }
 
 .gap-md {
-  gap: var(--fui-space-3, $fui-space-3);
+  row-gap: layout.gap("md");
 }
 
 .gap-lg {
-  gap: var(--fui-space-4, $fui-space-4);
+  row-gap: layout.gap("lg");
 }
 
 // List item
@@ -53,19 +51,16 @@
 }
 
 .iconItem {
-  display: flex;
-  align-items: flex-start;
-  gap: var(--fui-space-2, $fui-space-2);
+  align-items: start;
 }
 
 .iconWrapper {
-  display: flex;
+  display: inline-flex;
   align-items: center;
   justify-content: center;
-  flex-shrink: 0;
-  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+  min-inline-size: var(--fui-raw-space-12, 12px);
 }
 
 .itemContent {
-  flex: 1;
+  min-inline-size: 0;
 }

package/src/components/List/index.tsx

@@ -79,18 +79,12 @@ function ListItem({ children, icon, className, style, ...htmlProps }: ListItemPr
     .filter(Boolean)
     .join(' ');
 
-  if (variant === 'icon' && icon) {
-    return (
-      <li {...htmlProps} className={classes} style={style}>
-        <span className={styles.iconWrapper}>{icon}</span>
-        <span className={styles.itemContent}>{children}</span>
-      </li>
-    );
-  }
-
   return (
     <li {...htmlProps} className={classes} style={style}>
-      {children}
+      {variant === 'icon' && icon ? (
+        <span className={styles.iconWrapper}>{icon}</span>
+      ) : null}
+      <span className={styles.itemContent}>{children}</span>
     </li>
   );
 }

package/src/components/Listbox/Listbox.contract.json

@@ -1,16 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Listbox",
-  "description": "Controlled listbox for search results, autocomplete dropdowns, and command menus. Provides Menu-like styling without requiring a trigger.",
-  "category": "forms",
-  "tags": [
-    "listbox",
-    "search",
-    "autocomplete",
-    "combobox",
-    "command",
-    "dropdown"
-  ],
+  "description": "Shows a keyboard-navigable list of options with no trigger of its own.",
+  "category": "inputs",
+  "tags": ["listbox", "search", "autocomplete", "combobox", "command", "dropdown"],
   "status": "stable",
   "sourcePath": "src/components/Listbox/index.tsx",
   "exportName": "Listbox",
@@ -50,22 +43,22 @@
   },
   "usage": {
     "when": [
-      "Search result dropdowns",
+      "Results under a search field",
       "Autocomplete suggestions",
       "Command palette results",
-      "Keyboard-navigable option lists"
+      "Any list the user drives with arrow keys"
     ],
     "whenNot": [
-      "Static lists without selection (use List)",
-      "Action menus with trigger button (use Menu)",
-      "Form field selection (use Select)",
-      "Navigation menus (use Sidebar or Tabs)"
+      "A list nobody selects from (use List)",
+      "Actions behind a button (use Menu)",
+      "A form field (use Select)",
+      "Navigation (use Sidebar or Tabs)"
     ],
     "guidelines": [
-      "Control open/close state externally based on input focus or query",
-      "Listbox provides arrow/home/end + Enter/Space keyboard navigation when focused",
-      "Use Listbox.Empty for no results state",
-      "Group related items with Listbox.Group when appropriate"
+      "You own open state — drive it from the input's focus and query",
+      "Arrows, Home, End, Enter, and Space are handled for you",
+      "Always supply Listbox.Empty",
+      "Group once the list draws from more than one source"
     ],
     "accessibility": [
       "Uses listbox and option ARIA roles",
@@ -77,27 +70,27 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Basic listbox with selectable items",
+      "description": "Plain options, one selectable at a time.",
       "code": "<Listbox aria-label=\"Options\">\n  <Listbox.Item selected>First option</Listbox.Item>\n  <Listbox.Item>Second option</Listbox.Item>\n  <Listbox.Item>Third option</Listbox.Item>\n</Listbox>"
     },
     {
       "name": "Search Results",
-      "description": "Typical search results pattern with label and metadata",
+      "description": "Trailing metadata explains each match.",
       "code": "<Listbox aria-label=\"Search results\">\n  <Listbox.Item selected>\n    <span style={{ fontWeight: 500 }}>Button</span>\n    <span style={{ marginLeft: 'auto', fontSize: '0.75rem', color: 'var(--fui-text-tertiary)' }}>Components</span>\n  </Listbox.Item>\n  <Listbox.Item>\n    <span style={{ fontWeight: 500 }}>Badge</span>\n    <span style={{ marginLeft: 'auto', fontSize: '0.75rem', color: 'var(--fui-text-tertiary)' }}>Components</span>\n  </Listbox.Item>\n  <Listbox.Item>\n    <span style={{ fontWeight: 500 }}>Box</span>\n    <span style={{ marginLeft: 'auto', fontSize: '0.75rem', color: 'var(--fui-text-tertiary)' }}>Layout</span>\n  </Listbox.Item>\n</Listbox>"
     },
     {
       "name": "With Groups",
-      "description": "Grouped items with labels",
+      "description": "Labels split the list by source.",
       "code": "<Listbox aria-label=\"Commands\">\n  <Listbox.Group label=\"Recent\">\n    <Listbox.Item selected>Open file...</Listbox.Item>\n    <Listbox.Item>Save as...</Listbox.Item>\n  </Listbox.Group>\n  <Listbox.Group label=\"Actions\">\n    <Listbox.Item>Copy</Listbox.Item>\n    <Listbox.Item>Paste</Listbox.Item>\n    <Listbox.Item disabled>Cut</Listbox.Item>\n  </Listbox.Group>\n</Listbox>"
     },
     {
       "name": "Empty State",
-      "description": "No results found message",
+      "description": "Says so when nothing matches.",
       "code": "<Listbox aria-label=\"Search results\">\n  <Listbox.Empty>No results found</Listbox.Empty>\n</Listbox>"
     },
     {
       "name": "With Disabled Items",
-      "description": "Mix of enabled and disabled items",
+      "description": "Unavailable rows stay visible but inert.",
       "code": "<Listbox aria-label=\"Options\">\n  <Listbox.Item>Available option</Listbox.Item>\n  <Listbox.Item disabled>Disabled option</Listbox.Item>\n  <Listbox.Item>Another option</Listbox.Item>\n</Listbox>"
     }
   ],
@@ -130,21 +123,12 @@
       "Listbox.Item selected: boolean - highlight state",
       "Listbox.Item disabled: boolean - non-interactive"
     ],
-    "a11yRules": [
-      "A11Y_LISTBOX_ROLE",
-      "A11Y_OPTION_ROLE"
-    ]
+    "a11yRules": ["A11Y_LISTBOX_ROLE", "A11Y_OPTION_ROLE"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Item",
-      "Group",
-      "Empty"
-    ],
-    "requiredChildren": [
-      "Item"
-    ],
+    "subComponents": ["Item", "Group", "Empty"],
+    "requiredChildren": ["Item"],
     "commonPatterns": [
       "<Listbox aria-label=\"Search results\">{results.map(item => <Listbox.Item key={item.id} selected={item.id === selectedId} onClick={() => onSelect(item)}>{item.label}</Listbox.Item>)}</Listbox>"
     ]