@usefragments/ui 1.6.0 → 2.0.0

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

@@ -17,16 +17,22 @@
   }
 }
 
-// Variants
-.default {
-  color: var(--fui-color-accent, $fui-color-accent);
+// Tone. The accent ink is `--fui-link-ink` (the read-safe step, gated by
+// read-safe-contrast.test.ts); hover keeps the same ink and underlines.
+.toneAccent {
+  color: var(--fui-link-ink, #{$fui-link-ink});
+}
+
+.toneNeutral {
+  color: var(--fui-text-primary, $fui-text-primary);
 
   &:hover {
-    color: var(--fui-color-accent-hover, $fui-color-accent-hover);
+    color: var(--fui-color-accent, $fui-color-accent);
   }
 }
 
-.subtle {
+// Text-hierarchy colour on a neutral link; hover steps one rung up the ladder.
+.colorPrimary {
   color: var(--fui-text-primary, $fui-text-primary);
 
   &:hover {
@@ -34,7 +40,15 @@
   }
 }
 
-.muted {
+.colorSecondary {
+  color: var(--fui-text-secondary, $fui-text-secondary);
+
+  &:hover {
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+}
+
+.colorTertiary {
   color: var(--fui-text-tertiary, $fui-text-tertiary);
 
   &:hover {
@@ -45,15 +59,32 @@
 // Underline styles
 .underline-always {
   text-decoration: underline;
-  text-underline-offset: var(--fui-raw-space-2);
+  text-decoration-style: solid;
+  text-underline-offset: 0.2em;
 }
 
 .underline-hover {
-  text-decoration: none;
+  text-decoration-line: none;
+  text-decoration-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: 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: var(--fui-raw-space-2);
+    text-decoration-color: currentColor;
   }
 }
 

package/src/components/Link/index.tsx

@@ -13,12 +13,20 @@ function composeEventHandlers<T extends (...args: any[]) => void>(
   }) as T;
 }
 
-export interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+export type LinkTone = 'accent' | 'neutral';
+export type LinkColor = 'primary' | 'secondary' | 'tertiary';
+
+export interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'color'> {
   children: React.ReactNode;
-  /** Visual variant */
-  variant?: 'default' | 'subtle' | 'muted';
+  /** Colour. `accent` (default) is the link ink; `neutral` reads as body text
+   * until hovered, for secondary and contextual links.
+   * @default 'accent' */
+  tone?: LinkTone;
+  /** Text-hierarchy colour for a `neutral` link (Text's `color` axis).
+   * `tertiary` is the quietest link, for metadata and footers. */
+  color?: LinkColor;
   /** Underline style */
-  underline?: 'always' | 'hover' | 'none';
+  underline?: 'always' | 'hover' | 'none' | 'dotted';
   /** Open in new tab (adds rel="noopener noreferrer") */
   external?: boolean;
   /**
@@ -32,11 +40,23 @@ export interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement>
   style?: React.CSSProperties;
 }
 
+const TONE_CLASS: Record<LinkTone, string> = {
+  accent: styles.toneAccent,
+  neutral: styles.toneNeutral,
+};
+
+const COLOR_CLASS: Record<LinkColor, string> = {
+  primary: styles.colorPrimary,
+  secondary: styles.colorSecondary,
+  tertiary: styles.colorTertiary,
+};
+
 const LinkRoot = React.forwardRef<HTMLAnchorElement, LinkProps>(
   function Link(
     {
       children,
-      variant = 'default',
+      tone = 'accent',
+      color,
       underline = 'hover',
       external = false,
       asChild = false,
@@ -50,7 +70,8 @@ const LinkRoot = React.forwardRef<HTMLAnchorElement, LinkProps>(
   ) {
     const classes = [
       styles.link,
-      styles[variant],
+      TONE_CLASS[tone],
+      color && COLOR_CLASS[color],
       styles[`underline-${underline}`],
       className,
     ]

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

@@ -1,23 +1,17 @@
 {
   "$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",
   "propsSummary": [
     "children: node (required)",
     "as: ul|ol (default: ul)",
-    "variant: none|disc|decimal|icon (default: disc)",
-    "gap: none|xs|sm|md|lg (default: sm)",
+    "marker: none|disc|decimal|icon (default: disc)",
+    "gap: none|xs|sm|md|lg|xl (default: sm)",
     "style: object"
   ],
   "props": {
@@ -31,35 +25,21 @@
       "description": "List type",
       "default": "ul",
       "required": false,
-      "values": [
-        "ul",
-        "ol"
-      ]
+      "values": ["ul", "ol"]
     },
-    "variant": {
+    "marker": {
       "type": "enum",
-      "description": "List style variant",
+      "description": "Marker drawn before each item",
       "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", "xl"]
     },
     "style": {
       "type": "object",
@@ -69,50 +49,46 @@
   },
   "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",
-      "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>"
+      "description": "The default marker — reach for it when order does not matter.",
+      "code": "<List marker=\"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",
-      "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>"
+      "description": "as=\"ol\" makes the sequence real, not just visual.",
+      "code": "<List as=\"ol\" marker=\"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",
-      "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>"
+      "description": "Each item takes its own icon — checkmarks sell a feature list.",
+      "code": "<List marker=\"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",
-      "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>"
+      "description": "No markers, wider gap — the shape for stacked nav links.",
+      "code": "<List marker=\"none\" gap=\"md\">\n  <List.Item>Dashboard</List.Item>\n  <List.Item>Settings</List.Item>\n  <List.Item>Profile</List.Item>\n</List>"
     }
   ],
   "relations": [
@@ -131,19 +107,14 @@
     "propsSummary": [
       "children: List.Item[] - list items (required)",
       "as: ul|ol - list type",
-      "variant: none|disc|decimal|icon - list style",
-      "gap: none|xs|sm|md|lg - item spacing"
+      "marker: none|disc|decimal|icon - marker before each item",
+      "gap: none|xs|sm|md|lg|xl - 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,13 +1,14 @@
 @use "../../tokens/variables" as *;
+@use "../../tokens/measurements.generated" as measurements;
 @use "../../recipes/layout" as layout;
 @use "../../recipes/prose" as prose;
 
 .list {
-  margin: 0;
-  padding: 0;
+  margin: var(--fui-raw-space-0, #{measurements.raw-space(0)});
+  padding: var(--fui-raw-space-0, #{measurements.raw-space(0)});
 }
 
-// Variants
+// Markers
 .none {
   @include prose.list("none");
 }
@@ -24,7 +25,7 @@
   @include prose.list("icon");
 }
 
-// Gap variants
+// Gap
 .gap-none {
   row-gap: layout.gap("none");
 }
@@ -45,6 +46,10 @@
   row-gap: layout.gap("lg");
 }
 
+.gap-xl {
+  row-gap: layout.gap("xl");
+}
+
 // List item
 .item {
   color: var(--fui-text-primary, $fui-text-primary);
@@ -58,7 +63,7 @@
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  min-inline-size: var(--fui-raw-space-12);
+  min-inline-size: var(--fui-raw-space-12, #{measurements.raw-space(12)});
 }
 
 .itemContent {

package/src/components/List/index.tsx

@@ -7,19 +7,23 @@ import styles from './List.module.scss';
 // Types
 // ============================================
 
+export type ListMarker = 'none' | 'disc' | 'decimal' | 'icon';
+
 export interface ListProps extends React.HTMLAttributes<HTMLUListElement | HTMLOListElement> {
   children: React.ReactNode;
   /** List type */
   as?: 'ul' | 'ol';
-  /** List style variant */
-  variant?: 'none' | 'disc' | 'decimal' | 'icon';
-  /** Spacing between items */
-  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg';
+  /** Marker drawn before each item. Not chrome, so it is `marker`, not `variant`.
+   * @default 'disc' */
+  marker?: ListMarker;
+  /** Spacing between items
+   * @default 'sm' */
+  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
 }
 
 export interface ListItemProps extends React.HTMLAttributes<HTMLLIElement> {
   children: React.ReactNode;
-  /** Icon to display (only used with variant="icon") */
+  /** Icon to display (only used with marker="icon") */
   icon?: React.ReactNode;
 }
 
@@ -28,10 +32,10 @@ export interface ListItemProps extends React.HTMLAttributes<HTMLLIElement> {
 // ============================================
 
 interface ListContextValue {
-  variant: NonNullable<ListProps['variant']>;
+  marker: ListMarker;
 }
 
-const ListContext = React.createContext<ListContextValue>({ variant: 'disc' });
+const ListContext = React.createContext<ListContextValue>({ marker: 'disc' });
 
 function useListContext() {
   return React.useContext(ListContext);
@@ -44,7 +48,7 @@ function useListContext() {
 function ListRoot({
   children,
   as: Component = 'ul',
-  variant = 'disc',
+  marker = 'disc',
   gap = 'sm',
   className,
   style,
@@ -52,7 +56,7 @@ function ListRoot({
 }: ListProps) {
   const classes = [
     styles.list,
-    styles[variant],
+    styles[marker],
     styles[`gap-${gap}`],
     className,
   ]
@@ -60,7 +64,7 @@ function ListRoot({
     .join(' ');
 
   return (
-    <ListContext.Provider value={{ variant }}>
+    <ListContext.Provider value={{ marker }}>
       <Component {...htmlProps} className={classes} style={style}>
         {children}
       </Component>
@@ -69,11 +73,11 @@ function ListRoot({
 }
 
 function ListItem({ children, icon, className, style, ...htmlProps }: ListItemProps) {
-  const { variant } = useListContext();
+  const { marker } = useListContext();
 
   const classes = [
     styles.item,
-    variant === 'icon' && styles.iconItem,
+    marker === 'icon' && styles.iconItem,
     className,
   ]
     .filter(Boolean)
@@ -81,7 +85,7 @@ function ListItem({ children, icon, className, style, ...htmlProps }: ListItemPr
 
   return (
     <li {...htmlProps} className={classes} style={style}>
-      {variant === 'icon' && icon ? (
+      {marker === 'icon' && icon ? (
         <span className={styles.iconWrapper}>{icon}</span>
       ) : null}
       <span className={styles.itemContent}>{children}</span>

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>"
     ]

package/src/components/Listbox/Listbox.module.scss

@@ -1,18 +1,21 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../tokens/measurements.generated" as measurements;
+@use "../../recipes/layout" as layout;
 @use "../../recipes/popup" as popup;
 @use "../../recipes/typography" as typography;
 
 .listbox {
-  @include popup.container;
+  @include popup.inline-container;
   @include popup.viewport;
 
-  min-inline-size: var(--fui-listbox-min-inline, 192px);
-  border-color: var(--fui-form-group-border, $fui-border);
+  min-inline-size: layout.measure("menu-min");
 
   &:focus-visible {
     @include focus-ring;
   }
+
+  @include high-contrast-outline;
 }
 
 .item {
@@ -56,23 +59,14 @@
 .empty {
   @include typography.role("body-compact");
 
-  padding-block: var(--fui-popup-row-block-inset);
-  padding-inline: var(--fui-popup-row-inline-inset);
+  padding-block: var(
+    --fui-popup-row-block-inset,
+    var(--fui-raw-space-8, #{measurements.raw-space(8)})
+  );
+  padding-inline: var(
+    --fui-popup-row-inline-inset,
+    var(--fui-raw-space-8, #{measurements.raw-space(8)})
+  );
   color: var(--fui-text-tertiary, $fui-text-tertiary);
   text-align: center;
 }
-
-@media (prefers-contrast: more) {
-  .listbox {
-    border-color: var(--fui-text-primary, $fui-text-primary);
-    outline: var(--fui-stroke-hairline, 1px) solid var(--fui-text-primary, $fui-text-primary);
-    outline-offset: calc(-1 * var(--fui-stroke-default, 2px));
-  }
-
-  .itemSelected,
-  .itemActive {
-    outline: var(--fui-focus-ring-width, $fui-focus-ring-width) solid
-      var(--fui-color-accent, $fui-color-accent);
-    outline-offset: calc(-1 * var(--fui-focus-ring-width, $fui-focus-ring-width));
-  }
-}