Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,7 @@ Before opening a PR or merging, re-read the full diff end to end — including f
- Names state business meaning (see *Readability and Naming*).
- Every new abstraction, dependency, or config key has one line in the PR: the simpler option and why it was rejected. If you can't write that line, build the simpler option. No second caller yet → no abstraction.
- New code follows an existing pattern, named in the PR — or the PR says why none fits. If the pattern itself is wrong, fix it repo-wide in its own change; don't fork it locally.
- For every UI composition added or changed, the PR names the comparable existing instance or documented pattern used as its baseline — or says why none fits — and confirms that unrelated visual structure was preserved.

### Working in a git worktree

Expand Down
6 changes: 5 additions & 1 deletion apps/frontend/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,8 @@ A stack pack may bind move 2 to a component workshop (Storybook or equivalent) r
5. One density app-wide, set at the token layer — never mixed within a page (guide → *Screen archetypes*).
6. Tables, forms, and view states follow the composition patterns — the pattern outranks the component library's defaults (guide → *Tables & grids*, *Forms*, *View states & feedback*). A working table ships the standard kit (search, sort, column filters, pagination, column customisation, selection) by default; dropping a capability is the recorded decision.

**Existing screens are the baseline for tweak work.** Before changing an existing screen, inspect the current implementation in the affected state and viewport, using the running app or the review context already supplied with the request. Treat the request as a delta, not permission to redesign: preserve its layout, hierarchy, spacing, typography, component variants, copy, states, and responsive behaviour unless the request explicitly changes them. A tweak never re-derives the screen from the design guide or its original mockup; the existing app is the reference.

## UI component approach (decide with the user before building UI)

How much of the component layer the project writes is a Day-1 decision, and it belongs to the user. **Ask before the first screen or component is built; never pick silently.** When the user has no preference, record option 2 (the copy-in set) as the default. Record the answer as a line in root `CLAUDE.md` **Learnings**: which option, one sentence of reasoning, the date. Then reconcile the design guide with the answer and get it accepted before screen work starts (*Hydrating the design guide* above).
Expand Down Expand Up @@ -196,7 +198,8 @@ Consistency comes from reuse, not per-screen discipline. Every component sits in

**The DRY gate — the UI must be *actually* DRY:**

- **Reuse-first.** Before building any component, search `atoms/` and `molecules/` for one that exists. A second variant of something already there is the canonical failure this structure prevents.
- **Reuse components and compositions.** Before adding or changing a UI action, search the same feature and then the app for the most comparable existing instance of that action or composition. Reusing the same atom is not sufficient: in comparable contexts, also match placement, density, label shape, loading/disabled behaviour, and responsive treatment. If the new instance deliberately differs, record the contextual reason.
- **One owner at the second comparable instance.** When the same semantic composition appears twice in comparable contexts, give it one implementation in the same change: reuse or extend the owning molecule/organism, or extract one at the appropriate tier. Share a coherent interaction, not merely a bundle of matching classes. If the contexts require meaningfully different behaviour, keep them separate and document the distinction.
- **Never build a one-off.** Every header, button, input, modal, table, or icon button is the shared organism/primitive — never hand-rolled. Wrap from the start, even before a component is widely reused, so a later token/behaviour change lands everywhere at once.
- **No feature-specific atoms or molecules.** Genuinely generic → global `molecules/`; carries business meaning → organism. Nothing in between — this one rule stops the shared tiers re-fragmenting per feature.
- **Audit for duplication periodically** (in the spirit of the i18n key-parity check): two components that render the same thing are a defect to merge.
Expand Down Expand Up @@ -270,6 +273,7 @@ Run it; don't infer from reading the code.

- **A new screen's initial build is verified against its `design/` mockup** — render it and look (a screenshot or equivalent). No mockup? Sketch the screen in the feature's spec and get it approved there first — never invent UI for a non-trivial new screen silently. Later iterations verify against the running app, not the mockup. (Full loop + mockup inventory: `design/README.md`.)
- Start the dev server and load the touched screen.
- For a tweak to an existing screen, reuse the running screen or supplied review capture as the baseline; no separate before/after capture is required. Confirm the requested delta is present and unrelated visual structure is unchanged.
- Force all four states to render (loading/error/empty/success) — don't just read the code.
- One keyboard-only pass: tab order sane, focus visible, Esc/Enter work on any modal or dialog.
- Exercise the screen at the declared primary form factor, **and at ~320 px and 200% zoom** — confirm nothing overflows, clips, or forces horizontal scroll, and fixed chrome doesn't overlap content (force it; don't infer safety from the classes).
Expand Down
3 changes: 3 additions & 0 deletions design/design-guide.html
Original file line number Diff line number Diff line change
Expand Up @@ -2046,6 +2046,9 @@ <h2>Reuse order</h2>
cleaner to rewrite it" is not a valid reason to create another component; a
near-duplicate with different styling fails the bar — restyle or extend the
original instead.</p>
<p>The reuse order applies to compositions as well as component types. Before
arranging existing atoms in a new way, search for the same action or interaction
in a comparable context and reuse its composition.</p>
<figure class="figure">
<div class="tiers">
<div class="tier"><span class="t-name">1 · archetype</span><span>Use an existing <a href="#archetypes">screen archetype</a>.</span></div>
Expand Down
Loading