ui/components/card

Card

Simple bordered card primitives with floating border labels and semantic HTML support.

Preview

tsx

1 import { Button } from "@/components/ui/button";2 import { Card, CardContent, CardFooter, CardLabel } from "@/components/ui/card";3 4 export default function CardDefault() {5   return (6     <Card size="md">7       <CardLabel variant="border">Repository</CardLabel>8       <CardContent className="pt-6">9         <div className="space-y-4 text-sm">10           <p className="text-muted-foreground">Simple bordered card with floating border label.</p>11           <div className="flex justify-between py-1 border-b border-border">12             <span className="text-muted-foreground">Branch</span>13             <span className="font-mono">main</span>14           </div>15           <div className="flex justify-between py-1 border-b border-border">16             <span className="text-muted-foreground">Commit</span>17             <span className="font-mono">a1b2c3d</span>18           </div>19           <div className="flex justify-between py-1">20             <span className="text-muted-foreground">Status</span>21             <span className="font-bold text-success">PASS</span>22           </div>23         </div>24       </CardContent>25       <CardFooter>26         <Button variant="ghost">Cancel</Button>27         <Button variant="primary">Save</Button>28       </CardFooter>29     </Card>30   );31 }32

Installation

$pnpm exec dgadd add ui/card

[Installs to]src/components/ui/card[Item]ui/card

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS once packages are available.

Usage

tsx

1 import { Button } from "@/components/ui/button";2 import { Card, CardContent, CardFooter, CardLabel } from "@/components/ui/card";3 4 export default function CardDefault() {5   return (6     <Card size="md">7       <CardLabel variant="border">Repository</CardLabel>8       <CardContent className="pt-6">9         <div className="space-y-4 text-sm">10           <p className="text-muted-foreground">Simple bordered card with floating border label.</p>11           <div className="flex justify-between py-1 border-b border-border">12             <span className="text-muted-foreground">Branch</span>13             <span className="font-mono">main</span>14           </div>15           <div className="flex justify-between py-1 border-b border-border">16             <span className="text-muted-foreground">Commit</span>17             <span className="font-mono">a1b2c3d</span>18           </div>19           <div className="flex justify-between py-1">20             <span className="text-muted-foreground">Status</span>21             <span className="font-bold text-success">PASS</span>22           </div>23         </div>24       </CardContent>25       <CardFooter>26         <Button variant="ghost">Cancel</Button>27         <Button variant="primary">Save</Button>28       </CardFooter>29     </Card>30   );31 }32

Examples

Surfaces

Preview

tsx

1 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";2 3 export default function CardSurfaces() {4   return (5     <div className="space-y-8">6       <Card surface="flat" size="md">7         <CardHeader>8           <CardTitle>Flat</CardTitle>9           <CardDescription>Default clean border</CardDescription>10         </CardHeader>11         <CardContent>12           <p className="text-sm text-muted-foreground">Soft bordered card for everyday use.</p>13         </CardContent>14       </Card>15 16       <Card surface="stacked" size="md">17         <CardHeader>18           <CardTitle>Stacked</CardTitle>19           <CardDescription>Paper stack illusion</CardDescription>20         </CardHeader>21         <CardContent>22           <p className="text-sm text-muted-foreground">A hard offset plate creates depth.</p>23         </CardContent>24       </Card>25 26       <Card surface="inset" size="md">27         <CardHeader>28           <CardTitle>Inset</CardTitle>29           <CardDescription>Recessed surface step</CardDescription>30         </CardHeader>31         <CardContent>32           <p className="text-sm text-muted-foreground">Stamped effect from a surface step.</p>33         </CardContent>34       </Card>35 36       <Card surface="dotted" size="md">37         <CardHeader>38           <CardTitle>Dotted</CardTitle>39           <CardDescription>Blueprint wireframe style</CardDescription>40         </CardHeader>41         <CardContent>42           <p className="text-sm text-muted-foreground">43             Dashed border for draft or placeholder content.44           </p>45         </CardContent>46       </Card>47 48       <Card surface="glow" size="md">49         <CardHeader>50           <CardTitle>Glow</CardTitle>51           <CardDescription>Doubled outer edge</CardDescription>52         </CardHeader>53         <CardContent>54           <p className="text-sm text-muted-foreground">A second hard edge for emphasis.</p>55         </CardContent>56       </Card>57     </div>58   );59 }60

Interactive

Preview

tsx

