@lifechangers/ui
v1.1.4
Published
Design system du LIFE Hub : maquette « Claude Design » (jetons --dc-*, coquille du gabarit unique, briques React) pour toute nouvelle app, et l'ancienne DA LIFE CHANGERS (--lc-*) gardée pour les apps qui l'importent encore.
Maintainers
Readme
@lifechangers/ui — design system du LIFE Hub
Le socle visuel commun des applications du LIFE Hub : tokens clair et sombre, polices, texture de
marque « alvéoles iridescentes », logos et icônes (apps, domaines, sections) en composants React.
Direction « D · Épurée » validée par Redouane le 2026-09-05 sur les maquettes DonCollect
(_DOCS/DESIGN-SYSTEM/maquettes/).
Ce dépôt est l'étape 1 du chantier C3 du plan
_DOCS/DESIGN-SYSTEM/00-PLAN-HARMONISATION-DA-NAVIGATION.md.
Le suivi est dans ROADMAP-TODOLIST.md.
Démarrer une nouvelle app (1.0, maquette « Claude Design »)
Depuis la 1.0.0 (18/10/2026), toute nouvelle app du hub part de la maquette « Claude Design » : jetons --dc-*
(indigo #4C3C9F, pêche #FFEEE1, encre #17181C, Big Shoulders, Barlow Condensed, DM Sans), la coquille du
gabarit unique (GABARIT-COQUILLE.md) et les briques. Tout est
repris des apps en production (DonCollect main, Finance main). Vitrine : showcase/coquille/index.html
(npm run build:vitrine). Page du hub : KIT-NOUVELLE-APP.md.
Trois règles : toute couleur passe par un jeton --dc-* ; aucune donnée fictive (un compteur sans valeur
réelle ne s'affiche pas) ; la composition des pages reste propre au métier de l'app (le kit fournit la coquille
et les briques, pas les tableaux de bord).
1. Installer (dans le dossier de l'app)
npm install @lifechangers/ui@^12. Charger la feuille et les utilitaires
/* Tailwind 3 — src/index.css */
@import "@lifechangers/ui/dc.css"; /* polices + jetons + coquille + briques */// tailwind.config.ts
import dc from "@lifechangers/ui/dc/tailwind-preset";
export default { presets: [dc], darkMode: ["class"], content: ["./index.html", "./src/**/*.{ts,tsx}"] };/* Tailwind 4 — src/styles.css. Les polices par un <link> dans __root.tsx (la chaîne CSS de Tailwind 4
prend un @import url() pour un fichier local) :
https://fonts.googleapis.com/css2?family=Big+Shoulders+Display:wght@700;800&family=Barlow+Condensed:wght@600;700&family=DM+Sans:opsz,[email protected],400..700&display=swap */
@import "tailwindcss";
@import "@lifechangers/ui/dc/tokens.css";
@import "@lifechangers/ui/dc/composants.css";
@import "@lifechangers/ui/dc/theme.tailwind4.css";
@custom-variant dark (&:is(.dark *));Utilitaires : bg-dc-peche, text-dc-encre, bg-dc-g1, rounded-dc-carte, shadow-dc-carte, font-dc-titre…
3. Brancher shadcn — importer le pont en dernier (après le thème de l'app), depuis main.tsx :
import "@lifechangers/ui/dc/shadcn-bridge.css" (Tailwind 3) ou …/dc/shadcn-bridge-tw4.css (Tailwind 4).
Les composants shadcn prennent l'indigo, la pêche et le mode sombre sans être modifiés.
4. Écrire la carte de navigation et l'adaptateur de lien — les espaces du rail et leurs entrées, depuis le
métier de l'app ; le lien du routeur de l'app (react-router et TanStack prennent to) :
import { Link } from "react-router-dom";
import type { Espace, LienProps } from "@lifechangers/ui";
export const Lien = ({ href, ...p }: LienProps) => <Link to={href} {...p} />;
export const ESPACES: Espace[] = [
{ id: "pilotage", libelle: "Pilotage", court: "Pilotage", entrees: [{ id: "accueil", libelle: "Tableau de bord", href: "/" }] },
{ id: "aide", libelle: "Aide", court: "Aide", bas: true, entrees: [{ id: "centre", libelle: "Centre d'aide", href: "/aide" }] },
];5. Monter la coquille autour des routes, avec l'organisation et le compte de l'app :
import { Coquille } from "@lifechangers/ui";
<Coquille
app={{ nom: "Tasks", logo: <AppSwitcherDeLApp /> }}
espaces={ESPACES}
actif={{ espace: "pilotage", entree: "accueil" }} // calculé depuis l'adresse
Lien={Lien}
organisation={{ active, liste, changer: switchOrg, creer }} // le hook d'organisation de l'app
compte={{ nom, email, photo, profil, deconnexion, theme: { sombre, basculer } }}
recherche={{ libelle: "Rechercher…", ouvrir: ouvrirPalette }}
actions={<Bouton taille="s">Créer</Bouton>}
outils={<><AideContextuelle /><Notifications /></>}
cleStockage="tk_barre_espace_repliee"
>
<Outlet />
</Coquille>Puis composer les pages avec les briques (EnTeteVue, Carte, TuileChiffre, Tableau, Pastille,
EtatVide, EtatErreur…) et les données réelles de l'app. Contrôle : npm run check dans la bibliothèque.
Ce que contient la 1.0
| Chemin | Rôle |
|---|---|
| src/dc.css | Point d'entrée : polices, jetons, coquille et briques |
| src/dc/tokens.css | Jetons --dc-* clair et sombre (.dark ou [data-theme="dark"]) |
| src/dc/tailwind-preset.cjs · src/dc/theme.tailwind4.css | Utilitaires dc-* pour Tailwind 3 et Tailwind 4 |
| src/dc/shadcn-bridge.css · src/dc/shadcn-bridge-tw4.css | Pont shadcn (valeurs du back-office DonCollect) |
| src/dc/composants.css | Feuille des composants (classes dcui-*), CSS pur, sans couleur en dur |
| src/dc/Coquille.tsx | Coquille, Rail, BarreEspace, BarreHaut, TuileCompte, SelecteurOrganisation, BarreOnglets |
| src/dc/briques.tsx · src/dc/Tableau.tsx | Hex, Bouton, Carte, CarteTitre, TuileChiffre, EnTeteVue, Pastille, Puce, Bientot, états, Tableau |
| check/coquille.check.tsx | Contrôle de rendu de la coquille et des briques |
| vitrine/ → showcase/coquille/ | Vitrine montée avec les composants |
Exports JS : tout est dans @lifechangers/ui ; @lifechangers/ui/dc ne donne que la nouvelle DA.
Marque par asso (1.1)
Chaque asso règle sa marque dans Center ; la bibliothèque la transforme en variables. Guide et règles pour les
maquettes : docs/MARQUE.md. Sans marque, ou avec celle de LIFE, rien ne change.
| Export | Rôle |
|---|---|
| @lifechangers/ui/marque | Sans React ni Supabase : MarqueOrga, MARQUE_DEFAUT, jetonsDepuisMarque(marque, "clair" \| "sombre", { pont }), cssDepuisMarque, lienPolicesGoogle, estMarqueDefaut, appliquerMarque, appliquerInstantaneMarque, contraste (contraste, nuanceLisible, texteSur…) |
| @lifechangers/ui/marque/react | useMarqueOrga({ orgId, lireMarque, pont }) → { marque, chargement } |
| OrganisationCoquille.logo / logoSombre | Logo de l'orga dans le sélecteur d'organisation, à la place de l'hexagone |
Tests : npm test (vitest), dont la règle d'or « défaut = feuilles actuelles, jeton par jeton ».
Ancienne DA LIFE CHANGERS (0.x, --lc-*)
Tout ce qui suit décrit l'ancienne DA violette, gardée telle quelle dans la 1.0 (mêmes chemins, mêmes composants) tant que Studio, Bridge et Center l'importent. Ne pas l'utiliser pour une nouvelle app.
Ce que contient le package
| Chemin | Rôle |
|---|---|
| src/tokens/tokens.css | Toutes les variables --lc-* : couleurs (clair, sombre, accent par organisation), rayons, ombres, typographie, espacements, mouvement |
| src/tokens/tailwind-preset.cjs | Preset Tailwind 3 pour les 10 apps Lovable (React 18) |
| src/tokens/theme.tailwind4.css | Thème Tailwind 4 (@theme inline) pour les 6 apps TanStack Start (React 19) |
| src/fonts/fonts.css | Jeu libre actif (Anton, Archivo, JetBrains Mono) et emplacements du jeu officiel (Agharti, Acumin) |
| src/brand/texture.css | Surface de marque texturée, bouton principal, tuiles, médaillons, avatars (généré) |
| src/brand/logos/ | Emblème, logo application, principal, horizontal, vertical — dégradé et monochromes, SVG |
| src/tokens/shadcn-bridge.css | Le pont : donne aux variables de thème shadcn les valeurs des --lc-*. Une app l'importe et change de direction artistique sans qu'un composant soit modifié. Généré |
| src/react/ | Marque et icônes (BrandMark, AppIcon, DomainIcon, SectionIcon, HexAvatar), shell (AppShell, Sidebar, Topbar, PageHeader, DetailDrawer), primitives (Button, Pill, Card, StatCard, Segmented, FilterChip, EmptyState), données (DataTable, Honeycomb, SmoothAreaChart, DailyBars), et le style validé du 12/09 (SidebarRail, AiBar, HeroTitle, MiniTile, IconTile) |
| scripts/shadcn_bridge.py | Génère le pont, le pose dans une app (--to), dit s'il a dérivé (--check) |
| scripts/apply_to_app.py | Branche une app entière en une commande, ou vérifie qu'elle l'est (--check) |
| check/render.check.tsx | Contrôle de rendu sans framework (npm run check) |
| dist/ | JavaScript transpilé + déclarations de types, construits par npm run build (tsup). Une app ne compile jamais le TypeScript d'une dépendance |
| scripts/glyphs.py | Source de vérité des glyphes d'icônes ; scripts/build.py régénère CSS, TSX et vitrine |
| showcase/index.html | Page vitrine autonome : tout le package dans les deux thèmes |
Comment la bibliothèque arrive dans les applications (décision du 2026-09-12)
Le hub compte 14 applications, une par dépôt, réparties en deux familles, et elles ne se branchent pas pareil.
| Famille | Apps | Ce qu'elles reçoivent |
|---|---|---|
| Tailwind 3 + shadcn (Vite, déployées par Lovable) | 10 : Center, Bridge, CRM, DonCollect, Engage, People, Pilot, Projects, Studio, Tasks | shadcn-bridge.css posé par commande dans l'app |
| Tailwind 4 + TanStack Start | 4 : Drive, Finance, RGPD, Video | shadcn-bridge-tw4.css posé par la même commande, polices chargées par lien |
Pourquoi un fichier posé et non une dépendance pour la première famille, alors qu'une dépendance serait plus élégante :
- Ces apps sont construites par Lovable. Un fichier déjà présent dans le dépôt n'a rien à installer, rien à authentifier, rien à construire au moment du déploiement. Une dépendance ajoute trois points de panne dans un environnement qu'on ne contrôle pas.
- Lovable réécrit du code. Le pont agit sur les variables de thème de shadcn : tout composant que Lovable régénère hérite de la direction artistique sans rien savoir d'elle. Une bibliothèque de composants React, elle, se ferait écraser.
- Une copie posée ne dérive pas. Elle porte la version, la commande qui la régénère, et
--checkla compare à la bibliothèque. Ce n'est pas une copie recopiée, c'est une copie vérifiée.
La deuxième famille reçoit elle aussi une copie posée, par la même commande : un seul mécanisme pour
tout le hub. Ses polices sont chargées par un lien dans __root.tsx et non par un @import url() dans la
feuille, que la chaîne CSS de Tailwind 4 prend pour un fichier local.
La cible reste npm. Le jour où l'organisation @lifechangers existe sur npm, npm publish suffit :
le champ files n'embarque ni la démo ni ses chiffres réels. D'ici là le dépôt git fait le travail
pour la seconde famille, et la copie posée pour la première.
Brancher une application
Aujourd'hui — la bibliothèque n'est pas encore publiée
Le dépôt est local et n'a pas de dépôt distant. En attendant, une app reçoit une copie posée par la bibliothèque, pas une copie recopiée à la main : elle porte le numéro de version et la commande qui la régénère, et une commande dit si elle a dérivé.
cd DESIGN-SYSTEM/life-design-system
python3 scripts/apply_to_app.py ../../CENTER/life-suite-hub # brancher
python3 scripts/apply_to_app.py ../../CENTER/life-suite-hub --check # vérifierLa commande fait trois choses et ne touche aucun composant de l'app : elle pose
src/styles/lifechangers-da.css, l'importe dans src/main.tsx après ./index.css, et fait lire
var(--font-sans) / var(--font-display) à tailwind.config.ts. Elle est idempotente : la relancer
après un changement de couleur met la copie à jour.
Retour arrière dans une app : supprimer la ligne d'import dans src/main.tsx. Rien d'autre.
Deux pièges, vérifiés sur le CSS construit :
- le pont doit être importé après
index.css, depuismain.tsx. Tailwind 3 retire les at-rules@layerau build : seul l'ordre des règles dans le bundle décide. Importé depuis le haut d'index.css, il passe avant le thème d'origine et n'a aucun effet ; - si
tailwind.config.tscode les polices en dur, elles ne changent pas, quoi que disent les tokens.
Pour s'en assurer, la nouvelle valeur doit arriver en dernier :
npx vite build && grep -bo -- "--primary: [0-9][^;]*" dist/assets/*.cssAjouter une application qui n'existe pas encore
Rien de particulier : apply_to_app.py <chemin> suffit dès que l'app a un package.json, un
src/main.tsx qui importe ./index.css, et un tailwind.config.ts. C'est le cas du modèle d'app du hub.
La commande refuse et dit ce qui manque plutôt que de deviner.
Garde-fou
apply_to_app.py --check sort en erreur si le pont est absent, s'il a dérivé, s'il est importé au mauvais
endroit ou si les polices sont codées en dur. C'est la commande à mettre en intégration continue sur
chaque app du hub.
Après publication
npm install @lifechangers/ui # dans le dossier de l'APPLICATION, jamais dans celui de la bibliothèqueLancée depuis
DESIGN-SYSTEM/life-design-system, cette commande ajoute la bibliothèque comme dépendance d'elle-même. Sans gravité, mais à annuler :npm uninstall @lifechangers/ui.
/* src/index.css */
@import "@lifechangers/ui/index.css";// src/main.tsx — après "./index.css"
import "@lifechangers/ui/shadcn-bridge.css";App Lovable (React 18, Tailwind 3)
// tailwind.config.ts
import preset from "@lifechangers/ui/tailwind-preset";
export default { presets: [preset], content: ["./index.html", "./src/**/*.{ts,tsx}"] };App TanStack Start (React 19, Tailwind 4)
/* src/styles.css */
@import "tailwindcss";
@import "@lifechangers/ui/index.css";
@import "@lifechangers/ui/theme.tailwind4.css";Composants
import { AppIcon, DomainIcon, SectionIcon, BrandMark, HexAvatar } from "@lifechangers/ui";
<AppIcon app="doncollect" size={40} />
<DomainIcon domain="eau" size={32} />
<SectionIcon name="dons" />
<HexAvatar initials="RB" brand />Poser data-lc (ou la classe lc-root) sur le conteneur racine pour hériter du fond, de la couleur et
de la police. Le thème sombre suit prefers-color-scheme ; data-theme="dark" ou "light" sur <html>
force un thème.
Règles d'emploi
- Une surface texturée par écran au maximum (
.lc-surface-brand,.lc-btn-brand,AppIcon,HexAvatar brand) : bouton principal, tuile d'app, avatar d'équipe, panneau de connexion, en-tête d'email, progression. Jamais derrière un tableau, un formulaire ou un texte long. - Violet en clair, turquoise en sombre : l'accent change de couleur avec le thème pour rester lisible.
Le turquoise
#00B5BCde la charte n'est jamais utilisé en texte sur fond clair (contraste 2,2:1). - Couleur par organisation (décision D1) : une organisation cliente pose
data-org-accentet--lc-org-accentsur ses surfaces publiques (page de don, widget, email). LIFE garde le violet. - Aucune couleur en dur dans les apps : tout passe par
--lc-*ou les utilitaires Tailwindlc-*. - Polices : rôles fixes (display, corps, condensé, mono). Le jeu officiel (Agharti + Acumin) remplace le jeu libre par les tokens, sans toucher aux apps, quand les licences sont achetées.
Changer une couleur, une icône, une police
Toujours au même endroit, jamais dans une app :
| Quoi | Où | Puis |
|---|---|---|
| une couleur, un rayon, une ombre | src/tokens/tokens.css | npm run build:bridge, puis apply_to_app.py <app> sur chaque app branchée |
| une icône | scripts/glyphs.py | python3 scripts/build.py |
| la texture | scripts/texture.py | python3 scripts/build.py |
| un composant | src/react/*.tsx | npm run typecheck && npm run check && npm run build |
Les fichiers marqués « généré » en en-tête ne s'éditent pas à la main : ils seront écrasés.
Régénérer les fichiers dérivés
python3 scripts/build.pyModifie scripts/glyphs.py pour les icônes et scripts/texture.py pour la texture ; ne touche pas aux
fichiers marqués « généré ».
