J3W1 / DESIGN SYSTEM

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 · 1.1.0

Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.

Standalone example ↗Copy file manifest Canonical JSON Vue gallery ↗Prepare an agent kit →

Live variants

default

Window gaps

Inner 14px, outer −2px; the bar sits above the gap and the border is 1px.

Decided in D-009 · 3 fixtures

<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

Focus ring One dashed pixel at −2px on controls; two solid pixels at −3px on containers. Decided in D-006 · 5 fixtures

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

<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@1.1.0

import '@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.

Vue SFC, React, Astro and plain HTML integration →

Copy the complete implementation

npx --package=@j3w1/ui@1.1.0 j3w1-ui copy card --out ./vendor/j3w1/card

The 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

Purpose

Groups a small unit of content — a title, a line or two, a metadata line — so it reads as one thing. A card is static by default; it becomes a link when the whole unit leads somewhere, and an option when the user picks among several units. A card is not a dialog, not a form and not a table row.

Anatomy

A 1px color.border.default edge on color.surface.default, no shadow, no radius. Inside, a title in color.text.bright, body text in color.text.default, metadata in color.text.muted. Padding is 12px in comfortable and 8px in compact density. A link card is one anchor around the same content; a selectable card is an option inside a listbox group.

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` with `color.interaction.selection.text` on every line	`aria-selected="true"`; the fill’s on-fill text
selected+focus-visible	the fill and the 2px ring in `color.interaction.focus.ring-container`	both visible at once

A static card has no hover and no focus: nothing happens on a pointer and it is not in the tab order.

Keyboard

A link card is one tab stop and Enter follows it; controls inside a link card are not allowed (a link cannot contain a button). A selectable group is a listbox with roving tabindex: Tab lands on the selected card, the arrow keys move and select, Space toggles in a multi-select group. A static card that contains controls contributes those controls to the tab order and nothing else.

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 and the title comes first so it is read first. Selectable cards are role="option" inside role="listbox" with aria-label; aria-selected on each option. Contrast: title 10.10:1, body 8.43:1, metadata 5.66:1 on the card; on the selection fill every line switches to the on-fill text (12.47:1) because muted text would fall to 4.19:1. The ring is 10.10:1 on the card and 7.48:1 on the fill.

Portability

A bordered box with a background and an outline. Toolkits that add a shadow to their frames remove it. Hosts without container outlines draw the ring as a 2px inner border and record it.

Non-examples

A drop shadow or elevation. Rounded corners. A hover lift or scale. A static card with a hover fill. A card whose only clickable part is an invisible overlay. A link card containing buttons. A selected card shown by a border colour alone without the fill and aria-selected. Muted metadata left on the selection fill.