Skip to content

Commit 87fb297

Browse files
Jeffrey Lauwersclaude
Jeffrey Lauwers
and
claude
committed
chore: CLAUDE.md toegevoegd als permanente projectinstructies voor Claude
Bevat: documentatienavigatiekaart, twee-lagen implementatiepatroon, kritieke regels (button accessible naming, tokens, BEM, TS-warnings), nieuw-component checklist, Storybook-docs structuur en git-workflow. update-docs.md command bijgewerkt met 06-css-naming-conventions.md. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent dc7c26f commit 87fb297

File tree

2 files changed

+339
-0
lines changed

2 files changed

+339
-0
lines changed

‎.claude/commands/update-docs.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# Documentatie synchroniseren
2+
3+
Synchroniseer alle projectdocumentatie met de actuele staat van de codebase. Werk elke stap in volgorde af.
4+
5+
Optionele context die meegegeven kan worden (gebruik $ARGUMENTS als startpunt):
6+
7+
> $ARGUMENTS
8+
9+
---
10+
11+
## Stap 1 — Begrijp wat er veranderd is
12+
13+
Voer uit:
14+
15+
```
16+
git log --oneline -20
17+
```
18+
19+
Noteer wat er veranderd is:
20+
21+
- Nieuwe componenten toegevoegd?
22+
- Bestaande componenten gewijzigd (API, props, HTML klassen, tokens)?
23+
- Nieuwe of gewijzigde design tokens?
24+
- Breaking changes?
25+
- Versie-bumps?
26+
- Bug fixes of interne refactors?
27+
28+
Dit bepaalt welke bestanden daadwerkelijk updated moeten worden. Niet elk bestand hoeft bij elke sessie te veranderen.
29+
30+
---
31+
32+
## Stap 2 — Root `README.md`
33+
34+
Controleer en update waar nodig:
35+
36+
- **Componenttelling** — tel de werkelijke componenten in de codebase en vergelijk
37+
- **Testaantal** — haal het actuele getal op via: `pnpm test run 2>&1 | tail -5`
38+
- **Component tabel** — alle componenten vermeld? HTML/CSS + React + Web Component status correct?
39+
- **Scripts sectie** — zijn er nieuwe scripts bijgekomen in `package.json`?
40+
- **Tech stack** — zijn er versie-wijzigingen (bijv. Storybook, Vitest, TypeScript)?
41+
42+
---
43+
44+
## Stap 3 — `docs/` bestanden
45+
46+
### `docs/README.md`
47+
48+
- Componenttelling en statistieken up-to-date?
49+
- Links naar andere docs — alle 5 nummers aanwezig?
50+
51+
### `docs/01-architecture.md`
52+
53+
Alleen updaten als de **architectuur zelf** veranderd is: token-structuur, repo-layout, naming conventions, package-verantwoordelijkheden.
54+
55+
### `docs/02-design-tokens-reference.md`
56+
57+
Updaten bij:
58+
59+
- Nieuwe token-categorieën of schalen
60+
- Gewijzigde token-waarden (spacing, typografie, kleuren, borders)
61+
- Nieuwe token-types (bijv. box-shadow tokens werden hier toegevoegd in PR #73)
62+
63+
### `docs/03-components.md`
64+
65+
**Grootste kans op updates.** Updaten bij:
66+
67+
- Nieuwe componenten → toevoegen aan de juiste categorie met correcte BEM klassen, props, beschrijving
68+
- Gewijzigde API's → props, varianten, HTML klassen bijwerken
69+
- Componenttelling per categorie controleren:
70+
- Layout Components: 4 (Container, Stack, Grid, GridItem)
71+
- Content Components: 9 (Button, ButtonLink, Heading, Icon, Link, LinkButton, OrderedList, Paragraph, UnorderedList)
72+
- Display & Feedback Components: 4 (Alert, Note, StatusBadge, Table)
73+
- Form Components: 25 (7 option + 2 input + 7 field + 9 specialized)
74+
- **Totaal: 42**
75+
76+
### `docs/04-development-workflow.md`
77+
78+
Updaten bij: nieuwe scripts, gewijzigde test-strategie, nieuwe tooling, CI/CD wijzigingen.
79+
80+
### `docs/06-css-naming-conventions.md`
81+
82+
Updaten bij: nieuwe naamgevingspatronen, nieuwe utility-klassen, wijzigingen in het lokale alias-scoping-patroon of token-naamstructuur.
83+
84+
### `docs/05-storybook-configuration.md`
85+
86+
Updaten bij: nieuwe addons, nieuwe story-types, gewijzigde Storybook config, nieuwe TokenTable features.
87+
88+
### `docs/changelog.md`
89+
90+
Voeg een nieuwe entry toe voor commits die nog niet gedocumenteerd zijn. Formaat:
91+
92+
```markdown
93+
## [versie] — YYYY-MM-DD
94+
95+
### Added
96+
97+
- Omschrijving van nieuwe feature of component (PR #nummer)
98+
99+
### Changed
100+
101+
- Omschrijving van wijziging
102+
103+
### Fixed
104+
105+
- Omschrijving van bug fix
106+
107+
### Breaking Changes
108+
109+
- Omschrijving + migratiepad
110+
```
111+
112+
Gebruik commit messages en PR-nummers als bron. Sla het over als alle recente commits al een entry hebben.
113+
114+
---
115+
116+
## Stap 4 — Storybook `packages/storybook/src/*.docs.md`
117+
118+
**Voor elk nieuw component** dat nog geen `.docs.md` heeft:
119+
Maak een nieuw bestand aan in hetzelfde formaat als bestaande bestanden. Kijk naar een bestaand bestand in dezelfde categorie als voorbeeld. Secties:
120+
121+
1. Titel + korte beschrijving
122+
2. Use when
123+
3. Don't use when
124+
4. Best practices
125+
5. Design tokens tabel (tokennaam | waarde/beschrijving)
126+
127+
**Voor gewijzigde componenten:**
128+
129+
- Beschrijving updaten als de API of scope veranderd is
130+
- Design tokens tabel updaten bij nieuwe of gewijzigde tokens
131+
- Use when / Don't use when aanpassen als de aanbevolen inzet veranderd is
132+
133+
---
134+
135+
## Stap 5 — Commit
136+
137+
Zijn er bestanden gewijzigd? Commit ze dan met een beschrijvend bericht:
138+
139+
```
140+
git add README.md docs/README.md docs/03-components.md docs/changelog.md packages/storybook/src/*.docs.md
141+
git commit -m "docs: ..."
142+
```
143+
144+
Gebruik de `docs:` prefix. Noem in de commit message welke versie(s) gedocumenteerd zijn en wat er is toegevoegd of bijgewerkt.
145+
146+
Vraag daarna aan de gebruiker of de commit rechtstreeks naar main gepusht moet worden, of via een PR. Doe dit **niet automatisch** — wacht op expliciete bevestiging.
147+
148+
---
149+
150+
## Regels
151+
152+
- Wijzig **nooit** code-bestanden (`.ts`, `.tsx`, `.css`, `.json` tokens, Storybook stories)
153+
- Wijzig **nooit** `MEMORY.md` of bestanden in `.claude/` — dat is Claude's eigen domein
154+
- Voeg **geen** verzonnen statistieken toe — haal testaantal en componenttelling altijd uit de werkelijke codebase
155+
- Houd de **bestaande schrijfstijl** aan: toon, taal (Nederlands of Engels per bestand), opmaak, sectienamen
156+
- Update **alleen wat daadwerkelijk veranderd is** — niet elk bestand hoeft bij elke sessie te wijzigen
157+
- Als iets onduidelijk is: vraag eerst, update daarna

‎CLAUDE.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# Design System Starter Kit — Claude Instructions
2+
3+
Dit bestand wordt automatisch gelezen aan het begin van elke Claude-sessie.
4+
Het bevat de projectregels, architectuurpatronen en navigatiekaart naar de volledige documentatie.
5+
6+
---
7+
8+
## Documentatie — waar staat wat?
9+
10+
| Vraag | Lees dit |
11+
| -------------------------------------------------- | ------------------------------------ |
12+
| Hoe is het project opgebouwd? | `docs/01-architecture.md` |
13+
| Welke tokens bestaan er en wat zijn de waarden? | `docs/02-design-tokens-reference.md` |
14+
| Welke componenten bestaan er en wat zijn de specs? | `docs/03-components.md` |
15+
| Hoe werkt het development workflow / git / CI? | `docs/04-development-workflow.md` |
16+
| Hoe werken CSS-klassen en token-namen? | `docs/06-css-naming-conventions.md` |
17+
| Hoe werkt Storybook? | `docs/05-storybook-configuration.md` |
18+
| Wat is er recent veranderd? | `docs/changelog.md` |
19+
20+
**Voor een nieuw component:** lees altijd `docs/06-css-naming-conventions.md` en `docs/03-components.md` eerst.
21+
22+
---
23+
24+
## Twee-lagen implementatiepatroon — ALTIJD
25+
26+
Elk component in dit design system heeft **altijd twee lagen**. Geen uitzonderingen.
27+
28+
| Laag | Wat | Voorbeeld |
29+
| ------------ | ------------------------------------------ | --------------------------------------------- |
30+
| **HTML/CSS** | De kern — layout en stijllogica | `<div class="dsn-stack dsn-stack--space-md">` |
31+
| **React** | De wrapper — genereert de HTML/CSS klassen | `<Stack space="md">` |
32+
33+
- De CSS-klassen zijn de bron van waarheid
34+
- React is gemak bovenop de HTML/CSS-laag
35+
- Bij elk nieuw component: **beide** lagen uitwerken en documenteren
36+
- Storybook-docs tonen altijd zowel de HTML/CSS-variant als de React-variant
37+
38+
---
39+
40+
## Kritieke regels — nooit overtreden
41+
42+
### 1. Button accessible naming — NOOIT `aria-label`
43+
44+
Gebruik **altijd** een `dsn-button__label` span. `dsn-button--icon-only` verbergt hem visueel maar houdt hem beschikbaar voor screenreaders.
45+
46+
```html
47+
<!-- ✅ Standaard icon-only button -->
48+
<button
49+
type="button"
50+
class="dsn-button dsn-button--subtle dsn-button--size-small dsn-button--icon-only"
51+
>
52+
<svg class="dsn-icon" aria-hidden="true"><!-- icon --></svg>
53+
<span class="dsn-button__label">Instellingen</span>
54+
</button>
55+
56+
<!-- ✅ Icon-only met rij-context (tabelacties) -->
57+
<button
58+
type="button"
59+
class="dsn-button dsn-button--subtle dsn-button--size-small dsn-button--icon-only"
60+
>
61+
<svg class="dsn-icon" aria-hidden="true"><!-- dots-vertical --></svg>
62+
<span class="dsn-button__label">
63+
Toon acties
64+
<span class="dsn-visually-hidden"> voor product: Laptop Pro</span>
65+
</span>
66+
</button>
67+
68+
<!-- ❌ NOOIT -->
69+
<button aria-label="Instellingen">...</button>
70+
```
71+
72+
### 2. Tokens — nooit hardcoded waarden in CSS
73+
74+
```css
75+
/* ❌ */
76+
color: #1b59a4;
77+
padding: 8px;
78+
transition: 0.2s ease;
79+
80+
/* ✅ */
81+
color: var(--dsn-color-accent-1-color-default);
82+
padding: var(--dsn-space-block-md);
83+
transition: var(--dsn-transition-duration-normal)
84+
var(--dsn-transition-easing-default);
85+
```
86+
87+
### 3. BEM naming — zie `docs/06-css-naming-conventions.md`
88+
89+
Kernregels:
90+
91+
- Prefix altijd `dsn-`
92+
- Modifier altijd naast basis-klasse: `class="dsn-note dsn-note--info"`
93+
- Grootte altijd via `--size-{naam}`: `dsn-button--size-small`
94+
- Geen geneste element-namen: `dsn-alert__content__text` ❌
95+
- HTML-toestanden via pseudo-klassen: `.dsn-button:disabled` ✅
96+
97+
### 4. Twee TypeScript-waarschuwingen zijn pre-existing
98+
99+
`pnpm --filter storybook exec tsc --noEmit` geeft **4 warnings** in bestaande bestanden. Dit zijn bekende, pre-existing issues — geen blocker. Nieuwe code moet 0 nieuwe fouten introduceren.
100+
101+
---
102+
103+
## Nieuw component bouwen — checklist
104+
105+
### Bestanden aanmaken
106+
107+
Elk nieuw component vereist exact deze bestanden:
108+
109+
```
110+
packages/components-html/src/{component-name}/
111+
└── {component-name}.css # HTML/CSS implementatie
112+
113+
packages/components-react/src/{ComponentName}/
114+
├── {ComponentName}.tsx # React wrapper
115+
├── {ComponentName}.test.tsx # Tests
116+
└── {ComponentName}.css # @import van components-html CSS
117+
118+
packages/storybook/src/
119+
├── {ComponentName}.stories.tsx # Storybook stories
120+
├── {ComponentName}.docs.mdx # Storybook docs page (MDX)
121+
└── {ComponentName}.docs.md # Docs content (Markdown)
122+
```
123+
124+
### Exports en registraties
125+
126+
- `packages/components-react/src/index.ts` — export toevoegen
127+
- `packages/storybook/src/Introduction.mdx` — datum updaten + component in de lijst
128+
129+
### Token-bestanden (indien nieuwe tokens nodig)
130+
131+
```
132+
packages/design-tokens/src/tokens/components/{component-name}.json
133+
packages/design-tokens/src/tokens/themes/start/colors-light.json (indien kleur-tokens)
134+
packages/design-tokens/src/tokens/themes/start/colors-dark.json (altijd simultaan)
135+
packages/design-tokens/src/tokens/themes/start/base.json (indien structurele tokens)
136+
```
137+
138+
### Kwaliteitscontrole voor PR
139+
140+
```bash
141+
pnpm test # alle tests groen
142+
pnpm --filter storybook exec tsc --noEmit # 0 nieuwe TypeScript-fouten
143+
pnpm lint # 0 lint-fouten
144+
```
145+
146+
---
147+
148+
## Storybook-docs structuur
149+
150+
Elk component heeft een `.docs.md` met vaste secties in deze volgorde:
151+
152+
1. **Titel + korte beschrijving** (één zin)
153+
2. **Doel** — wat doet het component en wanneer gebruik je het?
154+
3. **Use when** — bulletlijst
155+
4. **Don't use when** — bulletlijst
156+
5. **Best practices** — subsecties per onderwerp
157+
6. **Design tokens** — tabel met alle `--dsn-{component}-*` tokens
158+
7. **Accessibility** — toegankelijkheidsaandachtspunten
159+
160+
Bekijk `packages/storybook/src/Button.docs.md` als referentie voor toon en opmaak.
161+
162+
---
163+
164+
## Git-workflow
165+
166+
```bash
167+
git checkout -b feature/naam # altijd een feature branch
168+
# ... implementatie ...
169+
pnpm test && pnpm lint # altijd testen voor commit
170+
git add [specifieke bestanden] # nooit git add -A of git add .
171+
git commit -m "feat(Component): ..." # conventional commits
172+
gh pr create # PR aanmaken
173+
gh pr merge --merge # na CI-groen en review
174+
```
175+
176+
Commit-prefixes: `feat` / `fix` / `docs` / `chore` / `refactor` / `test`
177+
178+
---
179+
180+
## Huidige staat — zie MEMORY.md
181+
182+
De actuele staat van het project (welke componenten af zijn, recente PRs, openstaande issues) staat in MEMORY.md. CLAUDE.md bevat de permanente projectregels; MEMORY.md bevat de actuele sessie-context.

0 commit comments

Comments
 (0)