@usefragments/ui 1.6.0 → 2.0.0

package/src/components/Image/Image.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Image",
-  "description": "Responsive image component with aspect ratio control, loading states, and error fallbacks. Handles image display with consistent styling.",
+  "description": "Renders a picture at a fixed shape with a built-in fallback when loading fails.",
   "category": "display",
-  "tags": [
-    "image",
-    "media",
-    "photo",
-    "picture",
-    "visual"
-  ],
+  "tags": ["image", "media", "photo", "picture", "visual"],
   "status": "stable",
   "sourcePath": "src/components/Image/index.tsx",
   "exportName": "Image",
@@ -44,25 +38,14 @@
       "description": "Aspect ratio of the image container",
       "default": "auto",
       "required": false,
-      "values": [
-        "1:1",
-        "4:3",
-        "16:9",
-        "21:9",
-        "auto"
-      ]
+      "values": ["1:1", "4:3", "16:9", "21:9", "auto"]
     },
     "objectFit": {
       "type": "enum",
       "description": "How the image fits within its container",
       "default": "cover",
       "required": false,
-      "values": [
-        "cover",
-        "contain",
-        "fill",
-        "none"
-      ]
+      "values": ["cover", "contain", "fill", "none"]
     },
     "width": {
       "type": "union",
@@ -79,13 +62,7 @@
       "description": "Border radius",
       "default": "none",
       "required": false,
-      "values": [
-        "none",
-        "sm",
-        "md",
-        "lg",
-        "full"
-      ]
+      "values": ["none", "sm", "md", "lg", "full"]
     },
     "fallback": {
       "type": "node",
@@ -120,50 +97,45 @@
   },
   "usage": {
     "when": [
-      "Displaying product images in cards or grids",
-      "Hero images with specific aspect ratios",
-      "User-uploaded content that may fail to load",
-      "Thumbnails in lists or galleries"
+      "Product shots, thumbnails, and hero art",
+      "Uploads you do not control and cannot trust to load"
     ],
     "whenNot": [
-      "User avatars (use Avatar component)",
-      "Icons or symbols (use Icon component)",
-      "Background images (use CSS background-image)",
-      "SVG illustrations (use inline SVG or Image component)"
+      "A person (use Avatar)",
+      "A symbol (use Icon)",
+      "Pure decoration behind content (use a CSS background)"
     ],
     "guidelines": [
-      "Always provide meaningful alt text for accessibility",
-      "Use appropriate aspect ratios for consistent layouts",
-      "Provide fallback content for failed loads",
-      "Use objectFit=\"contain\" for logos to preserve aspect ratio",
-      "Use imgProps / onImageLoad / onImageError when you need lower-level img control"
+      "Set aspectRatio so a grid holds its shape before the file arrives",
+      "objectFit=\"contain\" for logos, \"cover\" for photography",
+      "Always give fallback something to say",
+      "imgProps, onImageLoad, and onImageError expose the raw img when you need it"
     ],
     "accessibility": [
-      "Alt text is required and must describe the image content",
-      "Decorative images should have empty alt=\"\"",
-      "Avoid text in images; if necessary, describe the text in alt",
-      "Ensure sufficient contrast between image and surrounding content"
+      "alt is required — describe what the picture shows",
+      "Decoration takes alt=\"\"",
+      "Words baked into an image must be repeated in alt"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic image display",
+      "description": "src plus alt — the shape follows the file.",
       "code": "<Image\n  src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=400&h=300&fit=crop\"\n  alt=\"Code on a screen\"\n  width={300}\n/>"
     },
     {
       "name": "Aspect Ratios",
-      "description": "Different aspect ratio options",
+      "description": "Lock the frame so a grid stays even whatever the file is.",
       "code": "<div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap' }}>\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=200&h=200&fit=crop\"\n    alt=\"Square image\"\n    aspectRatio=\"1:1\"\n    width={100}\n  />\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=200&h=150&fit=crop\"\n    alt=\"4:3 image\"\n    aspectRatio=\"4:3\"\n    width={120}\n  />\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=320&h=180&fit=crop\"\n    alt=\"16:9 image\"\n    aspectRatio=\"16:9\"\n    width={160}\n  />\n</div>"
     },
     {
       "name": "Rounded Corners",
-      "description": "Border radius options",
+      "description": "Rounding softens the frame; match it to the surface it sits on.",
       "code": "<div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=100&h=100&fit=crop\"\n    alt=\"No rounding\"\n    rounded=\"none\"\n    width={80}\n    height={80}\n  />\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=100&h=100&fit=crop\"\n    alt=\"Medium rounding\"\n    rounded=\"md\"\n    width={80}\n    height={80}\n  />\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=100&h=100&fit=crop\"\n    alt=\"Full rounding\"\n    rounded=\"full\"\n    width={80}\n    height={80}\n  />\n</div>"
     },
     {
       "name": "With Fallback",
-      "description": "Fallback content for loading/error states",
+      "description": "A dead URL shows this instead of a broken-image glyph.",
       "code": "<Image\n  src=\"https://invalid-url.example/image.jpg\"\n  alt=\"Image that will fail\"\n  width={200}\n  height={150}\n  rounded=\"md\"\n  fallback={\n    <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'center', height: '100%', background: 'var(--fui-color-surface-secondary)' }}>\n      <span style={{ color: 'var(--fui-color-text-tertiary)' }}>No image</span>\n    </div>\n  }\n/>"
     }
   ],
