docs: add CLAUDE.md, and cover Storybook in CONTRIBUTING

[alukach]

Why

Four things keep having to be restated across sessions, and none of them are
visible from the code:

1. UI changes belong in Storybook, in the same PR — added, changed, or
   removed. A state you can only reach by clicking through the running app is a
   state nobody reviews.
2. A UI PR should link its stories and screenshot anything visual. The
   screenshot shows the change in the review itself, and outlives the branch
   deployment, which goes away with the branch.
3. A PR's title and description describe the branch as it stands — not as it
   stood when the PR was opened. A description is read later as the spec, so a
   stale one sends a reviewer looking for code that isn't there.
4. Comments say why the code is the way it is, in the present tense. What it
   used to do and what a change fixed belong in the commit message and PR
   description, where someone actually goes looking for history — and where it
   stays accurate as the code moves on.

CLAUDE.md is loaded automatically into every Claude Code session in this repo,
so it is the mechanism that makes these stick without being re-explained.

Rule 3 earned its place during this session: #533 still described a fixed-width
Storybook wrapper, and testing "inside the 320px container", two commits after
both had been replaced by a pinned viewport. It called out the two parts that rot
first — a Testing section asserting checks that predate the current commits, and
a Conventional Commits title that no longer matches the work's shape.

Also in CLAUDE.md

The Storybook gotchas that otherwise cost an hour to rediscover:

• async server components can't be storied (they read the session) — extract the
  presentational part, as ProductDoi does beside ProductSummaryCard;
• a component importing a server action needs sb.mock() in preview.tsx, or
  its story dies on __filename is not defined;
• responsive states want a pinned viewport, never a fixed-width wrapper. A box
  exactly as wide as the frame has none of the page padding the real layout has,
  so it invents overflow the page doesn't have. (Learned the hard way in fix(products): truncate a product's DOI instead of overflowing the row #533.)

CONTRIBUTING.md

Storybook has been published at ui.source.coop since #498 and was not mentioned
in CONTRIBUTING at all. Adds a Code Conventions section for it, plus two PR
steps: describing UI changes, and keeping the PR current. The gotchas stay in
CLAUDE.md — one copy of each rule, so the two files can't drift.

Notes

Rules 1–3 are not component-scoped, which is why this is a root CLAUDE.md
rather than a scoped src/components/CLAUDE.md.

Worth considering separately: much of rule 1 could be enforced rather than
documented — this repo already codifies conventions as no-restricted-syntax
rules with a teaching message. A test asserting every component has a sibling
.stories.tsx would need an allowlist for the current gaps, so it is left out
here.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JoNCbzms6gPxEbKCgSPe9L

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
source-coop-ui	Ready	Preview	Aug 29, 2026 6:46am
source-cooperative	Ready	Preview	Aug 29, 2026 6:46am

[claude]

Claude finished @alukach's task in 1m 4s —— View job

---

✅ No blocking issues — safe to merge.

This is a docs-only change (CLAUDE.md new, CONTRIBUTING.md +9/-1); there's no executable code, so there's nothing to flag on correctness or security.

One non-blocking consistency note:

• The PR description says the goal is "one copy of each rule, so the two files can't drift," but the "Storybook" and "Pull requests" guidance is stated in both files with near-duplicate wording:

  • CLAUDE.md:9-12 ("Every UI change lands in Storybook in the same PR...") vs. CONTRIBUTING.md:81 ("UI changes carry their stories with them...")
  • CLAUDE.md:30-33 (linking stories + screenshotting visuals) vs. CONTRIBUTING.md:16 ("Describe UI changes.")
  • CLAUDE.md:34-40 (keeping title/description current) vs. CONTRIBUTING.md:17 ("Keep the PR current.")

  Not a bug, but worth a look since it's the exact kind of drift risk the PR calls out — if one is edited later, the other may quietly go stale.

Simplify (ponytail)

• CONTRIBUTING.md:16-17 / CLAUDE.md:30-40 — the "Describe UI changes" and "Keep the PR current" checklist bullets restate CLAUDE.md's "Pull requests" section almost verbatim; cut one copy (e.g. keep the detailed version in CLAUDE.md, reduce CONTRIBUTING.md's bullets to a one-line pointer) → single source of truth per the PR's own stated intent.

---

💰 Estimated review cost: $0.27 · 1m03s · 16 turns