docs: bijwerk documentatie voor Container en box-shadow tokens (v5.2.0, v5.3.0)

Jeffrey Lauwers · claude · Jeffrey Lauwers · commit eae941cf7ad9 · 2026-03-06T23:01:21.000+01:00
- README.md: Layout Components 3→4, Container toegevoegd aan tabel en compositie-voorbeelden
- docs/README.md: versie bijgewerkt naar 5.3.0, componenttelling 37→41, tests 880→962
- docs/03-components.md: Container sectie toegevoegd aan Layout Components, statistieken bijgewerkt (40→41)
- docs/changelog.md: v5.2.0 (box-shadow tokens) en v5.3.0 (Container) toegevoegd
- packages/components-react/README.md: Layout Components sectie toegevoegd (Container, Grid, GridItem, Stack), Display &amp; Feedback en ButtonLink/LinkButton aangevuld

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -162,13 +162,14 @@ All components are fully typed with TypeScript and include comprehensive JSDoc d
 
 ### Current Components
 
-**Layout Components (3)**
+**Layout Components (4)**
 
-| Component    | HTML/CSS | React | Web Component |
-| ------------ | -------- | ----- | ------------- |
-| **Grid**     | Yes      | Yes   | —             |
-| **GridItem** | Yes      | Yes   | —             |
-| **Stack**    | Yes      | Yes   | —             |
+| Component     | HTML/CSS | React | Web Component |
+| ------------- | -------- | ----- | ------------- |
+| **Container** | Yes      | Yes   | —             |
+| **Grid**      | Yes      | Yes   | —             |
+| **GridItem**  | Yes      | Yes   | —             |
+| **Stack**     | Yes      | Yes   | —             |
 
 **Content Components (9)**
 
@@ -228,6 +229,27 @@ See the [Documentation](./docs/) for full component details and specifications.
 
 Components are designed to compose together:
 
