ki-card
@kimen/elements/ki-card- Source
- Agent reference
Group related media, a heading, supporting text and actions on one surface. Fill any subset of the regions.
Weekly report
Traffic is up 12% week over week; conversion held steady.<ki-card><h3 slot="header">Weekly report</h3>Traffic is up 12% week over week; conversion held steady.<ki-button slot="footer" variant="secondary" type="button">View details</ki-button></ki-card>Examples
Section titled “Examples”Regions
Section titled “Regions”media, header, the default body and footer are independent slots:
Just the header and body
Cards render only the regions you fill; empty regions collapse.<ki-card><h3 slot="header">Just the header and body</h3>Cards render only the regions you fill; empty regions collapse.</ki-card>Secondary controls
Section titled “Secondary controls”Place separate controls in the body or footer.
<ki-card>Ready to publish this draft?<ki-button slot="footer" variant="primary" type="button">Publish</ki-button><ki-button slot="footer" variant="ghost" type="button">Discard</ki-button></ki-card>Surface variants
Section titled “Surface variants”default uses the theme’s card. Use elevated for a raised surface,
filled for a tint or outlined for a visible border.
Elevated
A raised surface.Filled
A tinted surface.Outlined
A bordered surface.<ki-card variant="elevated"><h3 slot="header">Elevated</h3>A raised surface.</ki-card><ki-card variant="filled"><h3 slot="header">Filled</h3>A tinted surface.</ki-card><ki-card variant="outlined"><h3 slot="header">Outlined</h3>A bordered surface.</ki-card>Clickable cards
Section titled “Clickable cards”Set href to link to another view. Set interactive for a button that emits
ki-activate once. Each needs a single text heading in the header slot.
When both options are present, the card follows href.
Search index rebuild
Scheduled for midnight.
Preview monthly report
Review the new report before publishing it.
<ki-card variant="outlined" href="#examples"><h3 slot="header">Search index rebuild</h3><p>Scheduled for midnight.</p><ki-button slot="footer" variant="secondary" type="button">Bookmark</ki-button></ki-card><ki-card interactive variant="filled"><h3 slot="header">Preview monthly report</h3><p>Review the new report before publishing it.</p></ki-card>API reference
Section titled “API reference”When to use: group related media, a title, supporting text and actions into one scannable surface. Set href for navigation or interactive for a declared action. Give a clickable card one text heading in the header slot and place secondary controls in the body or footer.
When not to use: as a form field, fieldset, page landmark, section replacement or nested card. Use a standalone button or link for a control without supporting content.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
href | href | string | undefined | – | Destination for the card's title link. Supply a text heading in the header slot. A nonblank href takes precedence over interactive. |
interactive | interactive | boolean | undefined | false | Gives a titled card a primary button that emits ki-activate. Use href for navigation. Keep other actions in separate controls in the card. |
variant | variant | "default" | "elevated" | "filled" | "outlined" | undefined | 'default' | Surface treatment. Choose elevated for a raised panel, filled for a tinted group or outlined for a bordered surface. Use default to follow the theme's existing card treatment. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-activate | CustomEvent<void> | Fires once when the user activates an action card by pointer or keyboard. |
Slots
| Slot | Description |
|---|---|
| (default) | Body region for supporting text or arbitrary composed content. |
footer | Closing region for actions such as ki-button; no dedicated actions slot exists in v1. |
header | Title region. Supply one nonempty text heading at the surrounding document level for a clickable card. |
media | Leading visual region for an image, video or illustration. |
CSS parts
| Part | Description |
|---|---|
body | Body region wrapper around the default slot. |
card | Card surface: background, border, radius, elevation and region gap. |
footer | Footer region wrapper. |
header | Header region wrapper. |
media | Media region wrapper. |
trigger | Native link or action button in a clickable card’s heading. |
CSS custom properties
The public styling contract of ki-card: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-card-backdrop-filter | Complete card backdrop filter, off by default. |
--ki-card-bg | color used by the card component for background (MarsUI Dashboard masters bind Surface/special/light-s0_dark-s1: white light / Dark/900 dark; #f9f9fa is the nested media panel, so the old s1 value inverted the surface hierarchy). |
--ki-card-bg-image | Optional decorative image over the card background. |
--ki-card-body-padding | dimension used by the card component for body padding. |
--ki-card-border-color | color used by the card component for border color (MarsUI Outline/base_em hairline — painted on large Chart cards; Dashboard_info leaves width 0, which stays the default via ki.card.border-width). |
--ki-card-border-width | dimension used by the card component for border width. |
--ki-card-elevated-bg | Raised card background. |
--ki-card-elevated-fg | Text on the elevated card background. |
--ki-card-elevated-shadow | Resting shadow for an elevated card. |
--ki-card-elevation | Card resting elevation: MarsUI elevation ramp level e1 (brief §5, drop 0/1/1/-0.5 in the scheme shadow color; replaces the migrated M2-era shadow). |
--ki-card-fg | color used by the card component for foreground. |
--ki-card-filled-bg | Tinted card background. |
--ki-card-filled-fg | Text on the filled card background. |
--ki-card-footer-padding | dimension used by the card component for footer padding. |
--ki-card-gap | dimension used by the card component for gap (MarsUI Dashboard_info/Chart inter-region rhythm 12px; material3 keeps zero via its override). |
--ki-card-header-padding | dimension used by the card component for header padding. |
--ki-card-hover-overlay | Pointer hover state layer on a primary-action card. |
--ki-card-hover-shadow | Hover shadow of a primary-action card. |
--ki-card-media-padding | dimension used by the card component for media padding (MarsUI Dashboard masters inset media panels 8px inline; material3 keeps full-bleed zero via its override). |
--ki-card-media-radius | dimension used by the card component for slotted media corner radius (MarsUI nested media panel Radius/big_component/radius_sm 20px; formalizes the fallback ki-card.css already consumes). |
--ki-card-outlined-bg | Page-coloured background for an outlined card. |
--ki-card-outlined-border | Boundary colour for an outlined card. |
--ki-card-outlined-border-width | Hairline width for an outlined card. |
--ki-card-outlined-fg | Text on the outlined card background. |
--ki-card-padding-block | dimension used by the card component for the surface block padding (16px carried by the card surface itself so stacked region paddings no longer double to 32px; formalizes the fallback ki-card.css already consumes). |
--ki-card-radius | dimension used by the card component for radius (MarsUI card surfaces ride the big_component scale: Dashboard_info 400x128 binds radius_xs 16px; large Chart cards anchor radius_lg 28px). |
--ki-card-title-family | Family used for a clickable card title. |
--ki-density-space-scale | Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). |
--ki-density-target-min | The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). |
--ki-elevation-e2 | MarsUI Elevation/e2 (cumulative: e1 layers plus 0/3/3/-1.5). |
--ki-elevation-none | Flat surfaces carry no resting shadow. |
--ki-focus-ring-color | Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. |
--ki-focus-ring-offset | Gap between a focusable component and its keyboard focus ring. |
--ki-focus-ring-width | Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. |
--ki-motion-distance-sm | Motion travel distance sm (4px): small slide/settle offsets. |
--ki-motion-duration-fast | Fast interaction transition duration. |
--ki-motion-duration-medium-1 | M3 md.sys.motion.duration.medium1 (250ms). onmars: MarsUI moderate step (240ms, 2x the 120ms base). |
--ki-motion-easing-out | Decelerating interaction transition easing curve. |
--ki-motion-easing-standard | Standard interaction transition easing curve. |
--ki-typography-family-body | semantic font family for typography family body. |
--ki-typography-line-height-title-1 | semantic dimension for typography line height title 1. |
--ki-typography-size-title-1 | semantic dimension for typography size title 1. |
Accessibility
Section titled “Accessibility”Supply a heading in the header slot at the level required by the page
outline. In a clickable card, the title is the name of the primary link or
button. Tab reaches it once, with a focus ring around the card, and reaches
each secondary control separately. Supporting text remains selectable. Use
the title link for native link gestures such as opening a new tab.