# Contributing to `whynot-design`

Thanks for the curiosity. A few things before you open a PR.

## Where the language is decided

Visual decisions are made in the **Claude atelier project** (the `WhyNot Design System` template), not in this repo. This repo is the *implementation* — it ships what the atelier agreed.

If your change is purely visual (a new component, a token tweak, a new variant), do it in the atelier first. Get a designer or `whynot` lead to approve the variation. Then open a PR here with:

- A link to the atelier project / screenshot of the approved variation.
- A one-sentence rationale, written in `whynot` voice. E.g. *"The hover bar reads as 3px at 14” preview sizes; 2px disappears."*

If your change is purely mechanical (CI, tooling, dependency bumps, doc typos), skip the atelier — just open the PR.

## House rules

These are enforced by review, not CI. Internalise them.

1. **Quiet voice.** Sentence case. No emoji (except `→` and `?!`). No hype. No marketing language.
2. **No new colour without a fight.** The system is two neutrals and one accent. Adding a colour is a major decision. Add a *token* (e.g. status ramp extension) before adding a *colour*.
3. **No gradients. Anywhere.**
4. **No shadows on cards.** Elevation is intentionally near-zero. Popovers and modals only.
5. **Square corners on big things.** 0–4 px radii for cards/sheets; 8 px for large modals; pill only for label capsules.
6. **No hand-rolled SVG icons or emoji.** Lucide at 1.5 px stroke, or a placeholder.
7. **Lowercase organisation name** (`whynot`) in body copy.

When in doubt, re-read `README.md` and `SKILL.md`. Both are authoritative.

## Workflow

```
[atelier]                [this repo]                    [consumers]
                                                              
 explore  ──►   PR: tokens / components / CSS    ──►   Renovate PR
 decide        + CHANGELOG entry                       (auto, weekly)
               + Playwright snapshot updated
                       │                                      │
                       ▼                                      ▼
              merge → tag → release                     consumer CI
              (CI handles)                              + visual regression
```

### Branches

- `main` is always releasable. Tag `vN.N.N` directly from `main`.
- Feature branches: `feat/<short-slug>`. PRs squash-merge.

### Commits

Conventional Commits, lightly.

- `feat: add StageDot pulse variant`
- `fix(button): nudge ghost padding to match secondary`
- `tokens: tighten --tr-tight to -0.025em`
- `docs: clarify Lucide stroke override`
- `chore: bump @playwright/test`

The `tokens:` prefix is non-standard but useful — it marks PRs that touch `tokens/*.json` or `src/styles/colors_and_type.css` and trigger consumer visual-regression review.

## What CI checks

1. `pnpm install` succeeds.
2. `CHANGELOG.md` has a new entry that mentions the PR (this is `scripts/check-changelog.mjs`). Skip with the label `no-changelog` for trivial doc-only PRs.
3. `pnpm test:visual` — Playwright opens `examples/whynot-control/index.html` and compares against snapshots in `examples/whynot-control/__screenshots__/`.

If a snapshot intentionally needs to change, run `pnpm test:visual:update` locally, commit the new PNGs, and call it out in the PR description: *"Snapshot updated — see `Prototype.png`, hover bar is now 3 px."*

## Release process

After PR merge:

1. Bump `package.json` version following the [versioning rules in `DesignSystemIntroduction.md` §5](./DesignSystemIntroduction.md#5-versioning-discipline).
2. Move the `## [Unreleased]` block in `CHANGELOG.md` under a new `## [vX.Y.Z] — YYYY-MM-DD` header.
3. Tag: `git tag vX.Y.Z && git push --tags`.
4. CI's release workflow attaches the CHANGELOG slice to the Gitea release. (If publishing to a registry, this is where `npm publish` runs.)
5. Renovate picks up the new tag in consumer repos within ~24h. Or manually:

   ```sh
   cd ../whynot-prototype-WNO-022
   pnpm up @whynot/design
   ```

## Promoting past 1.0.0

Stay in `0.x.x` until something built with this system is in production for >30 days with at least S2 signal. Promotion to `1.0.0` must be recorded in `whynot-control/DECISIONS.md`, same as promotion to Helix, Coulomb, etc.

## What we don't accept

- PRs that add a colour palette without a corresponding atelier decision.
- PRs that import a UI library (Radix, Headless UI, shadcn) and re-export it. The system is small on purpose.
- PRs that add a build step before the system has >20 components.
- PRs that add storybook before the system has >2 contributors.

> A contribution can be interesting and still be parked. `whynot-design` exists to reduce visual uncertainty, not to absorb every good idea.