Components
Card
A bounded group of related content with a border and consistent padding is the ordinary box that most of a screen is made of.
Usage
pnpm dlx shadcn@latest add @opsinjs/card
The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.
import { Card } from "@/components/ui/card"<Card>
<Card.Header title={<h3>Recent readings</h3>} />
<Card.Body>Card content</Card.Body>
</Card>Examples
card · base base · style base-lyraOpen under the product themeThe whole card as one link
href makes the card one anchor and one tab stop. A chevron marks it at rest,
the title underlines on hover, and it holds no buttons.
card-as-a-link · base base · style base-lyraOpen under the product themeimport { Card } from "@/components/ui/card"
/* Fictional sections with no readings in them. A screenshot of an opsinjs
example must never be mistakable for somebody's own result, so there is no
number, no unit and no date anywhere in this file. */
const SECTIONS = [
{
title: "First example section",
description: "What the reader will find after they tap it.",
href: "#first-example-section",
},
{
title: "Second example section",
description: "One line, and it stays one line at the compact density.",
href: "#second-example-section",
},
]
export default function CardAsALink() {
return (
/* `role="list"` on a list that has already got one, because `list-style:
none` is the signal WebKit uses to drop list semantics: without it,
VoiceOver announces neither "list, 2 items" on entry nor "1 of 2" on each
card, which is the position information a reader scanning a list of link
cards navigates by. NVDA keeps the semantics either way, so the loss is
invisible in a desktop-Windows test and lands on the platform this
audience most uses. The role on the item is the same answer to the same
cause, and costs nothing where the parent role was enough on its own. */
<ul
role="list"
className="m-0 flex w-full max-w-sm list-none flex-col gap-opsin-4 p-0"
>
{SECTIONS.map((section) => (
<li key={section.href} id={section.href.slice(1)} role="listitem">
<Card href={section.href}>
<Card.Header
title={<h3>{section.title}</h3>}
description={section.description}
/>
</Card>
</li>
))}
</ul>
)
}Cards on a sheet, and the rung that stays put
The sheet is the layer; the cards on it stay on the card rung, since a
translucent rung never contains one.
card-on-a-sheet · base base · style base-lyraOpen under the product themeimport { Card } from "@/components/ui/card"
import { Surface } from "@/components/ui/surface"
const BACKDROP_TILES = [
"bg-foreground",
"bg-background",
"bg-primary",
"bg-muted",
"bg-primary",
"bg-foreground",
"bg-background",
"bg-muted",
]
const SECTIONS = [
{
title: "First example section",
body: "A card on the sheet, opaque, bounded by a line rather than a shadow.",
},
{
title: "Second example section",
body: "The same rung as the first. Nesting a rung here would be the second blur.",
},
]
export default function CardOnASheet() {
return (
<div className="relative w-full max-w-sm overflow-hidden rounded-opsin-lg">
<div
aria-hidden="true"
className="absolute inset-0 grid grid-cols-4 grid-rows-2"
>
{BACKDROP_TILES.map((tone, index) => (
<div key={`${tone}-${index}`} className={tone} />
))}
</div>
{/* One translucent surface, and everything on it is opaque. The count of
composited translucent layers on this example is exactly one, against
a budget of three. */}
<Surface rung="sheet" className="relative mt-opsin-16 rounded-t-opsin-xl">
<div className="flex flex-col gap-opsin-4 p-opsin-5">
{SECTIONS.map((section) => (
<Card
key={section.title}
className="rounded-[calc(var(--opsin-radius-xl)-var(--opsin-space-5))]!"
>
<Card.Header title={<h3>{section.title}</h3>} />
<Card.Body>
<p className="m-0 text-opsin-body">{section.body}</p>
</Card.Body>
</Card>
))}
</div>
</Surface>
</div>
)
}When to use it
Use it when
- Grouping content that belongs together and needs a visible boundary.
- Giving a block its own padding, radius and rung so it reads as one thing, not a region of the page.
- As the base for a purpose-built card with its own contract, the way ResultCard and CareCard are.
Do not use it when
- The content is a health result with a value, range, status and meaning.Use
result-cardinstead. - The content is an instruction the reader must act on.Use
care-cardinstead. - The content is one measurement in a dashboard grid.Use
metric-tileinstead. - You need a layer over scrolling content that must stay readable.Use
surfaceinstead. - You want a border for advisory prose.Use
calloutinstead.
Accessibility
A card takes no role or name unless it is a link. It carries the page's heading level
in a title slot that resets font and margin, floors a link target at
--opsin-target-minimum, and keeps its edge under greyscale, forced-colors and print.
The resting chevron is aria-hidden, backed by the title underline and anchor as
redundant cues. There is no axe violation and no 320px reflow failure, and
pnpm run check:a11y confirms on every commit that every colour is a role token, no
type size is in px, and no banned word appears. The audit moved the link card's
focus-visible ring from a hardcoded 2px outline to --opsin-border-focus and
--opsin-border-focus-offset, so a product raising those gets a wider ring here, and
the default stays 2px. A link card sinks to 0.98 when pressed and comes back on the
standard curve, never on a spring, because a card can hold a reading.
Residual items. A link card is one anchor, so its accessible name is all its text
at once. Weigh that verbosity before putting href on a long card.
| Key | Action | Notes |
|---|---|---|
| Tab | Moves to the card, when the card is a link | One stop per card. A card without href is not focusable. |
| Shift+Tab | Moves backwards to the card | Reverse order matches visual order. |
| Enter | Follows the link, on a card that has an href | The root is a real anchor, so this is browser behaviour. |
| Space | Scrolls the page | A link activates on Enter, not Space. |
Contrast: 52 measured token pairs, 16 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below floor |
| body text on the canvas material | light | 104.7 | 17.96:1 | Pass |
| body text on the canvas material | dark | -100.5 | 18.00:1 | Pass |
| body text on the inset material | light | 98.1 | 16.32:1 | Pass |
| body text on the inset material | dark | -100.1 | 17.18:1 | Pass |
| body text on the card material | light | 104.7 | 17.96:1 | Pass |
| body text on the card material | dark | -99.6 | 16.32:1 | Pass |
| body text on the raised material | light | 104.7 | 17.96:1 | Pass |
| body text on the raised material | dark | -97.5 | 13.77:1 | Pass |
| body text on the sheet material over the darkest backdrop | light | 99.9 | 16.76:1 | Pass |
| body text on the sheet material over the darkest backdrop | dark | -99.7 | 16.47:1 | Pass |
| body text on the sheet material over the lightest backdrop | light | 104.7 | 17.96:1 | Pass |
| body text on the sheet material over the lightest backdrop | dark | -80.8 | 6.07:1 | Pass |
| body text on the overlay material over the darkest backdrop | light | 85.9 | 13.48:1 | Pass |
| body text on the overlay material over the darkest backdrop | dark | -99.9 | 16.77:1 | Pass |
| body text on the overlay material over the lightest backdrop | light | 104.7 | 17.96:1 | Pass |
| body text on the overlay material over the lightest backdrop | dark | -54.2 | 2.69:1 | Below floor |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Prop
Type
Generated from CardProps in registry/bases/base/card.tsx.
rung defaults to card, not raised, and never goes above raised: a
translucent rung warns in development and renders. render takes the
router's link element, not a function, and does nothing without href. There is
no status, variant, color or category.
Prop
Type
Generated from CardHeaderProps in registry/bases/base/card.tsx.
Prop
Type
Generated from CardBodyProps in registry/bases/base/card.tsx.
Prop
Type
Generated from CardFooterProps in registry/bases/base/card.tsx.