# cards.css — portfolio card primitive

One CSS file with three variants for every card pattern in the portfolio.
Hosted at `https://assets.gf.cx/cards/cards.css`.

## Import

```html
<link rel="stylesheet" href="https://assets.gf.cx/cards/cards.css">
```

## The three variants

### `.card--system` — thumb + body

For top-level landings (pa.gf.cx, contractors, equipment) where each card
introduces a system / subject with a photo + headline + sub + status + last-touch.

```html
<div class="card-grid">

  <a class="card card--system" href="/foo/">
    <div class="card__thumb">
      <img src="/foo/photo.jpg" alt="Full descriptive sentence per SEO-rewrite pattern">
    </div>
    <div class="card__body">
      <h2 class="card__title">Foo <em>Bar</em> Subsystem</h2>
      <p class="card__sub">Make / model / serial · purchased Jun 2020</p>
      <span class="card__status">In service</span>
      <p class="card__last">Last touched 24 May 2026 · steward action TBD</p>
    </div>
  </a>

</div>
```

Empty / placeholder thumb variant:

```html
<a class="card card--system card--placeholder">
  <div class="card__thumb card__thumb--empty">Photo awaited</div>
  <div class="card__body">…</div>
</a>
```

### `.card--stat` — label + big value + sub

For status dashboards, savings rollups, enrichment-preview pages — anywhere
you're surfacing one number per tile.

```html
<div class="card-grid card-grid--narrow">

  <div class="card card--stat">
    <div class="card__label">Completed</div>
    <div class="card__value">5,669</div>
    <div class="card__sub">of 5,669</div>
    <div class="card__bar"><div class="card__bar-fill" style="width:100%"></div></div>
  </div>

  <div class="card card--stat">
    <div class="card__label">Date span covered</div>
    <div class="card__value">2022-2025</div>
    <div class="card__sub">Jul 2022 → Nov 2025 · 4 years</div>
  </div>

</div>
```

### `.card--tile` — compact title + meta

For category landings, year breakdowns, dense lists where each tile is mostly
text with a single $ / count line.

```html
<div class="card-grid">

  <a class="card card--tile" href="/amazon/tags/brand-apple.html">
    <h3 class="card__title">Apple</h3>
    <p class="card__meta">$19,613 · 294 items</p>
    <span class="card__count">brand</span>
  </a>

</div>
```

## Theming

`cards.css` reads CSS custom properties from `:root` with sensible defaults.
If your page already defines the portfolio palette (`--bg-card`, `--accent`,
`--line-strong`, etc.), `cards.css` picks those up automatically. Otherwise the
defaults take over.

To theme per-page:

```css
:root {
  --card-accent: #b85c00;   /* override accent on this surface */
  --card-grid-min: 200px;   /* tighter grid */
}
```

## Kicker numbering — singleton vs. siblings

The small uppercase `kicker` line above the card title (`.card__label`,
`.stack-card__kicker`, or equivalent) signals the card's category. **Drop
the trailing `· N` count when there is only one card of that category in
the grid.** The numbering only earns its place when 2+ siblings need
disambiguating.

```html
<!-- Singleton — bare category, no count -->
<div class="stack-card__kicker">Filtration</div>

<!-- Two-or-more siblings — disambiguate with a qualifier (preferred) -->
<div class="stack-card__kicker">Consumable · chlorine</div>
<div class="stack-card__kicker">Consumable · pH down</div>

<!-- Two-or-more siblings, no natural qualifier — fall back to · N -->
<div class="stack-card__kicker">Source · 1</div>
<div class="stack-card__kicker">Source · 2</div>
```

Captured in memory `feedback_kicker_no_singleton_numbering_2026-05-26.md`.
The rule applies to any kicker on any card variant in this library and on
sibling stack-grid implementations (e.g. `pa/well-water/`, `pa/pool/`).

## Hover behavior

Anchor-cards shift their border to `--card-accent` on hover. No transform —
the 1px shift was flagged as jarring on portfolio surfaces (`feedback`
captured 2026-05-21). To opt-in for hover on non-anchor cards, add
`.card--hoverable`.

Thumb images on `.card--system` start grayscale-with-contrast and restore color
on hover — the portfolio's grayscale-thumb pattern baked in.

## Print

Cards flatten to bordered boxes with no background, and thumb images preserve
grayscale. `page-break-inside: avoid` on each card.

## Cross-references

- `feedback_grayscale_thumb_hover_pattern.md` — the grayscale-on-hover gesture, baked into `.card--system`
- `feedback_micro_gestures_pattern.md` — sibling pattern library
- `feedback_seo_rewrite_for_dropped_images.md` — alt-text discipline for `card__thumb img`
- `parked_sketch_cards_primitive_2026-05-24.md` — design memo, now implemented
- `feedback_kicker_no_singleton_numbering_2026-05-26.md` — the rule above; drop `· 1` for singletons, keep numbering or qualifier only when 2+ siblings need disambiguating

## Version

v0.1.0 · 2026-05-24 · first shipped at https://assets.gf.cx/cards/cards.css