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".
This commit is contained in:
Julien Gautier
2026-04-30 18:59:02 +02:00
parent 0e58e32d29
commit c66ef4c7a4
@@ -99,10 +99,12 @@ Preferences are saved per user; an unauthenticated default is read from browser
### Component stack ### 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. - **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. - **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)). 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)).