ehoandClaude Opus 5
097e8468e0
app-choice-link rendered a component host between the keuzelijst <ul>
and its <li>. This broke the axe list/listitem rule for assistive
technology. Five story suppressions named WP-11 as the fix, but WP-11
closed with no open ticket left to own the defect.
choice-link now uses selector: 'li[app-choice-link]', the same
attribute-host pattern as application-link. The host carries the
keuzelijst__list-item class; the template drops its own <li>.
Position: relative stays on .keuzelijst__link so the stretched-link
overlay still resolves against the card, not the host.
aanvraag-block needed no component change: it renders a CIBG melding,
never an <li>. Only its story wrapped it in a <ul>, which is what axe
rejected. The wrapper is removed, and the four non-Concept stories are
deleted — the component's template only renders for status Concept, so
they rendered nothing.
All five a11y: { disable: true } suppressions are gone, with no
replacement. atomic-design.mdx now records that both molecules are the
<li>, kept separate for the vendored CSS they bind, not for list
semantics.
npm run ci --full passes, axe included.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
126 lines
7.5 KiB
Plaintext
126 lines
7.5 KiB
Plaintext
import { Meta, Canvas } from '@storybook/addon-docs/blocks';
|
|
import * as ButtonStories from '../src/ui/atoms/button/button.stories';
|
|
import * as FormFieldStories from '../src/ui/molecules/form-field/form-field.stories';
|
|
import * as PageShellStories from '../src/layout/page-shell/page-shell.stories';
|
|
import * as DocumentUploadStories from '../src/ui/organisms/upload/document-upload/document-upload.stories';
|
|
|
|
<Meta title="Foundations/Atomic Design" />
|
|
|
|
# Atomic design
|
|
|
|
Every screen in this app is built from a small set of layers, each composed **only from
|
|
the layer below it**. Read a screen top-down and you always land on the same handful of
|
|
atoms — that is the whole point: fewer things to understand, nothing bespoke per page.
|
|
|
|
<div style={{ display: 'grid', gap: '0.5rem', maxWidth: '32rem', margin: '1.5rem 0' }}>
|
|
{[
|
|
[
|
|
'Templates',
|
|
'shared/layout',
|
|
'shell, page-shell, wizard-shell — the page skeleton',
|
|
'#1e3a5f',
|
|
],
|
|
[
|
|
'Organisms',
|
|
'shared/ui/upload/document-upload …',
|
|
'self-contained sections that own a bit of behaviour',
|
|
'#2a5a8a',
|
|
],
|
|
['Molecules', 'shared/ui/form-field, async …', 'a label + control + error, grouped', '#3f7cb5'],
|
|
[
|
|
'Atoms',
|
|
'shared/ui/button, text-input …',
|
|
'thin wrappers over CIBG Huisstijl (Bootstrap) CSS classes',
|
|
'#6aa6d8',
|
|
],
|
|
].map(([name, where, why, bg], i) => (
|
|
<div
|
|
key={name}
|
|
style={{
|
|
background: bg,
|
|
color: '#fff',
|
|
padding: '0.75rem 1rem',
|
|
borderRadius: '6px',
|
|
marginLeft: `${i * 1.5}rem`,
|
|
}}
|
|
>
|
|
<strong>{name}</strong> <span style={{ opacity: 0.85 }}>— {why}</span>
|
|
<div
|
|
style={{ fontFamily: 'monospace', fontSize: '0.75rem', opacity: 0.8, marginTop: '0.2rem' }}
|
|
>
|
|
{where}
|
|
</div>
|
|
</div>
|
|
))}
|
|
</div>
|
|
|
|
## The rule, enforced
|
|
|
|
**Each layer only uses layers below it, and dependencies point inward.** This is not a
|
|
convention you have to remember — `eslint.config.mjs` fails the build if `domain/` imports
|
|
Angular, or if a context imports "upward". See [the FP-in-the-UI primer](?path=/docs/foundations-fp-in-the-ui--docs)
|
|
for how the same discipline shapes state and effects.
|
|
|
|
## A composition chain, live
|
|
|
|
Here is one real chain from atom → molecule → template. Each is a published Storybook
|
|
story below; click through to the sidebar entries to explore every variant.
|
|
|
|
### Atom — `button`
|
|
|
|
A thin wrapper: we own a typed `variant` input, the CIBG CSS owns the pixels.
|
|
|
|
<Canvas of={ButtonStories.Primary} />
|
|
|
|
### Molecule — `form-field`
|
|
|
|
Label + control + error text, grouped so the error is announced via `role="alert"`. It
|
|
composes atoms; it adds no new visual primitives of its own.
|
|
|
|
<Canvas of={FormFieldStories.WithError} />
|
|
|
|
### Organism — `document-upload`
|
|
|
|
`shared/ui/upload/document-upload` composes molecules (a file input, alert, progress bar,
|
|
chips) into a section that owns real upload behaviour.
|
|
|
|
<Canvas of={DocumentUploadStories.Default} />
|
|
|
|
### Template — `page-shell`
|
|
|
|
The page skeleton — title, optional back-link, content slot. Pages drop composed
|
|
organisms into it; the template never knows what they are.
|
|
|
|
<Canvas of={PageShellStories.WithBackLink} />
|
|
|
|
## Why bother
|
|
|
|
A new page should be **composition of existing blocks**. Adding a new building block is the
|
|
exception, not the reflex — if you reach for one, that is a signal to check whether an
|
|
existing atom/molecule already covers it. Fewer primitives → less to test, less to learn,
|
|
one place to fix a bug.
|
|
|
|
## Convergence decisions — pairs that look duplicated but stay separate
|
|
|
|
Periodically we audit for near-duplicate blocks. Some collapse into one; a few **look**
|
|
similar but earn their separation. This table records the "don't merge these" verdicts so
|
|
the next person doesn't spend an afternoon re-deciding. (Deliberate CIBG-specific deviations
|
|
live in [CIBG gaps](?path=/docs/foundations-cibg-gap-register--docs); the FE⇄DS "same shape, different
|
|
context" cases in [Domain-driven design](?path=/docs/foundations-domain-driven-design--docs).)
|
|
|
|
| Pair | Why kept separate |
|
|
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
| `choice-link` vs `application-link` | Share the same `to`/`clickable`/`activate` navigation triad, and both **are** the `<li>` (`selector: 'li[app-…]'`), but bind **different vendored patterns** — CIBG _Keuzelijst_ (`.keuzelijst__link`, `.stretched-link`) vs _Aanvragen_ (`.dashboard-block.applications li a`). Merging would fight the vendored CSS. Extract the shared triad into a mixin only if it grows. |
|
|
| `text-input` / `radio-group` / `checkbox` | Share only the standard Angular **ControlValueAccessor** boilerplate (the `writeValue`/`registerOn*`/`setDisabledState` block). They render genuinely different controls, so they stay three atoms. A base CVA class is the only DRY move — a refactor, not a component merge, and not worth it at three. |
|
|
| `button variant="subtle"` (`.btn-link`) vs `app-link` | A subtle button _looks_ like a link but is an **action** (`<button>`, emits click); `app-link` is **navigation** (`<a routerLink>`). Different semantics and a11y roles → keep both. |
|
|
| `shell` / `page-shell` / `wizard-shell` | Three distinct jobs that **compose**, not overlap: persistent app chrome (mounted once) → routed page body → the wizard form/step frame. |
|
|
| Raw `<h3>` in `application-link` vs the `heading` atom | The vendored `.applications li a h3` chain styles the **bare `<h3>`**; wrapping it in the `app-heading` host element would sit between the anchor and the h3 and can break that selector. This is the one sanctioned raw-heading; everywhere else uses `<app-heading [level]>`. |
|
|
|
|
Single-consumer shared blocks (e.g. `placeholder-chip`, `rich-text-editor`, `checkbox`, the
|
|
`task-list`/`choice-list`/`choice-link` family) currently have one consumer each. They stay in
|
|
`shared` as design-system primitives; relocate one into its consuming context only if it stays
|
|
single-consumer long-term. That is a watch-item, not a merge.
|
|
|
|
The last audit also **removed** a genuinely dead block — a generic white `app-card` with zero
|
|
consumers (superseded by the grey `app-data-block` as the single data surface).
|