@usefragments/ui 1.6.0 → 2.0.0

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,58 +36,58 @@
       "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",
-      "code": "<ButtonGroup>\n  <Button variant=\"secondary\">Cancel</Button>\n  <Button variant=\"primary\">Save</Button>\n</ButtonGroup>"
+      "description": "Confirming action sits last in the row.",
+      "code": "<ButtonGroup>\n  <Button variant=\"soft\">Cancel</Button>\n  <Button variant=\"solid\">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=\"soft\" size=\"sm\">None</Button>\n    <Button variant=\"soft\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n  <ButtonGroup gap=\"xs\">\n    <Button variant=\"soft\" size=\"sm\">XS</Button>\n    <Button variant=\"soft\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n  <ButtonGroup gap=\"sm\">\n    <Button variant=\"soft\" size=\"sm\">SM</Button>\n    <Button variant=\"soft\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n  <ButtonGroup gap=\"md\">\n    <Button variant=\"soft\" size=\"sm\">MD</Button>\n    <Button variant=\"soft\" 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=\"soft\" size=\"sm\">Start</Button>\n    <Button variant=\"soft\" size=\"sm\">Aligned</Button>\n  </ButtonGroup>\n  <ButtonGroup align=\"center\">\n    <Button variant=\"soft\" size=\"sm\">Center</Button>\n    <Button variant=\"soft\" size=\"sm\">Aligned</Button>\n  </ButtonGroup>\n  <ButtonGroup align=\"end\">\n    <Button variant=\"soft\" size=\"sm\">End</Button>\n    <Button variant=\"soft\" 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=\"soft\" size=\"sm\">Approve</Button>\n  <Button variant=\"soft\" size=\"sm\">Request changes</Button>\n  <Button variant=\"soft\" size=\"sm\">Reassign reviewer</Button>\n  <Button variant=\"soft\" size=\"sm\">Move to backlog</Button>\n  <Button variant=\"soft\" size=\"sm\">Archive</Button>\n</ButtonGroup>"
     },
     {
       "name": "Form Actions",
-      "description": "Common pattern for form submit/cancel",
-      "code": "<ButtonGroup align=\"end\" role=\"group\" aria-label=\"Form actions\">\n  <Button variant=\"ghost\">Cancel</Button>\n  <Button variant=\"primary\">Submit</Button>\n</ButtonGroup>"
+      "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=\"solid\">Submit</Button>\n</ButtonGroup>"
     }
   ],
   "relations": [
@@ -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/ButtonGroup/ButtonGroup.module.scss

@@ -1,3 +1,5 @@
+@use "../../tokens/variables" as *;
+@use "../../tokens/measurements.generated" as measurements;
 @use "../../recipes/layout";
 
 .group {
@@ -7,21 +9,21 @@
 
 // Gap sizes
 .gapNone {
-  gap: 0;
+  gap: var(--fui-raw-space-0, #{measurements.raw-space(0)});
 
   > * {
     position: relative;
   }
 
   > *:not(:first-child) {
-    margin-inline-start: calc(-1 * var(--fui-stroke-hairline, 1px));
-    border-top-left-radius: 0;
-    border-bottom-left-radius: 0;
+    margin-inline-start: calc(-1 * var(--fui-stroke-hairline, #{$fui-stroke-hairline}));
+    border-start-start-radius: var(--fui-radius-none, #{$fui-radius-none});
+    border-end-start-radius: var(--fui-radius-none, #{$fui-radius-none});
   }
 
   > *:not(:last-child) {
-    border-top-right-radius: 0;
-    border-bottom-right-radius: 0;
+    border-start-end-radius: var(--fui-radius-none, #{$fui-radius-none});
+    border-end-end-radius: var(--fui-radius-none, #{$fui-radius-none});
   }
 
   > *:hover,

package/src/components/Card/Card.consumer-fixture.module.scss

@@ -1,8 +1,11 @@
+@use "../../tokens/variables" as *;
+@use "../../tokens/measurements.generated" as measurements;
+
 // Deliberately unlayered: this proves ordinary consumer CSS can customize a
 // layered Card without specificity escalation or priority hacks.
 .consumerOverride {
   --fui-card-consumer-fixture: 1;
 
-  padding: 29px;
-  background-color: rgb(9 87 73);
+  padding: var(--fui-raw-space-32, #{measurements.raw-space(32)});
+  background-color: var(--fui-color-success-bg, #{$fui-color-success-bg});
 }

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

@@ -1,17 +1,52 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../tokens/measurements.generated" as measurements;
+@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 requested inset and lose its padding. Register them as
+// non-inheriting so each card resolves only its own channels.
+@property --_card-root-requested-inset {
+  syntax: "*";
+  inherits: false;
+}
+
+@property --_card-body-inset {
+  syntax: "*";
+  inherits: false;
+}
+
+// The earned-moment capsule: a tone-tinted hairline, a radial wash from the
+// top-right corner and the softer capsule radius. Any variant can wear it; the
+// tone decides the colour. Reserve it for the few surfaces that earn emphasis
+// (demo banner, upgrade panel, onboarding resume), never for routine content.
+@mixin _capsule($line, $wash) {
+  position: relative;
+  overflow: hidden;
+  border-color: $line;
+  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%, $wash, transparent 62%);
+  }
+}
+
 @layer fui.components {
   .card {
     @include surface-elevated;
     @include typography.role("body-compact");
+    @include high-contrast-outline;
 
-    padding: var(
-      --_card-root-forced-inset,
-      var(--_card-root-requested-inset, #{surface.inset("default")})
-    );
+    padding: 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}));
@@ -22,34 +57,24 @@
       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);
-  }
 
-  // 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);
-  }
-
-  .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;
+    // A divided header paints full-bleed chrome; clip it to the card radius.
+    &:has(> .headerDivided) {
+      overflow: hidden;
+    }
   }
 
-  .elevated {
+  // Variants — the surface only. Colour is the tone's job.
+  .solid {
     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));
+    box-shadow: var(--fui-card-shadow, none);
   }
 
-  // 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 {
+  // Quiet tint fill: metric tiles and dashboard panels read as one system
+  // rather than separate hero cards. Panels add `padding="none"` and let
+  // `Card.Header divided` + `Card.Body padding` own their inset.
+  .soft {
     background-color: var(
       --fui-card-stat-bg,
       var(
@@ -64,28 +89,36 @@
     box-shadow: var(--fui-card-stat-shadow, var(--fui-card-shadow, none));
   }
 
-  // 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")};
+  .outline {
+    background-color: transparent;
+    border-color: var(
+      --fui-card-outlined-border,
+      var(--fui-card-border, var(--fui-border-strong, #{$fui-border-strong}))
+    );
+    box-shadow: none;
+  }
+
+  // Tones — chroma is earned by state: accent = the moment, danger = a merge
+  // is held, warning = enforcement lapsed. Neutral is the absence of a class.
+  .toneAccent {
+    @include _capsule(
+      var(--fui-card-accent-border, #{$fui-card-accent-border}),
+      color-mix(in srgb, var(--fui-color-accent, #{$fui-color-accent}) 13%, transparent)
+    );
+  }
 
-    background-color: var(
-      --fui-panel-bg,
-      var(
-        --fui-card-bg,
-        color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 2%, transparent)
-      )
+  .toneDanger {
+    @include _capsule(
+      var(--fui-color-danger-border, #{$fui-color-danger-border}),
+      var(--fui-color-danger-bg, #{$fui-color-danger-bg})
     );
-    border-color: var(
-      --fui-panel-border,
-      var(--fui-card-border, var(--fui-border, #{$fui-border}))
+  }
+
+  .toneWarning {
+    @include _capsule(
+      var(--fui-color-warning-border, #{$fui-color-warning-border}),
+      var(--fui-color-warning-bg, #{$fui-color-warning-bg})
     );
-    box-shadow: var(--fui-card-panel-shadow, var(--fui-card-shadow, none));
-    overflow: hidden;
   }
 
   // Padding
@@ -131,31 +164,35 @@
       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)
+        inset 0 var(--fui-stroke-hairline, #{$fui-stroke-hairline})
+          var(--fui-raw-space-2, #{measurements.raw-space(2)})
+          color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 12%, transparent)
       );
     }
   }
 
   .header {
     display: grid;
-    gap: var(--fui-raw-space-4, 4px);
-    margin-bottom: var(--fui-raw-space-16, 16px);
+    gap: var(--fui-raw-space-4, #{measurements.raw-space(4)});
+    margin-bottom: var(--fui-raw-space-16, #{measurements.raw-space(16)});
   }
 
   // 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"`.
+  // panel body, which manages its own padding. Use with `padding="none"`.
   // 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: var(--fui-control-track-md, 32px);
+    gap: var(--fui-raw-space-12, #{measurements.raw-space(12)});
+    min-height: #{action.track("md")};
     padding: #{surface.inset("compact")};
-    margin-bottom: 0;
-    border-bottom: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
+    margin-bottom: var(--fui-raw-space-0, #{measurements.raw-space(0)});
+    background-color: var(--fui-card-header-bg, var(--fui-bg-subtle, #{$fui-bg-subtle}));
+    border-bottom: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid
+      var(--fui-border, $fui-border);
 
     // Multi-line copy: top-align trailing controls with the title line.
     &:has(.description) {
@@ -166,21 +203,21 @@
   .title {
     @include typography.role("title-sm");
 
-    margin: 0;
+    margin: var(--fui-raw-space-0, #{measurements.raw-space(0)});
     color: var(--fui-text-primary, $fui-text-primary);
   }
 
   .description {
     @include typography.role("body-compact");
 
-    margin: 0;
+    margin: var(--fui-raw-space-0, #{measurements.raw-space(0)});
     color: var(--fui-text-secondary, $fui-text-secondary);
   }
 
   .body {
     @include typography.role("body-compact");
 
-    padding: var(--_card-body-inset, 0);
+    padding: var(--_card-body-inset, var(--fui-raw-space-0, #{measurements.raw-space(0)}));
     color: var(--fui-text-primary, $fui-text-primary);
   }
 
@@ -203,10 +240,11 @@
   .footer {
     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);
+    gap: var(--fui-raw-space-8, #{measurements.raw-space(8)});
+    margin-top: var(--fui-raw-space-16, #{measurements.raw-space(16)});
+    padding-top: var(--fui-raw-space-16, #{measurements.raw-space(16)});
+    border-top: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid
+      var(--fui-border, $fui-border);
   }
 
   // ============================================
@@ -228,21 +266,4 @@
       }
     }
   }
-
-  // ============================================
-  // 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

@@ -7,26 +7,35 @@ import styles from "./Card.module.scss";
 // Types
 // ============================================
 
+export type CardVariant = "solid" | "soft" | "outline";
+export type CardTone = "neutral" | "accent" | "warning" | "danger";
+export type CardPadding = "none" | "sm" | "md" | "lg";
+
 /**
  * Card container for grouping related content.
  * @see https://usefragments.com/components/card
  */
 export interface CardProps extends Omit<React.HTMLAttributes<HTMLElement>, "children"> {
   children: React.ReactNode;
-  /** Visual style variant. `"outline"` is an alias for `"outlined"`.
+  /** Surface chrome.
    *
-   * - `default` / `outlined` / `elevated`: general-purpose cards.
-   * - `stat`: compact metric tile for dashboard grids — hairline border,
-   *   panel-subtle surface, tight radius, zero shadow.
-   * - `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.
-   * @default "default"
+   * - `solid`: the filled, elevated surface for general-purpose cards.
+   * - `soft`: quiet tint fill for metric tiles and dashboard panels. Add
+   *   `padding="none"` and let `Card.Header divided` + `Card.Body padding`
+   *   own their inset for a panel.
+   * - `outline`: transparent with a hairline border, for dense layouts.
+   * @default "solid"
    * @see https://usefragments.com/components/card#variants */
-  variant?: "default" | "outlined" | "outline" | "elevated" | "stat" | "panel";
+  variant?: CardVariant;
+  /** Earned-moment capsule. Any tone other than `neutral` paints a
+   * tone-tinted hairline, a radial wash and the capsule radius on top of the
+   * variant: `accent` (the moment), `danger` (a merge is held), `warning`
+   * (enforcement lapsed). Reserve it for the few surfaces that earn emphasis.
+   * @default "neutral" */
+  tone?: CardTone;
   /** Inner padding.
    * @default "md" */
-  padding?: "none" | "sm" | "md" | "lg";
+  padding?: CardPadding;
   /** Root element tag.
    * @default "article" */
   as?: "article" | "div" | "section";
@@ -36,7 +45,7 @@ export interface CardHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
   /** Renders the header as a divided region with a minimum height, canonical
    * inset, hairline bottom border, and no trailing margin. Used with
-   * `variant="panel"` for dashboard-style panel headers. */
+   * `padding="none"` for dashboard-style panel headers. */
   divided?: boolean;
 }
 
@@ -53,9 +62,9 @@ export interface CardDescriptionProps extends React.HTMLAttributes<HTMLParagraph
 
 export interface CardBodyProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
-  /** Inner padding for body-only spacing, useful with `variant="panel"`.
-   * Omit when the card root already owns padding. */
-  padding?: "none" | "sm" | "md" | "lg";
+  /** Inner padding for body-only spacing, useful with `padding="none"` on the
+   * root. Omit when the card root already owns padding. */
+  padding?: CardPadding;
 }
 
 export interface CardFooterProps extends React.HTMLAttributes<HTMLDivElement> {
@@ -67,8 +76,9 @@ export interface CardFooterProps extends React.HTMLAttributes<HTMLDivElement> {
 // ============================================
 
 interface CardContextValue {
-  variant: "default" | "outlined" | "elevated" | "stat" | "panel";
-  padding: "none" | "sm" | "md" | "lg";
+  variant: CardVariant;
+  tone: CardTone;
+  padding: CardPadding;
   isInteractive: boolean;
 }
 
@@ -100,17 +110,29 @@ function composeEventHandlers<E extends { defaultPrevented: boolean }>(
 // Components
 // ============================================
 
+const variantMap: Record<CardVariant, string> = {
+  solid: styles.solid,
+  soft: styles.soft,
+  outline: styles.outline,
+};
+
+const toneMap: Record<CardTone, string | undefined> = {
+  neutral: undefined,
+  accent: styles.toneAccent,
+  danger: styles.toneDanger,
+  warning: styles.toneWarning,
+};
+
 function CardRoot({
   children,
-  variant: variantProp = "default",
+  variant = "solid",
+  tone = "neutral",
   padding = "md",
   as: Component = "article",
   className,
   style,
   ...htmlProps
 }: CardProps) {
-  // Resolve alias: "outline" → "outlined"
-  const variant = variantProp === "outline" ? "outlined" : variantProp;
   const { onKeyDown, onKeyUp, role, tabIndex, ...elementProps } = htmlProps;
 
   const isInteractive = typeof elementProps.onClick === "function";
@@ -119,7 +141,8 @@ function CardRoot({
 
   const classes = [
     styles.card,
-    styles[variant],
+    variantMap[variant],
+    toneMap[tone],
     paddingMap[padding],
     isInteractive && styles.interactive,
     className,
@@ -129,6 +152,7 @@ function CardRoot({
 
   const contextValue: CardContextValue = {
     variant,
+    tone,
     padding,
     isInteractive,
   };