@usefragments/ui 1.6.0 → 1.7.0

package/src/components/Breadcrumbs/Breadcrumbs.contract.json

@@ -1,14 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Breadcrumbs",
-  "description": "Breadcrumb navigation showing the current page location within a hierarchy. Helps users navigate back through parent pages.",
+  "description": "Shows where the user is and links back up the hierarchy.",
   "category": "navigation",
-  "tags": [
-    "breadcrumbs",
-    "navigation",
-    "hierarchy",
-    "wayfinding"
-  ],
+  "tags": ["breadcrumbs", "navigation", "hierarchy", "wayfinding"],
   "status": "stable",
   "sourcePath": "src/components/Breadcrumbs/index.tsx",
   "exportName": "Breadcrumbs",
@@ -44,21 +39,22 @@
   },
   "usage": {
     "when": [
-      "Showing hierarchical page location (e.g., Home > Category > Product)",
-      "Allowing quick navigation to parent pages",
-      "Multi-level content structures like documentation or e-commerce"
+      "Nested content more than two levels deep",
+      "Jumping back to a parent in one click",
+      "Documentation and catalogue hierarchies"
     ],
     "whenNot": [
-      "Flat navigation with no hierarchy (use Tabs or Header nav)",
-      "Step-by-step wizards (use Stepper)",
+      "Flat structures with no parents (use Tabs or header navigation)",
+      "Steps in an order (use Stepper)",
       "Primary navigation (use Sidebar or Header)"
     ],
     "guidelines": [
-      "Always include the current page as the last, non-linked item",
-      "Keep labels short and descriptive",
-      "Use maxItems to collapse long paths, keeping first and last visible",
-      "The separator defaults to \"/\" but can be customized",
-      "Use the label prop to customize the nav landmark name (defaults to \"Breadcrumb\")"
+      "End on the current page, unlinked",
+      "Short labels — the trail is a path, not a summary",
+      "Set maxItems to fold long paths, keeping first and last",
+      "The separator defaults to a slash and takes any node",
+      "Set label to rename the landmark (defaults to \"Breadcrumb\")",
+      "Crumbs truncate at 200px so one long title cannot push the rest out"
     ],
     "accessibility": [
       "Uses <nav aria-label=\"Breadcrumb\"> for landmark navigation",
@@ -70,27 +66,27 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Basic breadcrumb navigation",
+      "description": "Each ancestor links; the last one does not.",
       "code": "<Breadcrumbs>\n  <Breadcrumbs.Item href=\"#\">Home</Breadcrumbs.Item>\n  <Breadcrumbs.Item href=\"#\">Products</Breadcrumbs.Item>\n  <Breadcrumbs.Item href=\"#\">Category</Breadcrumbs.Item>\n  <Breadcrumbs.Item current>Current Page</Breadcrumbs.Item>\n</Breadcrumbs>"
     },
     {
       "name": "With Icons",
-      "description": "Breadcrumbs with icons on items",
+      "description": "Glyphs mark what kind of thing each level is.",
       "code": "<Breadcrumbs>\n  <Breadcrumbs.Item\n    href=\"#\"\n    icon={\n      <svg viewBox=\"0 0 16 16\" fill=\"currentColor\">\n        <path d=\"M8 1.25l-7 6v7.5c0 .138.112.25.25.25H5.5V10h5v5h4.25a.25.25 0 0 0 .25-.25v-7.5l-7-6z\" />\n      </svg>\n    }\n  >\n    Home\n  </Breadcrumbs.Item>\n  <Breadcrumbs.Item\n    href=\"#\"\n    icon={\n      <svg viewBox=\"0 0 16 16\" fill=\"currentColor\">\n        <path d=\"M1.75 1A1.75 1.75 0 0 0 0 2.75v10.5C0 14.216.784 15 1.75 15h12.5A1.75 1.75 0 0 0 16 13.25v-8.5A1.75 1.75 0 0 0 14.25 3H7.5a.25.25 0 0 1-.2-.1l-.9-1.2C6.07 1.26 5.55 1 5 1H1.75z\" />\n      </svg>\n    }\n  >\n    Documents\n  </Breadcrumbs.Item>\n  <Breadcrumbs.Item current>Report.pdf</Breadcrumbs.Item>\n</Breadcrumbs>"
     },
     {
       "name": "Collapsed",
-      "description": "Long breadcrumb trail collapsed with ellipsis",
+      "description": "Middle levels fold behind an ellipsis.",
       "code": "<Breadcrumbs maxItems={3}>\n  <Breadcrumbs.Item href=\"#\">Home</Breadcrumbs.Item>\n  <Breadcrumbs.Item href=\"#\">Category</Breadcrumbs.Item>\n  <Breadcrumbs.Item href=\"#\">Subcategory</Breadcrumbs.Item>\n  <Breadcrumbs.Item href=\"#\">Section</Breadcrumbs.Item>\n  <Breadcrumbs.Item current>Current Page</Breadcrumbs.Item>\n</Breadcrumbs>"
     },
     {
       "name": "Custom Separator",
-      "description": "Breadcrumbs with a custom chevron separator",
+      "description": "Any node can replace the slash.",
       "code": "<Breadcrumbs\n  separator={\n    <svg width=\"12\" height=\"12\" viewBox=\"0 0 16 16\" fill=\"currentColor\">\n      <path fillRule=\"evenodd\" d=\"M6.22 3.22a.75.75 0 0 1 1.06 0l4.25 4.25a.75.75 0 0 1 0 1.06l-4.25 4.25a.75.75 0 0 1-1.06-1.06L9.94 8 6.22 4.28a.75.75 0 0 1 0-1.06z\" />\n    </svg>\n  }\n>\n  <Breadcrumbs.Item href=\"#\">Home</Breadcrumbs.Item>\n  <Breadcrumbs.Item href=\"#\">Settings</Breadcrumbs.Item>\n  <Breadcrumbs.Item current>Profile</Breadcrumbs.Item>\n</Breadcrumbs>"
     },
     {
       "name": "Custom Landmark Label",
-      "description": "Override the nav landmark label for screen readers",
+      "description": "Renames the landmark screen readers announce.",
       "code": "<Breadcrumbs label=\"Documentation breadcrumbs\">\n  <Breadcrumbs.Item href=\"#\">Docs</Breadcrumbs.Item>\n  <Breadcrumbs.Item href=\"#\">Components</Breadcrumbs.Item>\n  <Breadcrumbs.Item current>Breadcrumbs</Breadcrumbs.Item>\n</Breadcrumbs>"
     }
   ],
