From 29f3dcc6cf3606ea8c6d1205946259f436a9b0df Mon Sep 17 00:00:00 2001
From: Niek Otten <not@respellion.nl>
Date: Wed, 1 Jul 2026 13:13:04 +0200
Subject: [PATCH] docs(portal-self-service): record NL DS + DigiD decisions and
 demo note (refs #67)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/demo-script.md        | 23 +++++++++++++++++++++++
 docs/frontend-decisions.md | 24 ++++++++++++++++++++++++
 2 files changed, 47 insertions(+)

diff --git a/docs/demo-script.md b/docs/demo-script.md
index f98d265..8dfcd4d 100644
--- a/docs/demo-script.md
+++ b/docs/demo-script.md
@@ -5,6 +5,29 @@ copy-pasteable walkthrough against a local `make up` stack.
 
 ---
 
+## S-08c — Self-service submit form (NL Design System + DigiD)
+
+**Outcome:** a zorgprofessional logs in via mock DigiD and submits a BIG registration through the
+self-service portal (NL Design System styling); the page confirms with the reference returned by the
+BFF. The bsn comes from the DigiD token, so it's a confirm-and-submit flow (no bsn field).
+
+```bash
+# 1. Bring the backend + Keycloak up (BFF on :8080, Keycloak on :8180).
+make up
+
+# 2. Serve the portal (dev server); it redirects to Keycloak for DigiD login.
+pnpm nx serve self-service        # → http://localhost:4200
+
+# 3. In the browser: log in as the mock DigiD user jan-burger / test123, then submit.
+#    The page shows the returned registration reference.
+```
+
+> First real UI. The full **login → submit → success** happy path is automated in **S-08d**
+> (Playwright, against the compose-served app). Component tests + an axe WCAG 2.1 AA check on the
+> submit page run headless in the `frontend` CI lane. See `docs/frontend-decisions.md`.
+
+---
+
 ## S-08a — Nx workspace + self-service portal skeleton
 
 **Outcome:** the frontend foundation — an Nx (pnpm) monorepo with the `self-service` Angular app
diff --git a/docs/frontend-decisions.md b/docs/frontend-decisions.md
index bbc6dd0..0768bb1 100644
--- a/docs/frontend-decisions.md
+++ b/docs/frontend-decisions.md
@@ -48,3 +48,27 @@ with the submit form (S-08c, #67); any deviation from NL DS will be recorded her
 - The BFF endpoints carry no `operationId`, so orval synthesises method names
   (`postSelfServiceRegistrations`, `getOpenbaarRegister`); adding explicit operation ids to the BFF
   is a possible later polish.
+
+---
+
+## Self-service form: NL DS, DigiD auth, testing (S-08c, #67)
+
+- **NL Design System via `@utrecht/component-library-angular`** (`libs/ui`) + `@utrecht/design-tokens`
+  (imported once in `apps/self-service/src/styles.css`). Utrecht is NL DS's reference Angular
+  implementation. Its v3 components are **NgModule-based, not standalone**, so `libs/ui` re-exports
+  `UtrechtComponentsModule` (and the component classes, so the AOT compiler resolves the template
+  directives through the barrel); standalone components consume it via `imports: [UtrechtComponentsModule]`.
+  §10's "no NgModules in new code" governs *our* code — consuming a third-party module is fine.
+- **DigiD login via `angular-auth-oidc-client`** (`libs/auth`): auth-code + PKCE against the Keycloak
+  `digid` realm (public client `big-portal`). A small **`AuthService` abstraction** (bsn /
+  isAuthenticated / login) wraps the library so components and the `authenticatedGuard` depend on a
+  mockable surface; a **token `HttpInterceptor`** attaches the bearer to BFF calls (secure route).
+  The OIDC `authority`/`secureApiOrigin` are dev defaults in `app.config.ts`; the compose-served app
+  overrides them (S-08d), and the browser-vs-container issuer alignment is handled there (ADR-0010).
+- **Testing:** component tests use **`@testing-library/angular`** (§10) with `AuthService` and the
+  api-client mocked; the **axe** (`vitest-axe`) check runs scoped to WCAG 2.1 AA tags
+  (`wcag2a/2aa/21a/21aa`) with the document `lang` set, asserting zero violations on the submit page.
+  The real DigiD browser round-trip is exercised in S-08d (Playwright).
+- **Module boundaries:** replaced the demo eslint `depConstraints` (`scope:shop`/`scope:shared`, left
+  over from the Nx angular template) with a permissive `*` default; scope/type tags can be
+  introduced when the portal set grows.