## Contributing

This repo uses [mise](https://mise.jdx.dev) for the toolchain and
[hk](https://hk.jdx.dev) for git hooks.

```sh
mise run setup        # install tools, fetch deps, wire git hooks
cd assets && npm ci && cd ..
mise run check        # format, warnings-as-errors, TS, ExUnit, harness guards
mix assets.build      # build the docs CSS and JavaScript
mix dev               # boot the docs site at http://localhost:4001
# In a second terminal:
cd test/e2e && npm ci && npx playwright install chromium webkit && cd ../..
mise run e2e          # axe + behavior + dark/normal-motion Chromium and WebKit
mise run consumer     # packaged consumer, both styles (test/consumer/README.md)
```

Components live under `lib/shadix/components/`; the same
modules are what the generator copies (with namespace rewriting) into a host app.
After changing a component, hook, or its colocated CSS, run
`mix shadix.gen.registry` so the packaged manifests stay in sync.

Run all three gates before merging: `check`, `e2e`, and `consumer`. The fast gate
does not run browsers or build a consumer. CI has separate workflows for each;
do not infer all passed from a single workflow. Browser tests need the running
docs site; the consumer runner boots isolated apps itself. `CHROMIUM_BIN` and
`WEBKIT_BIN` can select locally installed browser executables.

Docs deployment is manual-only: after all three workflows pass for the same
revision, the owner can explicitly run the main CI workflow's manual trigger.
Pushes do not deploy; the fast workflow cannot enforce the independent jobs.
When testing a built docs release locally, set `PHX_BIND_IP=127.0.0.1`, `PORT`,
`PHX_HOST=localhost` and a throwaway `SECRET_KEY_BASE`; the deployment default
binds all interfaces for the container proxy.

The pre-commit hook regenerates manifests after component, hook, ColocatedCSS
or per-style CSS edits and stages the style aggregators too. ExUnit separately
checks drift without regenerating. Built docs JS/CSS are ignored artifacts,
not source to commit. Tailwind is pinned to 4.2.3 locally, in the docs CI build,
and in the packaged-consumer fixture.

For interactive changes, add a real LiveView regression that fails before the
fix. Assert submitted values and visible/ARIA state together; rendered HTML
alone cannot establish hook behavior through patches. Keep copied hooks
self-contained. Use stable, unique IDs for every hook, including each
`resizable_handle`. See `FOLLOWUPS.md` for release gates and limitations.