96 lines
4.7 KiB
Markdown
96 lines
4.7 KiB
Markdown
# 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.
|