ADR-0009 — Component Library: Atomic Design in Zwerfkei Documentation¶
| Status | Accepted |
| Date | 2026-06-08 |
| Deciders | Flooris development team |
Context¶
The Zwerfkei front-end is built with Vue 3 + TypeScript and contains a growing set of UI components. Until now there was no shared, structured overview of those components: which ones exist, how they are composed, what props they accept, and which visual states they support. This made it harder to:
- onboard new developers onto the front-end codebase
- reason about reuse and duplication across pages
- discuss UI with product owners and designers without a shared reference
A lightweight, version-controlled component reference was needed — one that could grow alongside the codebase without requiring a separate tooling investment upfront.
Decision¶
All Zwerfkei front-end components are documented in Zwerfkei Documentation (this MkDocs repository), under docs/front-end/components/.
Components are classified and organised according to the Atomic Design methodology (Brad Frost, atomicdesign.bradfrost.com/chapter-2):
| Level | Description |
|---|---|
| Atom | Smallest indivisible UI element — button, badge, icon, colour swatch. |
| Molecule | Small group of atoms that forms a functional unit — price display, stock label, spec row. |
| Organism | Complex UI section composed of molecules and atoms — product card, filter sidebar, header. |
| Template | Page-level layout structure that arranges organisms — no real content yet. |
| Page | A specific rendered instance of a template with real content. |
Every component page declares its Atomic Design level and maintains bidirectional links to its parent and child components (Organisms → Molecules → Atoms).
Milestones¶
| # | ClickUp | Deliverable | Sprint |
|---|---|---|---|
| 1 | ZWE-332 | Component library v1 — Atomic Design overview in Zwerfkei Documentation | Sprint 3 |
| 2 | ZWE-334 | Playground v1 — component playground op /component-library in Zwerfkei Website |
Sprint X |
ZWE-332 — User story
Als developer heb ik een overzicht van alle componenten met het Atomic Design principe in Zwerfkei Documentatie aan het einde van Sprint 3.
ZWE-334 — User story
Als developer heb ik een playground voor het ontwikkelen en testen van de belangrijkste componenten in Zwerfkei Website op: /component-library aan het einde van Sprint X.
Rationale¶
- Zero extra tooling. The documentation repository already exists, is deployed to Cloudflare Pages, and is part of the team's daily workflow. Adding component pages here costs nothing infrastructurally.
- Markdown + git = review workflow. Component documentation changes go through the same pull-request process as code, making it easy to keep docs in sync with implementation.
- Atomic Design is widely understood. The methodology has clear, stable definitions. It gives developers and product owners a shared vocabulary for discussing composition and reuse.
- Composability is made explicit. Documenting which atoms form a molecule, and which molecules form an organism, surfaces duplication and encourages deliberate reuse.
Alternatives considered¶
| Alternative | Why not chosen |
|---|---|
| Storybook | Requires a running front-end build and dedicated hosting. High initial setup cost; deferred to a later phase. |
| Figma component library only | Design-side only — developers need a code-level reference for props, states, and behaviour. |
| Inline JSDoc / TSDoc | Lives in the source code, not discoverable by product owners. Not suitable as a shared reference. |
Future: Component Playground¶
In a later phase, a Component Playground will be set up to develop and test the most important components in isolation — without hard dependencies on back-end APIs or a fully running application. This allows:
- visual regression testing of individual components
- rapid iteration on UI states with mocked prop data
- onboarding exercises for new front-end developers
ZWE-334 — Not in scope for Sprint 3
The Playground is tracked as ZWE-334 and will be planned as a dedicated milestone once the Atomic Design component overview (ZWE-332) is complete. Likely tooling candidates are Storybook or Histoire (Vue-native).
Consequences¶
- Every new front-end component must be documented in
docs/front-end/components/before the relevant user story is considered done. - Each component page must include its Atomic Design level, a Composition section (parent/child links), props table, visual states, and at least a placeholder for screenshots.
- Screenshots are committed to the repository under
docs/assets/images/screenshots/<component-slug>/. - The
docs/front-end/components/CLAUDE.mdfile provides detailed authoring instructions for this section. - When a Playground is introduced, its integration with this documentation (e.g. live embed or deep links) will be addressed as part of that initiative.