@synertech/ui 0.39.0

package/.claude/skills/use-synertech-ui/SKILL.md

@@ -0,0 +1,1578 @@
+---
+name: use-synertech-ui
+description: Guide for optimal usage of @synertech/ui components in consuming projects. Provides component API reference, composition patterns, setup instructions, and anti-patterns to avoid.
+allowed-tools: Read, Glob, Grep, Write, Edit, Bash(pnpm:*), Bash(npx:*), Bash(npm:*), Agent
+argument-hint: "[component-name or question]"
+---
+
+# @synertech/ui - Guide d'utilisation optimale
+
+Ce skill guide les développeurs pour utiliser correctement et efficacement la librairie `@synertech/ui` dans leurs projets Next.js/React.
+
+## Arguments
+
+Format : `[component-name]` ou question libre
+
+Exemples :
+- `/use-synertech-ui Button` - Guide d'utilisation du Button
+- `/use-synertech-ui Dropdown` - Guide d'utilisation du Dropdown
+- `/use-synertech-ui comment faire un formulaire` - Question libre
+- `/use-synertech-ui setup` - Instructions d'installation
+
+Arguments fournis : $ARGUMENTS
+
+## Comportement
+
+1. Si un **nom de composant** est fourni : afficher l'API complète, les exemples d'utilisation idiomatiques, et les anti-patterns à éviter
+2. Si une **question** est posée : répondre en utilisant les composants disponibles de la librairie
+3. Si `setup` est fourni : afficher les instructions d'installation complètes
+4. Sans argument : afficher le catalogue des composants disponibles avec un résumé
+
+---
+
+## Installation & Configuration
+
+### 1. Installer le package
+
+```bash
+pnpm add @synertech/ui
+```
+
+Le package est publié sur le registre npm public : aucun `.npmrc` ni token à configurer.
+
+### 2. Importer les styles
+
+Dans le fichier d'entrée de l'application (ex: `layout.tsx` ou `_app.tsx`) :
+
+```tsx
+import "@synertech/ui/styles.css";
+```
+
+### 3. Peer Dependencies
+
+React >= 18 et React-DOM >= 18 doivent etre installés dans le projet consommateur.
+
+`@mdxeditor/editor` est une peer dependency **optionnelle**, utilisée uniquement par
+`<HelpButton markdown editable>`. Sans elle, le mode édition affiche un message et tout
+le reste de la librairie fonctionne normalement. Pour l'activer :
+
+```bash
+pnpm add @mdxeditor/editor
+```
+
+```tsx
+import "@mdxeditor/editor/style.css";
+```
+
+---
+
+## Imports
+
+Tous les composants sont exportés depuis le point d'entrée unique :
+
+```tsx
+import { Button, Dropdown, DropdownTrigger, DropdownContent, Select, Card } from "@synertech/ui";
+import type { ButtonProps, SelectOption } from "@synertech/ui";
+```
+
+L'utilitaire `cn()` pour merger des classes Tailwind est aussi exporté :
+
+```tsx
+import { cn } from "@synertech/ui";
+```
+
+---
+
+## Catalogue des composants
+
+### Display & Media
+
+| Composant | Description | Server-compatible |
+|-----------|-------------|:-:|
+| `Avatar` | Photo de profil avec fallback texte | Oui |
+| `Skeleton` | Placeholder de chargement (pulse/wave) | Oui |
+| `Indicator` | Badge de notification (dot/count/status/legend) | Oui |
+
+### Navigation & Actions
+
+| Composant | Description | Server-compatible |
+|-----------|-------------|:-:|
+| `Button` | Bouton avec variantes de taille, couleur, icones | Oui |
+| `ButtonGroup` | Groupe de boutons avec sélection | Non |
+| `Breadcrumb` | Fil d'Ariane | Oui |
+| `Pagination` | Navigation par pages | Non |
+| `Dropdown` | Menu déroulant composable | Non |
+| `Tabs` | Interface à onglets composable | Non |
+
+### Forms & Input
+
+| Composant | Description | Server-compatible |
+|-----------|-------------|:-:|
+| `Input` | Champ texte/textarea avec label | Non |
+| `Select` | Combobox searchable avec portal | Non |
+| `Checkbox` | Case à cocher | Non |
+| `RadioButton` | Bouton radio | Non |
+| `Slider` | Curseur (range) accessible avec marques et tooltip | Non |
+| `ImageUploader` | Upload d'image (drag & drop, URL) | Non |
+| `FileSelector` | Sélection de fichiers/dossiers (drag & drop, validation) | Non |
+
+### Layout & Structure
+
+| Composant | Description | Server-compatible |
+|-----------|-------------|:-:|
+| `Card` | Carte composable (Header, Body, Footer) | Oui |
+| `Header` | En-tête de page avec navigation | Non |
+| `Footer` | Pied de page | Oui |
+| `Drawer` | Panneau latéral coulissant | Non |
+| `Divider` | Séparateur horizontal/vertical | Oui |
+
+### Data Display
+
+| Composant | Description | Server-compatible |
+|-----------|-------------|:-:|
+| `Table` | Tableau composable (Header, Body, Row, Cell) | Oui |
+| `DataGrid` | Tableau avancé data-driven (tri, pagination, filtres, sélection, export) | Non |
+| `Chip` | Tag/badge | Oui |
+| `Label` | Étiquette de formulaire | Oui |
+| `Banner` | Bannière notification/hero/promotion | Non |
+
+### Feedback & Overlays
+
+| Composant | Description | Server-compatible |
+|-----------|-------------|:-:|
+| `Modal` | Dialog/overlay | Non |
+| `Tooltip` | Info-bulle au survol/clic | Non |
+| `Toast` | Notification temporaire | Non |
+| `CircularProgress` | Indicateur de chargement | Oui |
+| `HelpButton` | Bouton d'aide contextuel avec Markdown | Non |
+
+### Advanced
+
+| Composant | Description | Server-compatible |
+|-----------|-------------|:-:|
+| `Detachable` | Portail popup (window.open + createPortal) | Non |
+| `AdvanceDetachable` | Detachable avancé (detach/clone, BroadcastChannel) | Non |
+| `WorkflowEditor` | Editeur de workflow visuel (nodes/edges, pan/zoom) | Non |
+| `SchemaEditor` | Editeur de schéma de base de données visuel | Non |
+| `DeviceMockup` | Cadre simulant l'apparence d'appareils (phone, tablet, laptop, etc.) | Non |
+
+---
+
+## API Reference par composant
+
+### Button
+
+```tsx
+import { Button } from "@synertech/ui";
+
+<Button
+  size="md"           // "sm" | "md" | "lg" | "xl"
+  rounded="lg"        // "none" | "sm" | "md" | "lg" | "full"
+  bgColor="bg-blue-600 hover:bg-blue-700"
+  textColor="text-white"
+  focusColor="focus:ring-blue-300"
+  loading={false}
+  fullWidth={false}
+  selected={false}
+  leftIcon={<Icon />}
+  rightIcon={<Icon />}
+  icon={<Icon />}     // Pour bouton icone seul
+  onClick={handleClick}
+>
+  Label
+</Button>
+```
+
+### ButtonGroup
+
+```tsx
+import { Button, ButtonGroup } from "@synertech/ui";
+
+<ButtonGroup
+  orientation="horizontal"  // "horizontal" | "vertical"
+  size="md"
+  selectedValue={selected}
+  onChange={setSelected}
+>
+  <Button value="a">Option A</Button>
+  <Button value="b">Option B</Button>
+  <Button value="c">Option C</Button>
+</ButtonGroup>
+```
+
+### Avatar
+
+```tsx
+import { Avatar } from "@synertech/ui";
+
+<Avatar
+  src="/photo.jpg"
+  alt="Nom"
+  fallback="JD"        // Initiales affichées si pas d'image
+  size="md"            // "xs" | "sm" | "md" | "lg" | "xl"
+  variant="circle"     // "circle" | "square" | "rounded"
+  border={false}
+/>
+```
+
+### Skeleton
+
+```tsx
+import { Skeleton } from "@synertech/ui";
+
+<Skeleton
+  variant="text"       // "text" | "circular" | "rectangular" | "rounded"
+  animation="pulse"    // "pulse" | "wave" | "none"
+  width={200}
+  height={20}
+  count={3}            // Nombre de lignes
+/>
+```
+
+### Indicator
+
+```tsx
+import { Indicator } from "@synertech/ui";
+
+<Indicator
+  variant="count"      // "dot" | "count" | "status" | "legend"
+  color="error"        // "default" | "primary" | "success" | "warning" | "error" | "info" | "dark" | "purple" | "indigo" | "teal"
+  size="md"            // "xs" | "sm" | "md" | "lg" | "xl"
+  placement="top-right"
+  count={5}
+  maxCount={99}
+  pulse={true}
+  bordered={true}
+>
+  <Avatar src="/photo.jpg" />
+</Indicator>
+```
+
+### Breadcrumb
+
+```tsx
+import { Breadcrumb } from "@synertech/ui";
+
+<Breadcrumb
+  items={[
+    { label: "Accueil", href: "/" },
+    { label: "Produits", href: "/products" },
+    { label: "Détail", icon: <ProductIcon /> },
+  ]}
+  separator="/"
+  size="md"            // "sm" | "md" | "lg"
+  maxItems={4}
+/>
+```
+
+### Pagination
+
+```tsx
+import { Pagination } from "@synertech/ui";
+
+<Pagination
+  page={currentPage}
+  totalPages={10}
+  onPageChange={setCurrentPage}
+  size="md"            // "sm" | "md" | "lg"
+  variant="default"    // "default" | "outlined" | "minimal"
+  showFirstLast={true}
+  siblings={1}
+  totalItems={100}
+  pageSize={10}
+  pageSizeOptions={[10, 20, 50]}
+  onPageSizeChange={setPageSize}
+/>
+```
+
+### Dropdown (Composable)
+
+```tsx
+import {
+  Dropdown, DropdownTrigger, DropdownContent,
+  DropdownItem, DropdownCheckboxItem, DropdownRadio,
+  DropdownSeparator, DropdownSubMenu,
+} from "@synertech/ui";
+
+<Dropdown
+  defaultOpen={false}
+  closeOnSelect={true}
+  onOpenChange={(open) => console.log(open)}
+>
+  <DropdownTrigger asChild>
+    <Button>Menu</Button>
+  </DropdownTrigger>
+
+  <DropdownContent
+    side="bottom"       // "top" | "right" | "bottom" | "left"
+    align="start"       // "start" | "center" | "end"
+    sideOffset={4}
+    animation="scale"   // "fade" | "scale" | "slide" | "none"
+    maxHeight={300}
+  >
+    <DropdownItem icon={<EditIcon />} shortcut="Ctrl+E" onClick={handleEdit}>
+      Modifier
+    </DropdownItem>
+    <DropdownItem variant="danger" onClick={handleDelete}>
+      Supprimer
+    </DropdownItem>
+
+    <DropdownSeparator />
+
+    <DropdownCheckboxItem
+      checked={isVisible}
+      onCheckedChange={setVisible}
+    >
+      Afficher les détails
+    </DropdownCheckboxItem>
+
+    <DropdownSubMenu trigger="Plus d'options">
+      <DropdownItem>Exporter</DropdownItem>
+      <DropdownItem>Archiver</DropdownItem>
+    </DropdownSubMenu>
+  </DropdownContent>
+</Dropdown>
+```
+
+### Tabs (Composable)
+
+```tsx
+import { Tabs, TabsList, TabsTrigger, TabsContent } from "@synertech/ui";
+
+<Tabs
+  defaultValue="tab1"
+  variant="underline"   // "underline" | "pills" | "enclosed" | "soft"
+  size="md"             // "sm" | "md" | "lg"
+  color="primary"
+  onValueChange={(v) => console.log(v)}
+>
+  <TabsList>
+    <TabsTrigger value="tab1">Onglet 1</TabsTrigger>
+    <TabsTrigger value="tab2">Onglet 2</TabsTrigger>
+  </TabsList>
+  <TabsContent value="tab1">Contenu 1</TabsContent>
+  <TabsContent value="tab2">Contenu 2</TabsContent>
+</Tabs>
+```
+
+### Input (Form)
+
+```tsx
+import { Input } from "@synertech/ui";
+
+<Input
+  label="Email"
+  type="email"
+  placeholder="you@example.com"
+  helperText="Votre adresse email professionnelle"
+  error={false}
+  hideLabel={false}
+  inline={false}
+  multiline={false}     // true pour textarea
+  rows={3}              // Nombre de lignes si multiline
+  focused={false}       // Focus programmatique
+/>
+```
+
+### Select / Combobox
+
+```tsx
+import { Select } from "@synertech/ui";
+import type { SelectOption } from "@synertech/ui";
+
+const options: SelectOption[] = [
+  { value: "fr", label: "France", icon: <FrFlag /> },
+  { value: "ca", label: "Canada", description: "Amérique du Nord" },
+  { value: "jp", label: "Japon", keywords: ["japan", "nippon"] },
+];
+
+<Select
+  options={options}
+  value={country}
+  onValueChange={setCountry}
+  searchable={true}
+  clearable={true}
+  loading={false}
+  size="md"             // "sm" | "md" | "lg"
+  variant="default"     // "default" | "outlined" | "filled"
+  placeholder="Choisir un pays..."
+  label="Pays"
+  description="Sélectionnez votre pays"
+  helperText="Requis pour la facturation"
+  error="Ce champ est requis"
+  required={true}
+  noOptionsText="Aucun résultat"
+  maxHeight={256}
+  name="country"        // Pour les formulaires natifs
+/>
+```
+
+### Checkbox
+
+```tsx
+import { Checkbox } from "@synertech/ui";
+
+<Checkbox
+  checked={accepted}
+  onChange={(checked) => setAccepted(checked)}
+  label="J'accepte les conditions"
+  description="En cochant, vous acceptez nos CGU"
+  error="Vous devez accepter les conditions"
+  size="md"             // "sm" | "md" | "lg"
+  variant="default"     // "default" | "filled" | "outlined"
+  shape="square"        // "square" | "rounded" | "circle"
+  labelPosition="right" // "left" | "right"
+  indeterminate={false}
+  checkedColor="bg-blue-600"
+/>
+```
+
+### RadioButton
+
+```tsx
+import { RadioButton } from "@synertech/ui";
+
+{["monthly", "yearly"].map((plan) => (
+  <RadioButton
+    key={plan}
+    value={plan}
+    checked={selectedPlan === plan}
+    onCheckedChange={() => setSelectedPlan(plan)}
+    label={plan === "monthly" ? "Mensuel" : "Annuel"}
+    description="Facturé chaque mois"
+    size="md"           // "sm" | "md" | "lg"
+    variant="default"   // "default" | "filled" | "outlined"
+  />
+))}
+```
+
+### Slider
+
+```tsx
+import { Slider } from "@synertech/ui";
+import type { SliderMark } from "@synertech/ui";
+
+<Slider
+  value={volume}                 // controlled (number)
+  onValueChange={setVolume}      // (value: number) => void
+  // defaultValue={40}           // alternative non-contrôlée
+  min={0}
+  max={100}
+  step={1}
+  size="md"                      // "sm" | "md" | "lg"
+  color="primary"               // "primary" | "success" | "warning" | "error" | "info" | "neutral"
+  label="Volume"
+  description="Réglez le niveau sonore"
+  showValue={true}               // affiche la valeur à côté du label
+  showTooltip={true}             // bulle de valeur au survol/focus du curseur
+  valueFormat={(v) => `${v} %`}  // formatage de la valeur affichée
+  error="Valeur trop élevée"    // boolean | string
+  disabled={false}
+  readOnly={false}
+/>
+
+// Marques (graduations) — tableau explicite…
+const marks: SliderMark[] = [
+  { value: 0, label: "0%" },
+  { value: 50, label: "50%" },
+  { value: 100, label: "100%" },
+];
+<Slider min={0} max={100} step={50} marks={marks} defaultValue={50} />
+
+// …ou `marks` auto-générées à chaque step
+<Slider min={0} max={10} step={1} marks defaultValue={6} showValue />
+
+// Couleurs personnalisées (au lieu de `color`)
+<Slider
+  defaultValue={55}
+  trackColor="#fde68a"   // rail
+  fillColor="#d97706"    // portion remplie
+  thumbColor="#92400e"   // curseur
+/>
+```
+
+> Construit sur un `<input type="range">` natif (clavier + ARIA), avec rail/remplissage/curseur stylés. Le curseur visible et le remplissage sont décalés de la largeur du curseur pour rester alignés et ne jamais déborder du rail.
+
+### ImageUploader
+
+```tsx
+import { ImageUploader } from "@synertech/ui";
+
+<ImageUploader
+  value={imageUrl}
+  onChange={setImageUrl}
+  onUpload={async (file) => {
+    const url = await uploadToS3(file);
+    return url;
+  }}
+  label="Photo de profil"
+  maxSize={5 * 1024 * 1024}  // 5MB
+  accept="image/*"
+  showUrlInput={true}
+  aspectRatio="1/1"    // "16/9" | "4/3" | "1/1" | "auto"
+/>
+```
+
+### Card (Composable)
+
+```tsx
+import { Card, CardHeader, CardBody, CardFooter, CardImage, CardTitle, CardDescription } from "@synertech/ui";
+
+<Card
+  variant="outlined"    // "default" | "outlined" | "elevated" | "filled"
+  rounded="lg"          // "none" | "sm" | "md" | "lg" | "xl" | "full"
+  padding="none"        // "none" | "sm" | "md" | "lg"
+  hoverable={true}
+  clickable={false}
+  as="article"          // "article" | "section" | "div"
+>
+  <CardImage src="/cover.jpg" alt="Cover" />
+  <CardHeader actions={<Button size="sm">Edit</Button>} divider>
+    <CardTitle>Titre de la carte</CardTitle>
+    <CardDescription>Description courte</CardDescription>
+  </CardHeader>
+  <CardBody>
+    <p>Contenu principal ici</p>
+  </CardBody>
+  <CardFooter>
+    <Button>Action</Button>
+  </CardFooter>
+</Card>
+```
+
+### Table (Composable)
+
+```tsx
+import { Table, TableHeader, TableHeaderCell, TableBody, TableRow, TableCell } from "@synertech/ui";
+
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHeaderCell>Nom</TableHeaderCell>
+      <TableHeaderCell>Email</TableHeaderCell>
+      <TableHeaderCell>Role</TableHeaderCell>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    {users.map((user) => (
+      <TableRow key={user.id}>
+        <TableCell>{user.name}</TableCell>
+        <TableCell>{user.email}</TableCell>
+        <TableCell><Chip label={user.role} size="sm" /></TableCell>
+      </TableRow>
+    ))}
+  </TableBody>
+</Table>
+```
+
+### Chip
+
+```tsx
+import { Chip } from "@synertech/ui";
+
+<Chip
+  label="Active"
+  variant="soft"        // "solid" | "outlined" | "soft" | "dot"
+  size="md"             // "sm" | "md" | "lg"
+  color="success"       // "default" | "primary" | "success" | "warning" | "error" | "info"
+  rounded="full"        // "none" | "sm" | "md" | "lg" | "full"
+  icon={<CheckIcon />}
+  closable={true}
+  onClose={handleRemove}
+  clickable={true}
+  selected={false}
+  as="button"           // "span" | "div" | "button"
+/>
+```
+
+### Label
+
+```tsx
+import { Label } from "@synertech/ui";
+
+<Label
+  htmlFor="email"
+  size="md"             // "xs" | "sm" | "md" | "lg" | "xl"
+  color="default"       // "default" | "primary" | "secondary" | "success" | "warning" | "error" | "info" | "muted"
+  weight="medium"       // "normal" | "medium" | "semibold" | "bold"
+  required={true}
+  tooltip="Information utile"
+  icon={<MailIcon />}
+  as="label"            // "label" | "span" | "p"
+>
+  Adresse email
+</Label>
+```
+
+### Banner
+
+```tsx
+import { Banner } from "@synertech/ui";
+
+<Banner
+  variant="notification"  // "notification" | "hero" | "promotion"
+  type="warning"          // "info" | "success" | "warning" | "error" | "default"
+  title="Maintenance prévue"
+  description="Le système sera indisponible demain de 2h à 4h."
+  icon={<WarningIcon />}
+  closable={true}
+  onClose={handleDismiss}
+  action={<Button size="sm">En savoir plus</Button>}
+/>
+```
+
+### Header
+
+```tsx
+import { Header } from "@synertech/ui";
+
+<Header
+  logo={<img src="/logo.svg" alt="Logo" />}
+  logoHref="/"
+  navItems={[
+    { label: "Accueil", href: "/" },
+    { label: "Produits", href: "/products", badge: "Nouveau" },
+    { label: "Docs", href: "/docs", external: true },
+  ]}
+  actions={<Button size="sm">Connexion</Button>}
+  variant="bordered"    // "default" | "transparent" | "bordered" | "shadow"
+  size="md"             // "sm" | "md" | "lg"
+  sticky={true}
+  showSearch={true}
+  onSearch={(q) => router.push(`/search?q=${q}`)}
+/>
+```
+
+### Footer
+
+```tsx
+import { Footer } from "@synertech/ui";
+
+<Footer
+  variant="bordered"    // "default" | "bordered" | "minimal" | "dark"
+  size="md"             // "sm" | "md" | "lg"
+  sticky={false}
+>
+  <p>2024 Synertech. Tous droits reserves.</p>
+</Footer>
+```
+
+### Drawer
+
+```tsx
+import { Drawer } from "@synertech/ui";
+
+<Drawer
+  open={isDrawerOpen}
+  onClose={() => setDrawerOpen(false)}
+  position="right"      // "left" | "right" | "top" | "bottom"
+  size="md"             // "sm" | "md" | "lg" | "xl" | "full"
+  title="Filtres"
+  footer={<Button onClick={applyFilters}>Appliquer</Button>}
+  showOverlay={true}
+  closeOnOverlayClick={true}
+  closeOnEscape={true}
+  // Accessibilite (voir la section "Dialogues accessibles")
+  closeLabel="Fermer le panneau"  // nom accessible du bouton de fermeture
+  aria-label="Menu principal"     // nom du dialogue si aucun `title`
+  trapFocus={true}                // Tab / Maj+Tab confines dans le drawer
+  initialFocus="dialog"           // "dialog" | "first" | "none" | ref
+  returnFocus={true}              // true | false | ref
+  lockScroll={true}
+>
+  <p>Contenu du panneau</p>
+</Drawer>
+```
+
+Le Drawer est un vrai dialogue modal : `role="dialog"` + `aria-modal`, focus
+deplace a l'ouverture, Tab confine, Echap, retour du focus au declencheur et
+reste de la page `inert`. L'overlay reste cliquable.
+
+### Divider
+
+```tsx
+import { Divider } from "@synertech/ui";
+
+<Divider
+  orientation="horizontal"  // "horizontal" | "vertical"
+  variant="solid"           // "solid" | "dashed" | "dotted"
+  label="ou"
+  textAlign="center"        // "left" | "center" | "right"
+  thickness={1}
+/>
+```
+
+### Modal
+
+```tsx
+import { Modal } from "@synertech/ui";
+
+<Modal
+  isOpen={isModalOpen}
+  onClose={() => setModalOpen(false)}
+  title="Confirmer la suppression"
+  description="Cette action est irreversible."
+  icon={<TrashIcon />}
+  size="md"              // "sm" | "md" | "lg" | "xl" | "full"
+  showSubmit={true}
+  submitLabel="Supprimer"
+  onSubmitClick={handleDelete}
+  showCancel={true}
+  cancelLabel="Annuler"
+  buttonsPosition="right" // "left" | "center" | "right"
+  reverseButtons={false}
+  allowFullScreen={false}
+  showHeaderDivider={true}
+  showFooterDivider={true}
+  // Accessibilite (voir la section "Dialogues accessibles")
+  closeLabel="Fermer la fenetre"       // nom accessible du bouton de fermeture
+  enterFullScreenLabel="Agrandir"
+  exitFullScreenLabel="Reduire"
+  aria-label="Detail de la tache"      // nom du dialogue si `title=""`
+  closeOnEscape={true}
+  trapFocus={true}                     // Tab / Maj+Tab confines dans la modale
+  initialFocus="dialog"                // "dialog" | "first" | "none" | ref
+  returnFocus={true}                   // true | false | ref
+  lockScroll={true}
+>
+  <p>Etes-vous sur de vouloir supprimer cet element ?</p>
+</Modal>
+```
+
+La modale est un vrai dialogue : `role="dialog"` + `aria-modal="true"`, nommee
+par son `title` (`aria-labelledby`) et decrite par sa `description`
+(`aria-describedby`). Elle prend le focus a l'ouverture, confine Tab / Maj+Tab,
+se ferme avec Echap, rend le focus au declencheur et rend le reste de la page
+`inert`. Les modales imbriquees sont empilees : Echap ne ferme que celle du
+dessus.
+
+**Ne pas** reimplementer un focus trap local ni ajouter `role="dialog"` sur un
+enfant : tout est deja fourni par le composant.
+
+### Tooltip
+
+```tsx
+import { Tooltip } from "@synertech/ui";
+
+<Tooltip
+  content="Information utile"
+  position="top"         // "top" | "bottom" | "left" | "right"
+  variant="default"      // "default" | "light" | "error" | "success" | "warning" | "info"
+  size="md"              // "sm" | "md" | "lg"
+  trigger="hover"        // "hover" | "click" | "manual"
+  delay={0}
+  showArrow={true}
+>
+  <Button>Survolez-moi</Button>
+</Tooltip>
+```
+
+### Toast
+
+```tsx
+import { Toast } from "@synertech/ui";
+
+<Toast
+  title="Sauvegarde reussie"
+  description="Vos modifications ont ete enregistrees."
+  type="success"         // "success" | "error" | "warning" | "info" | "default"
+  variant="soft"         // "solid" | "outlined" | "soft"
+  position="top-right"
+  closable={true}
+  duration={5000}
+  onClose={handleDismiss}
+  action={<Button size="sm">Annuler</Button>}
+/>
+```
+
+### CircularProgress
+
+```tsx
+import { CircularProgress } from "@synertech/ui";
+
+// Indéterminé (spinner)
+<CircularProgress indeterminate size="md" color="primary" />
+
+// Déterminé (progression)
+<CircularProgress
+  value={75}
+  size="lg"              // "xs" | "sm" | "md" | "lg" | "xl"
+  thickness="normal"     // "thin" | "normal" | "thick"
+  color="success"        // "default" | "primary" | "success" | "warning" | "error" | "info"
+  showValue={true}
+  animated={true}
+/>
+```
+
+### HelpButton
+
+```tsx
+import { HelpButton, WithHelpButton } from "@synertech/ui";
+
+// Standalone
+<HelpButton
+  content="Explication en **Markdown** supportee"
+  markdown={true}
+  position="bottom"      // "top" | "bottom" | "left" | "right"
+  size="sm"              // "xs" | "sm" | "md" | "lg"
+  width="md"             // "sm" | "md" | "lg" | "xl"
+  editable={true}
+  onSave={async (content) => { await save(content); return true; }}
+  title="Aide"
+/>
+
+// En wrapper autour d'un autre element
+<WithHelpButton content="Explication" position="right">
+  <Input label="Champ complexe" />
+</WithHelpButton>
+```
+
+### Detachable
+
+```tsx
+import { Detachable } from "@synertech/ui";
+import { useRef } from "react";
+
+const ref = useRef<DetachableRef>(null);
+
+<Detachable
+  ref={ref}
+  title="Editeur detache"
+  width={800}
+  height={600}
+  center={true}
+  copyStyles={true}
+  onDetach={() => console.log("Detached")}
+  onClose={() => console.log("Re-attached")}
+  onPopupBlocked={() => alert("Popup bloque")}
+>
+  <CodeEditor value={code} onChange={setCode} />
+</Detachable>
+
+// API imperative
+<Button onClick={() => ref.current?.detach()}>Detacher</Button>
+<Button onClick={() => ref.current?.attach()}>Rattacher</Button>
+```
+
+### AdvanceDetachable
+
+```tsx
+import { AdvanceDetachable } from "@synertech/ui";
+import { useRef } from "react";
+
+const ref = useRef<AdvanceDetachableRef>(null);
+
+// Mode "detach" : deplace le contenu dans la popup
+<AdvanceDetachable
+  ref={ref}
+  id="editor-1"
+  mode="detach"          // "detach" | "clone"
+  title="Editeur"
+  value={formData}
+  onValueChange={setFormData}
+>
+  {({ open, close, toggle, detached }) => (
+    <div>
+      <Button onClick={toggle}>{detached ? "Rattacher" : "Detacher"}</Button>
+      <FormEditor data={formData} onChange={setFormData} />
+    </div>
+  )}
+</AdvanceDetachable>
+
+// Mode "clone" : synchronise via BroadcastChannel
+<AdvanceDetachable
+  id="sync-editor"
+  mode="clone"
+  value={data}
+  onValueChange={setData}
+  serialize={JSON.stringify}
+  deserialize={JSON.parse}
+>
+  <DataEditor />
+</AdvanceDetachable>
+```
+
+### WorkflowEditor
+
+```tsx
+import { WorkflowEditor } from "@synertech/ui";
+import type { NodeRegistry, WorkflowValue, WorkflowEditorRef } from "@synertech/ui";
+import { useRef } from "react";
+
+const ref = useRef<WorkflowEditorRef>(null);
+
+const nodeRegistry: NodeRegistry = {
+  start: {
+    label: "Debut",
+    color: "#10b981",
+    ports: { outputs: [{ id: "out", label: "Suivant" }] },
+    render: (node) => <div>{node.data.label}</div>,
+  },
+  action: {
+    label: "Action",
+    color: "#3b82f6",
+    ports: {
+      inputs: [{ id: "in", label: "Entree" }],
+      outputs: [{ id: "out", label: "Sortie" }],
+    },
+  },
+};
+
+<WorkflowEditor
+  ref={ref}
+  defaultValue={{ nodes: [], edges: [] }}
+  onValueChange={(val) => console.log(val)}
+  nodeRegistry={nodeRegistry}
+  direction="horizontal"  // "horizontal" | "vertical"
+  draggableNodes={true}
+  connectable={true}
+  selectable={true}
+  panOnDrag={true}
+  zoomOnWheel={true}
+  snapToGrid={false}
+  gridSize={20}
+  showGrid={true}
+  toolbar={true}
+  autoFit={false}
+  minZoom={0.1}
+  maxZoom={3}
+/>
+
+// API imperative
+ref.current?.fitView();
+ref.current?.resetViewport();
+ref.current?.deleteNode("node-1");
+```
+
+### FileSelector
+
+```tsx
+import { FileSelector } from "@synertech/ui";
+
+// Sélection de fichiers (défaut)
+<FileSelector
+  mode="file"             // "file" | "directory" | "both"
+  variant="dropzone"      // "dropzone" | "button"
+  size="md"               // "sm" | "md" | "lg"
+  accept="image/*,.pdf"
+  multiple={true}
+  maxFiles={5}
+  maxSize={10 * 1024 * 1024}  // 10MB
+  value={files}
+  onChange={setFiles}
+  onReject={(file, reason) => console.log(reason)}
+  label="Upload documents"
+  helperText="PDF ou images, max 10MB"
+  error="Ce champ est requis"
+  showFileList={true}
+  placeholder="Glissez des fichiers ici, ou"
+  browseLabel="Parcourir"
+  disabled={false}
+  readOnly={false}
+/>
+
+// Sélection de dossiers
+<FileSelector
+  mode="directory"
+  label="Sélectionner un dossier"
+  multiple={true}
+  onChange={(files) => {
+    // files contient tous les fichiers du dossier sélectionné
+    // file.webkitRelativePath contient le chemin relatif
+    console.log(files);
+  }}
+/>
+
+// Les deux : fichiers ou dossiers
+<FileSelector
+  mode="both"
+  label="Fichiers ou dossiers"
+  browseLabel="Parcourir fichiers"
+  browseFolderLabel="Parcourir dossier"
+  multiple={true}
+  onChange={setFiles}
+/>
+```
+
+**Notes :**
+- En mode `"both"` dropzone, deux boutons "Browse files" et "Browse folder" sont affichés
+- En mode `"both"` button variant, deux boutons côte à côte
+- Le drag & drop de dossiers traverse l'arborescence récursivement
+- `webkitRelativePath` est affiché dans la liste de fichiers quand disponible
+- `accept` n'est pas appliqué au dialogue natif en mode directory (navigateur l'ignore) mais la validation JS reste active
+
+### DataGrid
+
+```tsx
+import { DataGrid } from "@synertech/ui";
+import type { ColumnDef, SortState, DataGridRef } from "@synertech/ui";
+import { useRef } from "react";
+
+const ref = useRef<DataGridRef>(null);
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+  age: number;
+  status: string;
+}
+
+const columns: ColumnDef<User>[] = [
+  { key: "name", header: "Nom", sortable: true, filterable: true },
+  { key: "email", header: "Email", sticky: "left" },
+  { key: "role", header: "Rôle", filterable: true, filterType: "select",
+    filterOptions: ["Admin", "User", "Manager"] },
+  { key: "age", header: "Âge", sortable: true, align: "right",
+    aggregate: "avg" },
+  { key: "status", header: "Statut",
+    render: (val) => <Chip label={String(val)} color={val === "Active" ? "success" : "error"} size="sm" /> },
+  { key: "actions", type: "actions",
+    render: (_, row) => <Button size="sm" onClick={() => edit(row)}>Modifier</Button> },
+];
+
+<DataGrid
+  ref={ref}
+  columns={columns}
+  data={users}
+  rowKey="id"
+  mode="client"               // "client" | "server"
+
+  // Tri
+  sortable
+  multiSort={false}
+  defaultSort={[{ key: "name", direction: "asc" }]}
+  onSort={(sort) => console.log(sort)}
+
+  // Pagination
+  pagination={{ pageSize: 10, pageSizeOptions: [10, 25, 50], showTotalItems: true }}
+  onPageChange={(page) => console.log(page)}
+
+  // Sélection
+  selectable
+  selectionMode="multiple"     // "single" | "multiple"
+  onSelectionChange={(keys) => console.log(keys)}
+
+  // Recherche & Filtres
+  searchable
+  searchPlaceholder="Rechercher..."
+  onSearch={(q) => console.log(q)}
+
+  // Lignes expandables
+  expandable
+  expandedContent={(row) => <div>Détails de {row.name}</div>}
+
+  // Édition inline
+  editable
+  onCellEdit={(rowKey, colKey, value) => console.log(rowKey, colKey, value)}
+
+  // Réordonnement
+  reorderable
+  onReorder={(from, to) => console.log(from, to)}
+
+  // Visibilité des colonnes
+  columnToggle
+
+  // Groupement
+  groupBy="role"
+
+  // Export
+  exportable
+  exportFormats={["csv", "json"]}
+  exportFilename="users-export"
+
+  // Footer agrégats
+  showFooter
+
+  // Visuel
+  density="default"            // "compact" | "default" | "comfortable"
+  striped
+  bordered={false}
+  stickyHeader
+  maxHeight="600px"
+  loading={false}
+  loadingRows={5}
+  emptyState={<p>Aucun utilisateur trouvé</p>}
+
+  // Événements
+  onRowClick={(row, index) => console.log(row)}
+  onRowDoubleClick={(row, index) => console.log(row)}
+
+  // Styles
+  className="my-4"
+  rowClassName={(row) => row.status === "Inactive" ? "opacity-50" : ""}
+/>
+
+// API impérative
+ref.current?.resetFilters();
+ref.current?.resetSort();
+ref.current?.selectAll();
+ref.current?.deselectAll();
+ref.current?.exportData("csv");
+ref.current?.scrollToRow(50);
+ref.current?.getVisibleData();
+```
+
+**Quand utiliser DataGrid vs Table :**
+- **Table** : tableaux simples, contrôle total du markup, server-compatible
+- **DataGrid** : tableaux data-driven avec tri, pagination, filtres, sélection, export
+
+**Mode server :**
+En mode `"server"`, le DataGrid ne fait pas le tri/pagination/filtre côté client. Il délègue via les callbacks `onSort`, `onPageChange`, `onSearch`, `onFilterChange`. Utilisez `totalItems` pour la pagination serveur.
+
+### DeviceMockup
+
+```tsx
+import { DeviceMockup } from "@synertech/ui";
+import type { DeviceType } from "@synertech/ui";
+
+// Avec du contenu React
+<DeviceMockup
+  device="phone"              // "phone" | "android" | "tablet" | "laptop" | "desktop" | "watch" | "browser"
+  orientation="portrait"      // "portrait" | "landscape"
+  theme="dark"                // "dark" | "light"
+  size="md"                   // "sm" | "md" | "lg"
+  showStatusBar={true}
+  statusBarTime="14:30"
+  animated={false}            // Auto-scroll du contenu
+  scrollSpeed={30}            // px/s pour l'animation
+  frameColor="#1e40af"        // Couleur du cadre (CSS)
+  contentClassName="bg-white"
+>
+  <div className="bg-gradient-to-b from-blue-500 to-blue-700 text-white h-full p-4">
+    <h2 className="text-lg font-bold mt-6">Mon App</h2>
+    <p className="text-sm opacity-80 mt-2">Bienvenue</p>
+  </div>
+</DeviceMockup>
+
+// Avec une image
+<DeviceMockup
+  device="laptop"
+  src="/screenshot.png"
+  alt="Capture d'écran de l'application"
+  theme="light"
+  size="lg"
+/>
+
+// Vitrine animée (défilement automatique)
+<DeviceMockup
+  device="phone"
+  animated
+  scrollSpeed={20}
+  showStatusBar
+>
+  <div className="p-4 space-y-4">
+    {/* Contenu plus grand que l'écran — défile automatiquement */}
+    {items.map((item) => (
+      <div key={item.id} className="bg-gray-100 rounded-lg p-3">{item.name}</div>
+    ))}
+  </div>
+</DeviceMockup>
+
+// Tous les appareils côte à côte
+<div className="flex flex-wrap gap-8 items-end">
+  <DeviceMockup device="watch" size="sm" showStatusBar>...</DeviceMockup>
+  <DeviceMockup device="phone" size="sm">...</DeviceMockup>
+  <DeviceMockup device="tablet" size="sm">...</DeviceMockup>
+  <DeviceMockup device="laptop" size="sm">...</DeviceMockup>
+  <DeviceMockup device="desktop" size="sm">...</DeviceMockup>
+  <DeviceMockup device="browser" size="sm">...</DeviceMockup>
+</div>
+```
+
+**Détails par appareil :**
+- **phone** : notch/dynamic island (en haut portrait, à droite landscape), home indicator, bords arrondis
+- **android** : caméra dot, bords arrondis fins
+- **tablet** : caméra discrète, bezels fins
+- **laptop** : écran + barre charnière + base clavier
+- **desktop** : moniteur + pied + socle
+- **watch** : couronne latérale, bracelets haut/bas
+- **browser** : chrome avec feux tricolores et barre URL
+
+**Notes :**
+- En mode `landscape`, le phone positionne le notch à droite (rotation réaliste)
+- `showStatusBar` fonctionne uniquement sur phone, android, tablet et watch
+- `animated` fait défiler le contenu automatiquement en boucle
+- `src` et `children` sont mutuellement exclusifs — `src` a priorité
+
+### SchemaEditor
+
+```tsx
+import { SchemaEditor } from "@synertech/ui";
+import type { SchemaValue, SchemaEditorRef } from "@synertech/ui";
+import { useRef } from "react";
+
+const ref = useRef<SchemaEditorRef>(null);
+
+<SchemaEditor
+  ref={ref}
+  defaultValue={{ tables: [], relations: [] }}
+  onValueChange={(val) => console.log(val)}
+  editable={true}
+  draggableTables={true}
+  panOnDrag={true}
+  zoomOnWheel={true}
+  showGrid={true}
+  toolbar={true}
+  legend={true}
+  autoFit={false}
+/>
+
+// API imperative
+ref.current?.fitView();
+ref.current?.exportSQL();
+ref.current?.autoLayout();
+ref.current?.addTable({ id: "users", name: "users", fields: [] });
+```
+
+---
+
+## Patterns essentiels
+
+### 1. Personnalisation avec className
+
+Tous les composants acceptent `className` pour surcharger les styles :
+
+```tsx
+<Button className="bg-purple-600 hover:bg-purple-700 rounded-full">
+  Custom
+</Button>
+
+<Card className="border-2 border-indigo-500">
+  <CardBody>Contenu</CardBody>
+</Card>
+```
+
+### 2. Controlled vs Uncontrolled
+
+Les composants de formulaire supportent les deux patterns :
+
+```tsx
+// Controlled (vous gerez l'etat)
+const [value, setValue] = useState("");
+<Select value={value} onValueChange={setValue} options={opts} />
+
+// Uncontrolled (etat interne)
+<Select defaultValue="fr" onValueChange={(v) => console.log(v)} options={opts} />
+```
+
+### 3. Composants dans Server Components (Next.js)
+
+Les composants **server-compatible** (sans `"use client"`) peuvent etre utilises directement dans les Server Components :
+
+```tsx
+// app/page.tsx (Server Component)
+import { Card, CardBody, Avatar, Chip, Divider, Skeleton } from "@synertech/ui";
+
+export default function Page() {
+  return (
+    <Card variant="outlined">
+      <CardBody>
+        <Avatar src="/photo.jpg" fallback="JD" />
+        <Chip label="Active" color="success" />
+        <Divider label="Details" />
+      </CardBody>
+    </Card>
+  );
+}
+```
+
+Les composants **non server-compatible** doivent etre utilises dans un Client Component :
+
+```tsx
+// components/UserForm.tsx
+"use client";
+import { Select, Input, Checkbox } from "@synertech/ui";
+
+export function UserForm() {
+  // ... useState, handlers, etc.
+  return (
+    <form>
+      <Input label="Nom" />
+      <Select options={countries} />
+      <Checkbox label="Accepter" />
+    </form>
+  );
+}
+```
+
+### 4. Composition de formulaire idiomatique
+
+```tsx
+"use client";
+import { Input, Select, Checkbox, RadioButton, Button, Label } from "@synertech/ui";
+import { useState } from "react";
+
+export function ContactForm() {
+  const [formData, setFormData] = useState({ name: "", email: "", subject: "", agree: false });
+
+  return (
+    <form className="flex flex-col gap-4">
+      <Input
+        label="Nom complet"
+        value={formData.name}
+        onChange={(e) => setFormData(prev => ({ ...prev, name: e.target.value }))}
+        required
+      />
+      <Input
+        label="Email"
+        type="email"
+        value={formData.email}
+        onChange={(e) => setFormData(prev => ({ ...prev, email: e.target.value }))}
+        error={!formData.email.includes("@")}
+        helperText="Adresse email valide requise"
+      />
+      <Select
+        label="Sujet"
+        options={[
+          { value: "support", label: "Support technique" },
+          { value: "sales", label: "Commercial" },
+          { value: "other", label: "Autre" },
+        ]}
+        value={formData.subject}
+        onValueChange={(v) => setFormData(prev => ({ ...prev, subject: v }))}
+        placeholder="Choisir un sujet..."
+        required
+      />
+      <Checkbox
+        label="J'accepte les conditions d'utilisation"
+        checked={formData.agree}
+        onChange={(checked) => setFormData(prev => ({ ...prev, agree: checked }))}
+      />
+      <Button type="submit" fullWidth>Envoyer</Button>
+    </form>
+  );
+}
+```
+
+### 5. Pattern de page complete
+
+```tsx
+import { Header, Footer, Card, CardBody, Table, TableHeader, TableHeaderCell, TableBody, TableRow, TableCell, Chip, Pagination, Button, Breadcrumb } from "@synertech/ui";
+
+// Server Component
+export default function DashboardPage() {
+  return (
+    <div className="min-h-screen flex flex-col">
+      <Header
+        logo={<Logo />}
+        navItems={[{ label: "Dashboard", href: "/", active: true }]}
+        sticky
+      />
+
+      <main className="flex-1 p-6">
+        <Breadcrumb items={[{ label: "Accueil", href: "/" }, { label: "Utilisateurs" }]} />
+
+        <Card variant="outlined" className="mt-4">
+          <CardBody>
+            <Table>
+              <TableHeader>
+                <TableRow>
+                  <TableHeaderCell>Nom</TableHeaderCell>
+                  <TableHeaderCell>Statut</TableHeaderCell>
+                </TableRow>
+              </TableHeader>
+              <TableBody>
+                <TableRow>
+                  <TableCell>Jean Dupont</TableCell>
+                  <TableCell><Chip label="Actif" color="success" size="sm" /></TableCell>
+                </TableRow>
+              </TableBody>
+            </Table>
+          </CardBody>
+        </Card>
+
+        {/* Pagination doit etre dans un Client Component */}
+      </main>
+
+      <Footer variant="bordered">
+        <p>2024 Synertech</p>
+      </Footer>
+    </div>
+  );
+}
+```
+
+---
+
+### 6. Dialogues accessibles (Modal / Drawer / Sidebar mobile)
+
+`Modal`, `Drawer` et la `Sidebar` en mode mobile implementent le contrat complet
+d'un dialogue modal. Il n'y a rien a rajouter cote application :
+
+| Besoin | Fourni par la librairie |
+| --- | --- |
+| Role et modalite | `role="dialog"` + `aria-modal="true"` |
+| Nom accessible | `aria-labelledby` sur le `title`, sinon prop `aria-label` |
+| Description | `aria-describedby` sur la `description` (Modal) |
+| Focus initial | le dialogue lui-meme (`initialFocus="first"` ou une `ref` au besoin) |
+| Confinement | Tab / Maj+Tab bouclent dans le dialogue (`trapFocus`) |
+| Echap | ferme le dialogue du dessus (`closeOnEscape`) |
+| Retour du focus | le declencheur reprend le focus a la fermeture (`returnFocus`) |
+| Fond inerte | le reste de la page passe en `inert` + `aria-hidden`, scroll bloque |
+| Dialogues imbriques | pile interne : Echap et le focus ne concernent que le dialogue du dessus |
+
+En dessous de `mobileBreakpoint`, la `Sidebar` bascule en tiroir modal et suit le
+meme contrat ; fermee, le panneau hors ecran passe en `inert` donc il sort de
+l'ordre de tabulation.
+
+```tsx
+// Le declencheur reprend le focus automatiquement a la fermeture
+<button onClick={() => setOpen(true)}>Ouvrir la tache</button>
+
+<Modal
+  isOpen={open}
+  onClose={() => setOpen(false)}
+  title="Detail de la tache"
+  description="Tous les champs sont obligatoires."
+>
+  <TaskForm />
+</Modal>
+```
+
+Cas particuliers :
+
+- **Focus sur un champ precis a l'ouverture** : `initialFocus={inputRef}`.
+- **Focus rendu ailleurs qu'au declencheur** (element supprime par l'action) :
+  `returnFocus={autreRef}`.
+- **Zone qui doit rester active derriere le dialogue** (conteneur de toasts,
+  region `aria-live`) : ajouter l'attribut `data-synertech-inert-ignore` sur son
+  element racine.
+- **Menu / popover maison rendu dans un portail** depuis l'interieur du
+  dialogue : le declarer avec `registerFloatingLayer(element, () => trigger)`,
+  sinon il sera rendu inerte avec le fond. Les composants de la librairie
+  (`Dropdown`, `Select`) le font deja : Echap y ferme d'abord le menu, un second
+  Echap ferme le dialogue.
+- **Dialogue maison** : le hook `useDialogA11y` est exporte et fournit le meme
+  comportement (`const { dialogRef, dialogProps } = useDialogA11y({ open, onClose })`).
+
+### 7. Traduction des libelles integres (FR / EN)
+
+Les libelles rendus par la librairie (« Close modal », « Close drawer »,
+« Confirm », « Cancel », plein ecran) sont traduisibles globalement via
+`UILabelsProvider`, ou au cas par cas via les props du composant (la prop gagne
+toujours).
+
+```tsx
+// app/layout.tsx (ou n'importe quel niveau de l'arbre)
+import { UILabelsProvider, frenchUILabels, defaultUILabels } from "@synertech/ui";
+
+<UILabelsProvider labels={locale === "fr" ? frenchUILabels : defaultUILabels}>
+  {children}
+</UILabelsProvider>;
+
+// Override partiel (les autres libelles restent ceux du provider parent)
+<UILabelsProvider labels={{ closeModal: "Fermer le detail" }}>
+  <TaskModal />
+</UILabelsProvider>;
+
+// Override ponctuel
+<Modal closeLabel="Fermer le detail" ... />
+<Drawer closeLabel="Fermer le menu" ... />
+<Sidebar closeLabel="Fermer la navigation" aria-label="Navigation principale" ... />
+```
+
+Cles disponibles : `closeModal`, `closeDrawer`, `closeSidebar`, `openSidebar`,
+`expandSidebar`, `collapseSidebar`, `sidebar`, `enterFullScreen`,
+`exitFullScreen`, `confirm`, `cancel`.
+
+## Anti-patterns a eviter
+
+### 1. Ne pas importer les styles
+
+```tsx
+// MAUVAIS - les composants n'auront pas de styles
+import { Button } from "@synertech/ui";
+
+// BON - importer les styles dans le layout racine
+import "@synertech/ui/styles.css";
+```
+
+### 2. Ne pas utiliser className directement sur les sous-composants composables
+
+```tsx
+// MAUVAIS - risque de casser le layout interne
+<DropdownContent style={{ position: "absolute", top: 100 }}>
+
+// BON - utiliser les props dediees
+<DropdownContent side="bottom" sideOffset={4} align="start">
+```
+
+### 3. Ne pas creer de wrappers inutiles pour les composants server-compatible
+
+```tsx
+// MAUVAIS - ajoute "use client" sans raison
+"use client";
+import { Card, CardBody } from "@synertech/ui";
+export function MyCard({ children }) {
+  return <Card><CardBody>{children}</CardBody></Card>;
+}
+
+// BON - utiliser directement dans un Server Component
+import { Card, CardBody } from "@synertech/ui";
+// Pas besoin de "use client" car Card est server-compatible
+```
+
+### 4. Ne pas re-implementer ce qui existe deja
+
+```tsx
+// MAUVAIS
+<div className="flex items-center gap-2">
+  <span className="w-2 h-2 rounded-full bg-green-500" />
+  <span>En ligne</span>
+</div>
+
+// BON
+<Indicator variant="status" color="success" label="En ligne" />
+```
+
+### 5. Ne pas oublier le pattern controlled pour les formulaires
+
+```tsx
+// MAUVAIS - pas de gestion d'etat
+<Select options={opts} />
+// L'utilisateur ne peut pas recuperer la valeur selectionnee
+
+// BON
+const [val, setVal] = useState("");
+<Select options={opts} value={val} onValueChange={setVal} />
+```
+
+### 6. Utiliser les props de couleur au lieu de className quand disponible
+
+```tsx
+// ACCEPTABLE mais moins idiomatique
+<Button className="bg-red-600 hover:bg-red-700 text-white">Supprimer</Button>
+
+// MIEUX - utilise les props dediees
+<Button bgColor="bg-red-600 hover:bg-red-700" textColor="text-white">Supprimer</Button>
+```
+
+### 7. Reimplementer l'accessibilite des dialogues cote application
+
+```tsx
+// MAUVAIS - focus trap maison, Echap maison, wrapper role="dialog"
+<div role="dialog" aria-modal="true" ref={monFocusTrap}>
+  <Modal isOpen={open} onClose={close}>...</Modal>
+</div>
+
+// BON - le composant fournit deja role/aria-modal, focus, Tab, Echap,
+// retour du focus et fond inerte
+<Modal isOpen={open} onClose={close} title="Detail de la tache">...</Modal>
+```
+
+Un dialogue vraiment specifique se construit avec le hook exporte
+`useDialogA11y`, pas avec un composant local qui duplique le comportement.
+
+---
+
+## Documentation interactive
+
+La documentation Storybook avec tous les composants et leurs variantes est disponible a :
+**https://ui.synertechweb.com/**
+
+Chaque composant a une page interactive avec :
+- Props table auto-generee
+- Exemples visuels de toutes les variantes
+- Playground interactif (Controls)