# Farn
> Token-first CSS design system for the web. Palette tokens, semantic tokens, and opt-in component classes. Zero framework assumptions — opt-in JavaScript available for nav and tab components.
## Install
```
npm install farn-theme
```
Then import in your bundler (Vite, webpack, Parcel, etc.):
```css
@import "farn-theme"; /* full bundle: tokens + base reset */
@import "farn-theme/tokens"; /* tokens only — no reset */
@import "farn-theme/components"; /* opt-in: nav, footer, buttons, cards, forms, badges, accordion… */
@import "farn-theme/typography"; /* opt-in: .text-h1, .text-body, .text-mono… */
@import "farn-theme/layout"; /* opt-in: .container, .stack, .cluster, .center, .auto-grid, .sidebar, .grid-2, .grid-3 */
```
Or link from CDN (replace `@0.7.0` with the latest tag):
```html
```
### Optional JavaScript
Two opt-in scripts ship alongside the CSS:
```js
import 'farn-theme/scripts/nav'; /* nav: theme toggle, mobile drawer, scroll fill/autohide */
import 'farn-theme/scripts/tabs'; /* tab component progressive enhancement */
```
`nav.js` is required for `.nav-theme-toggle`, mobile drawer open/close, and the
`data-nav-fill` / `data-nav-autohide` scroll behaviors. The `.nav` CSS classes render
correctly without it — the nav appears filled and the drawer is hidden.
## Core rules
- **Token hierarchy**: always reference semantic tokens (`--color-*`, `--space-*`, `--text-*`, `--font-*`, `--radius-*`). Never use raw palette tokens (`--in*`, `--bm*`, `--fo*`, `--bl*`) in component or page styles.
- **Fraunces headings**: every Fraunces usage must include `font-variation-settings: 'opsz' ` — the font renders incorrectly without it. Use `72` for display/`h1`, `24` for `h2`, `20` for `h3` and pullquotes.
- **Dark / light mode**: set `data-theme="dark"` or `data-theme="light"` on ``. Toggle via JavaScript and persist to `localStorage` under the key `farn-theme`.
- **Surface depth**: use `data-surface="base|layer|overlay|featured"` on any element to set depth context. All children inherit re-scoped tokens automatically — `base` is page-level, `layer` is cards/panels, `overlay` is modals/dropdowns, `featured` provides maximum contrast against the page (void in light mode, mist in dark mode — use for hero/brand sections).
- **Combine theme + surface**: `` renders a dark panel regardless of the page theme. `featured` is self-contained — do not also set `data-theme="dark"` on the same element.
- **FOWT prevention**: add an inline `
```
## Sample system prompt
```
This project uses the Farn design system.
- Use semantic tokens (--color-*, --space-*, --text-*), never palette tokens (--in*, --bm*, --fo*, --bl*)
- Every Fraunces heading: font-variation-settings: 'opsz'
- data-theme="dark|light" on , data-surface="base|layer|overlay" on elements
Full reference: https://farn.jbpt.de/llms.txt
```
## Templates
Copy-paste page sections assembled into complete layouts. All blocks use only Farn semantic tokens — no hardcoded values.
### Concept
Three levels: **Template** (complete page layout) → **Block** (named page section) → **Component** (Farn atoms like `.btn`, `.card`).
A template is a sequence of named blocks. A block combines layout HTML with Farn tokens and components. Block CSS class names (`.hero`, `.features`, etc.) are copy-paste starters — rename them to fit your project; they are not part of Farn's stable API.
**Strict rule:** every block uses only Farn semantic tokens (`--color-*`, `--space-*`, `--text-*`, `--font-*`, `--radius-*`). No hardcoded values.
### Landing Page template
Four blocks in assembly order:
| Block | Surface | Description |
|---|---|---|
| Hero | base | Full-page intro: eyebrow, display headline, body copy, primary + secondary CTA buttons |
| Intro | featured | Two-column text + visual. Left: eyebrow, heading, body, CTA. Right: open slot for image or illustration. Collapses to 1 col on mobile. |
| Features | base | Auto-fit card grid: icon, heading, short description per card. Uses `.card` component. |
| CTA | featured | Closing section: eyebrow, display headline with italic accent, body, action buttons. Constrained to prose width. |
Reference: [Templates](https://farn.jbpt.de/templates) — [Landing Page](https://farn.jbpt.de/templates/landing-page)
## Reference
- [Getting Started](https://farn.jbpt.de/getting-started) — install, load order, FOWT, theming, minimal example
- [Foundations](https://farn.jbpt.de/foundations) — design decisions, accessibility commitment, responsive approach
- [Surfaces & theming](https://farn.jbpt.de/foundations/surfaces) — full data-theme / data-surface reference with live examples (base / layer / overlay / featured)
- [Color tokens](https://farn.jbpt.de/styles/color) — palette + semantic token tables, WCAG contrast matrix
- [Typography](https://farn.jbpt.de/styles/typography) — type scale, Fraunces opsz guidance, utility class reference
- [Spacing](https://farn.jbpt.de/styles/spacing) — space scale, layout widths, border radius, z-index
- [Motion](https://farn.jbpt.de/styles/motion) — duration + easing token reference
- [Components › Actions](https://farn.jbpt.de/components/actions) — buttons (`.btn`, `.btn-p`, `.btn-s`, `.btn-g`, `.btn-d`) + links
- [Components › Layout](https://farn.jbpt.de/components/layout) — cards, section transitions, quotes, separators, footer
- [Components › Navigation](https://farn.jbpt.de/components/navigation) — nav, breadcrumbs, accordion, pagination, tabs
- [Components › Forms](https://farn.jbpt.de/components/forms) — inputs, textarea, select, labels, error states
- [Components › Data](https://farn.jbpt.de/components/data) — badges (7 variants), tables, code blocks, tooltips
- [Components › Status](https://farn.jbpt.de/components/status) — spinner, skeleton loader