From c66ef4c7a43ebc2c113208b8b3d63a218b838f84 Mon Sep 17 00:00:00 2001 From: Julien Gautier Date: Thu, 30 Apr 2026 18:59:02 +0200 Subject: [PATCH] docs: amend ADR-0016 to defer the spartan-ng library, keep its philosophy @spartan-ng/brain and @spartan-ng/cli are currently at 0.0.1-alpha.681 - pre-1.0, which trips the project rule against pre-1.0 dependencies ("Pre-1.0 dependencies and one-maintainer projects are rejected unless an ADR justifies the exception", per CLAUDE.md). ADR-0016 originally adopted spartan-ng with the copy-paste mitigation; the alpha state was not anticipated when the ADR was written. Amend ADR-0016 with a dated note: the spartan-ng *library* is deferred until it reaches 1.0.0. The spartan-ng *philosophy* - headless primitives on Angular CDK, Tailwind utility CSS, copy-paste components owned in-source - is unchanged. Components for v1 are written in-house in libs/shared/ui/, on Angular CDK directly. The spartan-ng project is consulted for design inspiration (component patterns, ARIA usage, theming) without taking the dependency. CLAUDE.md Architecture section adjusted accordingly: 'Angular CDK + TailwindCSS' (spartan-ng deferred), with the philosophy still in effect. The amendment is structured as an in-place '> Amended on YYYY-MM-DD' block in the Component stack section, consistent with how ADR-0001's recent path-relocation amendment was handled. Status remains 'accepted' - the design intent did not change, only the dependency selection. The argumentaire in notes/argumentaire-stack-ui-spartan-cdk-tailwind.md is left as-is (gitignored, personal). It still serves to explain to the dev team why we are NOT adopting React-side libs - the conclusion section now reads as "we apply the same philosophy via CDK + Tailwind in-house, deferring the lib until it stabilises". --- .../0016-accessibility-baseline-wcag-aa-targeted-aaa.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/decisions/0016-accessibility-baseline-wcag-aa-targeted-aaa.md b/docs/decisions/0016-accessibility-baseline-wcag-aa-targeted-aaa.md index 5e25280..ccc819f 100644 --- a/docs/decisions/0016-accessibility-baseline-wcag-aa-targeted-aaa.md +++ b/docs/decisions/0016-accessibility-baseline-wcag-aa-targeted-aaa.md @@ -99,10 +99,12 @@ Preferences are saved per user; an unauthenticated default is read from browser ### Component stack -**Angular CDK + spartan-ng + TailwindCSS**. See [`notes/argumentaire-stack-ui-spartan-cdk-tailwind.md`](../notes/argumentaire-stack-ui-spartan-cdk-tailwind.md) for the full rationale produced for the dev team. Summary: +**Angular CDK + TailwindCSS, with spartan-ng-style components written in-house** (the spartan-ng _library_ is deferred — see amendment below). See [`notes/argumentaire-stack-ui-spartan-cdk-tailwind.md`](../../notes/argumentaire-stack-ui-spartan-cdk-tailwind.md) for the original rationale; the design philosophy (headless primitives + Tailwind utility CSS + copy-paste components under our own control) is unchanged. Summary: + +> **Amended on 2026-04-30** — Adoption of the spartan-ng package itself is deferred. At the time of scaffolding (2026-04-30), `@spartan-ng/brain` and `@spartan-ng/cli` were still at version `0.0.1-alpha.681`, which trips the project rule against pre-1.0 dependencies. The mitigation is to apply the spartan-ng _philosophy_ (headless primitives on Angular CDK + Tailwind utility CSS + copy-paste components owned in-source) without depending on the lib. Components for v1 are written in-house, in `libs/shared/ui`, on Angular CDK directly. spartan-ng adoption is revisited when the lib reaches `1.0.0`. - **Angular CDK** (`@angular/cdk`) — primitives accessibility layer maintained by Google's Angular Material team. Equivalent role to Radix UI in React. Provides `Overlay`, `FocusTrap`, `FocusMonitor`, `LiveAnnouncer`, `A11yModule`, `ListKeyManager`, `Drag and Drop`, etc. Battle-tested since 2017. -- **spartan-ng** (https://www.spartan.ng/) — copy-paste component layer built on Angular CDK, styled with Tailwind. Components are checked into our repo (`libs/shared/ui/`) and modified freely. Equivalent role to shadcn/ui in React. +- ~~**spartan-ng**~~ _(deferred — see amendment above)_. Components are written in-house in `libs/shared/ui/`, on Angular CDK, copy-paste-style. The spartan-ng project is consulted for _design inspiration_ (component patterns, ARIA usage, theming approach) without taking the dependency. - **Tailwind CSS** — utility-first styling. Tokens for colour, spacing, contrast tiers live in `libs/shared/tokens/`. The contrast tiers map directly to the user preference modes above. Angular Material is **rejected** because its visual design system (Material Design) is opinionated in ways that clash with both APF branding and the multi-tier contrast requirements. React-ecosystem libraries (shadcn/ui, dice-ui, animate-ui) are rejected as incompatible with the Angular stack ([ADR-0004](0004-frontend-stack-angular-csr-zoneless-signals.md)).