@@ -115,21 +111,12 @@
       "Breadcrumbs.Item current: boolean - marks current page",
       "Breadcrumbs.Item icon: ReactNode - icon before label"
     ],
-    "a11yRules": [
-      "A11Y_NAV_LANDMARK",
-      "A11Y_ARIA_CURRENT",
-      "A11Y_TARGET_SIZE_MIN"
-    ]
+    "a11yRules": ["A11Y_NAV_LANDMARK", "A11Y_ARIA_CURRENT", "A11Y_TARGET_SIZE_MIN"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Item",
-      "Separator"
-    ],
-    "requiredChildren": [
-      "Item"
-    ],
+    "subComponents": ["Item", "Separator"],
+    "requiredChildren": ["Item"],
     "commonPatterns": [
       "<Breadcrumbs><Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item><Breadcrumbs.Item href=\"/products\">Products</Breadcrumbs.Item><Breadcrumbs.Item current>Widget</Breadcrumbs.Item></Breadcrumbs>"
     ]

package/src/components/Breadcrumbs/Breadcrumbs.module.scss

@@ -1,8 +1,8 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
-@use '../../recipes/action' as action;
-@use '../../recipes/target' as target;
-@use '../../recipes/typography' as typography;
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+@use "../../recipes/action" as action;
+@use "../../recipes/target" as target;
+@use "../../recipes/typography" as typography;
 
 // Root nav wrapper
 .root {
@@ -40,9 +40,12 @@
   white-space: nowrap;
   overflow: hidden;
   text-overflow: ellipsis;
+  // Intentional truncation width: one long crumb must not push the rest of the
+  // trail off screen. Keep in sync with .current below.
   max-width: 200px;
   border-radius: var(--fui-radius-sm, $fui-radius-sm);
-  transition: color var(--fui-transition-fast, $fui-transition-fast),
+  transition:
+    color var(--fui-transition-fast, $fui-transition-fast),
     background-color var(--fui-transition-fast, $fui-transition-fast);
 
   &:hover {
@@ -65,6 +68,7 @@
   white-space: nowrap;
   overflow: hidden;
   text-overflow: ellipsis;
+  // Intentional truncation width — matches .link above.
   max-width: 200px;
 }
 
@@ -92,7 +96,8 @@
   border-radius: var(--fui-radius-sm, $fui-radius-sm);
   color: var(--fui-text-secondary, $fui-text-secondary);
   cursor: pointer;
-  transition: color var(--fui-transition-fast, $fui-transition-fast),
+  transition:
+    color var(--fui-transition-fast, $fui-transition-fast),
     background-color var(--fui-transition-fast, $fui-transition-fast);
 
   &:hover {

package/src/components/Button/Button.module.scss

@@ -24,7 +24,6 @@
   color: var(--_button-color);
   font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
   white-space: nowrap;
-  user-select: none;
 
   // A composed link — `Button asChild` cloning an <a>, or an anchor rendered
   // as a child — must wear the button's own foreground, never the global
@@ -146,8 +145,10 @@
   --_button-bg: var(--fui-button-neutral-bg);
   --_button-bg-hover: var(--fui-button-neutral-bg-hover);
   --_button-bg-active: var(--fui-button-neutral-bg-active);
-  --_button-border: var(--fui-button-neutral-border);
-  --_button-border-hover: var(--fui-button-neutral-border-hover);
+  // Secondary hierarchy comes from its fill. The transparent border preserves
+  // control geometry while leaving visible neutral borders to `.outlined`.
+  --_button-border: transparent;
+  --_button-border-hover: transparent;
   --_button-color: var(--fui-button-neutral-color, var(--fui-text-primary, #{$fui-text-primary}));
   --_button-shadow: var(--fui-button-neutral-shadow);
   --_button-shadow-hover: var(--fui-button-neutral-shadow);
@@ -297,17 +298,17 @@
 
 @media (prefers-contrast: more) {
   .secondary {
-    border-width: 2px;
+    border-width: var(--fui-stroke-default, 2px);
     border-color: var(--fui-text-primary, $fui-text-primary);
   }
 
   .outlined {
-    border-width: 2px;
+    border-width: var(--fui-stroke-default, 2px);
     border-color: var(--fui-text-primary, $fui-text-primary);
   }
 
   .ghost {
-    border-width: 2px;
+    border-width: var(--fui-stroke-default, 2px);
 
     &:hover:not(:disabled) {
       border-color: var(--fui-text-primary, $fui-text-primary);
@@ -315,7 +316,7 @@
   }
 
   .link {
-    border-width: 2px;
+    border-width: var(--fui-stroke-default, 2px);
 
     &:hover:not(:disabled) {
       border-color: var(--fui-color-accent, $fui-color-accent);

package/src/components/ButtonGroup/ButtonGroup.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "ButtonGroup",
-  "description": "Groups related buttons together with consistent spacing and alignment. Useful for action bars, toolbars, and related button sets.",
-  "category": "forms",
-  "tags": [
-    "button",
-    "group",
-    "toolbar",
-    "actions",
-    "layout"
-  ],
+  "description": "Lays out related buttons in a row with one shared gap and alignment.",
+  "category": "actions",
+  "tags": ["button", "group", "toolbar", "actions", "layout"],
   "status": "stable",
   "sourcePath": "src/components/ButtonGroup/index.tsx",
   "exportName": "ButtonGroup",
@@ -30,12 +24,7 @@
       "description": "Spacing between buttons",
       "default": "sm",
       "required": false,
-      "values": [
-        "none",
-        "xs",
-        "sm",
-        "md"
-      ]
+      "values": ["none", "xs", "sm", "md"]
     },
     "wrap": {
       "type": "boolean",
@@ -47,57 +36,57 @@
       "type": "enum",
       "description": "Alignment of buttons",
       "required": false,
-      "values": [
-        "start",
-        "center",
-        "end"
-      ]
+      "values": ["start", "center", "end"]
     }
   },
   "usage": {
     "when": [
-      "Grouping related actions together",
-      "Creating toolbars or action bars",
-      "Form submit/cancel button pairs",
+      "Confirm/cancel pairs at the end of a form",
+      "Toolbars and action bars",
       "Pagination controls"
     ],
     "whenNot": [
-      "Unrelated buttons (use Stack instead)",
-      "Navigation links (use nav element)",
-      "Single button (no grouping needed)"
+      "Unrelated buttons — use Stack",
+      "Navigation links — use a nav element",
+      "A single button"
     ],
     "guidelines": [
-      "Keep button groups focused on related actions",
-      "Use consistent button variants within a group",
-      "Consider visual hierarchy - primary action should stand out",
-      "Limit to 2-4 buttons per group for clarity",
-      "Pass role/aria-label/id/data-* directly to ButtonGroup when you need semantic grouping hooks"
+      "Two to four buttons; more belongs in a Menu",
+      "Confirming action goes last",
+      "One primary button per group",
+      "align=\"end\" for form footers",
+      "Pass role, aria-label, id and data-* straight through to ButtonGroup"
     ],
     "accessibility": [
-      "Group provides semantic relationship between buttons",
-      "Each button remains individually focusable",
-      "Consider using role=\"group\" with aria-label for screen readers"
+      "Each button stays individually focusable",
+      "Add role=\"group\" plus aria-label when the set needs a name",
+      "Order buttons the way they read, not the way they look"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic button group with default spacing",
+      "description": "Confirming action sits last in the row.",
       "code": "<ButtonGroup>\n  <Button variant=\"secondary\">Cancel</Button>\n  <Button variant=\"primary\">Save</Button>\n</ButtonGroup>"
     },
     {
-      "name": "Gap Variants",
-      "description": "Different spacing options",
-      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>\n  <ButtonGroup gap=\"none\">\n    <Button variant=\"secondary\" size=\"sm\">None</Button>\n    <Button variant=\"secondary\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n  <ButtonGroup gap=\"xs\">\n    <Button variant=\"secondary\" size=\"sm\">XS</Button>\n    <Button variant=\"secondary\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n  <ButtonGroup gap=\"sm\">\n    <Button variant=\"secondary\" size=\"sm\">SM</Button>\n    <Button variant=\"secondary\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n  <ButtonGroup gap=\"md\">\n    <Button variant=\"secondary\" size=\"sm\">MD</Button>\n    <Button variant=\"secondary\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n</div>"
+      "name": "Spacing",
+      "description": "Four gap steps, from touching to airy.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"column\" gap=\"md\">\n  <ButtonGroup gap=\"none\">\n    <Button variant=\"secondary\" size=\"sm\">None</Button>\n    <Button variant=\"secondary\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n  <ButtonGroup gap=\"xs\">\n    <Button variant=\"secondary\" size=\"sm\">XS</Button>\n    <Button variant=\"secondary\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n  <ButtonGroup gap=\"sm\">\n    <Button variant=\"secondary\" size=\"sm\">SM</Button>\n    <Button variant=\"secondary\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n  <ButtonGroup gap=\"md\">\n    <Button variant=\"secondary\" size=\"sm\">MD</Button>\n    <Button variant=\"secondary\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n</Stack>"
     },
     {
       "name": "Alignment",
-      "description": "Different alignment options",
-      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '300px' }}>\n  <ButtonGroup align=\"start\">\n    <Button variant=\"secondary\" size=\"sm\">Start</Button>\n    <Button variant=\"secondary\" size=\"sm\">Aligned</Button>\n  </ButtonGroup>\n  <ButtonGroup align=\"center\">\n    <Button variant=\"secondary\" size=\"sm\">Center</Button>\n    <Button variant=\"secondary\" size=\"sm\">Aligned</Button>\n  </ButtonGroup>\n  <ButtonGroup align=\"end\">\n    <Button variant=\"secondary\" size=\"sm\">End</Button>\n    <Button variant=\"secondary\" size=\"sm\">Aligned</Button>\n  </ButtonGroup>\n</div>"
+      "description": "Pins the row to the left, centre, or right of its container.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"column\" gap=\"md\">\n  <ButtonGroup align=\"start\">\n    <Button variant=\"secondary\" size=\"sm\">Start</Button>\n    <Button variant=\"secondary\" size=\"sm\">Aligned</Button>\n  </ButtonGroup>\n  <ButtonGroup align=\"center\">\n    <Button variant=\"secondary\" size=\"sm\">Center</Button>\n    <Button variant=\"secondary\" size=\"sm\">Aligned</Button>\n  </ButtonGroup>\n  <ButtonGroup align=\"end\">\n    <Button variant=\"secondary\" size=\"sm\">End</Button>\n    <Button variant=\"secondary\" size=\"sm\">Aligned</Button>\n  </ButtonGroup>\n</Stack>"
+    },
+    {
+      "name": "Wrapping",
+      "description": "Buttons drop to a second line instead of overflowing.",
+      "code": "<ButtonGroup wrap>\n  <Button variant=\"secondary\" size=\"sm\">Approve</Button>\n  <Button variant=\"secondary\" size=\"sm\">Request changes</Button>\n  <Button variant=\"secondary\" size=\"sm\">Reassign reviewer</Button>\n  <Button variant=\"secondary\" size=\"sm\">Move to backlog</Button>\n  <Button variant=\"secondary\" size=\"sm\">Archive</Button>\n</ButtonGroup>"
     },
     {
       "name": "Form Actions",
-      "description": "Common pattern for form submit/cancel",
+      "description": "Right-aligned pair, named for screen readers.",
       "code": "<ButtonGroup align=\"end\" role=\"group\" aria-label=\"Form actions\">\n  <Button variant=\"ghost\">Cancel</Button>\n  <Button variant=\"primary\">Submit</Button>\n</ButtonGroup>"
     }
   ],
@@ -121,15 +110,11 @@
       "align: start|center|end - alignment",
       "Pass-through DOM props supported on root (id, role, aria-*, data-*, handlers)"
     ],
-    "a11yRules": [
-      "A11Y_GROUP_LABEL"
-    ]
+    "a11yRules": ["A11Y_GROUP_LABEL"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root"
-    ]
+    "subComponents": ["Root"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Card/Card.module.scss

@@ -1,8 +1,29 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../recipes/action" as action;
 @use "../../recipes/surface" as surface;
 @use "../../recipes/typography" as typography;
 
+// The private inset channels are element-scoped signals between a card's own
+// classes, but custom properties inherit by default — a Card nested inside
+// another Card (docs previews, dashboard panels) would receive the outer
+// card's forced/requested inset and lose its padding. Register them as
+// non-inheriting so each card resolves only its own channels.
+@property --_card-root-forced-inset {
+  syntax: "*";
+  inherits: false;
+}
+
+@property --_card-root-requested-inset {
+  syntax: "*";
+  inherits: false;
+}
+
+@property --_card-body-inset {
+  syntax: "*";
+  inherits: false;
+}
+
 @layer fui.components {
   .card {
     @include surface-elevated;
@@ -88,6 +109,65 @@
     overflow: hidden;
   }
 
+  // Accent capsule — the earned-moment surface (demo banner, upgrade panel,
+  // onboarding resume capsule). Accent-tinted hairline, radial accent wash
+  // from the top-right corner. Radius matches the default card.
+  .accent {
+    position: relative;
+    overflow: hidden;
+    background-color: var(--fui-card-accent-bg, #{$fui-card-accent-bg});
+    border-color: var(--fui-card-accent-border, #{$fui-card-accent-border});
+    border-radius: var(--fui-card-accent-radius, #{$fui-card-accent-radius});
+    box-shadow: none;
+
+    &::before {
+      content: "";
+      position: absolute;
+      inset: 0;
+      pointer-events: none;
+      background: radial-gradient(
+        90% 70% at 100% -10%,
+        color-mix(in srgb, var(--fui-color-accent, #{$fui-color-accent}) 13%, transparent),
+        transparent 62%
+      );
+    }
+  }
+
+  // Accent tones — same capsule, state-coloured hairline + wash. Chroma is
+  // earned by state (SPEC §4.4): danger = a merge is held, warning =
+  // enforcement lapsed, neutral = waiting (no wash at all).
+  .toneDanger {
+    border-color: var(--fui-color-danger-border, #{$fui-color-danger-border});
+
+    &::before {
+      background: radial-gradient(
+        90% 70% at 100% -10%,
+        var(--fui-color-danger-bg, #{$fui-color-danger-bg}),
+        transparent 62%
+      );
+    }
+  }
+
+  .toneWarning {
+    border-color: var(--fui-color-warning-border, #{$fui-color-warning-border});
+
+    &::before {
+      background: radial-gradient(
+        90% 70% at 100% -10%,
+        var(--fui-color-warning-bg, #{$fui-color-warning-bg}),
+        transparent 62%
+      );
+    }
+  }
+
+  .toneNeutral {
+    border-color: var(--fui-border, #{$fui-border});
+
+    &::before {
+      content: none;
+    }
+  }
+
   // Padding
   .paddingNone {
     --_card-root-requested-inset: #{surface.inset("panel")};
@@ -152,9 +232,10 @@
     align-items: center;
     justify-content: space-between;
     gap: var(--fui-raw-space-12, 12px);
-    min-height: var(--fui-control-track-md, 32px);
+    min-height: #{action.track("md")};
     padding: #{surface.inset("compact")};
     margin-bottom: 0;
+    background-color: var(--fui-card-header-bg, var(--fui-bg-subtle, #{$fui-bg-subtle}));
     border-bottom: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
 
     // Multi-line copy: top-align trailing controls with the title line.

package/src/components/Card/index.tsx

@@ -21,9 +21,19 @@ export interface CardProps extends Omit<React.HTMLAttributes<HTMLElement>, "chil
    * - `panel`: hairline-bordered panel with zero own padding, designed for
    *   compound use with `Card.Header divided` + `Card.Body` so each region
    *   manages its own spacing.
+   * - `accent`: the earned-moment capsule — accent-tinted hairline, radial
+   *   accent wash, soft fixed radius. Reserve for the few surfaces that earn
+   *   emphasis (demo banner, upgrade panel, onboarding resume), never for
+   *   routine content.
    * @default "default"
    * @see https://usefragments.com/components/card#variants */
-  variant?: "default" | "outlined" | "outline" | "elevated" | "stat" | "panel";
+  variant?: "default" | "outlined" | "outline" | "elevated" | "stat" | "panel" | "accent";
+  /** Semantic tone of the `accent` capsule. The wash and hairline follow the
+   * tone so the same earned-moment idiom can carry state: `danger` (a merge is
+   * held), `warning` (enforcement lapsed), `neutral` (waiting — ink hairline,
+   * no wash). Ignored for other variants.
+   * @default "accent" */
+  tone?: "accent" | "danger" | "warning" | "neutral";
   /** Inner padding.
    * @default "md" */
   padding?: "none" | "sm" | "md" | "lg";
@@ -67,7 +77,7 @@ export interface CardFooterProps extends React.HTMLAttributes<HTMLDivElement> {
 // ============================================
 
 interface CardContextValue {
-  variant: "default" | "outlined" | "elevated" | "stat" | "panel";
+  variant: "default" | "outlined" | "elevated" | "stat" | "panel" | "accent";
   padding: "none" | "sm" | "md" | "lg";
   isInteractive: boolean;
 }
@@ -100,9 +110,17 @@ function composeEventHandlers<E extends { defaultPrevented: boolean }>(
 // Components
 // ============================================
 
+const toneMap = {
+  accent: undefined,
+  danger: styles.toneDanger,
+  warning: styles.toneWarning,
+  neutral: styles.toneNeutral,
+} as const;
+
 function CardRoot({
   children,
   variant: variantProp = "default",
+  tone = "accent",
   padding = "md",
   as: Component = "article",
   className,
@@ -120,6 +138,7 @@ function CardRoot({
   const classes = [
     styles.card,
     styles[variant],
+    variant === "accent" && tone !== "accent" && toneMap[tone],
     paddingMap[padding],
     isInteractive && styles.interactive,
     className,

package/src/components/Chart/Chart.contract.json

@@ -1,14 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Chart",
-  "description": "Composable chart wrapper for recharts with theme-aware tooltips, legends, and color integration.",
+  "description": "Plots your data with tooltips, legends, and colors that track the theme.",
   "category": "display",
-  "tags": [
-    "chart",
-    "graph",
-    "data-visualization",
-    "recharts"
-  ],
+  "tags": ["chart", "graph", "data-visualization", "recharts"],
   "status": "stable",
   "dependencies": [
     {
@@ -55,48 +50,47 @@
   },
   "usage": {
     "when": [
-      "Displaying data trends over time",
-      "Comparing categorical data",
-      "Showing distribution or composition",
-      "Dashboard data visualizations"
+      "A trend over time is the point",
+      "Categories need comparing side by side",
+      "A whole splits into parts worth seeing"
     ],
     "whenNot": [
-      "Simple numeric values (use Text or Badge)",
-      "Progress toward a goal (use Progress)",
-      "Tabular data without visualization (use Table)"
+      "One number tells the story (use Text or Badge)",
+      "Distance to a goal (use Progress)",
+      "Readers need exact values (use Table)"
     ],
     "guidelines": [
-      "Use ChartContainer to wrap recharts chart components",
-      "Define a ChartConfig to map data keys to labels and colors (and optionally icons for custom legend/tooltip UIs)",
-      "Use FUI CSS variables for colors so charts adapt to theme changes",
-      "Use ChartTooltip and ChartLegend for consistent themed overlays",
-      "ChartTooltip and ChartLegend accept custom content renderers for advanced formatting"
+      "Wrap every recharts chart in ChartContainer",
+      "Map each data key to a label and color in ChartConfig",
+      "Colors come from --fui-* variables so both themes stay readable",
+      "Pair with ChartTooltip and ChartLegend rather than recharts' own",
+      "Give the container a real height — recharts cannot measure zero"
     ],
     "accessibility": [
-      "Charts include recharts accessibilityLayer by default",
-      "Provide meaningful labels in ChartConfig for screen readers",
-      "Consider providing a data table alternative for complex charts"
+      "accessibilityLayer is on by default",
+      "ChartConfig labels are what screen readers read",
+      "Pass dataTable to offer the same numbers as text"
     ]
   },
   "examples": [
     {
       "name": "Line Chart",
-      "description": "Multi-series line chart showing trends over time",
+      "description": "Two series share one scale, so the gap between them reads instantly.",
       "code": "<div style={{ width: '100%', height: 300 }}>\n  <ChartContainer\n    config={{\n      revenue: { label: 'Revenue', color: 'var(--fui-color-accent)' },\n      users: { label: 'Users', color: 'var(--fui-color-info)' },\n    }}\n  >\n    <LineChart data={monthlyData} margin={{ top: 5, right: 20, bottom: 5, left: 0 }}>\n      <CartesianGrid strokeDasharray=\"3 3\" />\n      <XAxis dataKey=\"month\" />\n      <YAxis />\n      <ChartTooltip />\n      <ChartLegend />\n      <Line type=\"monotone\" dataKey=\"revenue\" stroke=\"var(--fui-color-accent)\" strokeWidth={2} dot={false} />\n      <Line type=\"monotone\" dataKey=\"users\" stroke=\"var(--fui-color-info)\" strokeWidth={2} dot={false} />\n    </LineChart>\n  </ChartContainer>\n</div>"
     },
     {
       "name": "Bar Chart",
-      "description": "Categorical bar chart comparing device sessions",
+      "description": "Fixed categories, compared by height — the safest default.",
       "code": "<div style={{ width: '100%', height: 300 }}>\n  <ChartContainer\n    config={{\n      sessions: { label: 'Sessions', color: 'var(--fui-color-accent)' },\n    }}\n  >\n    <BarChart data={deviceData} margin={{ top: 5, right: 20, bottom: 5, left: 0 }}>\n      <CartesianGrid strokeDasharray=\"3 3\" />\n      <XAxis dataKey=\"device\" />\n      <YAxis />\n      <ChartTooltip />\n      <Bar dataKey=\"sessions\" fill=\"var(--fui-color-accent)\" radius={[4, 4, 0, 0]} />\n    </BarChart>\n  </ChartContainer>\n</div>"
     },
     {
       "name": "Area Chart",
-      "description": "Filled area chart showing revenue trend",
+      "description": "The fill under the line stresses volume, not just direction.",
       "code": "<div style={{ width: '100%', height: 300 }}>\n  <ChartContainer\n    config={{\n      revenue: { label: 'Revenue', color: 'var(--fui-color-accent)' },\n    }}\n  >\n    <AreaChart data={monthlyData} margin={{ top: 5, right: 20, bottom: 5, left: 0 }}>\n      <CartesianGrid strokeDasharray=\"3 3\" />\n      <XAxis dataKey=\"month\" />\n      <YAxis />\n      <ChartTooltip />\n      <Area type=\"monotone\" dataKey=\"revenue\" stroke=\"var(--fui-color-accent)\" fill=\"var(--fui-color-accent)\" fillOpacity={0.15} strokeWidth={2} />\n    </AreaChart>\n  </ChartContainer>\n</div>"
     },
     {
       "name": "Pie Chart",
-      "description": "Donut chart showing browser share distribution",
+      "description": "Parts of one whole — keep it under six slices or it stops reading.",
       "code": "<div style={{ width: '100%', height: 300 }}>\n  <ChartContainer\n    config={{\n      Chrome: { label: 'Chrome', color: 'var(--fui-color-accent)' },\n      Firefox: { label: 'Firefox', color: 'var(--fui-color-info)' },\n      Safari: { label: 'Safari', color: 'var(--fui-color-success)' },\n      Edge: { label: 'Edge', color: 'var(--fui-color-warning)' },\n    }}\n  >\n    <PieChart>\n      <ChartTooltip />\n      <ChartLegend />\n      <Pie\n        data={browserData}\n        dataKey=\"value\"\n        nameKey=\"name\"\n        cx=\"50%\"\n        cy=\"50%\"\n        innerRadius={60}\n        outerRadius={90}\n        strokeWidth={2}\n      >\n        {browserData.map((entry) => (\n          <Cell key={entry.name} fill={entry.color} />\n        ))}\n      </Pie>\n    </PieChart>\n  </ChartContainer>\n</div>"
     }
   ],
@@ -123,9 +117,7 @@
       "children: ReactElement - recharts chart component",
       "Chart.Tooltip / Chart.Legend support custom content renderers for advanced overlays"
     ],
-    "a11yRules": [
-      "A11Y_CHART_LABEL"
-    ]
+    "a11yRules": ["A11Y_CHART_LABEL"]
   },
   "provenance": {
     "source": "migrated",