Window gaps
Inner 14px, outer −2px; the bar sits above the gap and the border is 1px.
Card
A bordered panel that groups a title, body and metadata; a link card makes the whole panel one link, a selectable card is an option with the selection fill.
stable · light DOM · 4.0.0. Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.
Live variants
default
<j3w1-card id="example-card-default"><article class="card">
<h3 class="card-title">Window gaps</h3>
<p class="card-body">Inner 14px, outer −2px; the bar sits above the gap and the border is 1px.</p>
<p class="card-meta">Decided in D-009 · 3 fixtures</p>
</article></j3w1-card>link-card
Example destination: card focus
<j3w1-card id="example-card-link-card"><a class="card card-link card-demo-target" href="#example-card-link-card-card-focus">
<span class="card-title">Focus ring</span>
<span class="card-body">One dashed pixel at −2px on controls; two solid pixels at −3px on containers.</span>
<span class="card-meta">Decided in D-006 · 5 fixtures</span>
</a><p id="example-card-link-card-card-focus" tabindex="-1" class="j3w1-example-target">Example destination: card focus</p></j3w1-card>selectable
Tiling
Windows fill the screen without overlap; the gap is the only ornament.
Floating
Windows overlap and carry the one shadow the theme permits.
<j3w1-card id="example-card-selectable"><div class="card-group" role="listbox" aria-label="Layouts">
<div class="card card-selectable" role="option" aria-selected="false" tabindex="0">
<span class="card-title">Tiling</span>
<span class="card-body">Windows fill the screen without overlap; the gap is the only ornament.</span>
<span class="card-meta">Default</span>
</div>
<div class="card card-selectable card-demo-target" role="option" aria-selected="false" tabindex="-1">
<span class="card-title">Floating</span>
<span class="card-body">Windows overlap and carry the one shadow the theme permits.</span>
<span class="card-meta">Dialogs and tools</span>
</div>
</div></j3w1-card>Install and register
Use the exact version. If npm publication is pending, install the release tarball from the installation guide.
npm install --save-exact @j3w1/ui@4.0.0import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/card.css';
import '@j3w1/ui/register/card';Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.
Copy the complete implementation
npx --package=@j3w1/ui@4.0.0 j3w1-ui copy card --out ./vendor/j3w1/cardThe CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.
Public API
attributes
| Name | Type / signature | Meaning |
|---|---|---|
disabled | CustomEvent | Disable the native controls owned by this instance. |
loading | CustomEvent | Mark the primary control busy and prevent duplicate activation. |
properties
| Name | Type / signature | Meaning |
|---|---|---|
disabled | boolean | Delegates disabled state to native children. |
name | string | Native control name; application form keys remain explicit. |
methods
| Name | Type / signature | Meaning |
|---|---|---|
refresh | (): void | Reconnect behavior after replacing native child structure. |
focus | (options?: FocusOptions): void | Focus the first usable native control. |
events
| Name | Type / signature | Meaning |
|---|
Dependencies and verification
Registered components: none. Style dependencies: none.
Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.
Full implementation manifest, API and token dependency closure
Canonical specification
Card card
A bordered panel that groups a title, body and metadata; a link card makes the whole panel one link, a selectable card is an option with the selection fill.
Report an issue with this component
Tokens
Focus a role to inspect its values; follow its link for persistent usage and source details.
| Part | Role | Value | Use |
|---|---|---|---|
root.bg | color.surface.defaultapproveduse | #0d0707 | D-041 surface.default: color.primitive.modern.panel. |
root.border | color.border.defaultapproveduse | #482b2b | D-041 border.default: color.primitive.modern.divider. |
root.bg-hover | color.interaction.hover.bgapproveduse | #1c1010 | D-041 interaction.hover.bg: color.primitive.modern.hover. |
root.border-hover | color.border.controlapproveduse | #c81a1a | D-041 owner correction: red control and floating-frame borders, distinct from rose text. |
root.ring | color.interaction.focus.ring-containerobserveduse | #ffa2a7 | Focus colour for containers and explicitly mapped filled controls (D-015); component rules determine ring geometry. |
title.text | color.text.brightapproveduse | #ffa2a7 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
body.text | color.text.defaultapproveduse | #e99499 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
meta.text | color.text.mutedapproveduse | #d4868b | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
selected.bg | color.interaction.selection.bgapproveduse | #531310 | Selected row, tab, workspace; D-027 recessed the fill, leaving the 2px indicator and the check to carry selection. |
selected.text | color.interaction.selection.textobserveduse | #f4eeee | Text on the selection. |
selected.ring | color.interaction.focus.ringobserveduse | #e53935 | 1px dashed focus ring on controls and rows. |
State matrix
Every declared state and combination, statically rendered; the default cell is live. Sizes: compact, comfortable (switch with the density control above).
| State | Default | Link card | Selectable |
|---|---|---|---|
default | Window gapsInner 14px, outer −2px; the bar sits above the gap and the border is 1px. |
Tiling
Windows fill the screen without overlap; the gap is the only ornament.
Floating
Windows overlap and carry the one shadow the theme permits.
| |
hover | |||
focus-visible | |||
selected | |||
selected+focus-visible |
Purpose
Groups a title, a line or two and a metadata line so they read as one thing. Static by default; a link when the whole unit leads somewhere, an option when the user picks among units. Not a dialog, a form or a table row.
Anatomy
Parts as listed in the anatomy. Padding 12px in comfortable, 8px in
compact.
States
| State | Visual | Non-colour channel |
|---|---|---|
| default | 1px color.border.default on color.surface.default | — |
| hover | link and selectable cards only: background → color.interaction.hover.bg; border → color.border.control | cursor: pointer; the border lightens from decorative to control |
| focus-visible | container ring 2px solid color.interaction.focus.ring-container at −3px | the ring |
| selected | fill color.interaction.selection.bg, color.interaction.selection.text on every line | aria-selected="true"; the on-fill text |
| selected+focus-visible | the fill and 1px dashed color.interaction.focus.ring at −2px | both visible at once |
A static card has no hover and no focus, and is not in the tab order.
Keyboard
A link card may hold no controls (a link cannot contain a button). A static card contributes only the controls it contains to the tab order.
Accessibility
A static card is an article with a heading when it stands alone, or a
section inside a list. A link card names itself from its content, title
first. A selectable group’s listbox carries aria-label. On the selection
fill every line takes the on-fill text, because muted text would fall below
4.5:1. Text meets 4.5:1; the ring 3:1 on the card and on the fill.
Portability
A bordered box with a background and an outline. Toolkits that shadow their frames remove it. A host without outlines draws a 2px inner border for the container ring, 1px for the selected card, and records it.
Non-examples
A shadow or elevation. Rounded corners. A hover lift or scale. A hover fill
on a static card. An invisible overlay as the only clickable part. A link
card containing buttons. A selected card shown by border colour alone,
without the fill and aria-selected. Muted metadata left on the selection
fill.
Contrast report
13 declared pairs measured on resolved sRGB values with the WCAG 2.x formula; 0 waived (decorative only), 0 failing. A pass is a design target for the named role, not an application-wide conformance claim.
| Pair | State | Kind | Foreground | Background | Ratio | Min | Result |
|---|---|---|---|---|---|---|---|
| card default text | default | text | color.text.default #e99499 | color.surface.default #0d0707 | 8.72 | 4.5 | pass |
| card hover text | hover | text | color.text.default #e99499 | color.interaction.hover.bg #1c1010 | 8.10 | 4.5 | pass |
| card hover border | hover | ui | color.border.control #c81a1a | color.interaction.hover.bg #1c1010 | 3.20 | 3 | pass |
| card focus-visible text | focus-visible | text | color.text.default #e99499 | color.surface.default #0d0707 | 8.72 | 4.5 | pass |
| card focus-visible outline | focus-visible | ui | color.interaction.focus.ring-container #ffa2a7 | color.surface.default #0d0707 | 10.45 | 3 | pass |
| card selected text | selected | text | color.interaction.selection.text #f4eeee | color.interaction.selection.bg #531310 | 12.47 | 4.5 | pass |
| card selected+focus-visible text | selected+focus-visible | text | color.interaction.selection.text #f4eeee | color.interaction.selection.bg #531310 | 12.47 | 4.5 | pass |
| card selected+focus-visible outline | selected+focus-visible | ui | color.interaction.focus.ring #e53935 | color.interaction.selection.bg #531310 | 3.38 | 3 | pass |
| title on the card | — | text | color.text.bright #ffa2a7 | color.surface.default #0d0707 | 10.45 | 4.5 | pass |
| metadata on the card | — | text | color.text.muted #d4868b | color.surface.default #0d0707 | 7.22 | 4.5 | pass |
| title on the hover fill | hover | text | color.text.bright #ffa2a7 | color.interaction.hover.bg #1c1010 | 9.71 | 4.5 | pass |
| metadata on the hover fill | hover | text | color.text.muted #d4868b | color.interaction.hover.bg #1c1010 | 6.70 | 4.5 | pass |
| card edge (decorative; the card is not a control at rest) | — | ui | color.border.default #482b2b | color.surface.default #0d0707 | 1.58 | 1 | pass |
Keys
| Key | Action |
|---|---|
| Tab | Reaches a link card as one stop; reaches a selectable group at its selected card (roving tabindex). |
| Enter | Follows a link card. |
| Up / Down / Left / Right | Moves between selectable cards in the group and selects the focused one. |
| Space | Toggles the focused card in a multi-select group. |
For agents
Component JSON ·Implementation brief ·Build a task kit ·
Related: list link button table
Stress fixtures: FX-LONG FX-320 FX-ZOOM-200 FX-I18N FX-RTL FX-RM FX-HC FX-STATE-MATRIX