Seeded claude design

2026-05-23 16:34:14 +02:00
commit 9419f166ce
32 changed files with 2553 additions and 0 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -0,0 +1,95 @@
+# 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.