@@ -189,16 +161,11 @@
       "fallback: ReactNode - loading/error content",
       "imgProps/onImageLoad/onImageError - low-level img customization and events"
     ],
-    "a11yRules": [
-      "A11Y_IMG_ALT",
-      "A11Y_IMG_DECORATIVE"
-    ]
+    "a11yRules": ["A11Y_IMG_ALT", "A11Y_IMG_DECORATIVE"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root"
-    ]
+    "subComponents": ["Root"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Input/Input.contract.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Input",
-  "description": "Text input field for single-line user data entry",
-  "category": "forms",
+  "description": "Collects a single line of user-entered text.",
+  "category": "inputs",
   "tags": ["form", "input", "text"],
   "status": "stable",
   "sourcePath": "src/components/Input/index.tsx",
@@ -15,7 +15,6 @@
     "size: sm|md|lg (default: md)",
     "disabled: boolean (default: false)",
     "error: boolean (default: false)",
-    "success: boolean (default: false)",
     "label: string",
     "required: boolean (default: false)",
     "helperText: string",
@@ -78,12 +77,6 @@
       "default": "false",
       "required": false
     },
-    "success": {
-      "type": "boolean",
-      "description": "Whether to show success/validated styling",
-      "default": "false",
-      "required": false
-    },
     "label": {
       "type": "string",
       "description": "Label text displayed above input",
@@ -181,10 +174,9 @@
   },
   "usage": {
     "when": [
-      "Collecting single-line text data from users",
-      "Email, password, phone number, or URL input",
+      "Single-line answers: name, email, password, phone, URL",
       "Search fields",
-      "Short form fields (name, title, etc.)"
+      "Short free-form values a list cannot cover"
     ],
     "whenNot": [
       "Multi-line text (use Textarea)",
@@ -193,83 +185,73 @@
       "Date/time input (use DatePicker)"
     ],
     "guidelines": [
-      "Always provide a label for accessibility",
-      "Use appropriate input type for data validation",
-      "Show validation errors with error prop and helperText",
-      "Use placeholder for format hints, not labels",
-      "Use the shortcut prop for embedded keyboard hints instead of custom kbd markup around inputs",
-      "Shortcut hints are display-only by default; set shortcutBehavior=\"focus-input\" to opt into global hotkey focusing"
+      "Give every field a label",
+      "Match type to the data — it drives validation and mobile keyboards",
+      "Placeholder shows format; it never replaces the label",
+      "Pair error with helperText so the reason is announced",
+      "Use the shortcut prop for kbd hints instead of custom markup",
+      "shortcut is display-only; shortcutBehavior=\"focus-input\" adds the global hotkey"
     ],
     "accessibility": [
-      "Labels must be associated with inputs",
-      "Error messages should be announced to screen readers",
-      "Required fields should be indicated"
+      "Label is programmatically tied to the input",
+      "Error text is announced to screen readers",
+      "Required fields are marked"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic text input",
+      "description": "Label plus a placeholder that hints the format.",
       "code": "<Input label=\"Name\" placeholder=\"Enter your name\" />"
     },
     {
       "name": "With Value",
-      "description": "Input with pre-filled value",
+      "description": "Starts with a value already in the field.",
       "code": "<Input label=\"Email\" type=\"email\" value=\"user@example.com\" />"
     },
     {
       "name": "With Helper",
-      "description": "Input with helper text",
+      "description": "Supporting text sits under the field.",
       "code": "<Input\n  label=\"Password\"\n  type=\"password\"\n  placeholder=\"Create a password\"\n  helperText=\"Must be at least 8 characters\"\n/>"
     },
     {
       "name": "Error State",
-      "description": "Input showing validation error",
+      "description": "Red border, and helperText becomes the reason.",
       "code": "<Input\n  label=\"Email\"\n  type=\"email\"\n  value=\"invalid-email\"\n  error\n  helperText=\"Please enter a valid email address\"\n/>"
     },
     {
       "name": "Disabled",
-      "description": "Non-interactive input",
-      "code": "<Input label=\"Username\" value=\"readonly-user\" disabled />"
+      "description": "Dimmed, unfocusable, still shows its value.",
+      "code": "<Input label=\"Username\" value=\"ada.lovelace\" disabled />"
     },
     {
       "name": "Required",
-      "description": "Required field with asterisk indicator",
+      "description": "Asterisk marks the field as mandatory.",
       "code": "<Input\n  label=\"Email\"\n  type=\"email\"\n  placeholder=\"user@example.com\"\n  required\n/>"
     },
     {
       "name": "Sizes",
-      "description": "Available size variants",
+      "description": "Three heights: sm, md, lg.",
       "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '12px', maxWidth: '300px' }}>\n  <Input label=\"Small\" size=\"sm\" placeholder=\"Small input\" />\n  <Input label=\"Medium\" size=\"md\" placeholder=\"Medium input\" />\n  <Input label=\"Large\" size=\"lg\" placeholder=\"Large input\" />\n</div>"
     },
     {
       "name": "Bare Input (Field Composition)",
-      "description": "Disable the built-in wrapper for custom Field composition",
+      "description": "Drops the built-in label wrapper so Field owns the layout.",
       "code": "<Input\n  withFieldWrapper={false}\n  aria-label=\"Search\"\n  placeholder=\"Search...\"\n  rootProps={{ 'data-demo': 'bare-input-wrapper' }}\n/>"
     },
-    {
-      "name": "Shortcut Focus Hotkey",
-      "description": "Display shortcut hint and opt into focus behavior",
-      "code": "<Input\n  label=\"Command Palette\"\n  placeholder=\"Search commands\"\n  shortcut=\"⌘K\"\n  shortcutBehavior=\"focus-input\"\n/>"
-    },
     {
       "name": "Search With Shortcut",
-      "description": "Search input with a leading icon and embedded kbd hint",
+      "description": "Leading icon and a ⌘K hint that focuses the field.",
       "code": "<Input\n  aria-label=\"Search findings\"\n  placeholder=\"Search findings...\"\n  shortcut=\"⌘K\"\n  shortcutBehavior=\"focus-input\"\n  startAdornment={<MagnifyingGlass aria-hidden=\"true\" />}\n  withFieldWrapper={false}\n/>"
     },
-    {
-      "name": "Success State",
-      "description": "Input showing validated/success styling",
-      "code": "<Input\n  label=\"Email\"\n  type=\"email\"\n  value=\"user@example.com\"\n  success\n  helperText=\"Email verified\"\n/>"
-    },
     {
       "name": "With Start Adornment",
-      "description": "Input with icon or prefix before the text",
+      "description": "Prefix sits inside the field, before the text.",
       "code": "<Input\n  label=\"Price\"\n  placeholder=\"0.00\"\n  startAdornment={<span>$</span>}\n/>"
     },
     {
       "name": "With End Adornment",
-      "description": "Input with icon or suffix after the text",
+      "description": "Suffix sits inside the field, after the text.",
       "code": "<Input\n  label=\"Weight\"\n  placeholder=\"0\"\n  endAdornment={<span>kg</span>}\n/>"
     }
   ],
