# Contributing to Inkwash

Thanks for helping paint the web by hand. This guide covers how the pieces fit together so a change
lands consistently across the CSS library, the docs, the AI specs, and the React package.

## Principles

1. **CSS-first.** Every component must work with just `css/watercolor.css` and semantic HTML. JS is
   progressive enhancement only — never required for a component to render or be accessible.
2. **Hand-drawn, not skeuomorphic.** Reach for the existing primitives: `.wc-sketch` (wobbly ink
   border), `--wc-*` tokens, organic asymmetric `border-radius`, felt-pen icons. Don't hard-code
   colors — use tokens so all four themes follow.
3. **Accessible by default.** Visible `:focus-visible`, correct roles/ARIA, keyboard operable, and
   WCAG AA contrast in every theme.

## Project layout

| Path | What it is |
|------|-----------|
| `css/watercolor.css` | The library — all components and the four themes |
| `js/watercolor.js` | Optional enhancement (`WC.init`, `WC.toast`, grids, charts, pickers) |
| `tokens/tokens.json` | Source of truth for design tokens (W3C format) |
| `icons/` | `sprite.svg`, manifests, and the downloadable pack |
| `packages/react/` | Typed React package (`@inkwash/react`) |
| `registry.json`, `llms.txt` | Machine-readable specs consumed by AI tools |
| `index.html` | The showcase / docs |
| `scripts/` | Build + validate scripts |

## Adding or changing a component

1. **Style it** in `css/watercolor.css` under the right section, using tokens and the `.wc-` prefix.
2. **Demo it** in `index.html` in the section that matches its *type* (Forms, Feedback, Navigation,
   Overlays, Data, …). Give each demo a `.demo-cap` label.
3. **Register it** in `registry.json` (base class, variants, states, parts, a11y notes, example) and
   add its line to `llms.txt`.
4. **If interactive**, add/adjust the enhancement in `js/watercolor.js` (namespaced under `WC`), and
   add a typed component + test in `packages/react/src/`.
5. **Theme check** — verify it in Walk, Rain, Fire, and Dark Forest.

## Tokens

Edit `tokens/tokens.json`, then rebuild:

```bash
node scripts/build-tokens.mjs
```

Never edit generated token files by hand.

## Icons

Icons are re-inked from Feather at build time. To change the set or tuning, edit
`scripts/build-icons.mjs` (custom marks live in the `EXTRA` map) and run:

```bash
node scripts/build-icons.mjs         # rebuild sprite + manifests
node scripts/build-icon-pack.mjs && bash scripts/build-icon-pack.sh   # rebuild the download pack
```

## Before you open a PR

```bash
node scripts/validate.mjs            # tokens/registry/icons wiring
cd packages/react && npm run ci      # typecheck + build + test
```

- No console errors on `index.html`.
- New interactive components keyboard-operable and focus-visible.
- Contrast holds in all four themes.
- Docs, `registry.json`, and `llms.txt` updated alongside the code.

## Commit style

Small, focused commits with a clear imperative subject (e.g. `Add felt-pen checkbox to data grid`).

## License

By contributing you agree your work is licensed under the project's [MIT License](LICENSE).