+**Layout Components**
+
+```jsx
+// React — Container als visueel kader voor gerelateerde content
+<Container>
+  <Heading level={2}>Sectie</Heading>
+  <Paragraph>Inhoud van de container.</Paragraph>
+</Container>
+
+// React — Elevated container met schaduw (bijv. kaart)
+<Container elevated as="article">
+  <Paragraph>Dit is een elevated container.</Paragraph>
+</Container>
+
+// React — Grid met Containers als items
+<Grid contained>
+  <GridItem colSpan={8}><Container>Hoofdinhoud</Container></GridItem>
+  <GridItem colSpan={4}><Container>Sidebar</Container></GridItem>
+</Grid>
+```
+
 **Content Components**
 
 ```jsx
diff --git a/docs/03-components.md b/docs/03-components.md
@@ -1,6 +1,6 @@
 # Components
 
-**Last Updated:** March 5, 2026
+**Last Updated:** March 6, 2026
 
 Complete component specifications and guidelines for the Design System Starter Kit.
 
@@ -155,7 +155,61 @@ Components are designed to compose together:
 
 ## Layout Components
 
-Layout components bieden structuur voor paginalayouts zonder eigen visuele stijl. Ze zijn pure CSS-utilities.
+Layout components bieden structuur voor paginalayouts. Container heeft een visuele stijl; Grid en Stack zijn pure CSS-utilities.
+
+### Container
+
+Visueel kader voor het groeperen van gerelateerde content. Voegt achtergrond, border, border-radius en padding toe. De `elevated` variant voegt een lichte `box-shadow.sm` schaduw toe voor kaarten en panelen.
+
+**HTML/CSS:**
+
+```html
+<!-- Standaard container -->
+<div class="dsn-container">
+  <p class="dsn-paragraph">Inhoud van de container.</p>
+</div>
+
+<!-- Elevated container (kaart, paneel) -->
+<div class="dsn-container dsn-container--elevated">
+  <p class="dsn-paragraph">Elevated container.</p>
+</div>
+
+<!-- Als semantisch article -->
+<article class="dsn-container">
+  <p class="dsn-paragraph">Artikel-inhoud.</p>
+</article>
+```
+
+**React:**
+
+```tsx
+// Standaard
+<Container>
+  <Paragraph>Inhoud van de container.</Paragraph>
+</Container>
+
+// Elevated
+<Container elevated>
+  <Paragraph>Elevated container.</Paragraph>
+</Container>
+
+// Met semantisch element
+<Container as="article">
+  <Paragraph>Artikel-inhoud.</Paragraph>
+</Container>
+
+// Als kader rondom Grid-items
+<Grid contained>
+  <GridItem colSpan={8}><Container>Hoofdinhoud</Container></GridItem>
+  <GridItem colSpan={4}><Container>Sidebar</Container></GridItem>
+</Grid>
+```
+
+**Props:** `as` (`div` | `section` | `article` | `aside`, default `div`), `elevated` (boolean, default `false`).
+
+**Design tokens:** `--dsn-container-background-color`, `--dsn-container-border-color`, `--dsn-container-border-radius`, `--dsn-container-border-width`, `--dsn-container-box-shadow`, `--dsn-container-color`, `--dsn-container-padding-block`, `--dsn-container-padding-inline`, `--dsn-container-elevated-box-shadow`.
+
+---
 
 ### Grid
 
@@ -950,12 +1004,12 @@ defineButton('my-custom-button');
 
 ## Component Statistics
 
-**Total Components:** 40
+**Total Components:** 41
 
 **Implementations:**
 
-- **HTML/CSS:** 40 components
-- **React:** 40 components (962 tests total)
+- **HTML/CSS:** 41 components
+- **React:** 41 components (962 tests total)
 - **Web Component:** 7 components (Button, Heading, Icon, Link, OrderedList, Paragraph, UnorderedList)
 
 **Test Coverage:** 962 tests across 46 test suites
diff --git a/docs/README.md b/docs/README.md
@@ -1,7 +1,7 @@
 # Design System Documentation
 
-**Version:** 4.9.0
-**Last Updated:** March 5, 2026
+**Version:** 5.3.0
+**Last Updated:** March 6, 2026
 
 Complete documentation voor het Design System Starter Kit.
 
@@ -83,8 +83,8 @@ Complete documentation voor het Design System Starter Kit.
 
 - **Tokens per configuration:** ~1100 (400 semantic + 700 component)
 - **Configurations:** 8 (2 themes × 2 modes × 2 project types)
-- **Components:** 37 implemented (9 content + 3 display/feedback + 25 form; HTML/CSS + React)
-- **Tests:** 880 across 43 test suites
+- **Components:** 41 (4 layout + 9 content + 3 display/feedback + 25 form; HTML/CSS + React)
+- **Tests:** 962 across 46 test suites
 - **Storybook stories:** 130+
 
 ---
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -6,6 +6,37 @@ All notable changes to this project are documented in this file.
 
 ---
 
+## Version 5.3.0 (March 6, 2026)
+
+### Container layout component (PR #75, issue #74)
+
+- **Container component** (`dsn-container`) — Visueel kader voor het groeperen van gerelateerde content
+- `elevated` variant via `--dsn-container-elevated-box-shadow` → `box-shadow.sm` (kaarten, panelen, demo-wrappers)
+- `as` prop: `div` (default), `section`, `article`, `aside` — semantiek losgekoppeld van stijl
+- 9 component tokens: `background-color`, `border-color`, `border-radius`, `border-width`, `box-shadow`, `color`, `padding-block`, `padding-inline`, `elevated.box-shadow`
+- React `forwardRef` met `as`-prop casting via `React.Ref<HTMLDivElement>`
+- Storybook: Default, Elevated, ElevatedWithContent, AllStates stories
+- Stack en Grid stories: placeholder `Box` component vervangen door `Container` als inhoud-items
+- HTML/CSS export toegevoegd aan `components-html/package.json`
+
+---
+
+## Version 5.2.0 (March 6, 2026)
+
+### Elevatie box-shadow tokens: sm, md, lg (PR #73, issue #72)
+
+- **Drie semantische schaduw-niveaus**: `sm` (cards), `md` (dropdowns/tooltips), `lg` (modals)
+- Elke shadow bestaat uit 3 lagen: directe schaduw + ambient schaduw + spread-only outline (highlight)
+- **Kleurtokens** in `colors-light.json` / `colors-dark.json`: `dsn.color.shadow.{direct,ambient,highlight}`
+- **Shorthand tokens** in `base.json`: `dsn.box-shadow.{sm,md,lg}` als string met embedded SD-referenties
+- SD v3 aanpak: `outputReferences: true` resolvet embedded `{dsn.color.shadow.*}` naar `var(--dsn-color-shadow-*)` in CSS-output
+- Light mode: `highlight: transparent` (no-op); Dark mode: `highlight: color-mix(in srgb, white 8%, transparent)`
+- Dark mode: `direct` 60%, `ambient` 40% (zwart) — schaduwen bewust minder prominent
+- Wireframe thema: `box-shadow.sm/md/lg: none` (alles flat)
+- Storybook `TokenTable`: `previewType="shadow"` toont kaartje met shadow, reageert op theme/mode wisseling
+
+---
+
 ## Version 5.1.0 (March 5, 2026)
 
 ### Grid en GridItem layout componenten met 12 kolommen (PR #71, issue #21)
diff --git a/packages/components-react/README.md b/packages/components-react/README.md
@@ -45,16 +45,31 @@ function App() {
 
 ## Available Components
 
+### Layout Components
+
+- **Container** - Visueel kader voor het groeperen van gerelateerde content (achtergrond, border, padding, optionele schaduw)
+- **Grid** - 12-koloms CSS Grid container met gutter, outer margin en optionele max-width
+- **GridItem** - Grid child met colSpan (1–12), responsive varianten en fullBleed prop
+- **Stack** - Verticale stapeling met consistente ruimte via flexbox + gap (9 space-varianten)
+
 ### Content Components
 
 - **Button** - Primary action component with variants and sizes
+- **ButtonLink** - Semantisch `<a>`, visueel als Button (navigatie met hoge attentiewaarde)
 - **Heading** - Semantic heading component (h1-h6)
 - **Icon** - SVG icon component with 45+ icons
 - **Link** - Anchor element with external link support
+- **LinkButton** - Semantisch `<button>`, visueel als Link (JS-acties met lage attentiewaarde)
 - **OrderedList** - Numbered list component
 - **Paragraph** - Text paragraph component
 - **UnorderedList** - Bulleted list component
 
+### Display & Feedback Components
+
+- **Alert** - Belangrijk bericht met `role="alert"` (4 varianten: info, positive, negative, warning)
+- **Note** - Passieve notitie zonder live region (5 varianten incl. neutral)
+- **StatusBadge** - Compact inline label met signaalkleur (5 varianten)
+
 ### Form Components
 
 - **TextInput** - Single-line text input