@@ -299,7 +281,6 @@
       "disabled: boolean - disables interaction",
       "required: boolean - required field indicator",
       "error: boolean - shows error styling",
-      "success: boolean - shows success/validated styling",
       "startAdornment: ReactNode - content before the input (icon or prefix)",
       "endAdornment: ReactNode - content after the input (icon or suffix)",
       "shortcut: string - visual kbd hint inside the input; do not hand-roll extra kbd markup",

package/src/components/Input/Input.module.scss

@@ -40,6 +40,8 @@
   &:focus-visible {
     @include field.focus-state;
   }
+
+  @include high-contrast-outline;
 }
 
 // Size variants — shared control-size + field-padding path
@@ -63,18 +65,7 @@
   @include field.invalid-state;
 
   &:focus-visible {
-    border-color: var(--fui-color-danger-text, $fui-color-danger-text);
-    @include focus-ring-error;
-  }
-}
-
-// Success state — green border for validated fields (DoorDash/Stocksy pattern)
-.success {
-  border-color: var(--fui-color-success-text, $fui-color-success-text);
-
-  &:focus-visible {
-    border-color: var(--fui-color-success-text, $fui-color-success-text);
-    @include focus-ring-success;
+    @include field.invalid-focus-state;
   }
 }
 
@@ -83,12 +74,6 @@
   color: var(--fui-color-danger-text, $fui-color-danger-text);
 }
 
