COTON · Install

§ 01

Télécharger le package.

Le dossier /ds contient tout : tokens, composants React, preset Tailwind, logos. À glisser dans votre repo.

ds/ — package complet

tokens.css · tokens.json · tailwind.preset.js · src/*.tsx · README.md · assets/

ds/ ├── README.md ├── package.json ├── tokens.css — variables CSS --coton-* ├── tokens.json — format W3C Design Tokens (Tokens Studio) ├── tailwind.preset.js — preset Tailwind à brancher ├── src/ │ ├── index.tsx — exports publics │ ├── cn.ts — helper clsx + tailwind-merge │ ├── Button.tsx — primary, gold, outline, ghost │ ├── Card.tsx │ ├── Badge.tsx │ ├── Alert.tsx │ ├── Input.tsx │ ├── Tabs.tsx │ └── Avatar.tsx └── assets/ ├── logo-coton.svg — encre marine (fonds clairs) ├── logo-coton-blanc.png — blanc (fonds sombres) ├── favicon.ico └── favicon-blanc.ico

§ 02

Installer dans votre projet.

Trois options selon votre stack. Toutes valides.

# Option A — Mono-repo (recommandé)
cp -R ds packages/coton-ds

# Option B — Dépendance locale
npm install ./ds

# Option C — Lien symbolique pendant le dev
cd ds && npm link
cd ../votre-app && npm link @coton/ds

Puis dans votre app :

npm install clsx tailwind-merge class-variance-authority

§ 03

Importer les tokens CSS.

Une seule ligne, en tête de votre feuille globale. Toutes les variables --coton-* deviennent disponibles.

/* app/globals.css ou src/index.css */
@import "@coton/ds/tokens.css";

/* Optionnel : appliquer le fond signature (blanc + taches crème floutées) */
body { @apply coton-bg-maison; }

§ 04

Configurer Tailwind.

Le preset enregistre toutes les couleurs (marine, or, crème, ink, line, status), les fonts, échelles type, radii, ombres signature, animations shimmer.

// tailwind.config.ts
import cotonPreset from "@coton/ds/tailwind.preset";
import type { Config } from "tailwindcss";

export default {
  presets: [cotonPreset],
  content: [
    "./src/**/*.{ts,tsx}",
    "./node_modules/@coton/ds/**/*.{ts,tsx}",
  ],
} satisfies Config;

§ 05

Charger les fonts.

Trois familles : Fraunces (serif éditorial), Inter Tight (UI), JetBrains Mono (code & meta).

// Avec next/font (Next 13+)
import { Fraunces, Inter_Tight, JetBrains_Mono } from "next/font/google";

const serif = Fraunces({ subsets: ["latin"], variable: "--font-serif" });
const sans  = Inter_Tight({ subsets: ["latin"], variable: "--font-sans" });
const mono  = JetBrains_Mono({ subsets: ["latin"], variable: "--font-mono" });

§ 06

Utiliser les composants.

Tout passe par un import depuis @coton/ds. Composants entièrement typés, variantes via cva().

import {
  Button, Card, CardTitle, CardDescription,
  Badge, Alert, Input, Label,
} from "@coton/ds";

export default function Page() {
  return (
    <div className="max-w-3xl mx-auto p-12 space-y-6">
      <h1 className="font-serif text-5xl tracking-tight">
        Le bon profil. <em className="text-or-400 italic">Du premier coup.</em>
      </h1>

      <div className="flex gap-3">
        <Button variant="primary">Trouver un freelance</Button>
        <Button variant="outline">Comment ça marche</Button>
      </div>

      <Card hover>
        <Badge variant="or" dot>Top pick</Badge>
        <CardTitle>Pierre M.</CardTitle>
        <CardDescription>Lead Frontend · React/TS · Lyon</CardDescription>
      </Card>

      <Alert variant="info" title="Note">
        Le système est composable, pas monolithique.
      </Alert>
    </div>
  );
}

§ 07

Workflow · Storybook, dev, build.

Le package vit dans /ds. Build avec tsup (ESM + CJS + types), Storybook 8 pour explorer, Vitest + jest-axe pour les tests. Tout passe par npm scripts.

Installer en local

Le package n'est pas (encore) sur npm public. Trois façons de l'installer dans un projet COTON :

# A · Lien de fichier (mono-repo, le plus simple)
cd mon-projet
npm install file:../design-system/ds

