@kouji-ui/components 0.9.2 → 0.9.3

package/src/button/button.css

@@ -0,0 +1,295 @@
+/* ─────────────────────────────────────────────────────────────
+   .kj-button — component-layer tokens + structural CSS
+   Tokens default to shared-layer values from @kouji-ui/themes.
+   Variants/sizes/states retarget the component tokens; the
+   structural rules below are the only place raw var(--kj-button-*)
+   is read.
+   ──────────────────────────────────────────────────────────── */
+
+@layer kj.component {
+  .kj-button {
+    /* Component knobs are NOT declared here.
+       A custom property declared on an element always beats an inherited one,
+       so declaring the knobs on .kj-button made them unreachable from an
+       ancestor — including the <kj-button> host, which is display:contents and
+       is the only thing a consumer can put an inline style on. The knobs were
+       documented as "themes/users can override any of these" but in practice
+       could only be overridden by a rule targeting .kj-button itself.
+       Each knob is now read as var(name, <default>) at its use site, exactly
+       like --kj-button-shadow already was, so an ancestor value reaches the
+       component and the default still applies when nobody sets one.
+       Variant and size rules still DECLARE knobs on the element on purpose:
+       that is the component's own logic and must win. */
+    /* --kj-button-shadow / --kj-button-shadow-hover / --kj-button-shadow-active
+       are intentionally NOT declared here. Declaring them with element-level
+       specificity would win over the theme's `[data-theme="X"]` ancestor
+       declaration (e.g. kouji's `6px 6px 0 #2a2a2a` offset block), since
+       both selectors are (0,1,0) and same-layer source-order favours the
+       element. The hover/active rules below pull the value via
+       `var(name, fallback)` so the theme's inherited value reaches the
+       component AND the fallback (`none`) applies when no theme sets one. */
+    /* Typographic tone — themes override these for brand voice (e.g.
+       bauhaus bumps weight to 900; cyberpunk tightens tracking). */
+    /* Hover lift — pulls from the shared per-theme --kj-hover-translate
+       (bauhaus = -4px; everyone else = -2px). */
+
+    /* the only place raw var(--kj-button-*) is read */
+    display: inline-flex;
+    align-items: center;
+    justify-content: var(--kj-button-justify, center);
+    gap: var(--kj-button-gap, var(--kj-space-sm));
+    min-width: var(--kj-button-min-width, auto);
+    /* Explicit per-size height + align-self prevents flex parents
+       (align-items: stretch) from over-growing the button vertically. */
+    height: var(--kj-button-height, auto);
+    align-self: center;
+    background: var(--kj-button-bg, var(--kj-bg-primary));
+    color: var(--kj-button-fg, var(--kj-fg-on-primary));
+    border: var(--kj-button-border-width, var(--kj-border)) var(--kj-button-border-style, solid) var(--kj-button-border-color, transparent);
+    border-radius: var(--kj-button-radius, var(--kj-radius-field));
+    padding: var(--kj-button-padding-y, var(--kj-space-sm)) var(--kj-button-padding-x, var(--kj-space-md));
+    font: var(--kj-button-font-weight, 600) var(--kj-button-font-size, var(--kj-text-sm)) / 1.2 var(--kj-button-font, var(--kj-font-sans));
+    letter-spacing: var(--kj-button-letter-spacing, -0.01em);
+    text-transform: var(--kj-button-text-transform, none);
+    /* Button shadow is opt-in PER PAGE CONTEXT (e.g. landing hero, docs
+       playground stage) AND restricted to the `default` (primary) variant
+       — never global. Pages set `--kj-button-shadow` at their scope; the
+       applying rules below only fire for `[data-variant="default"]`. */
+    /* Transition only properties tied to user interaction (hover / active /
+       focus). NOT background-color — variant-driven bg changes propagate
+       through the wrapper input on the same tick as the host attribute, and
+       transitioning bg here animates the initial primary→variant flip on
+       components like <kj-button variant="ghost"> when the wrapper resolves. */
+    transition: color var(--kj-transition), border-color var(--kj-transition),
+                box-shadow var(--kj-transition), transform var(--kj-transition),
+                opacity var(--kj-transition);
+    cursor: pointer;
+    text-decoration: none;
+  }
+
+  /* Variants flip component tokens. Each variant owns its hover so the
+     hover surface is designed per intent, not derived heuristically.
+
+     Filled variants (default, destructive) darken on hover via a fixed
+     8% color-mix toward black. Themes can override the variant rules
+     entirely for a brand-correct shade. */
+
+  .kj-button[data-variant="destructive"] {
+    --kj-button-bg: var(--kj-bg-danger);
+    --kj-button-fg: var(--kj-fg-on-danger);
+  }
+  .kj-button[data-variant="destructive"]:hover {
+    --kj-button-bg: color-mix(in oklch, var(--kj-bg-danger), black 8%);
+  }
+
+  .kj-button[data-variant="ghost"] {
+    --kj-button-bg: transparent;
+    --kj-button-fg: var(--kj-fg-default);
+    --kj-button-border-color: transparent;
+  }
+  /* Use a foreground-tinted overlay rather than a static base-200 surface so
+     the hover state stays visible even on themes where base-100 / base-200
+     are nearly the same value (e.g. kouji's deep #0c0c0c / #141414 ramp). */
+  .kj-button[data-variant="ghost"]:hover {
+    --kj-button-bg: color-mix(in oklab, var(--kj-fg-default) 10%, transparent);
+  }
+
+  .kj-button[data-variant="outline"] {
+    --kj-button-bg: transparent;
+    --kj-button-fg: var(--kj-fg-default);
+    --kj-button-border-color: var(--kj-border-default);
+  }
+  .kj-button[data-variant="outline"]:hover {
+    --kj-button-bg: var(--kj-bg-surface);
+  }
+
+  /* Segmented — a member of a segmented control. Idle segments are quiet and
+     borderless: the GROUP draws one shared shell and the dividers (see
+     button-group.css), so per-button borders would double up. Only the
+     pressed segment is filled, so "which one is on" reads from fill and not
+     from colour alone.
+
+     The on-state pulls through `--kj-segmented-bg-on` / `-fg-on` rather than
+     naming the surface directly: variant rules declare knobs on the element
+     and would otherwise beat a consumer's ancestor value, which is the one
+     thing this variant needs to stay themable. */
+  .kj-button[data-variant="segmented"] {
+    --kj-button-bg: transparent;
+    --kj-button-fg: var(--kj-fg-muted, var(--kj-fg-default));
+    --kj-button-border-color: transparent;
+    --kj-button-border-width: 0;
+    --kj-button-radius: 0;
+    --kj-button-hover-translate: none;
+  }
+  .kj-button[data-variant="segmented"]:hover {
+    --kj-button-bg: transparent;
+    --kj-button-fg: var(--kj-fg-default);
+  }
+  .kj-button[data-variant="segmented"][aria-pressed="true"] {
+    --kj-button-bg: var(--kj-segmented-bg-on, var(--kj-bg-surface));
+    --kj-button-fg: var(--kj-segmented-fg-on, var(--kj-fg-default));
+    cursor: default;
+  }
+  .kj-button[data-variant="segmented"][aria-pressed="true"]:hover {
+    --kj-button-bg: var(--kj-segmented-bg-on, var(--kj-bg-surface));
+    --kj-button-fg: var(--kj-segmented-fg-on, var(--kj-fg-default));
+  }
+
+  .kj-button[data-variant="link"] {
+    --kj-button-bg: transparent;
+    --kj-button-fg: var(--kj-fg-primary);
+    --kj-button-padding-x: 0;
+    --kj-button-padding-y: 0;
+    /* Link variant is plain underlined text — explicitly null out any
+       theme-set --kj-button-shadow so kouji/bauhaus offsets don't leak
+       onto inline text links. Ghost / outline / destructive keep theirs. */
+    --kj-button-shadow: none;
+    --kj-button-shadow-hover: none;
+    --kj-button-shadow-active: none;
+    text-decoration: underline;
+    text-underline-offset: 4px;
+  }
+  .kj-button[data-variant="link"]:hover {
+    --kj-button-bg: transparent;
+    --kj-button-fg: color-mix(in oklch, var(--kj-fg-primary), black 8%);
+  }
+
+  /* sizes — heights are explicit so flex parents can't stretch the button.
+     padding-y is kept for the `height: auto` (token-overridden) case and
+     for visual rhythm with content larger than the height. */
+  .kj-button[data-size="xs"] {
+    --kj-button-padding-x: var(--kj-space-sm);
+    --kj-button-padding-y: 0;
+    --kj-button-font-size: 0.75rem;
+    --kj-button-height:    var(--kj-ctl-h-xs);   /*  28px */
+  }
+  .kj-button[data-size="sm"] {
+    --kj-button-padding-x: var(--kj-space-sm);
+    --kj-button-padding-y: 0.25rem;
+    --kj-button-font-size: 0.8125rem;
+    --kj-button-height:    var(--kj-ctl-h-sm);   /*  32px */
+  }
+  .kj-button[data-size="md"] {
+    --kj-button-height:    var(--kj-ctl-h-md);   /*  36px */
+  }
+  .kj-button[data-size="lg"] {
+    --kj-button-padding-x: var(--kj-space-lg);
+    --kj-button-padding-y: 0.625rem;
+    --kj-button-font-size: 1rem;
+    --kj-button-height:    var(--kj-ctl-h-lg);   /*  44px (AAA touch target) */
+  }
+  .kj-button[data-size="xl"] {
+    --kj-button-padding-x: var(--kj-space-2xl);
+    --kj-button-padding-y: 0.875rem;
+    --kj-button-font-size: 1.0625rem;
+    --kj-button-gap:       var(--kj-space-md);
+    --kj-button-height:    var(--kj-ctl-h-xl);   /*  52px */
+  }
+  .kj-button[data-size="icon"] {
+    --kj-button-padding-x: var(--kj-space-sm);
+    --kj-button-padding-y: var(--kj-space-sm);
+    --kj-button-height:    var(--kj-ctl-h-md);
+    aspect-ratio: 1;
+  }
+
+  /* Full-width: spans the parent (flex / block / grid track). */
+  .kj-button[data-full="true"] {
+    width: 100%;
+  }
+
+  /* Default-variant hover (catches the unset-or-`default` case). Specificity
+     here is lower than the variant-specific rules above, so destructive /
+     ghost / outline / link override correctly.
+
+     Themes can retarget the hover surface by setting
+     `--kj-button-bg-hover` (and optionally `--kj-button-fg-hover`) on
+     `[data-theme="X"]`. The fallbacks below preserve the default 8%
+     darken behaviour for any theme that doesn't customise. Defining the
+     defaults via `var(name, fallback)` instead of a `--kj-button-bg-hover:`
+     declaration on `.kj-button` keeps the theme's ancestor declaration
+     winning the cascade (an element-level default would override the
+     inherited value from `[data-theme]`). */
+  .kj-button:hover {
+    --kj-button-bg: var(--kj-button-bg-hover, color-mix(in oklch, var(--kj-bg-primary), black 8%));
+    /* Hover lift — themed via --kj-hover-translate. Bauhaus = -4px,
+       everyone else = -2px (default in :root). */
+    transform: translateY(var(--kj-button-hover-translate, var(--kj-hover-translate, -2px)));
+  }
+  /* fg-hover only applies to the default variant; ghost/outline/link own
+     their hover fg already, and destructive keeps its on-danger fg. */
+  .kj-button[data-variant="default"]:hover {
+    --kj-button-fg: var(--kj-button-fg-hover, var(--kj-fg-on-primary));
+  }
+  /* Shadow application — `default` (primary) variant only. Themes leave
+     `--kj-button-shadow` unset by default; pages opt in by declaring it
+     at their scope (landing hero, docs playground stage). Hover/active
+     fall back to the static shadow so a single declaration is enough. */
+  .kj-button[data-variant="default"] {
+    box-shadow: var(--kj-button-shadow, none);
+  }
+  .kj-button[data-variant="default"]:hover {
+    box-shadow: var(--kj-button-shadow-hover, var(--kj-button-shadow, none));
+  }
+  .kj-button[data-variant="default"]:active {
+    box-shadow: var(--kj-button-shadow-active, var(--kj-button-shadow, none));
+  }
+  .kj-button:active {
+    transform: var(--kj-button-translate-active, none);
+  }
+  .kj-button:focus-visible {
+    outline: 2px solid var(--kj-border-focus);
+    outline-offset: 2px;
+  }
+  .kj-button[aria-disabled="true"] {
+    opacity: 0.45;
+    cursor: not-allowed;
+    pointer-events: none;
+  }
+
+  /* ── Touch target enforcement (WCAG 2.5.5) ─────────────────────────── */
+  /* Icon-only buttons have no inline text affordance, so they need the
+     full 44×44 touch target. The `sm` text variant relies on its label
+     for the equivalent-inline exception and stays visually small. */
+  .kj-button[data-size='icon'] {
+    min-width: 2.75rem;  /* 44px */
+    min-height: 2.75rem; /* 44px */
+  }
+
+  /* ── Busy / loading state ───────────────────────────────────────────── */
+  .kj-button[aria-busy='true'] {
+    /* `opacity` dims the entire button (spinner + bg) uniformly. The
+       previous rule re-pointed --kj-button-fg at --kj-fg-default, which
+       on dark themes is the off-white page text — making the spinner
+       paint white over a yellow primary button. Opacity preserves the
+       variant's resolved fg so the spinner stays the same colour as
+       the would-be label. */
+    opacity: 0.7;
+    cursor: progress;
+  }
+
+  /* ── Pressed (toggle) state ─────────────────────────────────────────── */
+  .kj-button[aria-pressed='true'] {
+    --kj-button-bg: var(--kj-bg-field);
+    box-shadow: inset 0 1px 2px rgb(0 0 0 / 0.12);
+  }
+
+  /* ── Spinner element (placeholder until KjSpinner ships) ─────────────
+     The wrapper hides <ng-content> while loading and renders only this
+     spinner, so it should sit centred in the button (the host already
+     applies `justify-content: var(--kj-button-justify, center)` = center). No
+     trailing margin — there's nothing after it to push away. */
+  .kj-button__spinner {
+    display: inline-block;
+    width: 1em;
+    height: 1em;
+    vertical-align: -0.125em;
+    border: 2px solid currentColor;
+    border-right-color: transparent;
+    border-radius: 50%;
+    animation: kj-button-spinner-rotate 0.6s linear infinite;
+  }
+}
+
+@keyframes kj-button-spinner-rotate {
+  to { transform: rotate(360deg); }
+}

