# lib-theme-oat

A warm greige, cozy-neutral theme for everyday consumer utilities — personal-cloud dashboards, settings, inboxes, calm product surfaces. Oat, driftwood, mushroom, raw linen. A genuinely neutral grey-warm field (not a pale near-white, not a drenched color), warm charcoal-taupe ink, and a soft muted clay-rose coral accent spent surgically. Warm-humanist type: Fraunces headings over Hanken Grotesk body.

## Design philosophy

- **Surface treatment:** Depth through restraint. The body field is a real greige mid-tone (L≈0.91, C≈0.009, hue ~78) that sits noticeably below cream lightness, so it reads as soft grey-warm "oat" rather than a bright cream/parchment band. Cards step **up** to a warm near-white (L≈0.975) — the visible card-on-field lightness step is the theme's premium tell and does hierarchy work before the shadow does. No glass, no brutalist offsets.
- **Color:** Warm neutrals (hue ~55–78) anchor everything. Primary is a muted clay-rose coral (L≈0.55, C≈0.15, H≈35), deep enough that warm-white text clears 4.5:1 — used ≤10% on the primary action, selection and focus. One cool counterpoint: a muted slate-blue `info`. Status quartet (destructive hotter true-red, sage `success`, amber `warning`, slate `info`) stays clearly distinct from the coral.
- **Typography:** Fraunces (soft humanist serif, low optical size) for headings — cozy, not editorial-shouty. Hanken Grotesk for body and UI. JetBrains Mono for code. Product register: fixed rem sizes, full `hero → caption` ramp, body 1.0625rem at 1.65 line-height.
- **Motion:** Calm-buoyant. 160 / 300 / 450ms durations; emphasized moments settle on a gently damped real spring (`spring-gentle`), the other springs available for playful affordances.
- **Elevation:** Soft warm-grey diffuse shadows derived from the warm ink at low alpha — tactile, gentle, never a hard drop.
- **Radius:** 1rem — soft-friendly.
- **Borders:** Hairline (1px, alpha 0.14 of ink) so they frame without weight.

## Usage

In a consuming app's `app.css`:

```css
@import "../../lib-theme-oat/theme.css";
```

## Dark mode

Supported — "oats at night". A warm dark taupe-charcoal (L≈0.20, low chroma, hue ~70), deep but not pure black and never blue-gray. Cards step **lighter** (firelight-on-material logic), the coral brightens to L≈0.68 with dark-ink-on-bright foregrounds per the contrast contract, and shadows deepen.

## Font dependency

Load the fonts from the consuming app's entry CSS (top of the file, where `@import` is allowed):

```
https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..40,400;9..40,500;9..40,600&family=Hanken+Grotesk:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap
```

Or via Fontsource:

```bash
npm install @fontsource-variable/fraunces @fontsource-variable/hanken-grotesk @fontsource-variable/jetbrains-mono
```

Fraunces is loaded with a low `opsz` (optical-size) axis so headings stay soft and humanist rather than high-contrast editorial.