Design tokens

Vue d'ensemble

Yayaw prend en charge les surcharges de design tokens au runtime sans rebuild de l'application.

Scope de cette fonctionnalité :

cible les pages hors /dashboard/* et /auth/*
prend en charge les surcharges globales et les surcharges scopées organisation pour les hôtes publics d'organisation
prend en charge les couleurs sémantiques (y compris les couleurs de graphiques), les tokens de mise en page (radius, spacing, tracking-normal), les tokens typographiques (font-sans, font-serif, font-mono) et les tokens d'ombre (shadow-*)

Les design tokens sont la couche de présentation publique pour les pages et aperçus rendus par le CMS. Ils permettent aux opérateurs d'ajuster couleurs sémantiques, radius, espacement, typographie, tracking et ombres sans éditer les documents de page, définitions de section ou sources de composants.

Utilisez les tokens pour les décisions visuelles de niveau thème. Utilisez les documents de page et les sections pour la structure de contenu, et gardez le style dashboard/auth sur son scope d'app-shell dédié.

Modèle de données

Le payload est versionné et stocké comme cartes de tokens sémantiques :

interface DesignTokensV1 {
  version: 1;
  light: Partial<Record<DesignToken, string>>;
  dark: Partial<Record<DesignToken, string>>;
}

Stockage :

scope global : system_settings avec la clé design-tokens.non-dashboard.v1
scope organisation : organization_settings.designTokens

Résolution au runtime

Pipeline de résolution :

charger le payload de tokens global
charger le payload de tokens de l'organisation active lorsque la requête résout vers un hôte public d'organisation ou un aperçu scopé organisation
fusionner les valeurs organisation par-dessus les valeurs globales pour chaque token clair/sombre
générer les variables CSS scopées :
- .scope-nondashboard:not(.dark) { ... }
- .scope-nondashboard.dark { ... }

La classe de scope est appliquée uniquement aux pages hors routes dashboard/auth. Les domaines publics custom vérifiés appliquent le payload de tokens effectif de l'organisation propriétaire après la base globale, ce qui permet à une organisation de thèmer ses pages publiques sans changer le site canonique Yayaw ni l'hôte d'une autre organisation.

Les routes dashboard gardent volontairement leur style d'app-shell indépendant des surcharges de tokens du site public. Si une future fonctionnalité de thème dashboard est nécessaire, ajoutez un scope et une clé de stockage séparés au lieu de réutiliser design-tokens.non-dashboard.v1.

Familles de tokens

Les familles de tokens incluent :

couleurs sémantiques comme background, foreground, primary, secondary, accent, muted, destructive, border, input, ring, card, popover et couleurs de graphiques
tokens de mise en page comme radius et spacing
tokens typographiques comme les piles de polices sans, serif et mono
tokens de tracking comme tracking-normal
tokens d'ombre comme shadow-sm, shadow-md et les valeurs de profondeur associées

Seuls les tokens Yayaw déclarés sont acceptés. Les variables CSS inconnues issues de thèmes importés sont ignorées.

Flux d'édition

Route UI admin :

/dashboard/content/design-tokens

Comportement :

sauvegarde immédiate (pas de séparation brouillon/publication)
les champs de tokens sont initialisés depuis les valeurs de base du dépôt dans theme-vars.css
les tokens de couleur utilisent un picker avec saisie HEX
l'icône pinceau sur chaque input couleur copie la valeur HEX courante avec un retour de succès inline
les tokens de mise en page utilisent une saisie numérique avec unité sélectionnable
les tokens typographiques utilisent un select de presets avec saisie optionnelle de pile de polices personnalisée, et sont partagés entre clair/sombre
les tokens d'ombre utilisent des saisies texte directes
les tokens de police stockent actuellement des piles CSS font-family (par exemple Inter, sans-serif) ; le téléversement de fichiers de police et la sélection depuis un catalogue de polices ne font pas encore partie de cette UI
les valeurs sombres peuvent rester vides pour hériter d'abord du clair, puis du sombre de base (ou du clair de base quand aucune base sombre n'existe)
les valeurs de couleur sont canonicalisées et stockées au format OKLCH
l'import par URL est disponible directement dans l'éditeur (prise en charge fournisseur actuelle : URL TweakCN comme https://tweakcn.com/editor/theme?theme=neo-brutalism)
l'import par commande CLI shadcn est disponible directement dans l'éditeur (par exemple bunx --bun shadcn@latest add @ss-themes/ghibli-studio ou pnpm dlx shadcn@latest add https://shadcnthemer.com/r/themes/<id>.json ; agnostique au gestionnaire de paquets)
l'import par CSS collé est disponible directement dans l'éditeur (:root { ... } et .dark { ... } optionnel)
l'import de thème utilise un menu unique "Import Theme" qui ouvre une modale propre à la méthode (URL, commande ou CSS) avec des indications contextuelles
l'import remplit l'état de l'éditeur du scope courant ; il faut encore sauvegarder explicitement pour publier

Parsing des imports de thème

Le parser est basé sur des fournisseurs et inclut actuellement une implémentation :

tweakcn : accepte les URL editor/theme, résout le slug, puis récupère https://tweakcn.com/r/themes/{slug}.json
- si l'endpoint JSON de registre échoue pour une URL de page de thème valide (par exemple https://tweakcn.com/themes/{id}), Yayaw retombe sur le parsing du payload de thème rendu côté serveur depuis la page de thème
shadcn-registry : accepte une commande add de la CLI shadcn (ou une référence directe @scope/item), résout l'alias de registre, puis récupère l'endpoint d'élément JSON du registre
css : parse le CSS collé avec des blocs de variables :root et .dark optionnel

Règles de normalisation :

seuls les tokens Yayaw connus sont importés
les tokens de couleur sont convertis en OKLCH canonique
les tokens texte/mise en page/typographie/ombre sont validés avec les mêmes contraintes de valeurs que l'édition manuelle
les valeurs de tokens non prises en charge ou invalides sont ignorées

Consommateurs runtime

Les tokens effectifs sont consommés par :

pages publiques générées
wrappers de layout docs/public hors dashboard/auth
aperçus du catalogue de composants lors de la validation de recettes sensibles aux tokens
aperçus runtime de sections générées

Le catalogue de composants applique les tokens runtime effectifs aux surfaces d'aperçu afin que les auteurs puissent valider les composants importés ou locaux contre le thème public courant.

Permissions

L'édition exige :

global-variables:manage

Les sauvegardes scopées organisation exigent aussi que l'appelant opère dans le contexte de l'organisation active propriétaire de la surcharge.

L'accès lecture permet toujours d'ouvrir la page en mode lecture seule.

Validation

Vérifications utiles après des changements de design tokens :

bun test src/lib/server/services/design-tokens/design-tokens.test.ts
bun run check
bunx tsc --noEmit