frontend-anti-slop-playbook

Version : 1.0 — Mars 2026 Scope : Tout projet frontend Gentle Designs Objectif : Produire un frontend de qualité irréprochable et intentionnel, en éliminant systématiquement les signaux d'AI slop

0. Philosophie — Pourquoi ce document existe

L'IA générative (Claude, Copilot, Cursor…) produit par défaut une esthétique reconnaissable : Inter + gradients violets + cards uniformes + ombres identiques + layouts prévisibles. C'est l'AI slop — du contenu fonctionnel mais interchangeable, sans intention de design.

Le positionnement Gentle Designs est l'exact opposé : chaque pixel doit communiquer qu'un humain a pensé le design, pas qu'un prompt l'a généré. Ce document centralise les décisions, outils et patterns validés pour que chaque composant d'un projet bénéficie de la même approche — pas seulement celui qui a eu la chance d'être reworké.

Signaux d'AI Slop à éliminer systématiquement

• Polices génériques : Inter, Roboto, Arial, system-ui utilisées sans intention
• Gradients violets/bleus sur fond blanc (le cliché absolu)
• Ombres uniformes : même box-shadow sur cards, boutons, badges
• Rayons de bordure identiques partout (le fameux rounded-lg universel)
• Layouts 100% symétriques et prévisibles
• Fonds plats monochrome sans texture ni profondeur
• Emojis comme éléments de design (🚀📊💡) au lieu d'icônes intentionnelles
• Letter-spacing et line-height jamais ajustés selon le contexte
• Pas de hiérarchie visuelle : tout a le même poids

1. Stack de référence — Gentle Designs

2. Typographie — Le signal anti-slop #1

La typographie est le levier le plus immédiat pour échapper au rendu générique. Le choix de fonts doit être intentionnel, documenté et cohérent à travers tout le projet.

Polices à ne JAMAIS utiliser par défaut

Inter, Roboto, Arial, system-ui, Space Grotesk (devenu cliché IA), Poppins (sur-utilisée). Ces polices ne sont pas mauvaises en soi — elles sont juste tellement utilisées par les outils IA qu'elles signalent immédiatement "généré".

Polices recommandées (gratuites, web-optimisées)

Display / Titres

Body / Contenu

Monospace

Règles de typographie

1. Un projet = un pairing intentionnel. Choisir 1 display + 1 body + 1 mono MAX.
2. Letter-spacing contextuel — adapter selon l'usage :
   • Headings : -0.01em à -0.02em (serré = confiant)
   • Body text : 0em à 0.01em (légèrement aéré = confortable)
   • Badges/labels : 0.04em à 0.06em (aéré = se lit comme un label)
   • Petits caps/overlines : 0.08em à 0.12em (très espacé = signal catégoriel)
3. Line-height contextuel :
   • Headlines : 1.1 à 1.2
   • Body : 1.5 à 1.7
   • UI compacte : 1.3 à 1.4
4. Variable fonts quand possible — un seul fichier, poids ajustable en continu.
5. Ne jamais laisser Claude choisir la police — le pairing est une décision humaine documentée dans le design token du projet.

Implémentation Tailwind 4

@import "tailwindcss";

@theme {
  --font-display: 'Fraunces', Georgia, serif;
  --font-sans: 'DM Sans', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;
}

<h1 className="font-display text-5xl font-semibold tracking-tight">Titre</h1>
<p className="font-sans text-base leading-relaxed tracking-[0.01em]">Corps</p>
<code className="font-mono text-sm">code</code>

3. Design Tokens — Tailwind 4 @theme

Tailwind 4 remplace le tailwind.config.js par une approche CSS-first via @theme. Tous les tokens sont des CSS variables natives, utilisables partout.

Structure de tokens recommandée

@import "tailwindcss";

