# Inkwash

> A hand-drawn, watercolor-textured CSS component library with four themes (walk / rain / fire / dark-forest). Framework-agnostic, CSS-first. Use this file to generate correct Inkwash markup; see registry.json for the full machine-readable spec.

## Setup
- Include the stylesheet: `<link rel="stylesheet" href="css/watercolor.css">`
- Optional interactivity (modal, toast, tabs, rating): `<script src="js/watercolor.js"></script>` (exposes `window.WC`)
- Put `class="wc"` on the app root so components inherit fonts and tokens.
- Dark theme: add `class="wc-forest"` to any subtree.

## Rules for generating markup
- Only use the `.wc-*` classes below. Do not invent class names. (The `wc-` prefix is Inkwash's watercolor-wash engine — the stable API surface.)
- Use native semantic elements: `<button>`, `<dialog>`, `<details>`, `<input>`, `<table>`, `<nav>`.
- Never hardcode colors/sizes — everything derives from `--wc-*` tokens (see tokens/tokens.json). To restyle, override tokens, don't add hex.
- Hand-drawn border: add `class="wc-sketch"` (draws a wobbly ink outline on a filtered ::before; text stays crisp). Paper grain: `class="wc-paper-tex"`.
- Accessibility is required: icon-only buttons need `aria-label`; tablists use `role="tablist"`/`role="tab"`+`aria-selected`; pagination/breadcrumbs wrap in `<nav aria-label>`; alerts that appear dynamically use `role="alert"`/`role="status"`; never remove focus rings.

## Components (class → minimal usage)
- Button — `wc-btn` (+`wc-btn--secondary|--outline|--ghost|--danger`, +`wc-btn--sm|--lg|--icon`): `<button class="wc-btn">Go</button>`
- Card — `wc-card` (+`wc-sketch`,+`wc-paper-tex`; parts `wc-card__title|__body|__foot`)
- Field — `wc-field` wrapping `wc-label`(+`.wc-req`), a control, `wc-hint`/`wc-error`
- Input/Textarea/Select — `wc-input` / `wc-textarea` / `wc-select` (add `is-invalid` on error)
- Checkbox/Radio/Switch — `wc-check` / `wc-check wc-check--radio` / `wc-switch` (real native input inside the label)
- Badge/Chip/Tag — `wc-badge` / `wc-chip`(+`wc-sketch`) / `wc-tag`(+`wc-tag__x` remove button)
- Alert — `wc-alert wc-alert--{critical|warning|caution|info|tip}` (parts `wc-alert__title|__body`)
- Tooltip — `wc-tip-wrap` > trigger + `wc-tip` (placement: `wc-tip--bottom|--left|--right`; default top)
- Toast — JS: `WC.toast('msg', { variant:'critical|warning|caution|info|tip|primary', action:{ label, onClick } })`. Frosted-glass surface; variant tints the border. Tabs/menus have arrow-key nav; modal + drawer trap focus and restore it on close.
- Confirm dialog (pattern) — .wc-modal + centered icon/title/body + .wc-modal__foot with ghost + danger buttons; open via data-wc-open.
- Slider fill — WC.init syncs the painted track (--_fill) with the value automatically.
- Toast icons — WC.toast adds a semantic felt-pen icon per variant (set window.WC_SPRITE if the sprite isn't inlined).
- Kbd — `<span class="wc-kbd">K</span>` (pressed-key chip).
- Divider (labeled) — `<div class="wc-divider--label" role="separator">or</div>`.
- Quote/Callout — `<blockquote class="wc-quote">…<span class="wc-quote__by">— name</span></blockquote>`.
- Upload — `<label class="wc-upload"><input type="file">…</label>` (dashed dropzone; add .is-drag on dragover).
- OTP — `<div class="wc-otp" role="group" aria-label="Code">` of single-char `.wc-input` cells (maxlength=1, inputmode=numeric, per-cell aria-label).
- Tree — `<div class="wc-tree">` of nested `<details><summary>` + `.wc-tree__leaf` rows (CSS-only).
- Badge (overlay) — `<span class="wc-badge-anchor">…<span class="wc-badge--count">3</span></span>` or `.wc-badge--dot`.
- Icon — `<svg class="wc-icon" aria-hidden="true"><use href="icons/sprite.svg#wc-i-NAME"/></svg>` (288 felt-pen icons; filled variable-width marker strokes, fills currentColor; `wc-icon--sm|--lg`; names in icons/names.json). Icon-only controls still need `aria-label`.
- Progress/Spinner/Skeleton — `wc-progress`>`wc-progress__bar` / `wc-spinner` / `wc-skel`(+`--text|--title|--avatar`)
- Empty state — `wc-empty` > `wc-empty__art` + `wc-empty__title`
- Rating — `wc-rating` > `.star`(`.on`)
- Modal — `<dialog class="wc-modal">` + trigger `data-wc-open="#id"`, close `data-wc-close` (needs JS)
- Menu (dropdown) — `<details class="wc-menu">` > `summary` + `wc-menu__list`>`wc-menu__item`(`wc-menu__sep`)
- Accordion — `wc-accordion` > `<details class="wc-accordion__item">` > `summary` + `wc-accordion__body`
- Tabs — segmented `wc-tabs`>`wc-tab` · underline `wc-utabs`>`wc-utab` (both use `aria-selected`)
- Table — `wc-table`
- Avatar — `wc-avatar` (+`wc-avatar--sm|--lg`, `wc-avatar-group`)
- Presence — `<span class="wc-presence wc-presence--online|--away|--busy|--offline"><span class="wc-avatar">…</span><span class="wc-presence__dot"></span></span>` (online pulses green; also convey status in text)
- Pagination — `wc-pagination`>`wc-page`(`aria-current="page"`)
- Breadcrumbs — `wc-breadcrumb`>`a`+`.sep`+`[aria-current="page"]`
- Search/Slider — `wc-search`>svg+`wc-input` · `<input class="wc-slider" type="range">`
- Divider — `<hr class="wc-divider">`
- Button group — `wc-btn-group` wrapping `wc-btn`s · Toggle group — `wc-toggle-group`>`wc-toggle-btn`(`aria-pressed`)
- FAB — `<button class="wc-fab">` · App bar — `wc-appbar`(>`wc-appbar__brand`) · Link — `<a class="wc-link">` · Surface — `wc-surface`
- List — `wc-list`>`wc-list-item`(`aria-selected`, optional `wc-list-ic`) · Stepper — `wc-stepper`>`wc-step`(`.is-active`/`.is-done`)>`wc-step__dot`+`wc-step__bar`
- Layout — Container `wc-container`(+`--sm/--lg`) · Stack `wc-stack`(+`--row`,`--1…6`) · Grid `wc-grid`(+`--2/3/4`) · Image List `wc-imagelist` · Masonry `wc-masonry`
- Typography utils — `wc-display` `wc-h1` `wc-h2` `wc-h3` `wc-body`(+`--sm`) `wc-caption` `wc-overline` `wc-hand`
- Backdrop — `wc-backdrop`(`.is-open`) · Bottom nav — `wc-bottomnav`>`wc-bottomnav__item`(`aria-current="page"`, `.ic`)
- Drawer — `<aside class="wc-drawer">` + trigger `data-wc-drawer-open="#id"`, close `data-wc-drawer-close` (JS) · Speed dial — `wc-speeddial`>`wc-speeddial__actions`>`wc-speeddial__action` + `wc-fab`
- Menubar — `wc-menubar`>`wc-menu`(details) · Timeline — `wc-timeline`>`wc-timeline__item`>`wc-timeline__dot`+`__time`+`__title`
- Number field — `wc-numfield`>`wc-numfield__btn`(`data-step="up|down"`)+`input[type=number]` (JS) · Popover — native `[popover]` + `.wc-popover`, anchor via `popovertarget`
- Autocomplete — `wc-autocomplete`>input+`wc-autocomplete__list`>`wc-autocomplete__opt` (JS, combobox a11y) · Transfer list — `wc-transfer`>`wc-transfer__col`+`wc-transfer__mid`>`[data-wc-transfer="right|left"]` (JS)
- Chart — `<div class="wc-chart" data-chart="bar|line|pie|donut|sparkline" data-values="4,8,15" data-labels="A,B,C" aria-label="…"></div>` (JS renders themed SVG)
- Data grid — `<table class="wc-table wc-datagrid" data-select data-page-size="10" data-filter="#f">` with `<th data-sort>` headers (JS adds sort/filter/paginate/select)
- Calendar / date picker — `<div class="wc-calendar" data-wc-calendar data-value="YYYY-MM-DD"></div>` (JS renders month, nav, selection; fires `wc:datechange`)
- Date field — `<span class="wc-datefield"><input class="wc-input" type="text" readonly><button class="wc-datefield__btn" aria-label="Open calendar"></button></span>` (JS opens a calendar popover)
- Time field — `<span class="wc-timefield" data-start="08:00" data-end="20:00" data-step="30"><input class="wc-input" type="text" readonly><button class="wc-timefield__btn" aria-label="Open time list"></button></span>` (JS builds slot menu)
- Growth Mode (signature effect) — themed foliage grows from behind an element on hover. Wrap any element: `<span class="wc-grow" data-grow="3"><button class="wc-btn">…</button></span>`. Each theme has its own foliage set (paper=light flora, forest=dark mushrooms); the optional JS injects the right one. Decorative + reduced-motion aware.

## Resources
- registry.json — full component spec (variants, states, parts, a11y, examples) for programmatic use.
- icons/sprite.svg + icons/names.json + icons/icons.json — 288 hand-drawn icons (symbol ids: wc-i-<name>).
- tokens/tokens.json — W3C design tokens (color, type, space, radius, elevation, motion; default + forest themes).
- css/watercolor.css — the stylesheet. js/watercolor.js — optional enhancements.
- index.html — the live docs/showcase.