Brickslab.Tools repose sur deux outils complémentaires : Theme Builder pour construire votre système de tokens et Mockup Builder pour composer des écrans avec les composants du catalogue.
1. Theme Builder
Ajustez palette, typo, spacing, radius, ombres et générez un fichier CSS de tokens prêt à importer.
2. Mockup Builder
Assemblez les blocs visuellement, modifiez les props des composants et testez la composition par viewport.
Flux recommandé
1
2
3
4
1) Définir le thème dans /components/themebuilder
2) Exporter les tokens CSS
3) Composer les écrans dans /components/mockupbuilder
4) Intégrer les composants @brickslab./ui-web dans votre app Next/React
Panneau droite: édition des props de composant et du layout (x, y, w, h, z-index) du bloc sélectionné.
Historique: annuler/rétablir, duplication, copier/coller, suppression, reflow automatique des blocs.
Persistance: autosave local et action Restaurer pour récupérer un brouillon.
Export: Exporter le code ouvre un TSX prêt à intégrer, avec imports depuis @brickslab./ui-web.
Cycle complet recommandé (production)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// 1) Générer tokens.css dans Theme Builder puis l'importer globalement
@import "@brickslab./theme-default/dist/tokens.css";
@import "./tokens.css";
// 2) Assembler un écran dans Mockup Builder, puis exporter le TSX
import { Button, SectionHeader } from "@brickslab./ui-web";
export default function MyPage() {
return (
<div style={{ position: "relative" }}>
<SectionHeader title="Mon écran" />
<Button variant="primary">Action</Button>
</div>
);
}
Les deux outils partagent le même socle de composants et de tokens, ce qui limite les écarts entre prototype et implémentation production.
Design Tokens
Tous les composants utilisent exclusivement des variables CSS. Aucune valeur hardcodée (sauf exceptions documentées ci-dessous). Ces variables sont définies dans @brickslab./theme-default/dist/tokens.css.
Couleurs — Sémantiques
Token
Valeur (light)
Usage
--color-bg
#ffffff
Fond de page principal
--color-fg
#0b1220
Texte principal
--color-muted
#52607a
Texte secondaire, labels, métadonnées
--color-brand
#CC4A48
Couleur d'accentuation principale
--color-brand-dark
#8F2834
Variante sombre de la marque (hover)
--color-success
#4ADE80
État de succès
--color-warning
#F59E0B
État d'avertissement
--color-error
#CC4A48
État d'erreur
--color-info
#3B82F6
État informatif
--color-excellent
#22C55E
Score excellent, KPI positif
Couleurs — Surfaces
Token
Valeur (light)
Usage
--c-surface
#ffffff
Surface de base (cards, panels)
--c-surface-elevated
#f7f7f7
Surface surélevée (thead, hover rows)
--c-surface-secondary
#f5f5f5
Surface alternative (sidebars)
--c-border
#e0e0e0
Bordures et séparateurs
--c-brand-subtle
rgba(204,74,72,0.08)
Fond subtil brand (tags, callouts)
--c-brand-border
rgba(204,74,72,0.3)
Bordure subtile brand
Couleurs — Statuts (subtle & borders)
Token
Valeur (light)
--c-success-subtle
rgba(74,222,128,0.10)
--c-success-border
rgba(74,222,128,0.35)
--c-warning-subtle
rgba(245,158,11,0.10)
--c-warning-border
rgba(245,158,11,0.35)
--c-info-subtle
rgba(59,130,246,0.10)
--c-info-border
rgba(59,130,246,0.35)
Espacement
Token
Valeur
--space-1
2px
--space-1-5
4px
--space-2
8px
--space-3
12px
--space-4
16px
--space-5
20px
--space-6
24px
--space-7
28px
--space-8
32px
--space-10
40px
--space-12
48px
--space-15
60px
--space-20
80px
Typographie — Tailles
Token
Valeur
--fontsize-2xs
10px
--fontsize-xs
12px
--fontsize-sm
14px
--fontsize-medium
16px
--fontsize-lg
clamp(18px, 5vw, 48px)
--fontsize-xl
clamp(20px, 5vw, 48px)
--fontsize-2xl
clamp(24px, 5vw, 48px)
--fontsize-3xl
clamp(30px, 5vw, 48px)
--fontsize-4xl
clamp(36px, 5vw, 48px)
Typographie — Graisses
Token
Valeur
--fontweight-light
300
--fontweight-normal
400
--fontweight-medium
500
--fontweight-semibold
600
--fontweight-bold
700
--fontweight-extrabold
800
--fontweight-black
900
Radius
Token
Valeur
--radius-sm
6px
--radius-md
12px
--radius-lg
16px
--radius-full
999px
Ombres, Z-index & Utilitaires
Token
Valeur
--shadow-1
0 1px 2px rgba(0,0,0,0.06)
--shadow-2
0 10px 30px rgba(0,0,0,0.10)
--z-base
0
--z-drawer
50
--z-dropdown
100
--z-modal
1000
--height-topbar
60px
--height-input
38px
--focus-ring
0 0 0 3px rgba(204,74,72,0.25)
--transition-bg
background 0.2s ease
--transition-all
all 0.2s ease
Couleurs hardcodées autorisées — par convention, seules ces valeurs peuvent être écrites en dur dans les composants : #CC4A48 (brand), #4ADE80 (green), #FBFBFB (near-white), #F59E0B (amber). Tout le reste doit passer par un token.
Theming & Dark mode
Le thème supporte deux modes d'activation du dark mode : la préférence système (automatique) et le toggle manuel via classe CSS.
Light mode
Appliqué par défaut via :root. Activable manuellement avec la classe .light sur <html>.
:root / :root.light
Dark mode
Activé automatiquement via @media (prefers-color-scheme: dark). Activable manuellement avec .dark sur <html>.
:root.dark
Toggle dark mode (exemple Next.js)
1
2
3
4
5
6
// Basculer le dark mode via classe sur <html>
function toggleDarkMode(enabled: boolean) {
const root = document.documentElement;
root.classList.remove("light", "dark");
root.classList.add(enabled ? "dark" : "light");
}
Personnaliser les tokens (override)
Importez le fichier de tokens puis surchargez les variables dans votre propre CSS global. Seules les variables que vous déclarez seront modifiées.
Chaque composant = un dossier src/components/<category>/<snake_name>/ contenant <Name>.tsx + <Name>.type.ts
Styles
Inline styles uniquement — pas de fichiers CSS, pas de Tailwind dans ui-web
import React
import React from 'react' obligatoire dans chaque .tsx (JSX transform non configuré)
Composants contrôlés
Tous les composants interactifs reçoivent état + handlers en props — pas d'état interne
'use client'
Interdit sauf pour CodeBlock (clipboard API)
Icônes
react-icons/fi uniquement (react-icons@^5.5.0)
Types
Export depuis le .type.ts, jamais inline dans .tsx
Commandes principales
bash
1
2
3
4
5
6
7
8
9
10
11
12
13
# Développement
pnpm dev # sync + démarrer le catalogue
# Build
pnpm run build:packages # build des packages workspace
pnpm build # build packages + sync + next build
# Qualité
pnpm lint # lint du catalogue
# Utilitaires
pnpm sync:components # components.csv → components.data.ts
pnpm start # lancer en mode production
Ajouter un composant
Checklist complète à suivre pour chaque nouveau composant. Tous ces fichiers doivent être mis à jour pour que le composant soit correctement intégré dans le système.
1
Créer les fichiers source dans ui-web
bash
1
2
3
4
# Structure à créer
packages/ui-web/src/components/<category>/<snake_name>/
├── <Name>.tsx # Composant React
└── <Name>.type.ts # Types et interface des props
// ── Ma catégorie ──────────────────────────────────────────────────────────────
export * from "./components/<category>/<snake_name>/MonComposant";
export * from "./components/<category>/<snake_name>/MonComposant.type";
3
Ajouter les métadonnées dans components.csv
Fichier : components_docs/components.csv
csv
1
2
label,section,type,description,href,addedAt
MonComposant,Ma Catégorie,ui,Description courte du composant.,/components/moncomposant,2024-01-15
# Régénérer les métadonnées depuis le CSV
pnpm sync:components
# Vérifier le rendu
pnpm dev:catalog
# Vérifier les types
pnpm --filter @brickslab./ui-web typecheck
Rappel — si le composant est listé dans project_docs/we_need_composant.md, retirez-le après l'avoir créé.