@theme {
  /* ─── Couleurs : primitives ─── */
  --color-slate-950: #0a0f1a;
  --color-slate-900: #111827;
  --color-slate-800: #1e293b;
  --color-slate-700: #334155;
  --color-slate-400: #94a3b8;
  --color-slate-300: #cbd5e1;
  --color-slate-100: #f1f5f9;

  /* ─── Couleurs : sémantiques ─── */
  --color-surface: var(--color-slate-950);
  --color-surface-raised: var(--color-slate-900);
  --color-surface-overlay: var(--color-slate-800);
  --color-text-primary: var(--color-slate-100);
  --color-text-muted: var(--color-slate-400);
  --color-text-dim: var(--color-slate-700);
  --color-border: var(--color-slate-800);
  --color-accent: #a78bfa;        /* Exemple — à adapter par projet */
  --color-accent-hover: #8b5cf6;

  /* ─── Typographie ─── */
  --font-display: 'Fraunces', Georgia, serif;
  --font-sans: 'DM Sans', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;

  /* ─── Ombres : hiérarchisées ─── */
  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.2);
  --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.25);
  --shadow-lg: 0 8px 24px rgba(0, 0, 0, 0.3);
  --shadow-glow: 0 0 20px var(--color-accent) / 0.15;

  /* ─── Rayons : intentionnels ─── */
  --radius-sm: 6px;
  --radius-md: 10px;
  --radius-lg: 16px;
  --radius-full: 9999px;

  /* ─── Spacing custom si nécessaire ─── */
  --spacing-section: 6rem;
  --spacing-block: 3rem;
}

Principes

1. Séparer primitives et sémantiques — les couleurs brutes dans --color-slate-*, les rôles dans --color-surface, --color-text-*, etc.
2. Ombres hiérarchisées — JAMAIS la même ombre partout. Cards = shadow-md, boutons = shadow-sm, modals = shadow-lg. L'ombre raconte la profondeur.
3. Rayons intentionnels — Un bouton n'a pas le même rayon qu'une card qui n'a pas le même rayon qu'un badge. Documenter les choix.
4. Un accent dominant + variations — pas de palette distribuée uniformément. Un accent fort, le reste neutre.

4. Animations — Framer Motion (Motion)

Choix de bibliothèque

Règle : Framer Motion couvre 90% des besoins d'un site vitrine ou d'une app. N'ajouter GSAP que si le projet requiert des timelines complexes ou du SVG morphing. Ne jamais installer les deux "au cas où".

Patterns Framer Motion

// Pattern 1 : Stagger reveal (hero, listes)
const stagger = {
  hidden: {},
  visible: { transition: { staggerChildren: 0.12 } },
};
const fadeUp = {
  hidden: { opacity: 0, y: 24 },
  visible: { opacity: 1, y: 0, transition: { duration: 0.5, ease: "easeOut" } },
};

// Pattern 2 : Scroll reveal
<motion.div
  initial={{ opacity: 0, y: 30 }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true, margin: "-100px" }}
  transition={{ duration: 0.6 }}
/>

// Pattern 3 : Hover interaction
<motion.div
  whileHover={{ scale: 1.02, y: -2 }}
  transition={{ type: "spring", stiffness: 300, damping: 20 }}
/>

Principes d'animation

1. Un moment fort bien orchestré > plein de micro-interactions dispersées. Un page load avec stagger progressif crée plus de plaisir que des hover effects partout.
2. prefers-reduced-motion — toujours respecter. Wrapper utilitaire :

   const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;

3. Transform + opacity uniquement pour les animations fréquentes (GPU-accelerated).
4. Spring > ease pour les interactions utilisateur (plus naturel).
5. Durées : micro-interactions 150-300ms, transitions de section 400-600ms, page transitions 300-500ms.

5. Icônes — Phosphor Icons

Pourquoi Phosphor et pas Lucide/Heroicons

Lucide est devenu le défaut de shadcn/ui, Heroicons celui de Tailwind UI. Tout site généré par IA les utilise. Phosphor offre :

• 9 000+ icônes, 6 poids (thin, light, regular, bold, fill, duotone)
• Le style duotone apporte profondeur et caractère, surtout en dark mode
• Tree-shakable, MIT, activement maintenu

Usage stratégique des poids

Implémentation

import { Rocket, Lightning, ShieldCheck } from "@phosphor-icons/react";

// Duotone avec couleur d'accent
<Rocket size={32} weight="duotone" className="text-accent" />

// Regular pour la navigation
<Lightning size={20} weight="regular" className="text-muted" />

6. Composants — Architecture en couches

Couche 1 : shadcn/ui + Radix UI (fondations)

Composants structurels accessibles : Dialog, Dropdown, Tabs, Tooltip, etc.

• Code copié dans le projet (pas de dépendance npm)
• Stylé avec Tailwind, comportement via Radix
• Personnaliser systématiquement les styles par défaut pour correspondre au design token du projet

Interaction clavier : tout composant interactif (modal, dropdown, formulaire, navigation) doit suivre le standard keyboard-navigation.md. Si Radix/shadcn est utilisé, son Dialog/Dropdown gère déjà focus trap et clavier — préférer ces primitives au recodage manuel.

Couche 2 : Aceternity UI / ReactBits / Magic UI (différenciation)

Composants animés premium pour les moments clés :

