# Inkwash

A hand-drawn, watercolor-textured design system — as complete as a mainstream UI kit, but every
surface looks painted and every icon looks inked with a felt-tip marker. **CSS-first and
framework-agnostic**, with an optional typed **React** package. Four painterly themes: **Walk,
Rain, Fire,** and **Dark Forest**.

> **Status:** v0.1.0 — usable today. 60+ components, 288 hand-drawn icons, a token pipeline, a
> React package, and machine-readable specs for AI codegen.

<p align="center"><em>Open <code>index.html</code> for the live showcase.</em></p>

## Quick start

**1. Drop in the stylesheet (no build step):**

```html
<link rel="stylesheet" href="css/watercolor.css">
<body class="wc">
  <button class="wc-btn">Get started</button>
  <div class="wc-card wc-sketch">A painted card</div>
</body>
```

> The `wc-` prefix is Inkwash's **w**ater**c**olor-wash engine — kept stable so class names,
> tokens (`--wc-*`), and existing integrations never break across releases.

**2. Theme it** — add one class to any container:

| Theme | Class |
|-------|-------|
| Walk (default, warm daylight) | *(none)* |
| Rain | `class="wc-rain"` |
| Fire | `class="wc-fire"` |
| Dark Forest | `class="wc-forest"` |

**3. (Optional) progressive-enhancement JS** for the interactive pieces:

```html
<script src="js/watercolor.js"></script>
<script>WC.init();</script>  <!-- wires modals, tabs, toasts, data grids, charts, date pickers… -->
```

### React

```bash
npm i @inkwash/react
```

```tsx
import { ThemeProvider, Button, Card, DataGrid } from '@inkwash/react';
// the React package renders the .wc-* markup — include the core stylesheet once:
//   <link rel="stylesheet" href="watercolor.css">   (from the CSS kit)

export default () => (
  <ThemeProvider theme="forest">
    <Card sketch><Button>Get started</Button></Card>
  </ThemeProvider>
);
```

Components accept an `sx` prop (MUI-style shorthand) and the library ships full TypeScript types.

## What's inside

- **Design tokens** — `tokens/tokens.json` (W3C Design Tokens) compile to `--wc-*` CSS variables,
  SCSS, a JS module, and a Tailwind preset via `scripts/build-tokens.mjs`. Color, type, space,
  radius, elevation, and motion, per theme.
- **Hand-drawn engine** — `.wc-sketch` paints a wobbly ink border on a filtered pseudo-element
  (SVG `feTurbulence` + `feDisplacementMap`) so text stays crisp; `.wc-paper-tex` adds paper grain;
  organic asymmetric `border-radius` throughout.
- **60+ components** — buttons, cards, the full form set, feedback (alerts with 5 semantic levels,
  toasts, progress, skeletons), navigation (tabs, app bar, bottom nav, drawer, menubar, breadcrumbs,
  pagination), overlays (modal, popover, tooltip, speed dial), **data grid** (sort / filter /
  paginate / select), **charts** (bar / line / pie / donut / sparkline), date & time pickers,
  transfer list, autocomplete, stepper, timeline, and more. Full list in `registry.json`.
- **288 felt-pen icons** — Feather geometry re-inked into filled, variable-width marker strokes
  (`scripts/build-icons.mjs`), served as a symbol sprite and themed via `currentColor`. Downloadable
  as a full pack (SVG / PNG / PDF) — see below.
- **React package** — `packages/react/`, typed components, `ThemeProvider` + `useTheme`, `sx` shim,
  built with tsup (ESM + CJS + `.d.ts`), tested with Vitest + Testing Library.

## Icon pack

Every icon is downloadable in the formats designers actually use. Build it with:

```bash
node scripts/build-icon-pack.mjs && bash scripts/build-icon-pack.sh   # needs librsvg
```

Produces `icons/watercolor-icons.zip` containing individual **SVG** (recolorable `currentColor` +
pre-inked), **PNG** at 24/48/96/256, vector **PDF**, the **sprite**, JSON manifests, and a browsable
cheat-sheet. The "Download all icons" button on the showcase links to it.

## Built for AI

Inkwash ships machine-readable specs so an assistant (or codegen tool) emits correct markup:

- **`llms.txt`** — a concise, LLM-oriented map: setup, the rules for valid markup, and every
  component's class + minimal usage. Point your assistant here first.
- **`registry.json`** — the full spec: each component's base class, variants, states, parts,
  accessibility notes, and a copy-paste example. Designed to power a future
  `npx inkwash add <component>` CLI / MCP server.
- **`tokens/tokens.json`** — the W3C tokens the whole system derives from.

> Prompt an assistant with: *"Use Inkwash. Read llms.txt and only use `.wc-*` classes."*

## Accessibility

Every interactive component ships a visible `:focus-visible` ring, roving-tabindex/arrow-key
navigation where appropriate (tabs, menus), focus-trap + focus-return on modal and drawer, and ARIA
roles/state. Text meets **WCAG AA** contrast in all four themes (audited with axe). Motion respects
`prefers-reduced-motion`.

## Browser support

Modern evergreen browsers (Chrome / Edge / Firefox / Safari, ~2023+). Uses `color-mix()`,
`backdrop-filter` (with `-webkit-` prefixes), CSS custom properties, and the native `[popover]`
API. Graceful degradation: SVG-filter borders fall back to clean straight borders; `backdrop-filter`
falls back to the solid token color.

## Repository layout

```
css/watercolor.css        the library (all components + themes)
js/watercolor.js          optional progressive-enhancement JS (WC.init, WC.toast, …)
tokens/                   W3C design tokens + build outputs
icons/                    sprite.svg, manifests, downloadable pack
packages/react/           typed React package (@inkwash/react)
scripts/                  build-icons, build-icon-pack, build-tokens, validate
registry.json, llms.txt   machine-readable specs for AI
index.html                the showcase / docs
```

## Scripts

```bash
node scripts/build-tokens.mjs      # tokens.json → CSS/SCSS/JS/Tailwind
node scripts/build-icons.mjs       # re-ink the icon sprite
node scripts/validate.mjs          # sanity-check tokens/registry/icons wiring
cd packages/react && npm run ci    # typecheck + build + test the React package
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). In short: components are authored CSS-first in
`css/watercolor.css`, registered in `registry.json` and `llms.txt`, demoed in `index.html`, and
(if interactive) typed into the React package. Run `node scripts/validate.mjs` before opening a PR.

## License

[MIT](LICENSE) © Lance Essner. Icons derive from [Feather Icons](https://feathericons.com) (MIT).
