# Kutby Cards System

**Status:** Visual foundation (Phase 1)  
**Version:** 2.9.0  

**This is not a Layout Engine.** Cards are a reusable visual system for every post preview in Kutby.

**Related:** `DESIGN_SYSTEM.md`, `HEADER-ENGINE.md`, `FOOTER-ENGINE.md`, `HERO-ENGINE.md`

---

## 1. Philosophy

1. **One visual language** — archives, homepage sections, related posts, and future Hero migrations consume the same cards.
2. **Composition over duplication** — variants assemble Parts; Parts never know variant names.
3. **Tokens only** — radius, padding, shadow, color, type, motion from Design Tokens (+ Theme Options `cards` group).
4. **Content first** — hierarchy: image → category → title → meta → excerpt → action.
5. **Premium calm** — whitespace, clear type scale, subtle hover — no noisy chrome.

---

## 2. Variants

| Id | Use |
|----|-----|
| `editorial` | Large image, badge, large title, meta, excerpt, read more |
| `compact` | Small square thumb + title + meta (lists / sidebars) |
| `horizontal` | Image + content row (stacks on small screens) |
| `grid` | Standard grid tile (image, badge, title, meta) |
| `featured` | Full-bleed media, overlay + gradient, display title |

---

## 3. Parts (components)

`Thumbnail`, `CategoryBadge`, `Title`, `Meta`, `Excerpt`, `Author`, `Date`, `ReadingTime`, `ReadMore`, `Bookmark`, `Overlay`, `Gradient`

All implement `CardPartInterface` and read visibility from `CardContext`.

---

## 4. Usage

```php
use Kutby\Cards\Card;

Card::render( 'grid', get_post(), array(
    'ratio'         => '16x9',
    'show_excerpt'  => false,
    'lazy'          => true,
) );

Card::render( 'editorial', $post_id, array(
    'heading'       => 'h2',
    'show_reading_time' => true,
) );
```

Register a custom variant:

```php
add_action( 'kutby_cards_register_variants', function ( \Kutby\Cards\Services\CardRegistry $r ) {
    $r->add( 'course', \MyPlugin\CourseCard::class );
});
```

---

## 5. Design rules

- Prefer `kutby-card--*` modifiers; do not invent parallel `.post-box` styles.
- Image ratios: `16x9` | `4x3` | `1x1` | `auto` via `CardContext` + `.kutby-card__media--*`.
- Featured media uses Overlay + Gradient Parts — not ad-hoc CSS colors.
- Theme Options `cards.radius|padding|shadow` map to `--kutby-card-*` via `CardsModule`.

---

## 6. Accessibility

- Semantic `<article>` + heading hierarchy via `heading` arg.
- Title is the primary accessible name; media link is `tabindex="-1"` + `aria-hidden` to avoid duplicate tab stops.
- Read more includes visually hidden title context.
- Focus-visible rings use `--kutby-focus-ring`.
- Bookmark is a real `<button>` with `aria-pressed` (persistence later).

---

## 7. Performance

- No queries inside Parts — caller supplies `WP_Post`.
- Lazy-load thumbs by default; editorial/featured can pass `lazy => false`.
- Shared Parts prevent markup forks across templates.

---

## 8. Migration note (Hero)

Hero currently has its own article components. Future hardening may swap Hero cards to `Kutby\Cards\Card` — **out of Phase 1 scope**; do not redesign Hero in this sprint.