Règle critique : ces composants ne remplacent PAS un design system. Les utiliser comme accents sur les points d'impact (hero, CTA, features), pas comme base de toute l'UI.

Couche 3 : 21st.dev (inspiration + composants)

Registry ouvert de composants shadcn installables. Workflow :

1. Explorer 21st.dev pour trouver un effet/pattern
2. Installer via npx shadcn add [composant]
3. Adapter aux tokens du projet (ne JAMAIS utiliser tel quel)

7. Backgrounds & Textures — Profondeur visuelle

Les fonds plats à couleur unie sont un marqueur majeur d'AI slop. Techniques pour ajouter profondeur :

Noise / Grain

Ajoute une texture organique aux gradients et surfaces.

/* SVG noise inline — technique CSS-Tricks */
.noise-bg {
  position: relative;
}
.noise-bg::after {
  content: '';
  position: absolute;
  inset: 0;
  background: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.65' numOctaves='3' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E");
  opacity: 0.03;
  pointer-events: none;
  mix-blend-mode: overlay;
}

Outils de génération

• fffuel.co/gggrain — Générateur SVG de gradients granuleux
• grainy-gradients.vercel.app — Playground interactif CSS-Tricks
• cssmatic.com/noise-texture — Générateur de textures bruit

Gradient mesh

Alternative aux gradients linéaires plats :

• Utiliser des radial-gradient multiples avec positions décalées
• Combiner avec mix-blend-mode pour des effets de lumière

Glassmorphism (maîtrisé)

.glass {
  background: rgba(255, 255, 255, 0.05);
  backdrop-filter: blur(12px);
  border: 1px solid rgba(255, 255, 255, 0.08);
  border-radius: var(--radius-md);
}

Attention : le glassmorphism est devenu courant. L'utiliser avec parcimonie, jamais sur tous les éléments.

8. Layout — Casser la prévisibilité

Principes anti-slop

1. Asymétrie intentionnelle — pas tout centré. Un bloc texte à gauche, une illustration débordante à droite.
2. Densité variable — sections aérées alternant avec sections compactes.
3. Grid-breaking — un élément qui sort de la grille (image qui déborde, texte qui chevauche).
4. Espace négatif généreux — l'espace vide n'est pas du gaspillage, c'est du rythme.

Patterns concrets

{/* Asymétrie : contenu décalé */}
<div className="grid grid-cols-12 gap-8">
  <div className="col-span-5 col-start-2">Texte</div>
  <div className="col-span-4 col-start-8">Image</div>
</div>

{/* Overlap : élément qui chevauche */}
<div className="relative">
  <div className="bg-surface-raised rounded-lg p-8">Card</div>
  <div className="absolute -bottom-6 -right-6 bg-accent rounded-full p-4">
    Badge qui dépasse
  </div>
</div>

9. UI/UX Pro Max Skill — Position dans le workflow

Le plugin UI/UX Pro Max pour Claude Code fournit une base de données de 57 styles, 95 palettes, 56 font pairings et 98 guidelines UX.

Rôle assigné : assistant technique, PAS directeur artistique

Commandes utiles

# Chercher des guidelines UX pour un contexte spécifique
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "accessibility focus" --domain ux

# Vérifier un style spécifique
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "glassmorphism" --domain style

# Explorer des font pairings (à valider avec Section 2)
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "modern serif sans" --domain font

INTERDIT : laisser UI/UX Pro Max générer automatiquement le design system d'un projet. Ses palettes "par industrie" produisent des sites interchangeables.

10. Workflow complet — Du brief au composant

Phase 1 : Brief créatif (Claude.ai)

Avant tout code, définir dans le projet Claude.ai :

• Ton : luxe ? brutalist ? éditorial ? organique ? minimal raffiné ?
• Font pairing : 1 display + 1 body + 1 mono (choisis dans Section 2)
• Palette : accent dominant + neutres + 1-2 couleurs de support
• Élément mémorable : qu'est-ce qu'on retiendra de ce site ?
• Références visuelles : 2-3 sites qui incarnent la direction souhaitée

Phase 2 : Design tokens (code)

Traduire le brief en @theme Tailwind 4 (Section 3). Ce fichier est la source unique de vérité pour tout le projet.

Phase 3 : Composants (Claude Code)

Claude Code lit ce playbook + les tokens du projet et :

1. Utilise shadcn/ui pour les fondations (dialog, dropdown, etc.)
2. Pioche dans Aceternity UI / ReactBits pour les moments clés
3. Anime avec Framer Motion selon les patterns (Section 4)
4. Utilise Phosphor Icons avec le poids approprié (Section 5)
5. Ajoute texture/profondeur selon Section 7
6. Vérifie l'accessibilité via UI/UX Pro Max (Section 9)

