docs: fondation projet (CLAUDE.md, design system, spec + plan jalon 1)

Ignore les dépôts de référence imbriqués (linux-update-dashboard, nas-ops). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-05 04:41:30 +02:00
parent 032287e2ab
commit 1e1be7f627
15 changed files with 6279 additions and 0 deletions
@@ -0,0 +1,304 @@
+# mon design system — Gruvbox seventies
+
+> Design system rétro-futuriste pour applications de monitoring, ops, IoT, domotique.
+> Orange brûlé, fond brun délavé en sombre / gris clair usé en clair.
+> **Version 1.0** · deux thèmes (dark + light), 14+ composants React, palette GTK pour GNOME.
+
+---
+
+## 🚀 Démarrage rapide (web)
+
+```html
+<!DOCTYPE html>
+<html data-theme="dark">
+<head>
+  <!-- 1. Polices Google -->
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&family=Share+Tech+Mono&display=swap" rel="stylesheet">
+
+  <!-- 2. Icônes Font Awesome 6 -->
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css">
+
+  <!-- 3. Tokens (variables CSS) -->
+  <link rel="stylesheet" href="tokens/tokens.css">
+
+  <!-- 4. React + Babel -->
+  <script src="https://unpkg.com/react@18.3.1/umd/react.development.js"></script>
+  <script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.development.js"></script>
+  <script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js"></script>
+</head>
+<body>
+  <div id="root"></div>
+  <!-- 5. Composants UI -->
+  <script type="text/babel" src="components/ui-kit.jsx"></script>
+  <script type="text/babel">
+    // Tes composants ici
+  </script>
+</body>
+</html>
+```
+
+Pour voir tout fonctionner, ouvre `examples/exemple-minimal.html`.
+
+---
+
+## 📂 Contenu du package
+
+```
+export/
+├── README.md                         ← Ce fichier
+├── consigne_design_system.md         ← Brief pour agents IA (Claude, ChatGPT…)
+├── tokens/
+│   ├── tokens.css                    ← Variables CSS web (dark + light)
+│   ├── tokens.gnome.css              ← GTK 4 / libadwaita (apps GNOME)
+│   └── tokens.json                   ← Format générique (Tailwind, Figma…)
+├── components/
+│   └── ui-kit.jsx                    ← 14 composants React (Button, IconButton, Toggle, Tooltip,
+│                                        StatusLed, BatteryGauge, RadialGauge, BigRadialGauge,
+│                                        Popup, TreeNav, Sparkline, LineChart, Icon, …)
+└── examples/
+    └── exemple-minimal.html          ← Démo minimale autoportante
+```
+
+---
+
+## 🎨 Ce qui est paramétrable
+
+### 1. Thème global
+
+```html
+<html data-theme="dark">   <!-- ou "light" -->
+```
+
+Tu peux mettre `data-theme` sur **n'importe quel parent** pour basculer un sous-arbre uniquement (utile pour une preview en mode opposé dans un menu de réglages).
+
+### 2. Toutes les couleurs (CSS variables)
+
+Édite `tokens.css` ou surcharge dans ton propre CSS :
+
+```css
+:root[data-theme="dark"] {
+  --accent: #fe8019;           /* Couleur principale (orange seventies) */
+  --accent-soft: #d65d0e;
+  --bg-1: #2a231d;             /* Fond app */
+  --bg-3: #3c332a;             /* Cartes */
+  --ink-1: #f2e5c7;            /* Texte */
+  --ok: #4dbb26;
+  --warn: #fabd2f;
+  --err: #fb4934;
+  --blue: #3db0d1;             /* Datavis additionnel */
+  --purple: #c882c8;
+}
+```
+
+**4 statuts** (ok / warn / err / info) + **2 couleurs datavis** (blue / purple) + **6 niveaux de fond** + **4 niveaux d'encre** + **3 niveaux de bordure**.
+
+### 3. Polices
+
+Trois familles, toutes substituables :
+
+| Variable        | Usage                              | Défaut             |
+|-----------------|-------------------------------------|---------------------|
+| `--font-ui`     | Interface (titres, corps, boutons) | Inter              |
+| `--font-mono`   | Données, code, valeurs numériques  | JetBrains Mono     |
+| `--font-terminal` | Logs, terminal embarqué, vibe rétro | Share Tech Mono   |
+
+Pour changer, remplace simplement les `@import` Google Fonts et redéfinis les variables.
+
+### 4. Ombres et relief
+
+```css
+--tile-3d           /* Relief 3D marqué pour cartes */
+--shadow-1, -2, -3  /* Niveaux d'élévation */
+--shadow-press      /* Inset pour état pressé */
+--hover-glow        /* Halo accent au survol */
+```
+
+### 5. Composants — props paramétrables
+
+Chaque composant accepte des props pour personnaliser sans toucher au CSS. Exemples :
+
+```jsx
+<Button variant="primary|ghost|danger|default" size="sm|md|lg" icon="play">Texte</Button>
+
+<IconButton icon="cog" label="Tooltip obligatoire" primary danger active />
+
+<Toggle on={state} onChange={setState} label="Auto" icon="refresh" />
+
+<BatteryGauge
+  value={64} max={100} unit="%"
+  label="CPU"
+  warnAt={70} errAt={85}      // seuils de couleur
+  compact                      // mode 1 ligne
+  icon="cpu"
+  color="var(--blue)"          // couleur fixe (sinon auto selon seuils)
+/>
+
+<RadialGauge value={87} label="SCORE" size={120} />
+<BigRadialGauge value={87} label="santé système" />
+
+<Popup open={open} onClose={fn} title="…" footer={…}>
+  Contenu
+</Popup>
+
+<TreeNav groups={[
+  { id, icon: 'server', label, count, open, children: [
+    { id, label, status: 'ok|warn|err', meta }
+  ]}
+]} activeId={id} onSelect={fn} />
+```
+
+Voir la doc complète des props : `Component Reference.html` dans le projet original.
+
+---
+
+## 🐧 Utilisation dans une app GNOME (GTK 4 / libadwaita)
+
+Charge `tokens/tokens.gnome.css` comme provider CSS au démarrage de l'app.
+
+**Python (PyGObject)** :
+```python
+from gi.repository import Gtk, Gdk
+
+css_provider = Gtk.CssProvider()
+css_provider.load_from_path("tokens.gnome.css")
+Gtk.StyleContext.add_provider_for_display(
+    Gdk.Display.get_default(),
+    css_provider,
+    Gtk.STYLE_PROVIDER_PRIORITY_APPLICATION
+)
+```
+
+**GJS** :
+```javascript
+const provider = new Gtk.CssProvider();
+provider.load_from_path('tokens.gnome.css');
+Gtk.StyleContext.add_provider_for_display(
+    Gdk.Display.get_default(),
+    provider,
+    Gtk.STYLE_PROVIDER_PRIORITY_APPLICATION
+);
+```
+
+**Rust (gtk4-rs)** :
+```rust
+let provider = gtk::CssProvider::new();
+provider.load_from_path("tokens.gnome.css");
+gtk::style_context_add_provider_for_display(
+    &gdk::Display::default().unwrap(),
+    &provider,
+    gtk::STYLE_PROVIDER_PRIORITY_APPLICATION,
+);
+```
+
+Le fichier override directement les couleurs sémantiques de libadwaita (`@window_bg_color`, `@accent_color`, etc.) ET ajoute des styles spécifiques pour les widgets courants : `button.suggested-action`, `entry`, `switch`, `scale`, `progressbar`, `notebook`, `popover`…
+
+Classes CSS supplémentaires à appliquer via `add_css_class()` :
+- `.tile` / `.card` — Tuile en relief 3D
+- `.mono` — Texte monospace JetBrains Mono
+- `.terminal` — Texte terminal Share Tech Mono
+- `.status.ok` / `.status.warn` / `.status.error` / `.status.info` — Badge de statut
+
+---
+
+## 🔧 Intégration dans d'autres outils
+
+### Tailwind CSS
+
+Convertis `tokens.json` en `tailwind.config.js` :
+
+```js
+const tokens = require('./tokens/tokens.json');
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        accent: tokens.themes.dark.accent.primary.value,
+        ok:     tokens.themes.dark.status.ok.value,
+        // …
+      },
+      fontFamily: {
+        sans: [tokens.typography.fonts.ui.family, ...tokens.typography.fonts.ui.fallback],
+        mono: [tokens.typography.fonts.mono.family],
+      },
+    },
+  },
+};
+```
+
+### Figma / outils de design
+
+`tokens.json` suit un schéma compatible avec la plupart des plugins de tokens (Figma Tokens, Style Dictionary). Importe-le directement.
+
+### Variables Sass / SCSS
+
+```scss
+@use 'sass:map';
+$tokens: (
+  accent: #fe8019,
+  bg-1:   #2a231d,
+  ok:     #4dbb26,
+);
+// …
+```
+
+---
+
+## ⚙️ Personnalisation avancée
+
+### Créer un thème dérivé
+
+Duplique `tokens.css`, change le nom du sélecteur (`[data-theme="ocean"]` par exemple) et modifie les variables. Charge les deux fichiers — `data-theme` choisira automatiquement.
+
+### Ajouter une couleur status custom
+
+```css
+:root[data-theme="dark"] {
+  --critical: #ff0080;
+  --critical-glow: rgba(255, 0, 128, 0.45);
+}
+```
+
+Utilisable ensuite partout : `<StatusLed status="critical">` nécessite une PR dans `ui-kit.jsx` (carte `map` dans `StatusLed`), mais en raw CSS tu peux utiliser la variable directement.
+
+### Désactiver les effets
+
+Tous les effets de `transition` / `transform` / `box-shadow` sont concentrés dans les classes `.interactive`, `.bg-hover`, `.gauge-hover`. Surcharge-les en CSS si besoin :
+
+```css
+.interactive { transition: none !important; }
+```
+
+---
+
+## ✅ Checklist d'intégration
+
+- [ ] Polices Google Fonts chargées (Inter, JetBrains Mono, Share Tech Mono)
+- [ ] Font Awesome 6 chargé
+- [ ] `tokens.css` (web) **ou** `tokens.gnome.css` (GTK) chargé
+- [ ] Attribut `data-theme="dark"` (ou "light") sur `<html>` ou un parent
+- [ ] React 18 + Babel chargés (uniquement pour `ui-kit.jsx`)
+- [ ] `ui-kit.jsx` chargé en `type="text/babel"`
+
+---
+
+## 📋 Statuts du système
+
+| Couleur | Token  | Hex (dark) | Hex (light) | Usage                       |
+|---------|--------|------------|-------------|-----------------------------|
+| Accent  | `--accent` | `#fe8019` | `#af3a03` | Primaire, focus, sélection  |
+| OK      | `--ok`     | `#4dbb26` | `#3c911c` | Succès, état nominal        |
+| Warn    | `--warn`   | `#fabd2f` | `#b57614` | Attention, latence élevée   |
+| Err     | `--err`    | `#fb4934` | `#9d0006` | Erreur, alerte critique     |
+| Info    | `--info`   | `#83a598` | `#427b58` | Information neutre          |
+| Blue    | `--blue`   | `#3db0d1` | `#2d82a3` | Datavis catégorie 2         |
+| Purple  | `--purple` | `#c882c8` | `#8c468c` | Datavis catégorie 3         |
+
+---
+
+## 🤖 Pour les agents IA
+
+Si tu utilises ce design system avec une IA (Claude, GPT, Copilot, etc.), partage-lui le fichier **`consigne_design_system.md`**. Il y trouvera toutes les règles d'utilisation, conventions, contre-exemples à éviter.
+
+---
+
+**Licence** · Usage libre dans tes projets. Pas de garantie.