CngxCard

ComponentPrimaryOnPushNo encapsulationv0.1.0WCAG AA

projects/common/card/card.component.ts

GitHub

Import#

import { CngxCard } from '@cngx/common/card'

Description#

Semantic card component that adapts its host element role based on the as input.

Three archetypes:

'article' (default) - display card, no primary action
'button' - the entire card is a clickable button
'link' - the entire card is a navigation link

The host element is the semantic element - no inner wrapper. This eliminates double focus rings and wrapper problems for screen readers.

Action card with selection

<cngx-card as="button" [selectable]="true" [(selected)]="isSelected">
  <header cngxCardHeader><h3>Patient</h3></header>
  <div cngxCardBody>Details here</div>
</cngx-card>

Link card

<cngx-card as="link" href="/patients/42" ariaLabel="View patient">
  <img cngxCardMedia alt="Photo" />
</cngx-card>

https://cngxjs.github.io/cngx/examples/#/common/card/card-with-disclosure-expand-collapse https://cngxjs.github.io/cngx/examples/#/common/card/card-with-expandable-text

https://cngxjs.github.io/cngx/examples/#/common/card/card-with-speak-badge https://cngxjs.github.io/cngx/examples/#/common/card/disabled-with-reason

Metadata#

Selector: cngx-card
Change detection: ChangeDetectionStrategy.OnPush
Encapsulation: ViewEncapsulation.None
Style URLs: ./card.component.css
Host directives: CngxRovingItem

Host#

Class: cngx-card
Static attributes: [attr.role]hostRole()
[attr.tabindex]hostTabindex()
[attr.href]hostHref()
[attr.aria-label]ariaLabel() || null
[attr.aria-busy]loading() || null
[attr.aria-selected]interactive() && selectable() ? selected() : null
[attr.aria-disabled]disabled() || null
[attr.aria-describedby]describedByIds()
Bound classes: cngx-card--interactive ← interactive cngx-card--selected ← selected cngx-card--loading ← loading cngx-card--disabled ← disabled
Listeners: click → handleHostClick keydown.enter → handleHostKeydown keydown.space → handleHostKeydown

Index#

Inputs#

ariaLabel#string | undefined

input()

Accessible label for the card. Overrides the default screen reader announcement.

cardType#"article" | "link" | "button"

input()

Semantic archetype: 'article' (display), 'button' (action), or 'link' (navigation).

default 'article', { alias: 'as', }

disabled#boolean

input()

Whether the card is disabled. Prevents interaction and sets aria-disabled.

default false

disabledReason#string | undefined

input()

Explanation for why the card is disabled. Communicated to SR via aria-describedby.

href#string | undefined

input()

Navigation URL when as="link". Applied as href on the host.

loading#boolean

input()

Whether the card is in a loading state. Sets aria-busy and shows SR announcement.

default false

selectable#boolean

input()

Whether the card supports selection toggling.

default false

selected#boolean

model()

Two-way selection state. Only relevant when selectable is true.

default false

Outputs#

clicked#void

output()

Emits when an interactive card is clicked or activated via keyboard.

selected#boolean

model()

Two-way selection state. Only relevant when selectable is true.

HostBindings#

Binding	Expression
`[attr.role]`	`hostRole()`
`[attr.tabindex]`	`hostTabindex()`
`[attr.href]`	`hostHref()`
`[attr.aria-label]`	`ariaLabel() \|\| null`
`[attr.aria-busy]`	`loading() \|\| null`
`[attr.aria-selected]`	`interactive() && selectable() ? selected() : null`
`[attr.aria-disabled]`	`disabled() \|\| null`
`[attr.aria-describedby]`	`describedByIds()`
`[class.cngx-card--interactive]`	`interactive()`
`[class.cngx-card--selected]`	`selected()`
`[class.cngx-card--loading]`	`loading()`
`[class.cngx-card--disabled]`	`disabled()`

HostListeners#

Event	Handler
`(click)`	`click()`
`(keydown.enter)`	`keydown.enter()`
`(keydown.space)`	`keydown.space()`

Default visuals for CngxCard plus its slot directives. The host carries .cngx-card; slot directives project into the nested __media, __header, __title, __subtitle, __body, __footer, __actions, and __badge elements.

State modifiers

--interactive - hover shadow + touch-active opacity
--selected - accent border, tinted background, inset bar (non-color signal per WCAG 1.4.1)
--disabled - opacity dim + pointer-events: none
--loading - shimmer overlay (static fallback under prefers-reduced-motion)

Accent variants

Top stripe + tinted surface, one class per semantic intent:

--accent - neutral stripe, no tint
--accent-info - info stripe, info-tinted background
--accent-success - success stripe, success-tinted background
--accent-warning - warning stripe, warning-tinted background
--accent-danger - danger stripe, danger-tinted background
--accent-neutral - neutral stripe, foundation border colour

Badge slot

