Skip to content
opsinjs
Edit this page

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

Theme
Density
Text
Status
Accent theme
Accent
card · base base · style base-lyraOpen under the product theme

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.

Theme
Density
Text
Status
Accent theme
Accent
card-as-a-link · base base · style base-lyraOpen under the product theme
card-as-a-link.tsx
import { 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.

Theme
Density
Text
Status
Accent theme
Accent
card-on-a-sheet · base base · style base-lyraOpen under the product theme
card-on-a-sheet.tsx
import { 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-card instead.
  • The content is an instruction the reader must act on.Use care-card instead.
  • The content is one measurement in a dashboard grid.Use metric-tile instead.
  • You need a layer over scrolling content that must stay readable.Use surface instead.
  • You want a border for advisory prose.Use callout instead.

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.

KeyActionNotes
TabMoves to the card, when the card is a linkOne stop per card. A card without href is not focusable.
Shift+TabMoves backwards to the cardReverse order matches visual order.
EnterFollows the link, on a card that has an hrefThe root is a real anchor, so this is browser behaviour.
SpaceScrolls the pageA link activates on Enter, not Space.
Contrast: 52 measured token pairs, 16 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below floor
body text on the canvas materiallight104.717.96:1Pass
body text on the canvas materialdark-100.518.00:1Pass
body text on the inset materiallight98.116.32:1Pass
body text on the inset materialdark-100.117.18:1Pass
body text on the card materiallight104.717.96:1Pass
body text on the card materialdark-99.616.32:1Pass
body text on the raised materiallight104.717.96:1Pass
body text on the raised materialdark-97.513.77:1Pass
body text on the sheet material over the darkest backdroplight99.916.76:1Pass
body text on the sheet material over the darkest backdropdark-99.716.47:1Pass
body text on the sheet material over the lightest backdroplight104.717.96:1Pass
body text on the sheet material over the lightest backdropdark-80.86.07:1Pass
body text on the overlay material over the darkest backdroplight85.913.48:1Pass
body text on the overlay material over the darkest backdropdark-99.916.77:1Pass
body text on the overlay material over the lightest backdroplight104.717.96:1Pass
body text on the overlay material over the lightest backdropdark-54.22.69:1Below 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.