From 8329fa133d61f3bfd7ff98cf3c37a14c5a467f0b Mon Sep 17 00:00:00 2001
From: Julien Gautier <jgautier.webdev@gmail.com>
Date: Tue, 12 May 2026 01:17:30 +0200
Subject: [PATCH] refactor(libs): graduate Icon / LayoutStateService / brand
 tokens to libs/shared/* (#99)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

Per ADR-0020 §"Shared-libs graduation": the three primitives that `portal-shell` (today) and `portal-admin` (next) will both share move out of `apps/portal-shell/src/` and into the workspace libs. Mechanical move — no behaviour change, prepares the ground for the admin-app PR.

## Graduated

| Primitive | Old location | New location |
|---|---|---|
| `Icon` component (+ `IconName` type) | `apps/portal-shell/src/app/components/icon/` | [`libs/shared/ui/src/lib/icon/`](libs/shared/ui/src/lib/icon/) |
| `LayoutStateService` (+ `ThemeMode` type) | `apps/portal-shell/src/app/state/` | [`libs/shared/state/src/lib/`](libs/shared/state/src/lib/) |
| Brand-palette `@theme` block | `apps/portal-shell/src/styles.css` | [`libs/shared/tokens/src/brand-tokens.css`](libs/shared/tokens/src/brand-tokens.css) |

## Notable changes

- **Icon selector renamed `app-icon` → `lib-icon`.** Required by the lib's ESLint `@angular-eslint/component-selector` rule (prefix `lib` for shared libs). All ~20 usages in `portal-shell` templates updated in one sweep.
- **New `shared-state` library** generated via `nx g @nx/angular:library libs/shared/state`. Mirrors the existing `feature-auth` / `shared-ui` shape (vite + Angular + spec setup). `tsconfig.base.json` path alias `shared-state` added by the generator.
- **Lib tags rebalanced** to satisfy the module-boundary lint rule:
  - `shared-state`: new lib → `scope:shared, type:shared`.
  - `shared-ui`: was `scope:portal-shell` (scaffold default) → `scope:shared, type:shared`.
- **`shared-tokens` is now CSS-only.** The placeholder TS function is gone; `index.ts` is an empty `export {}` with a TODO note. Vitest config flips `passWithNoTests: true` so the test target stops failing on the empty lib.
- **`portal-shell`'s `styles.css`** drops the inline `@theme {}` block and instead `@import`s `../../../libs/shared/tokens/src/brand-tokens.css`. Both apps will read the same source.
- Placeholder scaffolded files in `shared-ui/src/lib/shared-ui/` removed.

## Verification

- `nx run-many -t lint test build` across `portal-shell, shared-ui, shared-state, shared-tokens` — green.
- Tests redistributed: **portal-shell 28**, **shared-state 9**, **shared-ui 3**, **shared-tokens 0** = 40 total (same as before the move).
- Production build: **128.7 KB gzip** initial per locale (was 128.5 KB on `main` — noise-level delta).
- Brand-color CSS variables (`--color-brand-primary-500: #12546c`, …) still inlined in the produced `styles-*.css`.
- `dist/.../browser/{en,fr}/` emitted as expected.

## What this PR explicitly does NOT do

- Move other components (Header, Sidebar, Footer, ThemeSwitcher, LocaleSwitcher). Those are app-specific shell concerns; if `portal-admin` ends up needing them, they graduate in their own PR.
- Set up `portal-admin`. That's the next PR on the admin track — and now imports from `shared-ui` / `shared-state` / `shared-tokens` will Just Work.
- Refactor `feature-auth`'s tagging. It still says `scope:portal-shell`; revisit when the auth implementation actually lands and the dual-audience design (per ADR-0008) makes the right scope obvious.

## Test plan

- [x] Per-project run-many — green.
- [x] Production build emits both locales with brand tokens applied.
- [ ] Manual: `pnpm exec nx serve portal-shell` — the dev experience is unchanged.
- [ ] Manual: serve-static + locale switcher / theme switcher / sidebar collapse / navigation — all the behaviours the moved primitives drive still work in production.

---------

Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr>
Reviewed-on: https://git.unespace.com/julien/apf_portal/pulls/99
---
 .../src/app/components/header/header.html     |  8 +--
 .../src/app/components/header/header.spec.ts  |  2 +-
 .../src/app/components/header/header.ts       |  4 +-
 .../locale-switcher/locale-switcher.html      |  6 +--
 .../locale-switcher/locale-switcher.ts        |  2 +-
 .../src/app/components/sidebar/sidebar.html   |  6 +--
 .../src/app/components/sidebar/sidebar.ts     |  4 +-
 .../theme-switcher/theme-switcher.html        |  6 +--
 .../theme-switcher/theme-switcher.spec.ts     |  2 +-
 .../theme-switcher/theme-switcher.ts          |  4 +-
 apps/portal-shell/src/styles.css              | 51 ++-----------------
 apps/portal-shell/tsconfig.app.json           | 10 +++-
 libs/shared/state/README.md                   |  7 +++
 libs/shared/state/eslint.config.mjs           | 34 +++++++++++++
 libs/shared/state/project.json                | 13 +++++
 libs/shared/state/src/index.ts                |  1 +
 .../src/lib}/layout-state.service.spec.ts     |  0
 .../state/src/lib}/layout-state.service.ts    |  0
 libs/shared/state/src/test-setup.ts           |  5 ++
 libs/shared/state/tsconfig.json               | 23 +++++++++
 libs/shared/state/tsconfig.lib.json           | 26 ++++++++++
 libs/shared/state/tsconfig.spec.json          | 23 +++++++++
 libs/shared/state/vite.config.mts             | 28 ++++++++++
 libs/shared/tokens/src/brand-tokens.css       | 46 +++++++++++++++++
 libs/shared/tokens/src/index.ts               |  8 ++-
 .../tokens/src/lib/shared-tokens.spec.ts      |  7 ---
 libs/shared/tokens/src/lib/shared-tokens.ts   |  3 --
 libs/shared/tokens/vitest.config.mts          |  3 ++
 libs/shared/ui/project.json                   |  2 +-
 libs/shared/ui/src/index.ts                   |  2 +-
 .../shared/ui/src/lib}/icon/icon.spec.ts      | 10 ++--
 .../shared/ui/src/lib}/icon/icon.ts           | 12 ++---
 .../shared/ui/src/lib/shared-ui/shared-ui.css |  0
 .../ui/src/lib/shared-ui/shared-ui.html       |  1 -
 .../ui/src/lib/shared-ui/shared-ui.spec.ts    | 21 --------
 libs/shared/ui/src/lib/shared-ui/shared-ui.ts |  9 ----
 tsconfig.base.json                            |  3 +-
 37 files changed, 267 insertions(+), 125 deletions(-)
 create mode 100644 libs/shared/state/README.md
 create mode 100644 libs/shared/state/eslint.config.mjs
 create mode 100644 libs/shared/state/project.json
 create mode 100644 libs/shared/state/src/index.ts
 rename {apps/portal-shell/src/app/state => libs/shared/state/src/lib}/layout-state.service.spec.ts (100%)
 rename {apps/portal-shell/src/app/state => libs/shared/state/src/lib}/layout-state.service.ts (100%)
 create mode 100644 libs/shared/state/src/test-setup.ts
 create mode 100644 libs/shared/state/tsconfig.json
 create mode 100644 libs/shared/state/tsconfig.lib.json
 create mode 100644 libs/shared/state/tsconfig.spec.json
 create mode 100644 libs/shared/state/vite.config.mts
 create mode 100644 libs/shared/tokens/src/brand-tokens.css
 delete mode 100644 libs/shared/tokens/src/lib/shared-tokens.spec.ts
 delete mode 100644 libs/shared/tokens/src/lib/shared-tokens.ts
 rename {apps/portal-shell/src/app/components => libs/shared/ui/src/lib}/icon/icon.spec.ts (85%)
 rename {apps/portal-shell/src/app/components => libs/shared/ui/src/lib}/icon/icon.ts (87%)
 delete mode 100644 libs/shared/ui/src/lib/shared-ui/shared-ui.css
 delete mode 100644 libs/shared/ui/src/lib/shared-ui/shared-ui.html
 delete mode 100644 libs/shared/ui/src/lib/shared-ui/shared-ui.spec.ts
 delete mode 100644 libs/shared/ui/src/lib/shared-ui/shared-ui.ts

diff --git a/apps/portal-shell/src/app/components/header/header.html b/apps/portal-shell/src/app/components/header/header.html
index aac8858..e7693dc 100644
--- a/apps/portal-shell/src/app/components/header/header.html
+++ b/apps/portal-shell/src/app/components/header/header.html
@@ -29,7 +29,7 @@
       <div
         class="flex w-full max-w-xl items-center gap-2 rounded-full border border-gray-200 bg-gray-50 px-4 py-2 focus-within:border-brand-primary-500 focus-within:bg-white focus-within:ring-2 focus-within:ring-brand-primary-200 dark:border-gray-700 dark:bg-gray-800 dark:focus-within:border-brand-primary-300 dark:focus-within:bg-gray-900 dark:focus-within:ring-brand-primary-700"
       >
-        <app-icon name="search" [size]="18" />
+        <lib-icon name="search" [size]="18" />
         <input
           id="global-search"
           type="search"
@@ -47,7 +47,7 @@
         i18n-aria-label="@@header.action.notifications"
         aria-label="Notifications"
       >
-        <app-icon name="bell" />
+        <lib-icon name="bell" />
         <span
           aria-hidden="true"
           class="absolute right-2 top-2 h-2 w-2 rounded-full bg-brand-accent-400 ring-2 ring-white dark:ring-gray-900"
@@ -59,7 +59,7 @@
         i18n-aria-label="@@header.action.help"
         aria-label="Help"
       >
-        <app-icon name="circle-help" />
+        <lib-icon name="circle-help" />
       </button>
       <app-theme-switcher />
       <button
@@ -68,7 +68,7 @@
         i18n-aria-label="@@header.action.settings"
         aria-label="Settings"
       >
-        <app-icon name="settings" />
+        <lib-icon name="settings" />
       </button>
       <span
         i18n-aria-label="@@header.action.userMenu"
diff --git a/apps/portal-shell/src/app/components/header/header.spec.ts b/apps/portal-shell/src/app/components/header/header.spec.ts
index 4e650ee..244d6dc 100644
--- a/apps/portal-shell/src/app/components/header/header.spec.ts
+++ b/apps/portal-shell/src/app/components/header/header.spec.ts
@@ -1,7 +1,7 @@
 import { TestBed } from '@angular/core/testing';
 import { provideRouter } from '@angular/router';
 import { Header } from './header';
-import { LayoutStateService } from '../../state/layout-state.service';
+import { LayoutStateService } from 'shared-state';
 
 describe('Header', () => {
   beforeEach(async () => {
diff --git a/apps/portal-shell/src/app/components/header/header.ts b/apps/portal-shell/src/app/components/header/header.ts
index 05710ba..2240519 100644
--- a/apps/portal-shell/src/app/components/header/header.ts
+++ b/apps/portal-shell/src/app/components/header/header.ts
@@ -1,8 +1,8 @@
 import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
 import { RouterLink } from '@angular/router';
-import { Icon } from '../icon/icon';
+import { Icon } from 'shared-ui';
 import { ThemeSwitcher } from '../theme-switcher/theme-switcher';
-import { LayoutStateService } from '../../state/layout-state.service';
+import { LayoutStateService } from 'shared-state';
 
 /**
  * Top-of-page banner.
diff --git a/apps/portal-shell/src/app/components/locale-switcher/locale-switcher.html b/apps/portal-shell/src/app/components/locale-switcher/locale-switcher.html
index ca49c7d..89de522 100644
--- a/apps/portal-shell/src/app/components/locale-switcher/locale-switcher.html
+++ b/apps/portal-shell/src/app/components/locale-switcher/locale-switcher.html
@@ -4,9 +4,9 @@
   [cdkMenuTriggerFor]="localeMenu"
   [attr.aria-label]="triggerAriaLabel"
 >
-  <app-icon name="globe" [size]="14" />
+  <lib-icon name="globe" [size]="14" />
   <span>{{ currentDisplayName }}</span>
-  <app-icon name="chevron-down" [size]="12" />
+  <lib-icon name="chevron-down" [size]="12" />
 </button>
 
 <ng-template #localeMenu>
@@ -30,7 +30,7 @@
     >
       <span class="locale-switcher__label">{{ locale.displayName }}</span>
       @if (locale.code === currentCode) {
-      <app-icon name="check" [size]="16" />
+      <lib-icon name="check" [size]="16" />
       }
     </button>
     }
diff --git a/apps/portal-shell/src/app/components/locale-switcher/locale-switcher.ts b/apps/portal-shell/src/app/components/locale-switcher/locale-switcher.ts
index 74e42e8..86563a7 100644
--- a/apps/portal-shell/src/app/components/locale-switcher/locale-switcher.ts
+++ b/apps/portal-shell/src/app/components/locale-switcher/locale-switcher.ts
@@ -1,7 +1,7 @@
 import { DOCUMENT } from '@angular/common';
 import { CdkMenu, CdkMenuItem, CdkMenuTrigger } from '@angular/cdk/menu';
 import { ChangeDetectionStrategy, Component, ViewEncapsulation, inject } from '@angular/core';
-import { Icon } from '../icon/icon';
+import { Icon } from 'shared-ui';
 
 /**
  * Locale switcher rendered in the footer.
diff --git a/apps/portal-shell/src/app/components/sidebar/sidebar.html b/apps/portal-shell/src/app/components/sidebar/sidebar.html
index 6976d0f..257d22e 100644
--- a/apps/portal-shell/src/app/components/sidebar/sidebar.html
+++ b/apps/portal-shell/src/app/components/sidebar/sidebar.html
@@ -31,7 +31,7 @@
             [attr.aria-label]="collapsed() ? item.label : null"
             [title]="collapsed() ? item.label : ''"
           >
-            <app-icon [name]="item.icon" />
+            <lib-icon [name]="item.icon" />
             @if (!collapsed()) {
             <span class="sidebar__label">{{ item.label }}</span>
             }
@@ -43,7 +43,7 @@
             [attr.aria-label]="collapsed() ? item.label : null"
             [title]="collapsed() ? item.label : ''"
           >
-            <app-icon [name]="item.icon" />
+            <lib-icon [name]="item.icon" />
             @if (!collapsed()) {
             <span class="sidebar__label">{{ item.label }}</span>
             }
@@ -77,7 +77,7 @@
       [attr.aria-expanded]="!collapsed()"
       [attr.aria-label]="toggleAriaLabel()"
     >
-      <app-icon [name]="collapsed() ? 'chevron-right' : 'chevron-left'" />
+      <lib-icon [name]="collapsed() ? 'chevron-right' : 'chevron-left'" />
       @if (!collapsed()) {
       <span class="sidebar__label" i18n="@@sidebar.toggle.collapse">Collapse</span>
       }
diff --git a/apps/portal-shell/src/app/components/sidebar/sidebar.ts b/apps/portal-shell/src/app/components/sidebar/sidebar.ts
index c1486aa..b495204 100644
--- a/apps/portal-shell/src/app/components/sidebar/sidebar.ts
+++ b/apps/portal-shell/src/app/components/sidebar/sidebar.ts
@@ -1,7 +1,7 @@
 import { ChangeDetectionStrategy, Component, computed, inject } from '@angular/core';
 import { RouterLink, RouterLinkActive } from '@angular/router';
-import { Icon, type IconName } from '../icon/icon';
-import { LayoutStateService } from '../../state/layout-state.service';
+import { Icon, type IconName } from 'shared-ui';
+import { LayoutStateService } from 'shared-state';
 
 /**
  * Primary side navigation.
diff --git a/apps/portal-shell/src/app/components/theme-switcher/theme-switcher.html b/apps/portal-shell/src/app/components/theme-switcher/theme-switcher.html
index 44c1335..c244318 100644
--- a/apps/portal-shell/src/app/components/theme-switcher/theme-switcher.html
+++ b/apps/portal-shell/src/app/components/theme-switcher/theme-switcher.html
@@ -4,7 +4,7 @@
   [cdkMenuTriggerFor]="themeMenu"
   [attr.aria-label]="triggerAriaLabel()"
 >
-  <app-icon [name]="currentIcon()" />
+  <lib-icon [name]="currentIcon()" />
 </button>
 
 <ng-template #themeMenu>
@@ -25,10 +25,10 @@
       role="menuitemradio"
       (click)="select(option.mode)"
     >
-      <app-icon [name]="option.icon" />
+      <lib-icon [name]="option.icon" />
       <span class="theme-switcher__label">{{ option.label }}</span>
       @if (mode() === option.mode) {
-      <app-icon name="check" [size]="16" />
+      <lib-icon name="check" [size]="16" />
       }
     </button>
     }
diff --git a/apps/portal-shell/src/app/components/theme-switcher/theme-switcher.spec.ts b/apps/portal-shell/src/app/components/theme-switcher/theme-switcher.spec.ts
index 033170c..74f4aaf 100644
--- a/apps/portal-shell/src/app/components/theme-switcher/theme-switcher.spec.ts
+++ b/apps/portal-shell/src/app/components/theme-switcher/theme-switcher.spec.ts
@@ -1,5 +1,5 @@
 import { TestBed } from '@angular/core/testing';
-import { LayoutStateService } from '../../state/layout-state.service';
+import { LayoutStateService } from 'shared-state';
 import { ThemeSwitcher } from './theme-switcher';
 
 describe('ThemeSwitcher', () => {
diff --git a/apps/portal-shell/src/app/components/theme-switcher/theme-switcher.ts b/apps/portal-shell/src/app/components/theme-switcher/theme-switcher.ts
index 642741b..50e2ffb 100644
--- a/apps/portal-shell/src/app/components/theme-switcher/theme-switcher.ts
+++ b/apps/portal-shell/src/app/components/theme-switcher/theme-switcher.ts
@@ -6,8 +6,8 @@ import {
   computed,
   inject,
 } from '@angular/core';
-import { Icon, type IconName } from '../icon/icon';
-import { LayoutStateService, type ThemeMode } from '../../state/layout-state.service';
+import { Icon, type IconName } from 'shared-ui';
+import { LayoutStateService, type ThemeMode } from 'shared-state';
 
 /**
  * Light / dark / auto color-scheme switcher rendered in the header.
diff --git a/apps/portal-shell/src/styles.css b/apps/portal-shell/src/styles.css
index f94bca5..9713bed 100644
--- a/apps/portal-shell/src/styles.css
+++ b/apps/portal-shell/src/styles.css
@@ -1,10 +1,9 @@
 /*
  * Global styles for portal-shell.
  *
- * Tailwind CSS 4 (CSS-first config). Theme tokens (palette, contrast tiers,
- * spacing, motion) will be defined under @theme via the libs/shared/tokens
- * library. spartan-ng components copy-pasted into libs/shared/ui will read
- * from these tokens.
+ * Tailwind CSS 4 (CSS-first config). The brand palette lives in
+ * `libs/shared/tokens/src/brand-tokens.css` so every app in the
+ * workspace (`portal-shell`, `portal-admin`) reads the same source.
  */
 
 @import 'tailwindcss';
