DesignsystemsthatpeopleandAIagentscanreuse.

1{2  "$schema": "./schema/component-spec.schema.json",3  "name": "Card",4  "description": "A surface that groups related content, such as a title, a short text and one action.",5  "source": "components/lab/demo-components.tsx (styles: RECIPES.card in lib/lab/playground.ts)",6  "element": "article",7  "extends": "HTMLAttributes<HTMLElement>",8  "whenToUse": [9    "Group related content with at most one main action: a project, an article, a setting summary.",10    "Show several items of the same kind side by side, each in its own Card."11  ],12  "whenNotToUse": [13    "As a clickable surface: Card has no button role or keyboard handling. Put a link or a Button inside it instead.",14    "For page layout or whole sections: use plain layout elements."15  ],16  "props": [17    {18      "name": "variant",19      "type": "enum",20      "values": [21        "elevated",22        "outlined",23        "filled"24      ],25      "default": "elevated",26      "required": false,27      "description": "Surface style: shadow, hairline border or a tint of color.primary."28    },29    {30      "name": "size",31      "type": "enum",32      "values": [33        "sm",34        "md",35        "lg"36      ],37      "default": "md",38      "required": false,39      "description": "Padding and maximum width, from RECIPES.card.sizes."40    },41    {42      "name": "disabled",43      "type": "boolean",44      "default": false,45      "required": false,46      "description": "Sets aria-disabled, dims the card to 50% and blocks pointer events."47    },48    {49      "name": "children",50      "type": "node",51      "default": null,52      "required": false,53      "description": "The content, styled with cardParts (eyebrow, title, body, action)."54    },55    {56      "name": "className",57      "type": "string",58      "default": null,59      "required": false,60      "description": "Extra classes, merged after the recipe with cn()."61    }62  ],63  "variants": [64    "elevated",65    "outlined",66    "filled"67  ],68  "sizes": [69    "sm",70    "md",71    "lg"72  ],73  "states": [74    {75      "name": "default",76      "description": "elevated: color.surface with a soft shadow. outlined: transparent with a color.border hairline. filled: color.surface tinted 10% with color.primary."77    },78    {79      "name": "hover",80      "description": "elevated: deeper shadow. outlined: the border turns color.primary. filled: the tint grows to 16%. data-force=\"hover\" pins this state for docs and visual tests."81    },82    {83      "name": "disabled",84      "description": "aria-disabled=\"true\", 50% opacity and no pointer events."85    }86  ],87  "tokens": [88    {89      "path": "color.surface",90      "usage": "elevated background, and the base of the filled tint."91    },92    {93      "path": "color.text",94      "usage": "Text colour, including cardParts.action."95    },96    {97      "path": "color.muted",98      "usage": "cardParts.body and cardParts.eyebrow text."99    },100    {101      "path": "color.primary",102      "usage": "cardParts.action underline and focus ring, outlined hover border, filled tint. Never text."103    },104    {105      "path": "color.border",106      "usage": "outlined border."107    },108    {109      "path": "radius.card",110      "usage": "Corner radius; the action's focus ring uses half of it."111    },112    {113      "path": "space.sm",114      "usage": "Padding at size sm (the web recipe's p-4 has the same value)."115    },116    {117      "path": "space.md",118      "usage": "Padding at size md (p-5, same value)."119    },120    {121      "path": "space.lg",122      "usage": "Padding at size lg (p-6, same value)."123    },124    {125      "path": "fontSize.title",126      "usage": "cardParts.title text (text-base, same value)."127    },128    {129      "path": "fontSize.body",130      "usage": "cardParts.body and cardParts.action text (text-sm, same value)."131    }132  ],133  "accessibility": {134    "role": "article, from the native <article> element. The Card itself is not interactive.",135    "keyboard": [136      "The Card is not focusable; Tab reaches the links or buttons inside it.",137      "When disabled, also take inner actions out of the tab order (tabIndex={-1}): aria-disabled and pointer-events do not do that."138    ],139    "focus": "The action (cardParts.action) shows a 2px color.primary ring on focus-visible. Inner Buttons keep their own ring.",140    "contrast": "Title and body text at least 4.5:1 against the card background in every variant (WCAG 2.2 AA, 1.4.3).",141    "contrastChecks": [142      {143        "label": "title and action text",144        "foreground": "color.text",145        "background": "color.surface",146        "min": 4.5147      },148      {149        "label": "body and eyebrow text",150        "foreground": "color.muted",151        "background": "color.surface",152        "min": 4.5153      },154      {155        "label": "action focus ring",156        "foreground": "color.primary",157        "background": "color.surface",158        "min": 3159      }160    ],161    "labels": "Start the content with a heading (cardParts.title) so the article can be found by heading navigation."162  },163  "composition": [164    "Content goes inside as children, styled with cardParts: eyebrow, title, body and action.",165    "cardParts.action styles a link. A Button can be the action instead, as in the 'One system, every stack' Card, which composes an image, a title and a primary Button."166  ],167  "example": {168    "language": "tsx",169    "code": "<Card variant=\"elevated\" size=\"md\">\n  <p className={cardParts.eyebrow}>Design system</p>\n  <h3 className={cardParts.title}>Tokens, not hex codes</h3>\n  <p className={cardParts.body}>Components read semantic tokens.</p>\n  <a href=\"/system\" className={cardParts.action}>Read the docs</a>\n</Card>"170  }171}