Brickslab.Lib

Documentation

Référence technique de @brickslab./ui-web — tokens CSS, theming, architecture du monorepo et guide de contribution.

Getting Started Catalogue

Design Tokens

Référence complète de toutes les variables CSS.

Theming & Dark mode

Personnalisation du thème et gestion du mode sombre.

Override composants

Comment surcharger taille, couleur et style des composants.

Architecture

Structure du monorepo, conventions de code.

Ajouter un composant

Checklist complète pour créer et publier un nouveau composant.

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)

// 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.

globals.css

@import "@brickslab./theme-default/dist/tokens.css";

/* Override : changer la couleur de marque */
:root {
  --color-brand: #6366F1;
  --c-brand-subtle: rgba(99, 102, 241, 0.08);
  --c-brand-border: rgba(99, 102, 241, 0.3);
}

/* Override dark mode */
:root.dark {
  --color-brand: #818CF8;
}

Override composants

L'override se fait à 3 niveaux, du plus précis au plus global :

Props du composant : prioritaire quand le composant expose une API (`variant`, `tone`, `size`, `align`, etc.).
Props de style : `style` / `className` quand disponibles dans l'API.
Tokens CSS : override local via variables (`--fontsize-*`, `--color-*`) sur un conteneur parent.

Dans chaque page composant, la section Props affiche maintenant un bloc Override qui liste les paramètres réellement overrideables pour ce composant.

1. Override via props (recommandé)

Exemple — Text

import { Text } from "@brickslab./ui-web";

<Text
  texte="Titre de section"
  variant="body-lg"
  tone="brand"
  align="left"
/>

2. Override local via tokens CSS (utile pour les composants type SectionHeader)

Exemple — SectionHeader

import { SectionHeader } from "@brickslab./ui-web";

<div
  style={
    {
      "--fontsize-3xl": "2.25rem",
      "--fontsize-xl": "1.125rem",
      "--color-fg": "#111827",
      "--color-muted": "#4B5563",
      "--color-brand": "#CC4A48",
    } as React.CSSProperties
  }
>
  <SectionHeader
    eyebrow="Nouveautés"
    title="Composants UI"
    subtitle="Personnalisation fine des styles"
    align="left"
  />
</div>

3. Override global (thème applicatif)

globals.css

:root {
  --color-brand: #6366F1;
  --fontsize-xl: 1.125rem;
  --fontsize-3xl: 2rem;
}

Architecture

Brickslab est un monorepo pnpm avec 4 packages et 1 application.

Packages & Applications

Package	Description
`packages/ui-web (@brickslab./ui-web)`	`Librairie React — source des composants. Publiée sur npm (public).`
`packages/token-contract (@brickslab./token-contract)`	`Déclarations CSS des tokens (contrat, sans valeurs).`
`packages/theme-default (@brickslab./theme-default)`	`Thème par défaut — implémente token-contract avec des valeurs concrètes.`
`apps/brickslab_catalog`	`Site de documentation Next.js 16 (App Router).`

Conventions — ui-web

Structure

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

# Développement
pnpm dev                    # sync + démarrer le catalogue en watch

# Build
pnpm build                  # audit → sync → build tous les packages
pnpm build:catalog          # build catalogue uniquement

# Qualité
pnpm run audit              # audit 7 axes → logs/audit-results.json
pnpm audit:verbose          # idem + affiche les tests échoués
pnpm typecheck              # typecheck tous les packages
pnpm lint                   # lint tous les packages

# Utilitaires
pnpm sync:components        # components.csv → components.data.ts

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.

Créer les fichiers source dans ui-web

bash

# Structure à créer
packages/ui-web/src/components/<category>/<snake_name>/
  ├── <Name>.tsx       # Composant React
  └── <Name>.type.ts  # Types et interface des props

MonComposant.tsx

import React from "react"; // obligatoire
import type { MonComposantProps } from "./MonComposant.type";

export function MonComposant({ label, variant = "default" }: MonComposantProps) {
  return (
    <div
      style={{
        color: "var(--color-fg)",
        background: "var(--c-surface)",
        borderRadius: "var(--radius-md)",
        padding: "var(--space-4)",
      }}
    >
      {label}
    </div>
  );
}

MonComposant.type.ts

export interface MonComposantProps {
  label: string;
  variant?: "default" | "brand";
}

Exporter depuis packages/ui-web/src/index.tsx

index.tsx (ajouter à la bonne section)

// ── Ma catégorie ──────────────────────────────────────────────────────────────
export * from "./components/<category>/<snake_name>/MonComposant";
export * from "./components/<category>/<snake_name>/MonComposant.type";

Ajouter les métadonnées dans components.csv

Fichier : components_docs/components.csv

csv

label,section,type,description,href,addedAt
MonComposant,Ma Catégorie,ui,Description courte du composant.,/components/moncomposant,2024-01-15

Ajouter l'entrée dans la sidebar

Fichier : apps/brickslab_catalog/src/catalog/navigation.data.ts

{
  section: "Ma Catégorie",
  items: [
    // ...composants existants...
    { label: "MonComposant", href: "/components/moncomposant" },
  ],
},

Créer la page catalogue

Fichier : apps/brickslab_catalog/src/app/components/moncomposant/page.tsx

tsx

"use client";
import { MonComposant } from "@brickslab./ui-web";
import { ComponentHeader, SectionTitle, Preview } from "../../../catalog/PageSection";
import { PropsTable, type PropDef } from "../../../catalog/PropsTable";
import { CodeBlock } from "../../../catalog/CodeBlock";

const props: PropDef[] = [
  { name: "label", type: "string", required: true, description: "Texte affiché." },
  { name: "variant", type: '"default" | "brand"', default: '"default"', description: "Variante visuelle." },
];

export default function MonComposantPage() {
  return (
    <div style={{ maxWidth: 800, margin: "0 auto", padding: "40px 24px 80px" }}>
      <ComponentHeader name="MonComposant" description="Description du composant." section="Ma Catégorie" />

      <SectionTitle>Démo</SectionTitle>
      <Preview>
        <MonComposant label="Exemple" />
      </Preview>

      <SectionTitle>Usage</SectionTitle>
      <CodeBlock language="tsx">
        {`import { MonComposant } from "@brickslab./ui-web";

<MonComposant label="Exemple" />`}
      </CodeBlock>

      <SectionTitle>Props</SectionTitle>
      <PropsTable props={props} />
    </div>
  );
}

Régénérer components.data.ts et vérifier

bash

# 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éé.

Récapitulatif — fichiers à toucher

packages/ui-web/src/components/<category>/<name>/<Name>.tsx + .type.ts
packages/ui-web/src/index.tsx — export
components_docs/components.csv — métadonnées
apps/brickslab_catalog/src/catalog/navigation.data.ts — sidebar
apps/brickslab_catalog/src/app/components/<lowercase>/page.tsx — page catalog
Lancer pnpm sync:components