-// Auto-detect success state via :has() — applies success color to helper
-.wrapper[data-success] .helper,
-.helperSuccess {
-  color: var(--fui-color-success-text, $fui-color-success-text);
-}
-
 // ============================================
 // Input with adornments or shortcut indicator
 // ============================================
@@ -149,18 +134,7 @@
     @include field.invalid-state;
 
     &:focus-within {
-      border-color: var(--fui-color-danger-text, $fui-color-danger-text);
-      @include focus-ring-error;
-    }
-  }
-
-  // Success state on adornment container
-  &:has(.success) {
-    border-color: var(--fui-color-success-text, $fui-color-success-text);
-
-    &:focus-within {
-      border-color: var(--fui-color-success-text, $fui-color-success-text);
-      @include focus-ring-success;
+      @include field.invalid-focus-state;
     }
   }
 }
@@ -200,7 +174,8 @@
   font-variant-numeric: tabular-nums;
   color: var(--fui-kbd-color, var(--fui-text-tertiary, #{$fui-text-tertiary}));
   background: var(--fui-kbd-bg, var(--fui-bg-elevated, #{$fui-bg-elevated}));
-  border: var(--fui-stroke-hairline, 1px) solid var(--fui-kbd-border, var(--fui-border, #{$fui-border}));
+  border: var(--fui-stroke-hairline, 1px) solid
+    var(--fui-kbd-border, var(--fui-border, #{$fui-border}));
   border-radius: var(--fui-kbd-radius, var(--fui-radius-sm, #{$fui-radius-sm}));
   box-shadow: var(--fui-kbd-shadow, none);
   pointer-events: none;
@@ -208,30 +183,6 @@
   user-select: none;
 }
 
-// ============================================
-// Accessibility: High Contrast Mode
-// ============================================
-
-@media (prefers-contrast: more) {
-  .input {
-    border-width: 2px;
-    border-color: var(--fui-text-primary, $fui-text-primary);
-
-    &:focus-visible {
-      border-color: var(--fui-color-accent, $fui-color-accent);
-    }
-  }
-
-  .error,
-  .input[aria-invalid] {
-    border-color: var(--fui-color-danger-text, $fui-color-danger-text);
-  }
-
-  .success {
-    border-color: var(--fui-color-success-text, $fui-color-success-text);
-  }
-}
-
 // ============================================
 // Accessibility: Reduced Motion
 // ============================================

package/src/components/Input/index.tsx

@@ -30,8 +30,6 @@ export interface InputProps extends Omit<
   disabled?: boolean;
   /** Show error styling */
   error?: boolean;
-  /** Show success styling */
-  success?: boolean;
   /** Visible label text */
   label?: string;
   /** Whether the field is required */
@@ -105,7 +103,6 @@ const InputRoot = React.forwardRef<HTMLInputElement, InputProps>(function Input(
     size: sizeProp,
     disabled = false,
     error = false,
-    success = false,
     required = false,
     label,
     helperText,
@@ -174,23 +171,11 @@ const InputRoot = React.forwardRef<HTMLInputElement, InputProps>(function Input(
 
   const hasAdornment = !!(startAdornment || endAdornment);
 
-  const inputClasses = [
-    styles.input,
-    styles[size],
-    error && styles.error,
-    success && styles.success,
-    inputClassName,
-  ]
+  const inputClasses = [styles.input, styles[size], error && styles.error, inputClassName]
     .filter(Boolean)
     .join(" ");
 
-  const helperClasses = [
-    styles.helper,
-    error && styles.helperError,
-    success && styles.helperSuccess,
-  ]
-    .filter(Boolean)
-    .join(" ");
+  const helperClasses = [styles.helper, error && styles.helperError].filter(Boolean).join(" ");
 
   const wrapperClasses = [styles.wrapper, className].filter(Boolean).join(" ");
   const labelClasses = styles.label;
@@ -275,7 +260,6 @@ const InputRoot = React.forwardRef<HTMLInputElement, InputProps>(function Input(
       {...rootProps}
       disabled={disabled}
       invalid={error}
-      data-success={success || undefined}
       className={[wrapperClasses, rootProps?.className].filter(Boolean).join(" ")}
       style={{ ...(rootProps?.style ?? {}), ...(style ?? {}) }}
     >

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

@@ -1,22 +1,17 @@
 {
   "$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)",
+    "tone: accent|neutral (default: accent)",
+    "color: primary|secondary|tertiary",
+    "underline: always|hover|none|dotted (default: hover)",
     "external: boolean (default: false)",
     "asChild: boolean (default: false)",
     "className: string",
@@ -30,27 +25,25 @@
       "description": "Link text content",
       "required": true
     },
-    "variant": {
+    "tone": {
+      "type": "enum",
+      "description": "Colour. accent is the link ink; neutral reads as body text until hovered",
+      "default": "accent",
+      "required": false,
+      "values": ["accent", "neutral"]
+    },
+    "color": {
       "type": "enum",
-      "description": "Visual style variant",
-      "default": "default",
+      "description": "Text-hierarchy colour for a neutral link (Text color axis); tertiary is the quietest link",
       "required": false,
-      "values": [
-        "default",
-        "subtle",
-        "muted"
-      ]
+      "values": ["primary", "secondary", "tertiary"]
     },
     "underline": {
       "type": "enum",
       "description": "Underline behavior",
       "default": "hover",
       "required": false,
-      "values": [
-        "always",
-        "hover",
-        "none"
-      ]
+      "values": ["always", "hover", "none", "dotted"]
     },
     "external": {
       "type": "boolean",
@@ -87,56 +80,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",
+      "tone=\"neutral\" for secondary links; add color=\"tertiary\" for metadata and footers",
+      "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>"
+      "name": "Tones",
+      "description": "Accent, then neutral, then the quietest neutral.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"md\" align=\"center\" wrap>\n  <Link href=\"#\" tone=\"accent\">Accent</Link>\n  <Link href=\"#\" tone=\"neutral\">Neutral</Link>\n  <Link href=\"#\" tone=\"neutral\" color=\"tertiary\">Tertiary</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 tone=\"neutral\" onClick={() => {}}>\n  <a href=\"#pricing\" onClick={() => {}}>\n    Client-side navigation\n  </a>\n</Link>"
     }
   ],
   "relations": [
@@ -155,21 +147,17 @@
     "propsSummary": [
       "children: ReactNode - link text (required)",
       "href: string - destination URL",
-      "variant: default|subtle|muted - visual style",
-      "underline: always|hover|none - underline behavior",
+      "tone: accent|neutral - colour",
+      "color: primary|secondary|tertiary - hierarchy colour on a neutral link",
+      "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",