@usefragments/ui 1.5.4 → 1.7.0

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

@@ -1,212 +1,329 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../recipes/action" as action;
+@use "../../recipes/surface" as surface;
+@use "../../recipes/typography" as typography;
 
-.card {
-  @include surface-elevated;
-  font-family: var(--fui-font-sans, $fui-font-sans);
-  color: var(--fui-text-primary, $fui-text-primary);
-  background-color: var(--fui-card-bg, var(--fui-bg-elevated, #{$fui-bg-elevated}));
-  border-color: var(--fui-card-border, var(--fui-border, #{$fui-border}));
-  border-radius: var(--fui-card-radius, var(--fui-radius-lg, #{$fui-radius-lg}));
-  box-shadow: var(--fui-card-shadow, none);
-  transition:
-    box-shadow var(--fui-transition-fast, $fui-transition-fast),
-    border-color var(--fui-transition-fast, $fui-transition-fast),
-    background-color var(--fui-transition-fast, $fui-transition-fast),
-    transform var(--fui-transition-fast, $fui-transition-fast);
+// 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;
 }
 
-// Variants
-.default {
-  background-color: var(--fui-card-bg, var(--fui-bg-elevated, #{$fui-bg-elevated}));
-  border-color: var(--fui-card-border, var(--fui-border, #{$fui-border}));
-  box-shadow: var(--fui-card-shadow, none);
+@property --_card-root-requested-inset {
+  syntax: "*";
+  inherits: false;
 }
 
-.outlined {
-  background-color: transparent;
-  border-color: var(
-    --fui-card-outlined-border,
-    var(--fui-card-border, var(--fui-border-strong, #{$fui-border-strong}))
-  );
-  box-shadow: none;
+@property --_card-body-inset {
+  syntax: "*";
+  inherits: false;
 }
 
-.elevated {
-  background-color: var(--fui-card-bg, var(--fui-bg-elevated, #{$fui-bg-elevated}));
-  border-color: var(--fui-card-border, var(--fui-border, #{$fui-border}));
-  box-shadow: var(--fui-card-elevated-shadow, var(--fui-card-shadow, none));
-}
+@layer fui.components {
+  .card {
+    @include surface-elevated;
+    @include typography.role("body-compact");
 
-// Compact metric tile for dashboard grids. It uses the same card radius and
-// hairline model as panels, with a quieter fill so adjacent metric tiles read
-// as one dashboard system rather than separate hero cards.
-.stat {
-  background-color: var(
-    --fui-card-stat-bg,
-    var(
-      --fui-card-bg,
-      color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 2%, transparent)
-    )
-  );
-  border-color: var(
-    --fui-card-stat-border,
-    var(--fui-card-border, var(--fui-border, #{$fui-border}))
-  );
-  box-shadow: var(--fui-card-stat-shadow, var(--fui-card-shadow, none));
-}
+    padding: var(
+      --_card-root-forced-inset,
+      var(--_card-root-requested-inset, #{surface.inset("default")})
+    );
+    color: var(--fui-text-primary, $fui-text-primary);
+    background-color: var(--fui-card-bg, var(--fui-bg-elevated, #{$fui-bg-elevated}));
+    border-color: var(--fui-card-border, var(--fui-border, #{$fui-border}));
+    border-radius: var(--fui-card-radius, var(--fui-radius-lg, #{$fui-radius-lg}));
+    box-shadow: var(--fui-card-shadow, none);
+    transition:
+      box-shadow var(--fui-transition-fast, $fui-transition-fast),
+      border-color var(--fui-transition-fast, $fui-transition-fast),
+      background-color var(--fui-transition-fast, $fui-transition-fast),
+      transform var(--fui-transition-fast, $fui-transition-fast);
+  }
 
-// Hairline-bordered panel with no own padding — designed for compound use
-// with `Card.Header divided` + `Card.Body` inside dashboards. Each region
-// owns its spacing so panel headers can be full-bleed with a hairline
-// divider underneath. Uses the same surface-agnostic overlay as `.stat`.
-// Padding is forced to 0 here so the variant works regardless of the
-// `padding` prop — children manage their own spacing inside a panel.
-.panel {
-  background-color: var(
-    --fui-panel-bg,
-    var(
-      --fui-card-bg,
-      color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 2%, transparent)
-    )
-  );
-  border-color: var(--fui-panel-border, var(--fui-card-border, var(--fui-border, #{$fui-border})));
-  box-shadow: var(--fui-card-panel-shadow, var(--fui-card-shadow, none));
-  overflow: hidden;
-  padding: 0;
-}
+  // Variants
+  .default {
+    background-color: var(--fui-card-bg, var(--fui-bg-elevated, #{$fui-bg-elevated}));
+    border-color: var(--fui-card-border, var(--fui-border, #{$fui-border}));
+    box-shadow: var(--fui-card-shadow, none);
+  }
 
-// Padding
-.paddingNone {
-  padding: 0;
-}
+  .outlined {
+    background-color: transparent;
+    border-color: var(
+      --fui-card-outlined-border,
+      var(--fui-card-border, var(--fui-border-strong, #{$fui-border-strong}))
+    );
+    box-shadow: none;
+  }
 
-// Canonical spacing scale (shared with Box/Stack/Grid/BentoGrid/List): sm=2 md=3 lg=4
-.paddingSm {
-  padding: var(--fui-space-2, $fui-space-2);
-}
+  .elevated {
+    background-color: var(--fui-card-bg, var(--fui-bg-elevated, #{$fui-bg-elevated}));
+    border-color: var(--fui-card-border, var(--fui-border, #{$fui-border}));
+    box-shadow: var(--fui-card-elevated-shadow, var(--fui-card-shadow, none));
+  }
 
-.paddingMd {
-  padding: var(--fui-space-3, $fui-space-3);
-}
+  // Compact metric tile for dashboard grids. It uses the same card radius and
+  // hairline model as panels, with a quieter fill so adjacent metric tiles read
+  // as one dashboard system rather than separate hero cards.
+  .stat {
+    background-color: var(
+      --fui-card-stat-bg,
+      var(
+        --fui-card-bg,
+        color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 2%, transparent)
+      )
+    );
+    border-color: var(
+      --fui-card-stat-border,
+      var(--fui-card-border, var(--fui-border, #{$fui-border}))
+    );
+    box-shadow: var(--fui-card-stat-shadow, var(--fui-card-shadow, none));
+  }
 
-.paddingLg {
-  padding: var(--fui-space-4, $fui-space-4);
-}
+  // Hairline-bordered panel with no root inset — designed for compound use
+  // with `Card.Header divided` + `Card.Body` inside dashboards. Each region
+  // owns its spacing so panel headers can be full-bleed with a hairline
+  // divider underneath. Uses the same surface-agnostic overlay as `.stat`.
+  // The private forced-inset channel makes this deterministic regardless of the
+  // `padding` prop or DOM class order.
+  .panel {
+    --_card-root-forced-inset: #{surface.inset("panel")};
 
-// Interactive card (when onClick is provided).
-// Card renders as an `article`/`div`/`section` (never a real `<button>`), so
-// applying `button-reset` here was gratuitous — and it was silently wiping
-// out variant-applied borders and backgrounds (the reset sets
-// `border: none; background: transparent`). Keep only the clickable
-// affordances; variants keep their surface and border untouched.
-.interactive {
-  @include interactive-base;
-
-  display: block;
-  width: 100%;
-  text-align: left;
-  cursor: pointer;
-  font: inherit;
-  color: inherit;
-
-  &:hover {
-    background-color: var(--fui-card-hover-bg, var(--fui-bg-hover, #{$fui-bg-hover}));
-    border-color: var(--fui-card-hover-border, var(--fui-border-strong, #{$fui-border-strong}));
-    box-shadow: none;
+    background-color: var(
+      --fui-panel-bg,
+      var(
+        --fui-card-bg,
+        color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 2%, transparent)
+      )
+    );
+    border-color: var(
+      --fui-panel-border,
+      var(--fui-card-border, var(--fui-border, #{$fui-border}))
+    );
+    box-shadow: var(--fui-card-panel-shadow, var(--fui-card-shadow, none));
+    overflow: hidden;
   }
 
-  &:active {
-    background-color: var(--fui-card-active-bg, var(--fui-bg-active, $fui-bg-active));
-    box-shadow: var(
-      --fui-card-active-shadow,
-      inset 0 1px 2px color-mix(in srgb, black 12%, transparent)
-    );
+  // 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%
+      );
+    }
   }
-}
 
-.header {
-  margin-bottom: var(--fui-space-2, $fui-space-2);
-}
+  // 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});
 
-// Full-bleed panel-header region with a 40px minimum height, canonical inset,
-// and a hairline bottom divider. No trailing margin — it sits flush above the
-// panel body, which manages its own padding. Use inside `variant="panel"`.
-.headerDivided {
-  display: flex;
-  align-items: center;
-  gap: var(--fui-space-1, $fui-space-1);
-  min-height: 2.857rem; // 40px
-  padding: var(--fui-space-2, $fui-space-2);
-  margin-bottom: 0;
-  border-bottom: 1px solid var(--fui-border, $fui-border);
-}
+    &::before {
+      background: radial-gradient(
+        90% 70% at 100% -10%,
+        var(--fui-color-danger-bg, #{$fui-color-danger-bg}),
+        transparent 62%
+      );
+    }
+  }
 
-.title {
-  margin: 0;
-  font-size: var(--fui-font-size-base, $fui-font-size-base);
-  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
-  color: var(--fui-text-primary, $fui-text-primary);
-  line-height: var(--fui-line-height-tight, $fui-line-height-tight);
-}
+  .toneWarning {
+    border-color: var(--fui-color-warning-border, #{$fui-color-warning-border});
 
-.description {
-  margin: 0 0 var(--fui-space-1, $fui-space-1) 0;
-  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
-  color: var(--fui-text-secondary, $fui-text-secondary);
-  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+    &::before {
+      background: radial-gradient(
+        90% 70% at 100% -10%,
+        var(--fui-color-warning-bg, #{$fui-color-warning-bg}),
+        transparent 62%
+      );
+    }
+  }
 
-  &:last-child {
-    margin-bottom: 0;
+  .toneNeutral {
+    border-color: var(--fui-border, #{$fui-border});
+
+    &::before {
+      content: none;
+    }
   }
-}
 
-.body {
-  color: var(--fui-text-primary, $fui-text-primary);
-  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
-  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
-}
+  // Padding
+  .paddingNone {
+    --_card-root-requested-inset: #{surface.inset("panel")};
+  }
 
-.footer {
-  display: flex;
-  align-items: center;
-  gap: var(--fui-space-2, $fui-space-2);
-  margin-top: var(--fui-space-2, $fui-space-2);
-  padding-top: var(--fui-space-2, $fui-space-2);
-  border-top: 1px solid var(--fui-border, $fui-border);
-}
+  .paddingSm {
+    --_card-root-requested-inset: #{surface.inset("compact")};
+  }
 
-// ============================================
-// Accessibility: Reduced Motion
-// ============================================
+  .paddingMd {
+    --_card-root-requested-inset: #{surface.inset("default")};
+  }
 
-@media (prefers-reduced-motion: reduce) {
-  .card {
-    transition: none;
+  .paddingLg {
+    --_card-root-requested-inset: #{surface.inset("roomy")};
   }
 
+  // Interactive card (when onClick is provided).
+  // Card renders as an `article`/`div`/`section` (never a real `<button>`), so
+  // applying `button-reset` here was gratuitous — and it was silently wiping
+  // out variant-applied borders and backgrounds (the reset sets
+  // `border: none; background: transparent`). Keep only the clickable
+  // affordances; variants keep their surface and border untouched.
   .interactive {
+    @include interactive-base;
+
+    display: block;
+    width: 100%;
+    text-align: left;
+    cursor: pointer;
+    font: inherit;
+    color: inherit;
+
     &:hover {
-      transform: none;
+      background-color: var(--fui-card-hover-bg, var(--fui-bg-hover, #{$fui-bg-hover}));
+      border-color: var(--fui-card-hover-border, var(--fui-border-strong, #{$fui-border-strong}));
+      box-shadow: none;
     }
 
     &:active {
-      transform: none;
+      background-color: var(--fui-card-active-bg, var(--fui-bg-active, $fui-bg-active));
+      box-shadow: var(
+        --fui-card-active-shadow,
+        inset 0 1px 2px color-mix(in srgb, black 12%, transparent)
+      );
     }
   }
-}
 
-// ============================================
-// Accessibility: High Contrast Mode
-// ============================================
+  .header {
+    display: grid;
+    gap: var(--fui-raw-space-4, 4px);
+    margin-bottom: var(--fui-raw-space-16, 16px);
+  }
 
-@media (prefers-contrast: more) {
-  .card {
-    border-width: 2px;
-    border-color: var(--fui-text-primary, $fui-text-primary);
+  // Full-bleed panel-header region on the control-md track, canonical inset,
+  // and a hairline bottom divider. No trailing margin — it sits flush above the
+  // panel body, which manages its own padding. Use inside `variant="panel"`.
+  // Title cluster (left) and trailing controls (right) pin to opposite edges —
+  // wrap Title + Description in a stack so space-between has two children.
+  .headerDivided {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--fui-raw-space-12, 12px);
+    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.
+    &:has(.description) {
+      align-items: flex-start;
+    }
+  }
+
+  .title {
+    @include typography.role("title-sm");
+
+    margin: 0;
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  .description {
+    @include typography.role("body-compact");
+
+    margin: 0;
+    color: var(--fui-text-secondary, $fui-text-secondary);
+  }
+
+  .body {
+    @include typography.role("body-compact");
+
+    padding: var(--_card-body-inset, 0);
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  .body.paddingNone {
+    --_card-body-inset: #{surface.inset("panel")};
+  }
+
+  .body.paddingSm {
+    --_card-body-inset: #{surface.inset("compact")};
+  }
+
+  .body.paddingMd {
+    --_card-body-inset: #{surface.inset("default")};
+  }
+
+  .body.paddingLg {
+    --_card-body-inset: #{surface.inset("roomy")};
   }
 
   .footer {
-    border-top-width: 2px;
+    display: flex;
+    align-items: center;
+    gap: var(--fui-raw-space-8, 8px);
+    margin-top: var(--fui-raw-space-16, 16px);
+    padding-top: var(--fui-raw-space-16, 16px);
+    border-top: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
+  }
+
+  // ============================================
+  // Accessibility: Reduced Motion
+  // ============================================
+
+  @media (prefers-reduced-motion: reduce) {
+    .card {
+      transition: none;
+    }
+
+    .interactive {
+      &:hover {
+        transform: none;
+      }
+
+      &:active {
+        transform: none;
+      }
+    }
+  }
+
+  // ============================================
+  // Accessibility: High Contrast Mode
+  // ============================================
+
+  @media (prefers-contrast: more) {
+    .card {
+      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));
+    }
+
+    .footer {
+      box-shadow: inset 0 var(--fui-stroke-hairline, 1px) 0
+        var(--fui-text-primary, $fui-text-primary);
+    }
   }
 }

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