# B · npm workspaces (si /ds et l'app sont dans le même repo)
# Dans le package.json racine :
"workspaces": ["ds", "apps/*"]

# C · Git submodule (cross-repo)
git submodule add git@github.com:coton-collectif/design-system.git ds
npm install file:./ds

Scripts disponibles

Tous se lancent depuis /ds.

Commande	Effet
npm run build	tsup → `dist/` (ESM + CJS + `.d.ts`). À lancer avant un release.
npm run dev	tsup en mode watch — recompile à chaque édition. Utile si le projet consomme via `file:`.
npm run storybook	Storybook 8 sur localhost:6006. Toutes les variantes des 25 composants.
npm run build-storybook	Storybook statique → `storybook-static/`, déployable sur S3/Vercel/Pages.
npm test	Vitest + Testing Library + jest-axe (smoke a11y).
npm run changeset	Décrire un changement → entrée dans `.changeset/`. À faire avant chaque PR.
npm run release	Bump version + `CHANGELOG.md` + tag git. Lancé par CI sur `main`.

Storybook

Le moyen le plus rapide d'explorer le système, isoler un composant pour debug, ou montrer un état précis à un client.

cd ds
npm install
npm run storybook        # → http://localhost:6006

Inclut l'addon @storybook/addon-a11y — chaque story est auditée live (contraste, ARIA, focus).

Dark mode

Les tokens contiennent les overrides sous [data-theme="dark"]. Activer en posant l'attribut sur <html> :

// Toggle minimal
const setTheme = (t: "light" | "dark") => {
  document.documentElement.dataset.theme = t;
  localStorage.setItem("theme", t);
};

// Au boot, respecter prefers-color-scheme
const saved = localStorage.getItem("theme");
const sys = matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
document.documentElement.dataset.theme = saved ?? sys;

Workflow recommandé

Cloner le repo design-system, cd ds && npm install && npm run dev
Dans le projet consommateur, npm install file:../design-system/ds
Importer "@coton/ds/tokens.css" en haut du main.tsx
Brancher le preset Tailwind (cf. § 04)
Importer les composants nommés depuis "@coton/ds"
Pour modifier un composant : éditer dans ds/src/, npm run dev recompile, le projet voit les changements en HMR
Avant PR : npm test, npm run changeset pour documenter le changement

Troubleshooting

Symptôme	Cause / fix
Polices manquantes (sans-serif système partout)	Le `<link>` Google Fonts n'est pas en place. Cf. § 05.
Couleurs hors palette	`tokens.css` n'est pas importé, ou le preset Tailwind n'est pas branché dans `tailwind.config.js`.
Erreur TS « Module not found »	`npm run build` jamais lancé — `dist/` n'existe pas. Ou le chemin `file:` est faux.
Modifications dans `ds/src` non reflétées	Lancer `npm run dev` dans `/ds` en parallèle du projet consommateur.
Dark mode ne change rien	L'attribut va sur `<html>`, pas `<body>`. Et `tokens.css` doit être chargé avant le CSS du projet.

§ 08

Logos & favicons.

Deux variantes — une pour les fonds clairs, une pour les fonds sombres. Plus deux .ico pour les onglets navigateur.

logo-coton.svg

logo-coton-blanc.png

<!-- Favicons -->
<link rel="icon" href="/assets/favicon.ico"
      media="(prefers-color-scheme: light)" />
<link rel="icon" href="/assets/favicon-blanc.ico"
      media="(prefers-color-scheme: dark)" />

§ 09

API des composants.

Variantes principales. Les types complets sont exportés depuis @coton/ds.

Composant	Variantes	Tailles
<Button>	primary · gold · outline · ghost · link	sm · md · lg
<Card>	+ Header / Eyebrow / Title / Description / Content / Footer	prop hover
<Badge>	marine · or · success · warning · error · info · outline · solid	prop dot
<Alert>	info · success · warning · error	props icon, title
<Input>	+ Label, HelpText	prop invalid
<Tabs>	+ TabsList, TabsTrigger, TabsContent	controlled / uncontrolled
<Avatar>	marine · gold · cream · ink + AvatarStack	sm · md · lg · xl
<Modal>	props open, onClose, title, description, footer	sm · md · lg
<Select>	native <select> stylé · prop invalid	h-10
<ToastProvider>	+ hook useToast() · variants info / success / warning / error	duration ms
<Table>	+ THead / TBody / TR / TH / TD	scroll-x auto

Toute la doc détaillée — props, exemples — est dans ds/README.md.