Card
Cards agrupam conteúdo e ações relacionados. A API cobre superfície padrão, borda explícita, elevação e composição com slots customizados.Cards group related content and actions. The API covers default surface, explicit border, elevation, and custom slot composition.
Quando usarWhen to use
Use cards quandoUse cards when
Agrupar informações relacionadas: listagens de produtos, previews de conteúdo, widgets de dashboard. Cards criam limites visuais que ajudam os usuários a escanear e comparar conteúdos distintos.Grouping related information: product listings, content previews, dashboard widgets. Cards create visual boundaries that help users scan and compare discrete pieces of content.
Não use cards quandoDon't use cards when
Exibir o resultado de uma ação única (use Alert), construir seções de página inteira (use primitivos de layout), ou apresentar dados tabulares densos (use linhas de tabela).Displaying a single action result (use Alert), building full-page sections (use layout primitives), or presenting dense tabular data (use a table row instead).
AnatomiaAnatomy
1
2
Card Title 3
Description text
Body content goes here. This is a flexible slot for any content.
4
1 Container (
2 Content container (
3 Header (
4 Body (
2 Content container (
3 Header (
4 Body (
.ds-card) — superfície com border-radius, borda ou sombra opcional dependendo da variante.2 Content container (
.ds-card__container) — aplica padding e gap internos.3 Header (
.ds-card__header) — wrapper para título e descrição opcionais.4 Body (
.ds-card__body) — área de conteúdo flexível.1 Container (.ds-card) — surface with border-radius, optional border or shadow depending on variant.2 Content container (
.ds-card__container) — applies inner padding and gap.3 Header (
.ds-card__header) — wrapper for optional title and description.4 Body (
.ds-card__body) — flexible content area.
PadrãoDefault
Card Title
Description or meta information
This is the card body content. It provides additional context or details about the subject of the card.
<div class="ds-card ds-card--default">
<div class="ds-card__container">
<div class="ds-card__header">
<h3 class="ds-card__title">Card Title</h3>
<p class="ds-card__description">Description or meta information</p>
</div>
<div class="ds-card__body">
<p>This is the card body content.</p>
</div>
</div>
</div>Com borda (Outlined)Outlined
Outlined Card
With a stronger border
Outlined cards use a more visible border to distinguish content sections clearly from the background.
<div class="ds-card ds-card--outlined">
<div class="ds-card__header">
<h3 class="ds-card__title">Outlined Card</h3>
<p class="ds-card__description">With a stronger border</p>
</div>
<div class="ds-card__body">
<p>Outlined cards use a more visible border.</p>
</div>
</div>Elevado (Elevated)Elevated
Elevated Card
Raised surface
Elevated cards use a raised surface and shadow instead of a border to create visual depth and hierarchy.
<div class="ds-card ds-card--elevated">
<div class="ds-card__header">
<h3 class="ds-card__title">Elevated Card</h3>
<p class="ds-card__description">Raised surface</p>
</div>
<div class="ds-card__body">
<p>Elevated cards use a raised surface and shadow.</p>
</div>
</div>ComparaçãoComparison
Default
Subtle border.
Outlined
Stronger border.
Elevated
Raised surface.
<div class="ds-card ds-card--default">...</div>
<div class="ds-card ds-card--outlined">...</div>
<div class="ds-card ds-card--elevated">...</div>Media e interativoMedia and interactive
<button class="ds-card ds-card--interactive" type="button">
<div class="ds-card__media" aria-hidden="true">...</div>
<div class="ds-card__container">
<div class="ds-card__header">
<h3 class="ds-card__title">Card Title</h3>
</div>
<div class="ds-card__body">
<p>Interactive card content.</p>
</div>
</div>
</button>Composição customizadaCustom composition
Use o card como container quando o conteúdo interno precisar ser montado com outros componentes. Header e footer são opcionais; o body recebe o conteúdo principal.Use the card as a container when the inner content needs to be composed with other components. Header and footer are optional; the body hosts the primary content.
Usage
128 active seats
Healthy
<div class="ds-card ds-card--outlined">
<div class="ds-card__body">
<!-- custom content / nested components -->
</div>
<div class="ds-card__footer">
<button class="ds-button ds-button--ghost ds-button--sm">Details</button>
</div>
</div>Boas práticasBest practices
Item A
Item B
Faça
Use variantes consistentes no mesmo contexto. Todos os cards em um grid devem compartilhar o mesmo estilo.Use consistent variants in the same context. All cards in a grid should share the same style.
Item A
Item B
Não faça
Misturar variantes default, outlined e elevated no mesmo grid. Isso cria hierarquia visual inconsistente.Mix default, outlined, and elevated variants in the same grid. It creates inconsistent visual hierarchy.
Cards outlined em uma lista densaOutlined cards in a dense list
Faça
Use outlined para layouts densos onde limites claros são necessarios. Use elevated para conteúdo proeminente e independente.Use outlined for dense layouts where clear boundaries are needed. Use elevated for prominent, standalone content.
Card elevated dentro de um painel elevatedElevated card inside elevated panel
Não faça
Colocar cards elevated dentro de um container ja elevado. Empilhar sombras cria ruído visual e quebra a hierarquia.Place elevated cards inside an already elevated container. Stacking shadows creates visual noise and breaks hierarchy.
Diretrizes de conteúdoContent guidelines
| RegraRule | ExemploExample |
|---|---|
| Cards são containers — diretrizes de conteúdo se aplicam ao que esta dentroCards are containers — content guidelines apply to what's inside | Use headings semânticos, texto de corpo e buttons de ação conforme necessarioUse semantic headings, body text, and action buttons as needed |
| Cards clicáveis: toda a superfície deve ser alvo de cliqueClickable cards: entire surface should be click target | Envolva o conteúdo em <a> ou use um link único com pseudo-elemento ::afterWrap content in <a> or use a single link with ::after pseudo-element |
| Mantenha o conteúdo escaneavelKeep content scannable | Título + 1-2 linhas de texto de corpo. Evite paragrafos longos dentro de cards.Title + 1-2 lines of body text. Avoid long paragraphs inside cards. |
Mapeamento de tokensToken mapping
| PropriedadeProperty | Token | Variável CSSCSS variable |
|---|---|---|
| background | semantic.surface.default | --ds-surface-default |
| background (elevated variant) | semantic.surface.raised | --ds-surface-raised |
| border (default variant) | semantic.border.subtle | --ds-border-subtle |
| border (outlined variant) | semantic.border.default | --ds-border-default |
| shadow (elevated) | semantic.shadow.card | --ds-shadow-card |
| border-radius | component.card.radius.default | --ds-card-radius-default |
| border-width | component.card.border-width.default | --ds-card-border-width-default |
.ds-card__container padding | component.card.container.padding.default | --ds-card-container-padding-default |
.ds-card__container gap | component.card.container.gap.default | --ds-card-container-gap-default |
.ds-card__header gap | component.card.header.gap.default | --ds-card-header-gap-default |
.ds-card__title typography | component.card.title.{font-size,line-height,font-weight}.default | --ds-card-title-*-default |
.ds-card__description typography | component.card.subtitle.{font-size,line-height,font-weight}.default | --ds-card-subtitle-*-default |
.ds-card__body typography | component.card.body.{font-size,line-height,font-weight}.default | --ds-card-body-*-default |
.ds-card__footer spacing | component.card.footer.gap.default | --ds-card-footer-gap-default |
.ds-card--interactive border | component.card-interactive.border-* | --ds-card-interactive-border-* |
.ds-card--interactive focus ring radius | component.card-interactive.focus-ring.radius.default | --ds-card-interactive-focus-ring-radius-default |
Classes CSSCSS classes
| ClasseClass | DescriçãoDescription |
|---|---|
ds-card | Container base do cardBase card container |
ds-card--default | Variante padrão com borda sutilDefault variant with subtle border |
ds-card--outlined | Variante outlined com borda mais forteOutlined variant with stronger border |
ds-card--elevated | Variante elevated com box shadow, sem bordaElevated variant with box shadow, no border |
ds-card--interactive | Card interativo derivado do outlined com hover, focus e selectedInteractive card derived from outlined with hover, focus, and selected states |
ds-card--selected | Estado selected do card interativoSelected state for interactive card |
ds-card__media | Slot de media full-bleed acima do container de conteúdoFull-bleed media slot above the content container |
ds-card__container | Container interno com padding e gap do conteúdoInner container with content padding and gap |
ds-card__header | Seção de header do cardCard header section |
ds-card__title | Texto do título do cardCard title text |
ds-card__description | Texto de descrição/meta do cardCard description/meta text |
ds-card__body | Área de conteúdo do corpo do cardCard body content area |
ds-card__footer | Área opcional para ações ou conteúdo complementarOptional area for actions or supporting content |
Interação por tecladoKeyboard interaction
Cards não possuem interação por teclado por padrão. Se o card for interativo (clicável), envolva o conteúdo em um elemento <a> ou adicione role="link" com tabindex="0" para torná-lo focável é operável via Enter.Cards have no keyboard interaction by default. If the card is interactive (clickable), wrap content in an <a> element or add role="link" with tabindex="0" to make it focusable and operable via Enter.
AccessibilityAccessibility
| Critério WCAGWCAG criterion | RequisitoRequirement | Status |
|---|---|---|
| 1.4.11 Non-text Contrast (AA) | Borda ou sombra deve ter pelo menos 3:1 de contraste com o fundo da páginaBorder or shadow must have at least 3:1 contrast against the page background | ✓ |
| 2.5.8 Target Size min (AA) | Se o card for clicável, toda a superfície deve ser o alvo de cliqueIf the card is clickable, the entire surface must be the click target | ✓ |
Markup semânticoSemantic markup
Cards são containers genericos e não requerem roles ARIA específicos por padrão. Use tags de heading semânticos (<h2>, <h3>) para títulos de cards para manter o outline adequado do documento. Se o card inteiro for clicável, envolva-o em um elemento <a> ou <button>, ou use um único link dentro do card com um nome acessível claro.Cards are generic containers and do not require specific ARIA roles by default. Use semantic heading tags (<h2>, <h3>) for card titles to maintain proper document outline. If the entire card is clickable, wrap it in an <a> or <button> element, or use a single link inside the card with a clear accessible name.