@@ -19,45 +18,5 @@
  */
 @custom-variant dark (&:where(.dark, .dark *));
 
-/*
- * Brand palette — APF charte graphique.
- *
- *   primary: #12546c (dark teal)  — header bar, sidebar active items,
- *                                   primary buttons, headings on light bg
- *   accent:  #f7a919 (warm orange) — CTAs, highlights, focus rings on
- *                                    branded surfaces
- *
- * The two scales below are hand-tuned (each step roughly halves the
- * delta from the previous toward white / black). Tailwind v4 surfaces
- * them automatically as utility classes — `bg-brand-primary-700`,
- * `text-brand-accent-500`, `ring-brand-primary-500`, etc.
- *
- * Use the `500` step as the canonical brand value; the lighter / darker
- * steps are for hover / focus / muted text without dropping out of the
- * brand family.
- */
-@theme {
-  --color-brand-primary-50: #eaf3f7;
-  --color-brand-primary-100: #cae0e8;
-  --color-brand-primary-200: #9ac4d2;
-  --color-brand-primary-300: #5fa2b6;
-  --color-brand-primary-400: #2f7f96;
-  --color-brand-primary-500: #12546c;
-  --color-brand-primary-600: #0f475c;
-  --color-brand-primary-700: #0c394a;
-  --color-brand-primary-800: #082a36;
-  --color-brand-primary-900: #051c24;
-  --color-brand-primary-950: #020e12;
-
-  --color-brand-accent-50: #fef5e0;
-  --color-brand-accent-100: #fce6b3;
-  --color-brand-accent-200: #fad17a;
-  --color-brand-accent-300: #f8bb47;
-  --color-brand-accent-400: #f7a919;
-  --color-brand-accent-500: #de9415;
-  --color-brand-accent-600: #b97a11;
-  --color-brand-accent-700: #93600d;
-  --color-brand-accent-800: #6e4709;
-  --color-brand-accent-900: #4a3006;
-  --color-brand-accent-950: #271903;
-}
+/* Brand palette tokens — shared with `portal-admin` once it ships. */
+@import '../../../libs/shared/tokens/src/brand-tokens.css';
diff --git a/apps/portal-shell/tsconfig.app.json b/apps/portal-shell/tsconfig.app.json
index 2ee35fa..c951182 100644
--- a/apps/portal-shell/tsconfig.app.json
+++ b/apps/portal-shell/tsconfig.app.json
@@ -5,5 +5,13 @@
     "types": ["@angular/localize"]
   },
   "include": ["src/**/*.ts"],