.cngx-card__badge is absolutely positioned with three axes:

Corner: --top-end, --top-start, --bottom-end, --bottom-start
Size: --size-sm, --size-md, --size-lg
Intent: --intent-primary, --intent-danger, --intent-warning, --intent-success, --intent-neutral

Empty content collapses to the sm status-dot fallback regardless of the size input.

Inheritance

Surface tokens fall back to the foundation so brand overrides propagate without per-component theming:

--cngx-card-bg -> --cngx-color-surface
--cngx-card-color -> --cngx-color-text
--cngx-card-border -> --cngx-color-border
--cngx-card-divider -> --cngx-color-border
--cngx-card-radius -> --cngx-radius-lg
--cngx-card-padding -> --cngx-space-md
--cngx-card-focus-color -> --cngx-color-primary
--cngx-card-selected-border -> --cngx-color-primary
--cngx-card-badge-*-bg -> --cngx-badge-*-bg -> --cngx-color-{intent}

Tinted-surface accents and the selected background use color-mix() against the matching foundation semantic colour and the card surface; themes only need to pin the tokens when the runtime mix is not desired.

Dark mode

Three hooks swap the subtitle, selected background, four accent tints, and the badge ring:

prefers-color-scheme: dark
[data-color-scheme="dark"]
.dark class

Foundation-delegated tokens ride the foundation cascade unchanged.

Pair with

@cngx/themes/material/card-theme - Material 3 surface + elevation

Index#

Layout

--cngx-card-radius#<length>

Default value 12px

Corner radius. Defaults to --cngx-radius-lg.

--cngx-card-min-width#<length>

Default value 120px

Minimum inline size of the card so empty cards still read as a surface.

--cngx-card-badge-offset#<length>

Default value -6px

Offset of the badge slot from the card corners (negative pulls the badge half-out so it overlaps the edge).

Surface

--cngx-card-bg#<color>

Default value oklch(1 0 0)

Card surface color. Falls back through --cngx-color-surface.

See: [[--cngx-color-surface]]

--cngx-card-color#<color>

Default value oklch(0.2 0.01 290)

Card text color. Falls back through --cngx-color-text.

--cngx-card-border#*

Default value 1px solid oklch(0.81 0.005 250)

Border shorthand. Falls back through --cngx-color-border.

--cngx-card-divider#<color>

Default value oklch(0.81 0.005 250)

Border color of the actions divider.

--cngx-card-badge-border#*

Default value 2px solid oklch(1 0 0)

Ring around the badge - contrasts the pill against the card surface so the corner anchor reads as a separate element. The :root dark-mode override swaps the colour; inherits: true so the swap reaches the host element through the cascade.

State / Hover

--cngx-card-hover-shadow#*

Default value 0 2px 8px 0 oklch(0 0 0 / 0.12)

Drop-shadow applied on hover for .cngx-card--interactive.

State / Active

--cngx-card-active-opacity#<number>

Default value 0.88

Opacity multiplier applied on touch-active. Only fires under (hover: none) so it doesn't compete with the hover shadow.

State / Focus

--cngx-card-focus-width#<length>

Default value 2px

Focus-ring width.

--cngx-card-focus-offset#<length>

Default value 2px

Outline offset of the focus ring.

--cngx-card-focus-color#<color>

Default value oklch(0.66 0.19 50)

Focus-ring color. Falls back to --cngx-color-primary.

See: [[--cngx-color-primary]]

State / Selected

--cngx-card-selected-border#<color>

Default value oklch(0.66 0.19 50)

Border color of the selected state and the inset selection bar. Falls back to --cngx-color-primary.

See: [[--cngx-color-primary]]

--cngx-card-selected-bg#<color>

Default value oklch(0.96 0.04 50)

Background of the selected state. The runtime fallback uses color-mix() against --cngx-color-primary, so this static default only matters when a theme pins the token explicitly.

--cngx-card-selected-bar-width#<length>

Default value 3px

Width of the inset selection bar drawn via ::before - provides a non-color-only selection signal (WCAG 1.4.1).

State / Disabled

--cngx-card-disabled-opacity#<number>

Default value 0.5

Opacity multiplier applied by .cngx-card--disabled.

State / Loading

--cngx-card-loading-shimmer#<color>

Default value oklch(1 0 0 / 0.4)

Shimmer band color for the loading overlay gradient.

--cngx-card-loading-overlay#<color>

Default value oklch(1 0 0 / 0.3)

Static overlay shown when prefers-reduced-motion suppresses the shimmer animation.

Typography

--cngx-card-title-size#*

Default value 1rem

Font-size of the title slot.

--cngx-card-title-weight#<number>

Default value 600

Font-weight of the title slot.

--cngx-card-title-color#<color>

Default value oklch(0.2 0.01 290)

Text color of the title slot.

--cngx-card-subtitle-size#*

Default value 0.8125rem