package/src/button-group/button-group.css

@@ -0,0 +1,114 @@
+/* ─────────────────────────────────────────────────────────────
+   .kj-button-group — segmented cluster of <kj-button> children.
+   The wrapper itself is a flex container with no padding/bg of
+   its own; segmented "chunky" feel comes from collapsing the
+   inner borders between adjacent buttons and squaring their
+   touching edges while keeping the group's outer corners
+   rounded.
+   ──────────────────────────────────────────────────────────── */
+
+@layer kj.component {
+  .kj-button-group {
+    --kj-button-group-gap: 0;
+    display: inline-flex;
+    flex-direction: row;
+    align-items: stretch;
+    gap: var(--kj-button-group-gap);
+    border-radius: var(--kj-radius-field);
+    /* Hide pseudo-overflow from collapsed-corner siblings. Children also
+       inherit display:contents semantics from <kj-button>, so the inner
+       <button> is the actual flex item. */
+    isolation: isolate;
+  }
+
+  .kj-button-group[data-orientation='vertical'] {
+    flex-direction: column;
+  }
+
+  /* Each <kj-button> sets `display: contents` on its host (see button.ts);
+     the styled element is the inner `.kj-button`. Squarish inner edges +
+     rounded outer edges fall out of :first-child / :last-child rules on
+     those inner buttons. */
+
+  /* ── Horizontal: collapse left/right radii on middle items ─────────── */
+  .kj-button-group:not([data-orientation='vertical']) > kj-button > .kj-button {
+    border-radius: 0;
+    /* Pull adjacent borders into a single visual line. */
+    margin-left: calc(-1 * var(--kj-border));
+  }
+  .kj-button-group:not([data-orientation='vertical']) > kj-button:first-child > .kj-button {
+    border-top-left-radius: var(--kj-radius-field);
+    border-bottom-left-radius: var(--kj-radius-field);
+    margin-left: 0;
+  }
+  .kj-button-group:not([data-orientation='vertical']) > kj-button:last-child > .kj-button {
+    border-top-right-radius: var(--kj-radius-field);
+    border-bottom-right-radius: var(--kj-radius-field);
+  }
+
+  /* ── Vertical: collapse top/bottom radii on middle items ───────────── */
+  .kj-button-group[data-orientation='vertical'] > kj-button > .kj-button {
+    border-radius: 0;
+    margin-top: calc(-1 * var(--kj-border));
+    width: 100%;
+  }
+  .kj-button-group[data-orientation='vertical'] > kj-button:first-child > .kj-button {
+    border-top-left-radius: var(--kj-radius-field);
+    border-top-right-radius: var(--kj-radius-field);
+    margin-top: 0;
+  }
+  .kj-button-group[data-orientation='vertical'] > kj-button:last-child > .kj-button {
+    border-bottom-left-radius: var(--kj-radius-field);
+    border-bottom-right-radius: var(--kj-radius-field);
+  }
+
+  /* Lift the focused / hovered / pressed button above its neighbours so its
+     border isn't clipped by the negative-margin overlap. */
+  .kj-button-group > kj-button > .kj-button:hover,
+  .kj-button-group > kj-button > .kj-button:focus-visible,
+  .kj-button-group > kj-button > .kj-button[aria-pressed='true'] {
+    z-index: 1;
+  }
+
+  /* ── Segmented: one shared shell, hairline dividers ────────────────
+     With `kjVariant="segmented"` the group — not each button — owns the
+     border and the rounded outer corners, and adjacent segments are parted
+     by a single hairline. The children go borderless (see button.css), so
+     the negative-margin overlap used by the default look is dropped here.
+
+     Typography and the on-state fill come from the `--kj-segmented-*`
+     hooks, set on this host by the consumer. */
+  .kj-button-group[data-variant='segmented'] {
+    border: var(--kj-border) solid var(--kj-segmented-border, var(--kj-border-default));
+    border-radius: var(--kj-radius-field);
+    overflow: hidden;
+  }
+
+  .kj-button-group[data-variant='segmented'] > kj-button > .kj-button {
+    margin-left: 0;
+    margin-top: 0;
+    border-radius: 0;
+  }
+
+  .kj-button-group[data-variant='segmented']:not([data-orientation='vertical'])
+    > kj-button
+    + kj-button
+    > .kj-button {
+    border-left: var(--kj-border) solid var(--kj-segmented-border, var(--kj-border-default));
+  }
+
+  .kj-button-group[data-variant='segmented'][data-orientation='vertical']
+    > kj-button
+    + kj-button
+    > .kj-button {
+    border-top: var(--kj-border) solid var(--kj-segmented-border, var(--kj-border-default));
+  }
+
+  /* Group-level disabled: visually muted when the directive flags it. The
+     individual <kj-button>s still render their own aria-disabled when their
+     own kjDisabled is true; consumers wiring the group context as a fallback
+     will get aria-disabled on every child. */
+  .kj-button-group[data-disabled] {
+    opacity: 0.7;
+  }
+}

