Skip to content

Commit 873d2b6

Browse files
maxyingerclaude
andcommitted
docs(repo): keep rationale out of the swingset component docs
The docs describe the API as it is; the reasoning that produced it belongs in a code comment or the PR. Written into the mosaic skill and the swingset house style, since it is a mistake agents make repeatedly — and stated against the opposite rule for code, where a comment earns its place by explaining what the source cannot say for itself. Drops the paragraph arguing for `variant` over `size` from the Dialog page. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 parent ba29c56 commit 873d2b6

3 files changed

Lines changed: 36 additions & 4 deletions

File tree

‎.claude/skills/mosaic/SKILL.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,3 +78,38 @@ layer. Copy from it.
7878
The migration workflow (`migration.md`) ties the flow references together: it
7979
treats the legacy component as the spec and drives you through the model,
8080
controller, and view layers, then verifies parity with `parity-audit.md`.
81+
82+
## Documenting a component in swingset
83+
84+
`packages/swingset/CLAUDE.md` is the house style — archetypes, required section
85+
order, `meta` conventions. One rule on top of it, because it is the one agents
86+
get wrong:
87+
88+
**The docs describe the API as it is. They do not carry the reasoning that
89+
produced it.** No "not a `size`, because…", no rejected alternatives, no history
90+
of what the prop used to be. A reader is there to learn what the thing does, and
91+
every sentence of rationale is a sentence they have to skim past to find it.
92+
State the behaviour plainly and briefly, then stop.
93+
94+
```mdx
95+
<!-- no -->
96+
97+
### Variant
98+
99+
Which surface the dialog holds, and so the geometry it is given. Not a `size`,
100+
because these are different surfaces rather than one surface at two widths — a
101+
second card width would be a size of the `card` variant, with nowhere to sit on
102+
this axis.
103+
104+
<!-- yes -->
105+
106+
### Variant
107+
108+
Which surface the dialog holds, and the geometry that comes with it.
109+
```
110+
111+
This is the opposite of the rule for **code**, where a comment earns its place by
112+
explaining what the code cannot say for itself — the cascade fight behind a
113+
`null`, the measured reason a duration is what it is. Keep that reasoning where a
114+
future maintainer will hit it, which is the source file. The trade you rejected
115+
belongs in a code comment or the PR description; the docs get the conclusion.

‎packages/swingset/CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -273,6 +273,7 @@ import * as UserButtonStories from './user-button.stories';
273273

274274
- Keep the intro to one short, present-tense paragraph: what the thing is and what it's for. For primitives, say explicitly that it's headless and ships no styles.
275275
- Prose should add what a demo can't — behavior, accessibility, when to reach for it — not restate prop names already in the table.
276+
- Describe the API as it is; leave the reasoning that produced it out. No "not a `size`, because…", no rejected alternatives, no history of what a prop used to be — that belongs in a code comment or the PR. The docs get the conclusion, stated plainly and briefly.
276277
- Lead every page with the heading hierarchy its archetype prescribes; don't invent new top-level sections or reorder them. Consistency across pages is the goal.
277278

278279
### Before you finish

‎packages/swingset/src/stories/dialog.component.mdx‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -68,10 +68,6 @@ committing.
6868

6969
### Variant
7070

71-
Which surface the dialog holds, and so the geometry it is given. Not a `size`, because these are
72-
different surfaces rather than one surface at two widths — a second card width would be a size of
73-
the `card` variant, with nowhere to sit on this axis.
74-
7571
| Value | Width | For |
7672
| --------- | ---------------------------------------- | -------------------------------------------------------------------- |
7773
| `card` | `25rem`, height from content | Everything a `Card` holds — a flow, a confirmation, a form (default) |

0 commit comments

Comments
 (0)