1 import { Fragment } from "react";2 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";3 4 // Hover and focus-visible only exist under a pointer or a keyboard, so the5 // matrix below applies the same treatments statically: each string is the6 // unprefixed twin of a `hover:` / `focus-visible:` class in cardVariants, which7 // keeps the deltas reviewable in a screenshot. Real usage never needs them —8 // the interactive prop applies them for you.9 const FORCED_HOVER = {10   flat: "border-border bg-[color-mix(in_oklab,var(--foreground)_4%,var(--background))]",11   stacked:12     "border-border bg-[color-mix(in_oklab,var(--foreground)_4%,var(--background))] shadow-[5px_5px_0_0_var(--background),6px_6px_0_0_color-mix(in_oklab,var(--foreground)_45%,transparent)]",13   inset: "border-border bg-[color-mix(in_oklab,var(--foreground)_10%,var(--background))]",14   dotted: "border-border bg-[color-mix(in_oklab,var(--foreground)_4%,var(--background))]",15   glow: "border-border outline-foreground/70 bg-[color-mix(in_oklab,var(--foreground)_4%,var(--background))]",16 } as const;17 18 const FORCED_FOCUS = "outline-2 outline-ring outline-offset-0";19 20 const SURFACES = [21   { surface: "flat", delta: "border brightens" },22   { surface: "stacked", delta: "offset plate grows" },23   { surface: "inset", delta: "recessed fill deepens" },24   { surface: "dotted", delta: "dashed border brightens" },25   { surface: "glow", delta: "outer edge strengthens" },26 ] as const;27 28 export default function CardInteractive() {29   return (30     <div className="space-y-10">31       <section className="space-y-4">32         <p className="font-mono text-xs uppercase tracking-wider text-muted-foreground">33           Rest / hover / focus — states forced statically34         </p>35         <div className="grid gap-6 sm:grid-cols-3">36           {SURFACES.map(({ surface, delta }) => (37             <Fragment key={surface}>38               <SwatchCard surface={surface} label="rest" />39               <SwatchCard40                 surface={surface}41                 label={`hover — ${delta}`}42                 force={FORCED_HOVER[surface]}43               />44               <SwatchCard surface={surface} label="focus-visible ring" force={FORCED_FOCUS} />45             </Fragment>46           ))}47         </div>48       </section>49 50       <section className="space-y-8">51         <p className="font-mono text-xs uppercase tracking-wider text-muted-foreground">52           Live — hover or Tab into each card53         </p>54         <Card55           as="a"56           href="#flat"57           surface="flat"58           size="md"59           interactive60           className="block no-underline"61         >62           <CardHeader>63             <CardTitle>Flat Interactive</CardTitle>64             <CardDescription>Tab to focus, hover to see border brighten</CardDescription>65           </CardHeader>66           <CardContent>67             <p className="text-sm text-muted-foreground">Cursor and background shift on hover.</p>68           </CardContent>69         </Card>70 71         <Card72           as="a"73           href="#stacked"74           surface="stacked"75           size="md"76           interactive77           className="block no-underline"78         >79           <CardHeader>80             <CardTitle>Stacked Interactive</CardTitle>81             <CardDescription>Tab to focus, hover to see the offset plate grow</CardDescription>82           </CardHeader>83           <CardContent>84             <p className="text-sm text-muted-foreground">The paper stack deepens on hover.</p>85           </CardContent>86         </Card>87 88         <Card89           as="a"90           href="#inset"91           surface="inset"92           size="md"93           interactive94           className="block no-underline"95         >96           <CardHeader>97             <CardTitle>Inset Interactive</CardTitle>98             <CardDescription>Tab to focus, hover to see the fill deepen</CardDescription>99           </CardHeader>100           <CardContent>101             <p className="text-sm text-muted-foreground">102               The recessed fill steps further on hover.103             </p>104           </CardContent>105         </Card>106 107         <Card108           as="a"109           href="#dotted"110           surface="dotted"111           size="md"112           interactive113           className="block no-underline"114         >115           <CardHeader>116             <CardTitle>Dotted Interactive</CardTitle>117             <CardDescription>Tab to focus, hover to see the dashed border brighten</CardDescription>118           </CardHeader>119           <CardContent>120             <p className="text-sm text-muted-foreground">The dashed border brightens on hover.</p>121           </CardContent>122         </Card>123 124         <Card125           as="button"126           type="button"127           surface="glow"128           size="md"129           interactive130           className="block w-full text-left"131         >132           <span className="block px-4 py-3 text-xl font-bold tracking-wide">Glow Interactive</span>133           <span className="block px-4 pb-4 text-sm text-muted-foreground">134             Rendered as a button — it takes keyboard focus; the outer edge strengthens on hover.135           </span>136         </Card>137       </section>138     </div>139   );140 }141 142 function SwatchCard({143   surface,144   label,145   force,146 }: {147   surface: (typeof SURFACES)[number]["surface"];148   label: string;149   force?: string;150 }) {151   return (152     <Card surface={surface} className={force}>153       <span className="block px-4 py-3 font-mono text-xs">154         <span className="block font-bold">{surface}</span>155         <span className="block text-muted-foreground">{label}</span>156       </span>157     </Card>158   );159 }160