package/src/calendar/calendar.css

@@ -0,0 +1,129 @@
+.kj-calendar {
+  display: inline-block;
+  padding: var(--kj-space-sm);
+  /* No chrome of its own — when projected into `.kj-date-picker__panel`
+     (which already paints `bg-elevated` + border + radius + shadow), a
+     duplicate border reads as a hairline ring inside the panel. A
+     stand-alone calendar inherits its parent container's surface. */
+  background: transparent;
+  font-family: inherit;
+  font-size: 0.8125rem;
+  color: var(--kj-fg-default);
+}
+
+.kj-calendar__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--kj-space-xs, 0.25rem);
+  margin-bottom: var(--kj-space-xs, 0.25rem);
+}
+
+.kj-calendar__caption {
+  margin: 0;
+  font-size: 0.8125rem;
+  font-weight: 600;
+  flex: 1;
+  text-align: center;
+}
+
+.kj-calendar__nav {
+  appearance: none;
+  background: transparent;
+  border: var(--kj-border) solid transparent;
+  width: 1.75rem;
+  height: 1.75rem;
+  border-radius: var(--kj-radius-field);
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 0.875rem;
+  color: inherit;
+}
+
+.kj-calendar__nav:hover:not([disabled]) {
+  /* `bg-field` (not `bg-surface`) — guarantees the hover is visible on
+     `bg-elevated` panels where surface and elevated collapse to the same
+     value (light / corporate themes). */
+  background: var(--kj-bg-field);
+}
+
+.kj-calendar__nav[disabled] {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+.kj-calendar__grid {
+  border-collapse: collapse;
+  /* Fixed layout so every column gets the same explicit `2rem` width set
+     on `.kj-calendar__weekday` / `.kj-calendar__cell` regardless of cell
+     content. */
+  width: auto;
+  table-layout: fixed;
+}
+
+/* th/td share the same width contributor (the inner button or label) so
+   weekday headers align perfectly above day cells. `min-width: 2rem` on
+   both keeps the seven columns equal even when a weekday abbreviation is
+   narrower than a 2-digit day. */
+.kj-calendar__weekday {
+  width: 2rem;
+  padding: 0;
+  font-size: 0.6875rem;
+  font-weight: 500;
+  color: var(--kj-fg-muted);
+  text-align: center;
+}
+
+.kj-calendar__cell {
+  width: 2rem;
+  padding: 1px;
+}
+
+.kj-calendar__day {
+  appearance: none;
+  background: transparent;
+  border: var(--kj-border) solid transparent;
+  border-radius: var(--kj-radius-selector);
+  width: 100%;          /* Fill the cell so the button hits-area aligns
+                           with the header column above. */
+  height: 2rem;
+  min-height: 1.75rem;  /* WCAG 2.5.5 AA: ≥ 24×24px */
+  cursor: pointer;
+  font: inherit;
+  font-size: 0.8125rem;
+  color: inherit;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.kj-calendar__day:hover:not([disabled]) {
+  background: var(--kj-bg-field);
+}
+
+.kj-calendar__day:focus-visible {
+  outline: 2px solid var(--kj-border-focus);
+  outline-offset: 2px;
+}
+
+.kj-calendar__day[data-today] {
+  border-color: var(--kj-border-focus);
+  font-weight: 600;
+}
+
+.kj-calendar__day[data-selected] {
+  background: var(--kj-bg-primary);
+  color: var(--kj-fg-on-primary);
+}
+
+.kj-calendar__day[data-outside-month] {
+  opacity: 0.35;
+}
+
+.kj-calendar__day[data-disabled],
+.kj-calendar__day[disabled] {
+  opacity: 0.35;
+  cursor: not-allowed;
+}

package/src/card/card.css

@@ -0,0 +1,120 @@
+/* ─────────────────────────────────────────────────────────────
+   .kj-card — component-layer tokens + structural CSS
+   ──────────────────────────────────────────────────────────── */
+
+@layer kj.component {
+  .kj-card {
+    --kj-card-bg:           var(--kj-bg-surface);
+    --kj-card-fg:           var(--kj-fg-default);
+    --kj-card-border-color: transparent;
+    --kj-card-border-width: var(--kj-border);
+    --kj-card-radius:       var(--kj-radius-box);
+    --kj-card-padding-x:    var(--kj-space-xl);
+    --kj-card-padding-y:    var(--kj-space-xl);
+    --kj-card-shadow:       none;
+
+    display: block;
+    background: var(--kj-card-bg);
+    color: var(--kj-card-fg);
+    border: var(--kj-card-border-width) solid var(--kj-card-border-color);
+    border-radius: var(--kj-card-radius);
+    box-shadow: var(--kj-card-shadow);
+    overflow: hidden;
+    transition: var(--kj-transition);
+  }
+
+  /* When no sub-components are used, fall back to the padded wrapper for plain content. */
+  .kj-card:not(:has(.kj-card-header, .kj-card-content, .kj-card-footer, .kj-card-cover)) {
+    padding: var(--kj-card-padding-y) var(--kj-card-padding-x);
+  }
+
+  .kj-card[data-variant="outline"] {
+    --kj-card-bg: transparent;
+    --kj-card-border-color: var(--kj-border-default);
+  }
+
+  .kj-card[data-variant="subtle"] {
+    --kj-card-bg: var(--kj-bg-field);
+  }
+
+  /* Lift modifier — borrows the theme's button-shadow value so cards in
+     brutalist themes (kouji / bauhaus) get the same hard offset block as
+     primary buttons. Themes without an offset signature fall back to
+     `--kj-shadow-md` so the card still reads as elevated. */
+  .kj-card[data-shadow="lift"] {
+    --kj-card-shadow: var(--kj-button-shadow, var(--kj-shadow-md));
+    --kj-card-border-color: var(--kj-border-default);
+  }
+
+  /* Cover image. Fixed aspect ratio + cover-fit prevents tall hero images
+     from blowing the card. The `--kj-card-cover-height` knob lets a
+     consumer override the height; `--kj-card-cover-fit` swaps cover/contain. */
+  .kj-card-cover {
+    --kj-card-cover-height: 12rem;
+    --kj-card-cover-fit:    cover;
+
+    display: block;
+    height: var(--kj-card-cover-height);
+    background: var(--kj-bg-field);
+    overflow: hidden;
+  }
+  .kj-card-cover img,
+  .kj-card-cover video {
+    width: 100%;
+    height: 100%;
+    display: block;
+    object-fit: var(--kj-card-cover-fit);
+    object-position: center;
+  }
+  /* Per-instance override via [data-fit]. */
+  .kj-card-cover[data-fit="contain"] { --kj-card-cover-fit: contain; }
+  .kj-card-cover[data-fit="cover"]   { --kj-card-cover-fit: cover; }
+  .kj-card-cover[data-size="sm"] { --kj-card-cover-height: 8rem; }
+  .kj-card-cover[data-size="lg"] { --kj-card-cover-height: 16rem; }
+
+  /* Header */
+  .kj-card-header {
+    display: flex;
+    flex-direction: column;
+    gap: var(--kj-space-xs, 0.25rem);
+    padding: var(--kj-card-padding-y) var(--kj-card-padding-x);
+  }
+
+  /* Title */
+  .kj-card-title {
+    font: 600 1rem / 1.3 var(--kj-font-sans);
+    margin: 0;
+    color: var(--kj-fg-default);
+  }
+
+  /* Subtitle */
+  .kj-card-subtitle {
+    font: 0.875rem / 1.4 var(--kj-font-sans);
+    color: var(--kj-fg-default);
+    opacity: 0.6;
+    margin: 0;
+  }
+
+  /* Content */
+  .kj-card-content {
+    display: block;
+    color: var(--kj-fg-default);
+    font: 0.9375rem / 1.5 var(--kj-font-sans);
+  }
+  .kj-card-content[data-padded] {
+    padding: var(--kj-card-padding-y) var(--kj-card-padding-x);
+  }
+
+  /* Footer */
+  .kj-card-footer {
+    display: flex;
+    align-items: center;
+    gap: var(--kj-space-sm);
+    padding: var(--kj-card-padding-y) var(--kj-card-padding-x);
+    border-top: var(--kj-border) solid var(--kj-border-default);
+  }
+  .kj-card-footer[data-align="start"]   { justify-content: flex-start; }
+  .kj-card-footer[data-align="center"]  { justify-content: center; }
+  .kj-card-footer[data-align="end"]     { justify-content: flex-end; }
+  .kj-card-footer[data-align="between"] { justify-content: space-between; }
+}