Font-size of the subtitle slot.

--cngx-card-subtitle-weight#<number>

Default value 400

Font-weight of the subtitle slot.

--cngx-card-subtitle-color#<color>

Default value oklch(0.36 0.02 290)

Text color of the subtitle slot - muted by default.

Variant / Accent

--cngx-card-accent-width#<length>

Default value 3px

Width of the top accent stripe applied by .cngx-card--accent.

--cngx-card-accent-color#<color>

Default value transparent

Color of the top accent stripe. Per-variant rules set it to the matching foundation semantic color.

--cngx-card-accent-info-bg#<color>

Default value oklch(0.97 0.03 250)

Tinted background for .cngx-card--accent-info. The runtime fallback uses color-mix() against --cngx-color-info; this static default only matters when a theme pins the token directly.

--cngx-card-accent-success-bg#<color>

Default value oklch(0.97 0.04 145)

Tinted background for .cngx-card--accent-success.

--cngx-card-accent-warning-bg#<color>

Default value oklch(0.97 0.04 75)

Tinted background for .cngx-card--accent-warning.

--cngx-card-accent-danger-bg#<color>

Default value oklch(0.97 0.03 25)

Tinted background for .cngx-card--accent-danger.

Sizing

--cngx-card-badge-size-sm#<length>

Default value 10px

Diameter (and minimum width) of the badge pill at the sm size. Also drives the :empty status-dot fallback regardless of the size input.

--cngx-card-badge-size-md#<length>

Default value 22px

Diameter (and minimum width) of the badge pill at the md size.

--cngx-card-badge-size-lg#<length>

Default value 28px

Diameter (and minimum width) of the badge pill at the lg size.

--cngx-card-badge-padding-inline#<length>

Default value 5px

Inline padding around content-bearing badges. Zeroed by the :empty dot fallback.

--cngx-card-badge-font-size-sm#*

Default value 0.625rem

Font-size at the sm size.

--cngx-card-badge-font-size-md#*

Default value 0.7rem

Font-size at the md size.

--cngx-card-badge-font-size-lg#*

Default value 0.8125rem

Font-size at the lg size.

--cngx-card-badge-radius#<length>

Default value 999px

Corner radius. Defaults to the pill radius via --cngx-radius-pill so the surface reads as a round indicator across all three sizes.

Variant / Primary

--cngx-card-badge-primary-bg#<color>

Default value oklch(0.66 0.19 50)

Background of the primary intent. Falls back through --cngx-badge-primary-bg then --cngx-color-primary.

See: [[--cngx-color-primary]]

--cngx-card-badge-primary-color#<color>

Default value oklch(1 0 0)

Text colour of the primary intent.

Variant / Danger

--cngx-card-badge-danger-bg#<color>

Default value oklch(0.62 0.22 25)

Background of the danger intent. Falls back through --cngx-badge-error-bg then --cngx-color-danger.

See: [[--cngx-color-danger]]

--cngx-card-badge-danger-color#<color>

Default value oklch(1 0 0)

Text colour of the danger intent.

Variant / Warning

--cngx-card-badge-warning-bg#<color>

Default value oklch(0.72 0.18 70)

Background of the warning intent. Falls back through --cngx-badge-warning-bg then --cngx-color-warning.

See: [[--cngx-color-warning]]

--cngx-card-badge-warning-color#<color>

Default value oklch(0.2 0.01 250)

Text colour of the warning intent.

Variant / Success

--cngx-card-badge-success-bg#<color>

Default value oklch(0.6 0.15 145)

Background of the success intent. No CngxBadge analogue - falls straight back to --cngx-color-success.

See: [[--cngx-color-success]]

--cngx-card-badge-success-color#<color>

Default value oklch(1 0 0)

Text colour of the success intent.

Variant / Neutral

--cngx-card-badge-neutral-bg#<color>

Default value oklch(0.68 0.01 240)

Background of the neutral intent. Falls back through --cngx-badge-neutral-bg then --cngx-color-text-muted.

--cngx-card-badge-neutral-color#<color>

Default value oklch(1 0 0)

Text colour of the neutral intent.

CngxCard

Import#

Description#

Action card with selection#

Link card#

Related#

Metadata#

Host#

Index#

Inputs

Outputs

Derived State

HostBindings

HostListeners

Inputs#

Outputs#

HostBindings#

HostListeners#

Index#

Layout

Surface

State / Hover

State / Active

State / Focus

State / Selected

State / Disabled

State / Loading

Typography

Variant / Accent

Sizing

Variant / Primary

Variant / Danger

Variant / Warning

Variant / Success

Variant / Neutral

Layout

Surface

State / Hover

State / Active

State / Focus

State / Selected

State / Disabled

State / Loading

Typography

Variant / Accent

Sizing

Variant / Primary

Variant / Danger

Variant / Warning

Variant / Success

Variant / Neutral

Action card with selection

Link card