Sizes

Preview

tsx

1 import {2   Card,3   CardContent,4   CardDescription,5   CardHeader,6   CardLabel,7   CardTitle,8 } from "@/components/ui/card";9 import { InlineCode } from "@/components/ui/code-block";10 11 export default function CardSizes() {12   return (13     <div className="space-y-8">14       <Card size="sm">15         <CardHeader>16           <CardTitle>Small Card</CardTitle>17           <CardDescription>max-w-sm size</CardDescription>18         </CardHeader>19         <CardContent>20           <p className="text-sm text-muted-foreground">Compact card layout.</p>21         </CardContent>22       </Card>23 24       <Card size="md">25         <CardLabel variant="gap">Inside Gap Label</CardLabel>26         <CardContent className="pt-6">27           <p className="text-sm text-muted-foreground">28             Use <InlineCode>variant="border"</InlineCode> for a boxed label or{" "}29             <InlineCode>variant="gap"</InlineCode> for a clean border cutout.30           </p>31         </CardContent>32       </Card>33 34       <Card size="lg" surface="stacked">35         <CardHeader>36           <CardTitle>Stacked Surface</CardTitle>37           <CardDescription>Paper stack depth effect</CardDescription>38         </CardHeader>39         <CardContent>40           <p className="text-sm text-muted-foreground">41             Opt in with surface="stacked" when you need extra weight.42           </p>43         </CardContent>44       </Card>45     </div>46   );47 }48

Header Action

Preview

tsx

1 import { Button } from "@/components/ui/button";2 import {3   Card,4   CardAction,5   CardContent,6   CardDescription,7   CardFooter,8   CardHeader,9   CardTitle,10 } from "@/components/ui/card";11 12 export default function CardActionExample() {13   return (14     <Card size="md">15       <CardHeader>16         <CardTitle>Deploy Preview</CardTitle>17         <CardDescription>Production build from main branch</CardDescription>18         <CardAction>19           <Button variant="ghost" size="sm" aria-label="More actions">20             ···21           </Button>22         </CardAction>23       </CardHeader>24       <CardContent>25         <div className="space-y-2 text-sm">26           <div className="flex justify-between py-1 border-b border-border">27             <span className="text-muted-foreground">Status</span>28             <span className="font-bold text-success">READY</span>29           </div>30           <div className="flex justify-between py-1">31             <span className="text-muted-foreground">Branch</span>32             <span className="font-mono">main</span>33           </div>34         </div>35       </CardContent>36       <CardFooter>37         <Button variant="ghost">Logs</Button>38         <Button variant="primary">Visit</Button>39       </CardFooter>40     </Card>41   );42 }43

Article (accessible)

Preview

tsx

