graphite-ui

Design system neutre, inspiré de Paperclip : gris purs, couleur réservée aux statuts et aux données, peu de texte, gros chiffres, explications au survol. Un cœur neutre, une couche de marque interchangeable, un thème sombre de référence et un thème clair dérivé.

• Principes et règles d'usage : DESIGN.md
• Thèmes (sombre, clair, marque) : docs/THEMING.md
• Vitrine : tous les composants et variantes, sombre et clair, npm run dev (http://localhost:3010)
• Skill Claude : skills/graphite-ui — voir « Skill Claude » plus bas

Composants

AppShell · Sidebar · PageHeader · SectionTitle · GroupDivider · Tabs · Button · IconButton · ToggleGroup · ModeSwitch · FilterSelect · Badge · StatusDot · Card · ChartCard · KpiStat · KpiGrid · BarChart · LineChart (bande d'incertitude) · Treemap · List · ListRow · DataTable · Drawer · InfoTooltip · EmptyState

Props et pièges : skills/graphite-ui/reference/components.md. Aucun texte ni donnée métier : tout est générique.

Installer (dépôt et paquet privés)

Le dépôt est privé. Le paquet est publié sur GitHub Packages (registre npm privé de GitHub) sous le nom @lucgsn/graphite-ui, à chaque release (Actions → Release). Il n'y a plus d'installation depuis Git, et rien n'est publié sur le registre npm public, où le nom graphite-ui appartient à un autre paquet.

1. Créer un jeton en lecture seule

GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic) (GitHub Packages n'accepte que ces jetons, pas les jetons « fine-grained »).

• Nom : graphite-ui (lecture) ; expiration : 90 jours à 1 an (à renouveler avant l'échéance).
• Cocher uniquement read:packages. Rien d'autre (surtout pas repo ni write:packages).
• Le compte qui crée le jeton doit avoir accès au dépôt LucGsn/graphite-ui : le paquet hérite des droits du dépôt privé.
• Copier le jeton une fois : GitHub ne le réaffiche pas. Ne jamais l'écrire dans un fichier du dépôt.

2. En local

Poser le jeton dans l'environnement du poste, hors de tout dépôt (ex. ~/.zshrc) :

export NPM_TOKEN=<votre-jeton>

Dans le projet qui consomme le paquet, créer (et versionner) un fichier .npmrc à la racine. Il ne contient aucun jeton, seulement la référence à la variable (.npmrc.example) :

@lucgsn:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}

Installer avec un alias, pour que les imports restent graphite-ui :

npm install graphite-ui@npm:@lucgsn/[email protected] recharts

package.json contient alors "graphite-ui": "npm:@lucgsn/[email protected]", et tous les extraits ci-dessous (transpilePackages, @import, @source, imports) s'appliquent tels quels. Sans alias (npm install @lucgsn/graphite-ui), remplacer graphite-ui par @lucgsn/graphite-ui partout, y compris dans @source "../node_modules/@lucgsn/graphite-ui/src".

recharts n'est nécessaire que pour BarChart et LineChart. NPM_TOKEN doit être défini à chaque npm install / npm ci ; sinon npm répond « Failed to replace env in config: ${NPM_TOKEN} ».

3. Sur Vercel (chaque projet qui consomme le paquet)

1. Le .npmrc ci-dessus est dans le dépôt du projet (il ne contient pas de jeton).
2. Vercel → le projet → Settings → Environment Variables → ajouter NPM_TOKEN = le jeton, cochée pour Production, Preview et Development (sans Preview, les déploiements de branches échouent), type Sensitive.
3. Redéployer. L'installation de Vercel lit le .npmrc et la variable ; aucune autre commande n'est nécessaire.

La vitrine de ce dépôt n'a pas besoin de NPM_TOKEN : elle importe ../src directement. Dans les GitHub Actions d'un projet consommateur : env: NPM_TOKEN: ${{ secrets.NPM_TOKEN }} (secret du dépôt).

Dépannage

Message ou symptôme	Cause probable
401 Unauthorized	NPM_TOKEN absent, expiré, révoqué, ou non défini pour cet environnement Vercel (Preview).
404 Not Found - @lucgsn/graphite-ui	Le compte du jeton n'a pas accès au dépôt, ou la ligne @lucgsn:registry=… manque dans le .npmrc.
Failed to replace env in config	NPM_TOKEN n'est pas défini dans l'environnement qui lance npm.
Un autre paquet graphite-ui s'installe (ou 404 npmjs)	Installation sans alias ni scope : utiliser graphite-ui@npm:@lucgsn/graphite-ui@<version>.
No matching version	Cette version n'est pas publiée (la 0.2.0 ne l'a jamais été : voir le CHANGELOG).

1. next.config.ts — le paquet est livré en TypeScript :

const config: NextConfig = { transpilePackages: ["graphite-ui"] };

2. app/globals.css :

@import "tailwindcss";
@import "graphite-ui/styles.css";
/* @import "graphite-ui/themes/omnes.css"; */ /* thème de marque d'exemple, facultatif */
@source "../node_modules/graphite-ui/src";

@source est relatif au fichier CSS : ajuster le nombre de ../ selon son emplacement.

3. app/layout.tsx — thème posé sur <html>, police Inter :

This is the beginning of the README. Read the rest at the original. Read the full README ↗