-  "exclude": ["src/**/*.spec.ts", "src/**/*.test.ts"]
+  "exclude": ["src/**/*.spec.ts", "src/**/*.test.ts"],
+  "references": [
+    {
+      "path": "../../libs/shared/ui"
+    },
+    {
+      "path": "../../libs/shared/state"
+    }
+  ]
 }
diff --git a/libs/shared/state/README.md b/libs/shared/state/README.md
new file mode 100644
index 0000000..52f8324
--- /dev/null
+++ b/libs/shared/state/README.md
@@ -0,0 +1,7 @@
+# shared-state
+
+This library was generated with [Nx](https://nx.dev).
+
+## Running unit tests
+
+Run `nx test shared-state` to execute the unit tests.
diff --git a/libs/shared/state/eslint.config.mjs b/libs/shared/state/eslint.config.mjs
new file mode 100644
index 0000000..8e41cc1
--- /dev/null
+++ b/libs/shared/state/eslint.config.mjs
@@ -0,0 +1,34 @@
+import nx from '@nx/eslint-plugin';
+import baseConfig from '../../../eslint.config.mjs';
+
+export default [
+  ...nx.configs['flat/angular'],
+  ...nx.configs['flat/angular-template'],
+  ...baseConfig,
+  {
+    files: ['**/*.ts'],
+    rules: {
+      '@angular-eslint/directive-selector': [
+        'error',
+        {
+          type: 'attribute',
+          prefix: 'lib',
+          style: 'camelCase',
+        },
+      ],
+      '@angular-eslint/component-selector': [
+        'error',
+        {
+          type: 'element',
+          prefix: 'lib',
+          style: 'kebab-case',
+        },
+      ],
+    },
+  },
+  {
+    files: ['**/*.html'],
+    // Override or add rules here
+    rules: {},
+  },
+];
diff --git a/libs/shared/state/project.json b/libs/shared/state/project.json
new file mode 100644
index 0000000..b56011b
--- /dev/null
+++ b/libs/shared/state/project.json
@@ -0,0 +1,13 @@
+{
+  "name": "shared-state",
+  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/shared/state/src",
+  "prefix": "lib",
+  "projectType": "library",
+  "tags": ["scope:shared", "type:shared"],
+  "targets": {
+    "lint": {
+      "executor": "@nx/eslint:lint"
+    }
+  }
+}
diff --git a/libs/shared/state/src/index.ts b/libs/shared/state/src/index.ts
new file mode 100644
index 0000000..6f50c4e
--- /dev/null
+++ b/libs/shared/state/src/index.ts
@@ -0,0 +1 @@
+export { LayoutStateService, type ThemeMode } from './lib/layout-state.service';
diff --git a/apps/portal-shell/src/app/state/layout-state.service.spec.ts b/libs/shared/state/src/lib/layout-state.service.spec.ts
similarity index 100%
rename from apps/portal-shell/src/app/state/layout-state.service.spec.ts
rename to libs/shared/state/src/lib/layout-state.service.spec.ts
diff --git a/apps/portal-shell/src/app/state/layout-state.service.ts b/libs/shared/state/src/lib/layout-state.service.ts
similarity index 100%
rename from apps/portal-shell/src/app/state/layout-state.service.ts
rename to libs/shared/state/src/lib/layout-state.service.ts
diff --git a/libs/shared/state/src/test-setup.ts b/libs/shared/state/src/test-setup.ts
new file mode 100644
index 0000000..17b7965
--- /dev/null
+++ b/libs/shared/state/src/test-setup.ts
@@ -0,0 +1,5 @@
+import '@angular/compiler';
+import '@analogjs/vitest-angular/setup-snapshots';
+import { setupTestBed } from '@analogjs/vitest-angular/setup-testbed';
+
+setupTestBed();
diff --git a/libs/shared/state/tsconfig.json b/libs/shared/state/tsconfig.json
new file mode 100644
index 0000000..116e088
--- /dev/null
+++ b/libs/shared/state/tsconfig.json
@@ -0,0 +1,23 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "emitDecoratorMetadata": false,
+    "module": "preserve"
+  },
+  "angularCompilerOptions": {
+    "enableI18nLegacyMessageIdFormat": false,
+    "strictInjectionParameters": true,
+    "strictInputAccessModifiers": true,
+    "strictTemplates": true
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}
diff --git a/libs/shared/state/tsconfig.lib.json b/libs/shared/state/tsconfig.lib.json
new file mode 100644
index 0000000..a9b98ba
--- /dev/null
+++ b/libs/shared/state/tsconfig.lib.json
@@ -0,0 +1,26 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../../dist/out-tsc",
+    "declaration": true,
+    "declarationMap": true,
+    "inlineSources": true,
+    "types": []
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": [
+    "src/**/*.spec.ts",
+    "src/**/*.test.ts",
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx",
+    "src/test-setup.ts"
+  ]
+}
diff --git a/libs/shared/state/tsconfig.spec.json b/libs/shared/state/tsconfig.spec.json
new file mode 100644
index 0000000..39a8c3f
--- /dev/null
+++ b/libs/shared/state/tsconfig.spec.json
@@ -0,0 +1,23 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../../dist/out-tsc",
+    "types": ["vitest/globals", "vitest/importMeta", "vite/client", "node", "vitest"]
+  },
+  "include": [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx",
+    "src/**/*.d.ts"
+  ],
+  "files": ["src/test-setup.ts"]
+}
diff --git a/libs/shared/state/vite.config.mts b/libs/shared/state/vite.config.mts
new file mode 100644
index 0000000..10136c8
--- /dev/null
+++ b/libs/shared/state/vite.config.mts
@@ -0,0 +1,28 @@
+/// <reference types='vitest' />
+import { defineConfig } from 'vite';
+import angular from '@analogjs/vite-plugin-angular';
+import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
+import { nxCopyAssetsPlugin } from '@nx/vite/plugins/nx-copy-assets.plugin';
+
+export default defineConfig(() => ({
+  root: __dirname,
+  cacheDir: '../../../node_modules/.vite/libs/shared/state',
+  plugins: [angular(), nxViteTsPaths(), nxCopyAssetsPlugin(['*.md'])],
+  // Uncomment this if you are using workers.
+  // worker: {
+  //   plugins: () => [ nxViteTsPaths() ],
+  // },
+  test: {
+    name: 'shared-state',
+    watch: false,
+    globals: true,
+    environment: 'jsdom',
+    include: ['{src,tests}/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+    setupFiles: ['src/test-setup.ts'],
+    reporters: ['default'],
+    coverage: {
+      reportsDirectory: '../../../coverage/libs/shared/state',
+      provider: 'v8' as const,
+    },
+  },
+}));
diff --git a/libs/shared/tokens/src/brand-tokens.css b/libs/shared/tokens/src/brand-tokens.css
new file mode 100644
index 0000000..f02177e
--- /dev/null
+++ b/libs/shared/tokens/src/brand-tokens.css
@@ -0,0 +1,46 @@
+/*
+ * Brand palette — APF charte graphique.
+ *
+ *   primary: #12546c (dark teal)  — header bar, sidebar active items,
+ *                                   primary buttons, headings on light bg
+ *   accent:  #f7a919 (warm orange) — CTAs, highlights, focus rings on
+ *                                    branded surfaces
+ *
+ * The two scales below are hand-tuned (each step roughly halves the
+ * delta from the previous toward white / black). Tailwind v4 surfaces
+ * them automatically as utility classes — `bg-brand-primary-700`,
+ * `text-brand-accent-500`, `ring-brand-primary-500`, etc.
+ *
+ * Use the `500` step as the canonical brand value; the lighter / darker
+ * steps are for hover / focus / muted text without dropping out of the
+ * brand family.
+ *
+ * Owned by `libs/shared/tokens` so every app in the workspace
+ * (`portal-shell`, `portal-admin`) reads from the same source. To
+ * consume, `@import` this file from the app's entry stylesheet.
+ */
+@theme {
+  --color-brand-primary-50: #eaf3f7;
+  --color-brand-primary-100: #cae0e8;
+  --color-brand-primary-200: #9ac4d2;
+  --color-brand-primary-300: #5fa2b6;
+  --color-brand-primary-400: #2f7f96;
+  --color-brand-primary-500: #12546c;
+  --color-brand-primary-600: #0f475c;
+  --color-brand-primary-700: #0c394a;
+  --color-brand-primary-800: #082a36;
+  --color-brand-primary-900: #051c24;
+  --color-brand-primary-950: #020e12;
+
+  --color-brand-accent-50: #fef5e0;
+  --color-brand-accent-100: #fce6b3;
+  --color-brand-accent-200: #fad17a;
+  --color-brand-accent-300: #f8bb47;
+  --color-brand-accent-400: #f7a919;
+  --color-brand-accent-500: #de9415;
+  --color-brand-accent-600: #b97a11;
+  --color-brand-accent-700: #93600d;
+  --color-brand-accent-800: #6e4709;
+  --color-brand-accent-900: #4a3006;
+  --color-brand-accent-950: #271903;
+}
diff --git a/libs/shared/tokens/src/index.ts b/libs/shared/tokens/src/index.ts
index 4915f95..6e38c18 100644
--- a/libs/shared/tokens/src/index.ts
+++ b/libs/shared/tokens/src/index.ts
@@ -1 +1,7 @@
-export * from './lib/shared-tokens';
+// `shared-tokens` is currently CSS-only — see `./brand-tokens.css`,
+// which apps import from their entry stylesheet (e.g.
+// `apps/portal-shell/src/styles.css`). The TS module exists so the
+// Nx lib boilerplate / package layout stays uniform with the other
+// shared libs; expand when a typed token API (e.g. CSS-variable
+// name constants for runtime lookups) is genuinely needed.
+export {};
diff --git a/libs/shared/tokens/src/lib/shared-tokens.spec.ts b/libs/shared/tokens/src/lib/shared-tokens.spec.ts
deleted file mode 100644
index b9fc896..0000000
--- a/libs/shared/tokens/src/lib/shared-tokens.spec.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-import { sharedTokens } from './shared-tokens';
-
-describe('sharedTokens', () => {
-  it('should work', () => {
-    expect(sharedTokens()).toEqual('shared-tokens');
-  });
-});
diff --git a/libs/shared/tokens/src/lib/shared-tokens.ts b/libs/shared/tokens/src/lib/shared-tokens.ts
deleted file mode 100644
index 2e2c8c6..0000000
--- a/libs/shared/tokens/src/lib/shared-tokens.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-export function sharedTokens(): string {
-  return 'shared-tokens';
-}
diff --git a/libs/shared/tokens/vitest.config.mts b/libs/shared/tokens/vitest.config.mts
index e44534d..81c8506 100644
--- a/libs/shared/tokens/vitest.config.mts
+++ b/libs/shared/tokens/vitest.config.mts
@@ -12,6 +12,9 @@ export default defineConfig(() => ({
     globals: true,
     environment: 'node',
     include: ['{src,tests}/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+    // CSS-only library — no TS to test yet. Pass instead of failing
+    // the gate; revisit when a typed token API lands.
+    passWithNoTests: true,
     reporters: ['default'],
     coverage: {
       reportsDirectory: '../../../coverage/libs/shared/tokens',
diff --git a/libs/shared/ui/project.json b/libs/shared/ui/project.json
index 3f44d25..803c896 100644
--- a/libs/shared/ui/project.json
+++ b/libs/shared/ui/project.json
@@ -4,7 +4,7 @@
   "sourceRoot": "libs/shared/ui/src",
   "prefix": "lib",
   "projectType": "library",
-  "tags": ["scope:portal-shell", "type:shared"],
+  "tags": ["scope:shared", "type:shared"],
   "targets": {
     "lint": {
       "executor": "@nx/eslint:lint"
diff --git a/libs/shared/ui/src/index.ts b/libs/shared/ui/src/index.ts
index 59dee3e..e648a49 100644
--- a/libs/shared/ui/src/index.ts
+++ b/libs/shared/ui/src/index.ts
@@ -1 +1 @@
-export * from './lib/shared-ui/shared-ui';
+export { Icon, type IconName } from './lib/icon/icon';
diff --git a/apps/portal-shell/src/app/components/icon/icon.spec.ts b/libs/shared/ui/src/lib/icon/icon.spec.ts
similarity index 85%
rename from apps/portal-shell/src/app/components/icon/icon.spec.ts
rename to libs/shared/ui/src/lib/icon/icon.spec.ts
index fa8f1de..b59bed9 100644
--- a/apps/portal-shell/src/app/components/icon/icon.spec.ts
+++ b/libs/shared/ui/src/lib/icon/icon.spec.ts
@@ -3,9 +3,9 @@ import { TestBed } from '@angular/core/testing';
 import { Icon } from './icon';
 
 @Component({
-  selector: 'app-icon-test-host',
+  selector: 'lib-icon-test-host',
   imports: [Icon],
-  template: `<app-icon [name]="name" [size]="size" [strokeWidth]="strokeWidth" />`,
+  template: `<lib-icon [name]="name" [size]="size" [strokeWidth]="strokeWidth" />`,
 })
 class IconTestHost {
   name: 'home' | 'bell' = 'home';
@@ -21,7 +21,7 @@ describe('Icon', () => {
   it('renders a lucide <svg> for the given name', async () => {
     const fixture = TestBed.createComponent(IconTestHost);
     await fixture.whenStable();
-    const svg = fixture.nativeElement.querySelector('app-icon svg') as SVGElement | null;
+    const svg = fixture.nativeElement.querySelector('lib-icon svg') as SVGElement | null;
     expect(svg).not.toBeNull();
     expect(svg?.classList.contains('lucide')).toBe(true);
   });
@@ -30,7 +30,7 @@ describe('Icon', () => {
     const fixture = TestBed.createComponent(IconTestHost);
     await fixture.whenStable();
     const host = fixture.nativeElement.querySelector(
-      'app-icon lucide-angular',
+      'lib-icon lucide-angular',
     ) as HTMLElement | null;
     expect(host?.getAttribute('aria-hidden')).toBe('true');
   });
@@ -41,7 +41,7 @@ describe('Icon', () => {
     fixture.componentInstance.strokeWidth = 2;
     fixture.detectChanges();
     await fixture.whenStable();
-    const svg = fixture.nativeElement.querySelector('app-icon svg') as SVGElement | null;
+    const svg = fixture.nativeElement.querySelector('lib-icon svg') as SVGElement | null;
     expect(svg?.getAttribute('width')).toBe('32');
     expect(svg?.getAttribute('height')).toBe('32');
     expect(svg?.getAttribute('stroke-width')).toBe('2');
diff --git a/apps/portal-shell/src/app/components/icon/icon.ts b/libs/shared/ui/src/lib/icon/icon.ts
similarity index 87%
rename from apps/portal-shell/src/app/components/icon/icon.ts
rename to libs/shared/ui/src/lib/icon/icon.ts
index c0cc980..394267b 100644
--- a/apps/portal-shell/src/app/components/icon/icon.ts
+++ b/libs/shared/ui/src/lib/icon/icon.ts
@@ -29,19 +29,19 @@ import {
 } from 'lucide-angular';
 
 /**
- * Icon façade for the SPA.
+ * Icon façade — single point of truth for the icon set across every
+ * app in the workspace (`portal-shell` today, `portal-admin` next).
  *
  * v1 is backed by `lucide-angular`. The migration to an in-house
- * icomoon-generated set (sprite SVG under
- * `apps/portal-shell/public/icons/`) is a single-file change to
- * THIS component — every consumer just writes `<app-icon name="…">`,
+ * icomoon-generated set (sprite SVG) is a single-file change to
+ * THIS component — every consumer just writes `<lib-icon name="…">`,
  * so swapping the implementation never touches them.
  *
  * Convention: `name` is the lowercase, kebab-cased "logical" name we
  * will keep across implementations (`home`, `bar-chart`, etc.). The
  * registry below maps each logical name to its lucide-angular icon
  * data. When the icomoon export lands, each name will instead map to
- * a `<symbol id="icon-…">` in the sprite — but the template-side
+ * a `<symbol id="icon-…">` in the sprite — the template-side
  * contract stays identical.
  */
 
@@ -79,7 +79,7 @@ const ICON_REGISTRY = {
 export type IconName = keyof typeof ICON_REGISTRY;
 
 @Component({
-  selector: 'app-icon',
+  selector: 'lib-icon',
   imports: [LucideAngularModule],
   template: `<lucide-angular
     [img]="icon()"
diff --git a/libs/shared/ui/src/lib/shared-ui/shared-ui.css b/libs/shared/ui/src/lib/shared-ui/shared-ui.css
deleted file mode 100644
index e69de29..0000000
diff --git a/libs/shared/ui/src/lib/shared-ui/shared-ui.html b/libs/shared/ui/src/lib/shared-ui/shared-ui.html
deleted file mode 100644
index 3585dd1..0000000
--- a/libs/shared/ui/src/lib/shared-ui/shared-ui.html
+++ /dev/null
@@ -1 +0,0 @@
-<p>SharedUi works!</p>
diff --git a/libs/shared/ui/src/lib/shared-ui/shared-ui.spec.ts b/libs/shared/ui/src/lib/shared-ui/shared-ui.spec.ts
deleted file mode 100644
index f267a25..0000000
--- a/libs/shared/ui/src/lib/shared-ui/shared-ui.spec.ts
+++ /dev/null
@@ -1,21 +0,0 @@
-import { ComponentFixture, TestBed } from '@angular/core/testing';
-import { SharedUi } from './shared-ui';
-
-describe('SharedUi', () => {
-  let component: SharedUi;
-  let fixture: ComponentFixture<SharedUi>;
-
-  beforeEach(async () => {
-    await TestBed.configureTestingModule({
-      imports: [SharedUi],
-    }).compileComponents();
-
-    fixture = TestBed.createComponent(SharedUi);
-    component = fixture.componentInstance;
-    await fixture.whenStable();
-  });
-
-  it('should create', () => {
-    expect(component).toBeTruthy();
-  });
-});
diff --git a/libs/shared/ui/src/lib/shared-ui/shared-ui.ts b/libs/shared/ui/src/lib/shared-ui/shared-ui.ts
deleted file mode 100644
index 7b19e89..0000000
--- a/libs/shared/ui/src/lib/shared-ui/shared-ui.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-import { Component } from '@angular/core';
-
-@Component({
-  selector: 'lib-shared-ui',
-  imports: [],
-  templateUrl: './shared-ui.html',
-  styleUrl: './shared-ui.css',
-})
-export class SharedUi {}
diff --git a/tsconfig.base.json b/tsconfig.base.json
index 8d3300a..8f14b4e 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -6,7 +6,8 @@
       "shared-tokens": ["./libs/shared/tokens/src/index.ts"],
       "shared-util": ["./libs/shared/util/src/index.ts"],
       "shared-ui": ["./libs/shared/ui/src/index.ts"],
-      "feature-auth": ["./libs/feature/auth/src/index.ts"]
+      "feature-auth": ["./libs/feature/auth/src/index.ts"],
+      "shared-state": ["./libs/shared/state/src/index.ts"]
     },
     "sourceMap": true,
     "declaration": false,