1 import { Button } from "@/components/ui/button";2 import {3   Card,4   CardContent,5   CardDescription,6   CardFooter,7   CardHeader,8   CardTitle,9 } from "@/components/ui/card";10 11 export default function CardArticle() {12   return (13     <div className="space-y-6">14       <Card as="article" aria-labelledby="deploy-title" size="md">15         <CardHeader>16           <CardTitle id="deploy-title">Deploy Preview</CardTitle>17           <CardDescription>Production build from main branch</CardDescription>18         </CardHeader>19         <CardContent>20           <div className="space-y-2 text-sm">21             <div className="flex justify-between py-1 border-b border-border">22               <span className="text-muted-foreground">Status</span>23               <span className="font-bold text-success">READY</span>24             </div>25             <div className="flex justify-between py-1 border-b border-border">26               <span className="text-muted-foreground">Branch</span>27               <span className="font-mono">main</span>28             </div>29             <div className="flex justify-between py-1">30               <span className="text-muted-foreground">Commit</span>31               <span className="font-mono">f3a1b2c</span>32             </div>33           </div>34         </CardContent>35         <CardFooter>36           <Button variant="ghost">Logs</Button>37           <Button variant="primary">Visit</Button>38         </CardFooter>39       </Card>40 41       <Card as="article" aria-labelledby="review-title" size="md">42         <CardHeader>43           <CardTitle id="review-title">Code Review</CardTitle>44           <CardDescription>PR #42 awaiting approval</CardDescription>45         </CardHeader>46         <CardContent>47           <p className="text-sm text-muted-foreground">48             2 files changed, 14 additions, 3 deletions.49           </p>50         </CardContent>51         <CardFooter>52           <Button variant="ghost">Dismiss</Button>53           <Button variant="primary">Review</Button>54         </CardFooter>55       </Card>56     </div>57   );58 }59

API Reference

Card

Name	Type	Default	Description
as	"div" \| "article" \| "section" \| "aside" \| "a" \| "button"	"div"	Rendered HTML element. Use article/section/aside when the card is a self-contained content region, or a/button to make an interactive card keyboard-focusable.
surface	"flat" \| "stacked" \| "inset" \| "dotted" \| "glow"	"flat"	Surface treatment. Flat is a clean border, stacked adds a hard offset plate, inset steps the background down, dotted uses a dashed wireframe border, and glow doubles the outer edge.
interactive	boolean	false	Enables hover and focus-visible states with surface-specific treatments. Pair with a focusable host (as='a' or as='button') so keyboard users can reach the card.
size	"default" \| "sm" \| "md" \| "lg"	"default"	Max-width constraint. Default is full width.
children	ReactNode	—	Card subparts (Header, Label, Content, Footer, etc.).

Card.Label

Name	Type	Default	Description
variant	"border" \| "gap"	"border"	Visual treatment of the floating label. Border boxes the label; gap omits the box.
children	ReactNode	—	Label content.

Card.Title

Name	Type	Default	Description
as	"h2" \| "h3" \| "h4" \| "h5"	"h3"	Heading level. Match your document outline.
children	ReactNode	—	Title text.

Card.Description

Name	Type	Default	Description
children	ReactNode	—	Supporting description text.

Card.Header

Name	Type	Default	Description
children	ReactNode	—	Header content. When a Card.Action child is present, the header switches to a two-column grid.

Card.Action

Name	Type	Default	Description
children	ReactNode	—	Action element (button or badge) anchored to the top-right of Card.Header.

Card.Content

Name	Type	Default	Description
children	ReactNode	—	Body content.

Card.Footer

Name	Type	Default	Description
children	ReactNode	—	Footer actions or meta, right-aligned by default.

Accessibility

Notes

Surfaces

Card supports five surface treatments: flat (default clean border), stacked (paper-stack depth from a hard offset plate), inset (recessed surface step), dotted (dashed wireframe border), and glow (hard doubled outer edge). Depth comes from borders and background steps — cards never cast a soft shadow. Use surface='flat' for everyday cards, surface='stacked' for elevated emphasis, surface='inset' for recessed areas, surface='dotted' for drafts or placeholders, and surface='glow' for highlighted content.

Interactive

Add the interactive prop to enable hover and focus-visible states. Each surface has a unique hover treatment: flat brightens the border, stacked grows the offset plate, inset deepens the recessed fill, dotted brightens the dashed border, and glow strengthens the outer edge. The interactive prop only styles the surface — it does not make a div focusable. Render an interactive card on a focusable host (as='a' with href, or as='button' with onClick) or wrap its content in a link/button so keyboard users can reach it and the focus-visible treatment is reachable. See the Interactive example.

Floating Border Labels

Use CardLabel variant='border' for a boxed border label, or variant='gap' for a border cutout label with no border around the text. When using CardLabel, add pt-6 (or similar) to sibling CardContent to clear the floating label.

Padding rhythm

CardHeader, CardContent, and CardFooter all use px-6, so header text, body text, and footer actions share one vertical edge. Only the block padding differs per region (header py-3, content p-6, footer py-4). Override className if a product layout needs a different rhythm — but override all three regions together, never one.

Size

Card supports size='sm' | 'md' | 'lg' for max-width constraints. Default is full width.

Heading Level

CardTitle renders an h3 by default. Use the as prop to change the heading level (h2, h3, h4, h5).

Header Actions

Use CardAction inside CardHeader to place an action (button, badge) in the top-right corner. The header switches to a two-column grid layout automatically when CardAction is present.

Semantic HTML

Card renders a div by default. Use as='article' for self-contained content, as='section' for grouped content, or as='aside' for tangential content.

Accessible Article Cards

When using as='article', connect the card to its heading with aria-labelledby so screen readers announce card boundaries. Give CardTitle an id and pass the same id to Card's aria-labelledby. See the Article example.

Source

Install via CLI: pnpm exec dgadd add ui/card.

Highlighted source loads after this disclosure opens. Browse the source repository.

Card

Installation

Usage

Examples

Surfaces

Interactive

Sizes

Header Action

Article (accessible)

API Reference

Card

Card.Label

Card.Title

Card.Description

Card.Header

Card.Action

Card.Content

Card.Footer

Accessibility

Notes

Surfaces

Interactive

Floating Border Labels

Padding rhythm

Size

Heading Level

Header Actions

Semantic HTML

Accessible Article Cards

Source

View component source (15 files)