Phase 4 : Review anti-slop

Checklist avant chaque livraison :

• Aucune police générique non-intentionnelle (Inter, Roboto, Arial)
• Letter-spacing et line-height ajustés selon le contexte
• Ombres hiérarchisées (pas la même partout)
• Rayons de bordure variés selon le type d'élément
• Au moins un élément de layout non-symétrique
• Backgrounds avec texture/gradient (pas de fond plat monochrome sur les sections hero)
• Icônes Phosphor avec poids intentionnel (pas tout en regular)
• Animations avec prefers-reduced-motion respecté
• Pas d'emojis comme éléments de design
• Design tokens utilisés partout (pas de valeurs hardcodées)
• Navigation clavier complète : focus visible, Escape ferme les overlays, équivalent clavier de chaque action souris (cf. keyboard-navigation.md)

11. Ressources & Veille

Libraries (à jour mars 2026)

Typographie

Textures & backgrounds

Veille design

12. Annexe — Extrait anti-patterns

❌ AI Slop typique

// TOUT est mauvais ici :
<div className="bg-white rounded-lg shadow-md p-6">
  <h2 className="text-2xl font-bold text-gray-900">Feature</h2>
  <p className="text-gray-600 mt-2">Description générique</p>
  <button className="bg-purple-600 text-white rounded-lg px-4 py-2 mt-4">
    🚀 Get Started
  </button>
</div>

Problèmes : Inter par défaut, purple gradient cliché, shadow-md uniforme, rounded-lg partout, emoji comme design, aucune texture, aucune intention.

✅ Approche Gentle Designs

<motion.div
  className="bg-surface-raised/80 backdrop-blur-sm border border-border/50 rounded-[var(--radius-md)] p-8 relative overflow-hidden"
  whileHover={{ y: -2 }}
  transition={{ type: "spring", stiffness: 300, damping: 25 }}
>
  {/* Noise texture subtile */}
  <div className="absolute inset-0 opacity-[0.02] mix-blend-overlay pointer-events-none noise-bg" />

  <ShieldCheck size={28} weight="duotone" className="text-accent mb-4" />
  <h3 className="font-display text-xl font-semibold tracking-[-0.01em]">
    Sécurité intégrée
  </h3>
  <p className="font-sans text-text-muted text-sm leading-relaxed tracking-[0.005em] mt-3">
    Chaque intégration est auditée pour protéger vos données.
  </p>
</motion.div>

Différences : font display intentionnel, tracking ajusté, icône Phosphor duotone, couleurs via tokens sémantiques, texture noise, animation spring, pas d'emoji, rayon via variable.

13. Installation dans gentlewits

Emplacement

gentlewits/knowledge/references/frontend-anti-slop-playbook.md

Référencement dans le CLAUDE.md d'un projet

Ajouter dans la section "Documentation transversale" :

## Documentation transversale (docs/gentlewits/)
IMPORTANT : Vérifie si un fichier ci-dessous est pertinent et lis-le.
- `knowledge/references/frontend-anti-slop-playbook.md` — Standards frontend anti-AI-slop

Fichier compagnon par projet

Chaque projet frontend doit avoir un docs/claude-mds/frontend/design-tokens.md qui traduit les principes de ce playbook en valeurs concrètes pour CE projet :

• Fonts choisies (pairing spécifique)
• Palette (couleurs exactes)
• Ombres, rayons, spacing custom
• Direction artistique

Ce fichier est référencé dans la section "Documentation projet" du CLAUDE.md :

## Documentation projet (docs/claude-mds/)
IMPORTANT : Lis le fichier pertinent avant de commencer une tâche.
- `frontend/design-tokens.md` — Palette, fonts, ombres, rayons de CE projet
- `frontend/components.md` — Libraries utilisées, conventions de composants
- `frontend/animations.md` — Patterns d'animation, timings, easings

Quand Claude Code le lit

Ce playbook est lu via progressive disclosure : Claude ne le charge PAS au démarrage de chaque session. Il le lit dès qu'une tâche frontend est demandée, grâce au mot "IMPORTANT" dans l'instruction du CLAUDE.md.

Ce document doit être mis à jour à chaque découverte significative d'outil, de pattern ou de technique. L'écosystème frontend/IA évolue quasi-quotidiennement — une source de plus de 3 mois doit être vérifiée.

Dernière mise à jour : mars 2026