RootCX UI

Le thème et les composants des applications RootCX, distribués comme un registry shadcn/ui officiel.

Ce dépôt est aussi l'unique source du package npm @rootcx/ui. La vitrine, le registry et le package utilisent les mêmes fichiers dans src/components/ui et src/globals.css. Les applications consomment le package sans conserver de copie du thème.

Utiliser le package npm

Prérequis : React 19 et Tailwind CSS 4.

npm install @rootcx/ui

/* src/globals.css : point d'entrée complet du thème */
@import "@rootcx/ui/theme.css";

import { Button, TooltipProvider, Toaster } from "@rootcx/ui";
// Les imports par composant sont aussi disponibles :
import { Field, FieldLabel } from "@rootcx/ui/components/field";

Ce CSS inclut Tailwind, les animations, Inter et la détection des classes du package. Monter TooltipProvider à la racine et Toaster une fois si nécessaire. Le thème est clair ; aucun ThemeProvider n'est requis.

Langue des composants

Les composants n'affichent eux-mêmes que quelques textes : boutons de fermeture, libellés pour lecteurs d'écran, titre de la navigation mobile. Ils sont en anglais par défaut et fournis en français, allemand, espagnol et italien :

import { UiLabelsProvider } from "@rootcx/ui";

<UiLabelsProvider locale={locale}>        {/* "fr", "de-DE", "es"… ; inconnu → anglais */}
  <App />
</UiLabelsProvider>

// Autre langue ou formulation maison : surcharger tout ou partie des textes.
<UiLabelsProvider locale="fr" labels={{ close: "Refermer" }}>…</UiLabelsProvider>

Chaque texte reste surchargeable au cas par cas : closeLabel sur DialogContent et SheetContent, aria-label sur SidebarTrigger, Breadcrumb, Spinner et Table, mobileTitle / mobileDescription sur Sidebar. Tout texte métier (titres, descriptions, libellés d'actions) reste fourni par l'application.

bun run build:package  # dist-package/ : JavaScript et déclarations TypeScript
npm pack              # archive installable localement ; ne publie rien

Le package conserve les API composables du design. DataGrid fournit la grille interactive commune ; les applications gèrent les données, formulaires, statuts et navigation. Voir le guide de la grille pour l’intégration, les sources serveur, les interactions clavier et l’édition optionnelle.

Un espace de travail minimaliste et précis : base blanche, Inter, filets translucides, matières perlées et signature bleue #009EFF discrète. La spécification complète est dans DESIGN.md.

• Base : shadcn/ui Radix, style Nova, Tailwind CSS v4, icônes Tabler.
• Vitrine : bun run dev → http://localhost:5794 (écran de démonstration et galerie).
• Registry : registry.json (source) → public/r/*.json (généré par shadcn build).

Installer dans une application

Prérequis : une app React + Vite avec Tailwind v4 et shadcn initialisé en base Radix.

# App neuve
npx shadcn@latest init --template vite --base radix

1. Déclarer le registry dans components.json :

   {
     "registries": {
       "@rootcx": "https://<hôte-du-registry>/r/{name}.json"
     }
   }

2. Installer le style complet (thème, police Inter, utilitaires et tous les composants) :

   npx shadcn@latest add @rootcx/style

   Ou seulement une partie :

   npx shadcn@latest add @rootcx/theme          # variables, typographie, rayons, ombres
   npx shadcn@latest add @rootcx/button @rootcx/badge @rootcx/property-list

3. Monter TooltipProvider à la racine, et Toaster une fois si les notifications sont utilisées.

Le thème est clair uniquement. Si le template d'init ajoute un ThemeProvider, le fixer sur light. Si le preset d'init a ajouté une autre police (par exemple @import "@fontsource-variable/geist" dans le CSS), supprimer cette ligne : Inter est installée par l'item font-inter.

Contenu du registry

| Item | Type | Rôle | | --- | --- | --- | | style | registry:style | Tout le système en une commande | | theme | registry:theme | Variables, @theme, règles de base, utilitaire tabular, préférences d'accessibilité ; dépend de font-inter | | utils | registry:lib | cn() | | use-mobile | registry:hook | Point de rupture mobile | | page | registry:ui | PageFrame, PagePanel, PageTopbar, PageTopbarActions, Page, PageHeader, PageHeading, PageTitle, PageDescription, PageActions, PageToolbar, IconTile | | property-list | registry:ui | PropertyList, PropertyRow, PropertyLabel, PropertyValue, PropertySection | | metric-card | registry:ui | MetricCard, bande MetricStrip et élément Metric | | data-grid, data-grid-types, data-grid-view-options | registry:ui | Grille interactive, moteur useDataGrid, types et réglages des colonnes ; sélection, copie, édition optionnelle, lignes virtualisées | | context-menu | registry:ui | Menu contextuel Radix dans le thème commun | | alert, alert-dialog, avatar, badge, breadcrumb, button, button-group, card, checkbox, dialog, dropdown-menu, empty, field, input, input-group, kbd, label, native-select, popover, progress, scroll-area, select, separator, sheet, sidebar, skeleton, sonner, spinner, switch, table, tabs, textarea, toggle, toggle-group, tooltip | registry:ui | Composants shadcn aux variantes du thème |

Variantes ajoutées

• Button : outline (action courante), default (action décisive, bleu profond avec texte blanc), secondary (rempli gris), ghost, toolbar (icône nue), soft, destructive, link.
• Badge : blanc bordé ; neutral, info, success, warning, destructive, violet colorent l'icône ou le BadgeDot ; secondary pour les compteurs ; mint, teal, lavender, pink, yellow, blue pour les étiquettes pastel ; ColorSwatch.
• Tabs : default, segmented, line ; TabsCount.
• ToggleGroup : default, outline, segmented.
• SelectTrigger : variant="filled".
• Card : variant="raised".

Utilitaires du thème

glass-chrome, glass-floating, bg-action, text-action-foreground, bg-primary, bg-primary-soft, bg-surface, bg-surface-raised, bg-field, bg-selection, text-placeholder, text-icon, bg-info / bg-success / bg-warning / bg-destructive / bg-violet / bg-green, bg-pastel-* + text-pastel-*-foreground, text-page, text-record, text-display, text-metric, h-(--header-height), h-(--row-height), px-(--page-gutter), tabular.

Développer

bun install
bun run dev             # vitrine sur :5794, registry servi sous /r/
bun run build           # vérification des types + build de la vitrine
bun run registry:build  # régénère registry.json puis public/r/
bun run registry:check  # échoue si registry.json ne correspond plus aux sources
bun run test           # sélection et presse-papiers
bun run test:browser   # interactions de la grille, Chrome requis

Les sources font foi :

| Fichier | Rôle | | --- | --- | | src/globals.css | Thème | | src/components/ui/ | Composants distribués | | src/lib/utils.ts, src/hooks/use-mobile.ts | Utilitaires distribués | | scripts/build-registry.mjs | Génère registry.json (dépendances lues dans les imports) | | src/demo/ | Vitrine, non distribuée |

Après toute modification d'un composant ou du thème : bun run registry:build, puis commiter registry.json et public/r/.

Pour tester le registry localement, la vitrine le sert sur http://localhost:5794/r/{name}.json (déjà configuré dans components.json de ce dépôt).

Pour comparer un composant avec l'amont : npx shadcn@latest add <composant> --diff, en conservant les variantes du thème.