veille-ia-gen/SPECS_SVELTE.md

SPECS_SVELTE.md — Conventions Svelte/SvelteKit pour « veille-ia »

Statut : ce fichier PRÉVAUT sur tout choix technique frontend (cf. prompt_kimi_cli_veille_ia.md). Il consolide les recommandations de doc2sveltekit-transition/ (playbook SvelteKit, charte OKI, best practices Svelte 5) adaptées à une app privée d'administration self-hosted YunoHost — pas un site vitrine public : pas de SEO, pas de motion « Awwwards », pas de PWA.

En cas de conflit : ce document prime sur la recette générique pour la marque et le style ; le PRD (plan_prd_veille_ia.md) prime pour le fonctionnel ; la recette prime pour la méthode technique.

---

1. Stack

• SvelteKit 2 + Svelte 5 (runes uniquement) + TypeScript strict (strict: true).
• @sveltejs/adapter-node — l'app tourne en service systemd derrière nginx (YunoHost).
• Vite (fourni par SvelteKit). Aucune configuration exotique.
• CSS vanilla + tokens OKI — pas de Tailwind, aucun framework CSS lourd (décision : recette §2.3, charte OKI).
• Zod pour la validation des schémas YAML (registre, profils, alertes).
• js-yaml pour la persistance YAML ; simple-git pour les commits automatiques du data_dir.
• vitest pour les tests (moteur de recommandation notamment).
• eslint + prettier (config SvelteKit standard).
• Gestionnaire de paquets : npm (lockfile package-lock.json, jamais mélangé avec pnpm/yarn).
• Node : 24 LTS en dev comme en prod (ressource nodejs YunoHost alignée sur le catalogue : nodered, etherpad, hedgedoc utilisent "24").

Interdictions (recette §0, adaptées) :

• Jamais de dépendance installée sans être importée et utilisée.
• Jamais de SSR désactivé globalement pour « faire marcher » une lib client.
• Jamais d'appel à un service tiers au chargement (fonts, CDN, analytics) — tout asset est self-hébergé.
• Aucune dépendance propriétaire ou source-available (licences OSI uniquement, projet AGPL-3.0).

2. Structure de dossiers (app/)

app/
├── src/
│   ├── app.html                  # lang="fr", script theme.js externe (anti-FOUC)
│   ├── app.d.ts                  # typage Locals (user SSO), env
│   ├── hooks.server.ts           # auth SSO (YNH_USER), CSP, paths.base
│   ├── lib/
│   │   ├── styles/
│   │   │   ├── oki-tokens.css    # tokens charte OKI (copie versionnée, §4)
│   │   │   └── base.css          # reset, primitives, gate reduced-motion
│   │   ├── server/               # code serveur uniquement (jamais importé côté client)
│   │   │   ├── config.ts         # variables d'env (DATA_DIR, OLLAMA_URL, ALERTS_TOKEN…)
│   │   │   ├── registre.ts       # lecture/écriture YAML + validation Zod
│   │   │   ├── profils.ts
│   │   │   ├── alertes.ts
│   │   │   ├── git.ts            # simple-git : commit atomique à chaque écriture
│   │   │   └── recommandation.ts # moteur (pur, testable, sans I/O)
│   │   ├── components/           # Badge, Card, Tag, Icon, DataTable, FormField…
│   │   └── types.ts              # types TS partagés (inférés des schémas Zod)
│   └── routes/
│       ├── +layout.svelte        # skip-link, nav SSO-aware, flag-bar
│       ├── +layout.server.ts     # expose l'utilisateur SSO aux pages
│       ├── +page.svelte          # accueil (public minimal si non connecté)
│       ├── +error.svelte         # erreurs designées (P5)
│       ├── registre/             # CRUD registre (protégé SSO)
│       ├── profils/              # CRUD profils (protégé SSO)
│       ├── recommander/          # UI moteur de recommandation
│       ├── alertes/              # inbox (phase 2)
│       └── api/
│           ├── recommander/+server.ts
│           └── alerts/+server.ts # POST protégé par token (phase 2)
├── static/
│   ├── fonts/                    # Archivo + Inter woff2 self-hébergées + fonts.css
│   ├── theme.js                  # bascule thème clair/sombre anti-FOUC
│   └── icons.svg                 # sprite SVG (<symbol>), zéro emoji
├── package.json                  # private: true
├── svelte.config.js              # adapter-node, paths
└── vite.config.ts

Règles :

• Tout code qui lit des fichiers, des variables d'env ou fait du fetch sortant vit dans lib/server/.
• Le moteur de recommandation est une fonction pure (entrées → sorties), testable sans serveur.
• Les données d'exemple/seed vivent dans app/src/lib/server/seed/ et ne sont copiées dans le DATA_DIR qu'au premier démarrage (jamais d'écrasement de données existantes).

3. Conventions Svelte 5 (obligatoires)

• Runes only. $state uniquement pour du réactif ; gros objets réassignés (réponses API) → $state.raw.
• $derived pour tout calcul ; $derived.by si l'expression est complexe. Jamais $effect pour calculer.
• $effect = escape hatch uniquement (sync avec lib externe), toujours avec cleanup symétrique.
• $props() en traitant les props comme changeantes : toute valeur dérivée d'une prop passe par $derived.
• Événements : onclick={...} (jamais on:click) ; listeners globaux via <svelte:window> / <svelte:document>.
• {#each} avec clé unique (id métier), jamais l'index ; pas de destructuration si mutation (bind:).
• Snippets {#snippet} / {@render} plutôt que <slot>.
• Classes conditionnelles : tableaux/objets style clsx dans class={...}, pas de class:.
• Liens internes via resolve() de $app/paths ; assets via asset(). Jamais de chemin en dur (l'app peut être servie sous un sous-chemin YunoHost).
• {@html} interdit sauf contenu first-party, commenté comme tel.
• État partagé inter-composants : module .svelte.ts avec $state + fonctions — pas de stores legacy.
• Règle des loads : toute donnée lue côté serveur (YAML, API externe) passe par +page.server.ts / +layout.server.ts ou des form actions — jamais de fetch direct vers le data_dir côté client.
• Mutations : form actions SvelteKit par défaut (progressive enhancement, fonctionne sans JS) ; fetch JSON uniquement pour les endpoints API externes (/api/*).
• Persistance de préférences : ?? défaut, jamais || défaut (un 0/false persisté est légitime).
• Validation systématique via npx @sveltejs/mcp svelte-autofixer <fichier> avant de finaliser un composant.

4. Style — tokens OKI (charte §2, copie versionnée)

Un seul fichier src/lib/styles/oki-tokens.css importé en premier dans +layout.svelte (aucune valeur recopiée à la main dans les composants) :

:root {
  /* Noyau (thème sombre = défaut) */
  --noir-oki: #0D0D0D;          /* background */
  --noir-profond: #1A0F1A;      /* surface */
  --blanc-creme: #FFF8E7;       /* foreground */
  --line: rgba(255,255,255,0.10);
  --or-oki: #FDB813;            /* accent : SEULE couleur d'action */
  --rouge-oki: #FF1654;         /* signal — jamais un lien/bouton */
  --vert-oki: #00D66C;          /* succès, validation */
  --or-clair: #FFE066;          /* survol des boutons */
  --muted: color-mix(in srgb, var(--blanc-creme) 70%, transparent);
  --card-bg: rgba(255,255,255,0.03);
  /* Typographie */
  --font-display: 'Archivo', 'Arial Black', sans-serif;
  --font-body: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
  /* Formes, espacements */
  --radius-sm: 3px; --radius-md: 6px;
  --border-card: 1px solid var(--line);
  --border-btn: 2px solid var(--or-oki);
  --space-1: 0.75rem; --space-2: 1rem; --space-3: 1.5rem; --space-4: 2rem; --space-5: 4rem;
  --container: 1200px;
  /* Motion */
  --ease-ka: cubic-bezier(0.22, 1, 0.36, 1);
  --ease-syncope: cubic-bezier(0.65, 0, 0.35, 1);
  --dur-tanbou: 120ms; --dur-mesure: 480ms; --dur-phrase: 960ms;
}

Sémantique des couleurs, adaptée au back-office (rôles jamais permutés) :

• Or = agir : boutons, liens, focus. Seule couleur d'action.
• Vert = valider : statut production, licence vérifiée, alerte traitée.
• Rouge = signaler : statut mort, urgence haute, erreur — jamais cliquable.
• Badge « ⚠️ à vérifier » (règle anti-hallucination du PRD) : fond or 8 % + bordure or 1 px (tag OKI canonique) + texte crème ; rendu par un composant <BadgeAVerifier> dédié, utilisé dès qu'un champ est null. Le pictogramme ⚠ fait partie du sprite SVG (règle zéro emoji ci-dessous).

Règles d'usage :

• Thème sombre par défaut, clair opt-in via html.light-theme posée par static/theme.js (script externe, localStorage, anti-FOUC). Accents assombris en thème clair pour WCAG AA.
• Texte secondaire = crème 70–85 % d'opacité ; filets = blanc 10 %, jamais de gris plein.
• Titres h1–h4 : Archivo majuscules, letter-spacing: -0.01em. Boutons : Archivo 700 uppercase, bordure 2 px or, survol --or-clair. Corps : Inter, line-height: 1.5.
• Cartes : fond --card-bg, liseré gauche 4 px d'accent, rayon ≤ 6 px. Angles nets partout.
• Flag-bar (6 px, 4 segments francs noir/or/vert/rouge) sous la navigation — une occurrence visible par écran maximum.
• Iconographie : sprite static/icons.svg (<symbol> 24×24, stroke 2 px, currentColor) + <svg><use href="...#id"/></svg>. Zéro emoji en production — y compris dans les badges et messages d'état (le glyph ⚠ est fourni par le sprite, pas par un emoji Unicode).
• Fonts self-hébergées : woff2 dans static/fonts/, @font-face avec font-display: swap, preload de la display uniquement. Aucun appel Google Fonts.
• Motion : micro-interactions sobres uniquement (--dur-tanbou sur hover/focus, --dur-mesure sur transitions de vues). Uniquement transform + opacity. Durées lues depuis les tokens, jamais hardcodées. Gate unique prefers-reduced-motion dans base.css (contenu statique complet).
• Styles scopés dans les composants ; personnalisation parent→enfant via custom properties ; :global en dernier recours.
• Layout « app » : height: 100dvh + overflow par panneau si pertinent ; cibles tactiles ≥ 44 px.
• Listes longues (registre, inbox) : content-visibility: auto + contain-intrinsic-size d'abord, pagination « charger plus » avant toute virtualisation.

5. Accessibilité (non négociable)

• Navigation clavier complète : tab order logique, focus visible (outline or 2 px), skip-link « Aller au contenu » en premier élément du layout.
• Contrôles de formulaire tous labellisés (<label for>), erreurs de validation annoncées (aria-describedby, aria-invalid).
• Contrastes WCAG AA vérifiés sur les deux thèmes (texte courant ≥ 4,5:1).
• Icônes décoratives aria-hidden="true" ; icônes seules dans un bouton → aria-label.
• Tableaux de données sémantiques (<th scope>), tri annoncé via aria-sort.
• Focus déplacé sur le <h1> après chaque navigation ; lang="fr" sur <html>.
• Le badge « à vérifier » ne repose jamais sur la couleur seule (pictogramme + texte).
• Zéro warning d'accessibilité svelte-check toléré.

6. i18n

• Français d'abord : tous les libellés UI en français, regroupés dans src/lib/i18n/fr.ts (objet typé clé → libellé), jamais de chaîne en dur dans les templates.
• Structure prête pour créole/anglais : un fichier par locale, sélection par data-locale (pas de routing i18n au MVP — app monoprivée).
• Microcopy signature en kréyòl admise (404, états vides) avec attribut lang="gcf" sur le span.

7. Sécurité & intégration YunoHost (côté app)

• SSO : hooks.server.ts lit le header Ynh-User injecté par SSOwat via proxy_params_with_auth (conf nginx du package ; le header est vidé côté nginx avant d'être renseigné après authentification, donc non spoofable). Sans header valide → seule la page d'accueil publique minimale est accessible ; toutes les routes /registre, /profils, /recommander, /alertes et les form actions exigent un utilisateur. En dev local, DEV_USER simule le header (documenté, ignoré en production).
• CSP via la config SvelteKit (kit.csp, mode nonce, dans vite.config.ts — SvelteKit ≥ 2.62 n'utilise plus svelte.config.js) : default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self'; frame-ancestors 'none'; base-uri 'self'; form-action 'self'; object-src 'none' + X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin. Aucun script inline — theme.js est un fichier externe.
• Sous-chemin : l'app doit fonctionner servie sous https://domaine.tld/veille : paths.relative: false dans svelte.config.js, base injectée par variable d'env au build/runtime, et tous les liens via resolve()/asset().
• POST /api/alerts : token ALERTS_TOKEN (header Authorization: Bearer), généré à l'install YunoHost, jamais commité. Aucune route mutative sans vérification (SSO ou token).
• Toutes les entrées (YAML, formulaires, webhooks) validées par Zod côté serveur avant tout traitement.
• Journaux : console structuré (JSON), récupéré par journald via systemd.

8. Qualité — définition de « terminé » (chaque commit)

• npm run check (svelte-check) : 0 erreur, 0 warning.
• npm run lint (eslint + prettier --check) : propre.
• npm run test (vitest) : vert — moteur de recommandation couvert (cas nominaux + cas limites : licence null, seuil de revenus dépassé, modèle statut mort, champ null pénalisé).
• npm run build : vert.
• Grep de vérité avant livraison : zéro domaine tiers dans le build, zéro emoji dans le HTML buildé.
• Revue clavier + prefers-reduced-motion sur les pages ajoutées.
• Commits git atomiques et explicites, en français ; README.md à jour à chaque phase.

9. Explicitement hors périmètre (app privée)

• SEO, OG/Twitter cards, sitemap, robots — pas d'indexation, app derrière SSO.
• PWA / service worker / mode hors-ligne.
• Motion riche (Lenis, GSAP, WebGL, kinetic type) — la charte motion OKI s'applique en version sobre (§4).
• Imagerie afrofuturiste, footer fédéré public — interface utilitaire ; le favicon OKI suffit.
• Multi-utilisateurs, notifications push natives (PRD §10).