diff --git a/COMPARISON_DESIGN_SYSTEM_PRS.md b/COMPARISON_DESIGN_SYSTEM_PRS.md new file mode 100644 index 0000000..98edefc --- /dev/null +++ b/COMPARISON_DESIGN_SYSTEM_PRS.md @@ -0,0 +1,458 @@ +# Comparaison des deux Pull Requests Design System + +**Date:** 2026-01-12 +**Objectif:** Analyser et comparer les deux approches pour rationaliser le design system Ocobo + +--- + +## Vue d'ensemble + +| Aspect | PR "clean" (BMAD) | PR "first" (Direct DS) | +|--------|-------------------|------------------------| +| **Branche** | `origin/clean` | `origin/first` | +| **Approche** | Process structuré avec PRD | Documentation technique directe | +| **Orientation** | Business + Management | Developer-centric | +| **Stack cible** | Tailwind local (pas de migration immédiate) | PandaCSS + ArkUI (migration production) | +| **Documentation** | `_bmad-output/` + `docs/` | `docs/design-system/` | +| **Commits** | 4 commits (PRD, spec, docs, CLAUDE.md) | 1 commit (DS spec challenge) | + +--- + +## 🎯 Objectifs et Scope + +### PR "clean" - Approche Progressive + +**Objectif principal:** Rationaliser le prototype en restant sur Tailwind + +**Phases définies:** +1. **Phase 1:** Centraliser tokens dans `tailwind.config.js` (migration CDN → local) +2. **Phase 2:** Créer composants core (Container, Button, Badge, Input, Card) +3. **Phase 3:** Créer composants Section (Hero, CTA, Feature, Grid, etc.) +4. **Phase 4:** Refactorer les 15 pages + +**Out of scope:** +- Migration vers PandaCSS/Park UI (projet séparé) +- Tests automatisés +- Optimisation performance +- Accessibilité (déférée) + +### PR "first" - Approche Migration Directe + +**Objectif principal:** Documenter pour migration immédiate vers PandaCSS + ArkUI + +**Phases définies:** +1. **Phase 1 (Quick wins):** PageHero, SectionHeading, CTASection, ClientMarquee (~60% duplication) +2. **Phase 2 (Cards):** FeatureCard, StepCard, ValueCard (~25% duplication) +3. **Phase 3 (Spécifiques):** TeamMemberCard, StoryCard, ComparisonBlock, CheckList (~15% duplication) + +**Inclus dans le scope:** +- Spécifications PandaCSS complètes (recipes, slot recipes) +- Documentation animations avec keyframes +- Migration stack complète + +--- + +## 📐 Architecture des Composants + +### Pattern de Composition + +**Les deux PRs adoptent le même pattern Park UI:** + +```tsx + + + + + +``` + +**Props uniformes identiques:** +- `variant`: `default | outlined | ghost | filled | elevated` +- `size`: `sm | md | lg` +- `colorPalette`: `yellow | mint | sky | coral | dark` + +### Différences clés + +| Aspect | PR "clean" | PR "first" | +|--------|-----------|-----------| +| **Implémentation** | Classes Tailwind inline | PandaCSS recipes (CSS-in-JS) | +| **Syntax** | `className="px-4 py-2"` | `className={css({ px: '4', py: '2' })}` | +| **Configuration** | `tailwind.config.js` | `panda.config.ts` | +| **Type safety** | TypeScript props | Full type-safe CSS-in-JS | + +--- + +## 🎨 Design Tokens + +### Comparaison des Tokens + +| Token | PR "clean" | PR "first" | Statut | +|-------|-----------|-----------|--------| +| **Couleurs core** | ✅ Identiques | ✅ Identiques | ✅ Alignés | +| **Couleurs light** | ✅ (yellowLight, mintLight, etc.) | ✅ (yellowLight, mintLight, etc.) | ✅ Alignés | +| **Border radius** | 5 tokens (sm, md, lg, xl, full) | 10 tokens (+ card, button customs) | ⚠️ "first" plus détaillé | +| **Shadows** | 4 tokens (sm, md, lg, hero) | 7 tokens standard + 5 brutal customs | ⚠️ "first" plus complet | +| **Typography** | 12 tailles | 11 tailles | ✅ Quasi identique | +| **Semantic tokens** | ✅ Définis | ✅ Définis avec mapping | ✅ Alignés | + +### Tokens manquants/différents + +**PR "clean" uniquement:** +- `radius-full` pour pills/avatars (mais existe en `full: 9999px`) + +**PR "first" uniquement:** +- Shadows "brutal" (brutal, brutalYellow, brutalMint, brutalSky, brutalCoral) +- Radius customs (`card: 2.5rem`, `button: 9999px`) +- Z-index scale complète (8 niveaux) +- Semantic tokens plus granulaires (bg.primary, bg.secondary, text.muted, etc.) + +**Recommandation:** Le système de tokens de "first" est plus complet et production-ready. + +--- + +## 🧩 Inventaire des Composants + +### Composants Core (Phase 1-2) + +| Composant | PR "clean" | PR "first" | Alignement | +|-----------|-----------|-----------|------------| +| Container | ✅ Planned | ❌ Non mentionné | ⚠️ À clarifier | +| Button | ✅ Refacto prévu | ✅ Spec complète avec 4 variants + size | ✅ Aligné | +| Badge | ✅ Planned | ❌ Non mentionné | ⚠️ À clarifier | +| Input/Form | ✅ Planned | ❌ Non mentionné | ⚠️ À clarifier | +| Card (primitives) | ✅ 9 sub-components | ❌ Non mentionné explicitement | ⚠️ Approches différentes | + +### Composants Section + +| Composant | PR "clean" | PR "first" | Alignement | +|-----------|-----------|-----------|------------| +| PageHero | ❌ → HeroSection générique | ✅ Spec complète (slot recipe) | ⚠️ "first" plus spécifique | +| SectionHeading | ❌ Non mentionné | ✅ Spec complète | ⚠️ Manque dans "clean" | +| CTASection | ✅ Prévu Phase 3 | ✅ Spec complète (3 variants) | ✅ Aligné | +| ClientMarquee | ❌ Non mentionné | ✅ Spec complète avec animations | ⚠️ Manque dans "clean" | +| FeatureSection | ✅ Prévu Phase 3 | ✅ Via FeatureCard Phase 2 | ⚠️ Nommage différent | +| GridSection | ✅ Prévu Phase 3 | ❌ Non mentionné explicitement | ⚠️ Approches différentes | +| TestimonialSection | ✅ Prévu Phase 3 | ❌ Non mentionné | ⚠️ À clarifier | +| StatsSection | ✅ Prévu Phase 3 | ❌ Non mentionné | ⚠️ À clarifier | +| DecorativeBlob | ✅ Prévu Phase 3 | ❌ Non mentionné | ⚠️ À clarifier | + +### Composants Spécialisés (Phase 3) + +| Composant | PR "clean" | PR "first" | Note | +|-----------|-----------|-----------|------| +| TeamMemberCard | ❌ → Via Card primitives | ✅ Phase 3 | "first" plus prescriptif | +| StoryCard | ❌ → Via Card primitives | ✅ Phase 3 | "first" plus prescriptif | +| ComparisonBlock | ❌ Non mentionné | ✅ Phase 3 | Manque dans "clean" | +| CheckList | ❌ Non mentionné | ✅ Phase 3 | Manque dans "clean" | + +--- + +## 📋 Stratégie d'Implémentation + +### PR "clean" - Progressive Refactoring + +**Philosophie:** Rationaliser d'abord, migrer ensuite + +**Avantages:** +- ✅ Approche low-risk (pas de changement de stack) +- ✅ PRD complet avec user journeys (AI agent + developer) +- ✅ Métriques de succès définies +- ✅ Process de validation visuelle défini +- ✅ 15 pages priorisées avec ordre d'implémentation +- ✅ Checklist de validation par page +- ✅ Risques identifiés et mitigations + +**Inconvénients:** +- ⚠️ Nécessite une migration ultérieure vers PandaCSS (double travail?) +- ⚠️ Specs moins détaillées pour les composants +- ⚠️ Pas de code exemple PandaCSS + +### PR "first" - Direct Migration Path + +**Philosophie:** Documenter pour la prod stack immédiatement + +**Avantages:** +- ✅ Prêt pour production (PandaCSS + ArkUI) +- ✅ Specs détaillées avec code recipes complet +- ✅ Animations documentées (keyframes) +- ✅ Priorisation par impact (quick wins = 60% duplication) +- ✅ Mapping Tailwind → PandaCSS explicite +- ✅ Type-safety CSS-in-JS out-of-the-box + +**Inconvénients:** +- ⚠️ Plus risqué (changement de stack) +- ⚠️ Pas de PRD/documentation business +- ⚠️ Pas de process de validation défini +- ⚠️ Coverage incomplète (manque Input, Badge, Section components) + +--- + +## 📖 Documentation + +### PR "clean" - Documentation Exhaustive + +**Livrables:** +- ✅ `_bmad-output/planning-artifacts/prd.md` (417 lignes) - PRD complet +- ✅ `_bmad-output/analysis/design-system-spec.md` (317 lignes) - Spec DS +- ✅ `_bmad-output/analysis/action-plan.md` (199 lignes) - Plan d'action +- ✅ `_bmad-output/analysis/brainstorming-session-2026-01-12.md` - Notes brainstorming +- ✅ `_bmad-output/analysis/tailwind-config-example.js` - Config exemple +- ✅ `CLAUDE.md` - Point d'entrée pour AI agent +- ✅ `docs/` - 8 fichiers documentation complète projet + +**Total:** ~15 fichiers de documentation + +### PR "first" - Documentation Technique + +**Livrables:** +- ✅ `docs/design-system/README.md` - Vue d'ensemble +- ✅ `docs/design-system/01-tokens.md` (252 lignes) - Tokens complets +- ✅ `docs/design-system/02-animations.md` - Keyframes et animations +- ✅ `docs/design-system/03-components-phase1.md` (465 lignes) - Quick wins specs +- ✅ `docs/design-system/04-components-phase2.md` - Cards specs +- ✅ `docs/design-system/05-components-phase3.md` - Composants spécifiques +- ✅ `docs/design-system/06-button.md` (169 lignes) - Migration Button + +**Total:** 7 fichiers de documentation design system + +### Comparaison + +| Aspect | PR "clean" | PR "first" | +|--------|-----------|-----------| +| **Volume** | Plus volumineux (~1000+ lignes) | Plus concis (~800 lignes) | +| **Type** | Business + Technical | Pure technical | +| **Cible** | AI Agent + Developer + PM | Developer only | +| **Actionnable** | Process-oriented | Code-oriented | +| **Complétude** | Full project scope | DS specs only | + +--- + +## 🔍 Analyse Critique + +### Forces de chaque PR + +#### PR "clean" (BMAD) + +**🟢 Points forts:** +1. **Process complet** - PRD, user journeys, success criteria +2. **Low risk** - Migration progressive sans changement stack +3. **AI-first** - Documentation optimisée pour agent AI +4. **Gouvernance** - Métriques, risques, mitigations +5. **Scope clair** - 15 pages inventoriées et priorisées +6. **Navbar strategy** - Problème identifié (17KB) avec plan + +**🔴 Points faibles:** +1. **Double travail potentiel** - Rationaliser Tailwind puis migrer PandaCSS +2. **Specs génériques** - Moins de détails techniques sur composants +3. **Pas de code exemple** - Manque d'exemples PandaCSS concrets +4. **Animations non documentées** - Pas de spec animations + +#### PR "first" (Direct DS) + +**🟢 Points forts:** +1. **Production-ready** - Specs PandaCSS complètes et utilisables +2. **Code examples** - Recipes complets avec tous variants +3. **Animations** - Keyframes documentés +4. **Quick wins** - Priorisation par impact (60% → 25% → 15%) +5. **Shadows brutal** - Tokens custom Ocobo bien identifiés +6. **Type-safety** - CSS-in-JS full type-safe + +**🔴 Points faibles:** +1. **Higher risk** - Changement de stack complet +2. **Coverage incomplète** - Manque Input, Badge, certains Section components +3. **Pas de process** - Manque PRD, validation, gouvernance +4. **Pas de priorisation pages** - Focus composants, pas pages +5. **Illustrations non traitées** - Mentionnées mais pas de stratégie + +--- + +## 💡 Recommandations pour Rationalisation + +### Option 1: Approche Hybride (RECOMMANDÉE) + +**Combiner le meilleur des deux mondes:** + +#### Phase 0: Documentation (de "clean") +- ✅ Adopter le PRD et le process de validation +- ✅ Garder la gouvernance (métriques, risques) +- ✅ Utiliser CLAUDE.md comme point d'entrée AI + +#### Phase 1: Tokens (de "first") +- ✅ Utiliser les tokens complets de "first" (plus détaillés) +- ✅ Inclure les shadows brutal +- ✅ Inclure les semantic tokens granulaires +- ⚠️ Mais implémenter dans Tailwind d'abord (comme "clean") + +#### Phase 2: Composants Quick Wins (de "first") +- ✅ Suivre la priorisation par impact de "first" +- ✅ Implémenter PageHero, SectionHeading, CTASection, ClientMarquee +- ⚠️ Mais en Tailwind inline d'abord + +#### Phase 3: Core Components (de "clean") +- ✅ Implémenter Container, Button, Badge, Input +- ✅ Card avec primitives (architecture "clean") + +#### Phase 4: Pages Refactoring (de "clean") +- ✅ Utiliser l'ordre et checklist de "clean" +- ✅ 15 pages dans l'ordre défini + +#### Phase 5: Migration PandaCSS (de "first") +- ✅ Une fois rationalisé, migrer vers PandaCSS +- ✅ Utiliser les recipes déjà spécifiées dans "first" + +**Avantages:** +- ✅ Low risk au début (Tailwind) +- ✅ Specs techniques complètes +- ✅ Process et gouvernance +- ✅ Path clair vers production stack + +### Option 2: Full "clean" (Low Risk) + +Si la priorité est de **minimiser les risques:** + +**Adopter:** PR "clean" entièrement +**Compléments à ajouter de "first":** +- Utiliser les tokens plus détaillés (shadows brutal, semantic tokens) +- Ajouter specs pour PageHero, SectionHeading, ClientMarquee +- Documenter les animations (keyframes) + +**Quand:** Migration PandaCSS = projet séparé ultérieur + +### Option 3: Full "first" (Fast to Prod) + +Si la priorité est **time-to-production:** + +**Adopter:** PR "first" entièrement +**Compléments à ajouter de "clean":** +- Créer un PRD minimal +- Définir process de validation visuelle +- Inventorier et prioriser les 15 pages +- Compléter avec Badge, Input, Section components manquants + +**Quand:** Migration immédiate vers PandaCSS + ArkUI + +--- + +## 📊 Matrice de Décision + +| Critère | Poids | PR "clean" | PR "first" | Hybride | +|---------|-------|------------|------------|---------| +| **Risk mitigation** | 🔴🔴🔴 | 9/10 | 4/10 | 8/10 | +| **Time to production** | 🔴🔴 | 4/10 | 9/10 | 6/10 | +| **Completeness (specs)** | 🔴🔴 | 6/10 | 9/10 | 9/10 | +| **Process & governance** | 🔴🔴 | 10/10 | 3/10 | 9/10 | +| **AI-readability** | 🔴 | 9/10 | 7/10 | 9/10 | +| **Type-safety** | 🔴 | 6/10 | 10/10 | 8/10 | +| **Future-proof** | 🔴 | 7/10 | 10/10 | 10/10 | + +**Scores totaux:** +- **PR "clean":** 7.3/10 +- **PR "first":** 7.4/10 +- **Hybride:** 8.4/10 ⭐ + +--- + +## ✅ Plan d'Action Recommandé + +### Étape 1: Merge Strategy + +**Créer une nouvelle branche `design-system-unified`:** + +```bash +# Partir de main +git checkout main +git checkout -b design-system-unified + +# Cherry-pick les meilleurs éléments +git cherry-pick +git cherry-pick +git cherry-pick +git cherry-pick +``` + +### Étape 2: Documentation Consolidée + +**Créer structure hybride:** + +``` +docs/ +├── CLAUDE.md # De "clean" - AI entry point +├── design-system/ +│ ├── 00-overview.md # Nouveau - Vue d'ensemble unifiée +│ ├── 01-tokens.md # De "first" (complet) +│ ├── 02-animations.md # De "first" +│ ├── 03-core-components.md # Fusion clean + first +│ ├── 04-section-components.md # Fusion clean + first +│ └── 05-migration-pandacss.md # De "first" + roadmap +└── project-management/ + ├── prd.md # De "clean" + ├── action-plan.md # De "clean" + updates + └── validation-checklist.md # De "clean" +``` + +### Étape 3: Tokens Unifiés + +**Utiliser tokens de "first" mais implémenter en Tailwind:** + +```js +// tailwind.config.js +module.exports = { + theme: { + extend: { + // Tokens de "first" (plus complets) + colors: { /* ... */ }, + shadows: { + // Standard + sm: '...', + md: '...', + lg: '...', + // Ocobo brutal customs (de "first") + brutal: '8px 8px 0px 0px rgba(33,35,35,1)', + brutalYellow: '8px 8px 0px 0px #F1CF25', + // ... + } + } + } +} +``` + +### Étape 4: Composants Priorisés + +**Phase 1 (Quick Wins - de "first"):** +1. PageHero (Tailwind version) +2. SectionHeading (Tailwind version) +3. CTASection (Tailwind version) +4. ClientMarquee (Tailwind version) + +**Phase 2 (Core - de "clean"):** +1. Container +2. Button (avec specs "first") +3. Badge +4. Input +5. Card primitives + +**Phase 3-4:** Suivre le plan de "clean" + +### Étape 5: Validation + +**Utiliser le process de "clean":** +- Checklist de validation visuelle par page +- Validation progressive +- Commit par page + +--- + +## 🎯 Conclusion + +**Les deux PRs sont complémentaires:** + +- **PR "clean"** excelle sur le **process, la gouvernance, et la minimisation des risques** +- **PR "first"** excelle sur les **specs techniques, le code production-ready, et la migration PandaCSS** + +**L'approche hybride recommandée permet de:** +1. ✅ Démarrer low-risk (Tailwind rationalization) +2. ✅ Avoir des specs techniques complètes dès le départ +3. ✅ Suivre un process structuré avec validation +4. ✅ Avoir un path clair vers PandaCSS quand prêt + +**Next step:** Créer la branche `design-system-unified` et consolider la documentation. diff --git a/_bmad-output/analysis/design-system-spec.md b/_bmad-output/analysis/design-system-spec.md new file mode 100644 index 0000000..dd93a18 --- /dev/null +++ b/_bmad-output/analysis/design-system-spec.md @@ -0,0 +1,316 @@ +# Ocobo Design System Specification + +**Date:** 2026-01-12 +**Source:** Brainstorming Session - Rationalisation Prototype + +--- + +## 1. Design Tokens + +### 1.1 Couleurs + +#### Primitifs + +``` +colors: + ocobo: + dark: '#212323' + yellow: + DEFAULT: '#F1CF25' + light: '#FFFCEE' + mint: + DEFAULT: '#9ADBBA' + light: '#EBFDF5' + sky: + DEFAULT: '#99D1DF' + light: '#F0F9FB' + coral: + DEFAULT: '#FE9C87' + light: '#FFF5F2' + gray: + 50: '#FAFAFA' + 100: '#F5F5F5' + 200: '#E5E5E5' + 300: '#D4D4D4' + 400: '#A3A3A3' + 500: '#737373' + 600: '#525252' + 700: '#404040' + 800: '#262626' + 900: '#171717' + white: '#FFFFFF' + black: '#000000' +``` + +#### Sémantiques + +``` +semantic: + color-primary: '{colors.ocobo.yellow.DEFAULT}' + color-primary-light: '{colors.ocobo.yellow.light}' + color-accent: '{colors.ocobo.coral.DEFAULT}' + color-success: '{colors.ocobo.mint.DEFAULT}' + color-info: '{colors.ocobo.sky.DEFAULT}' + color-surface: '{colors.gray.50}' + color-background: '{colors.white}' + color-text: '{colors.ocobo.dark}' + color-text-muted: '{colors.gray.600}' + color-border: '{colors.gray.200}' +``` + +--- + +### 1.2 Border Radius + +| Token | Valeur | Usage | +|-------|--------|-------| +| `radius-sm` | `0.5rem` (8px) | Petits éléments, badges, inputs | +| `radius-md` | `1rem` (16px) | Cards standard, boutons | +| `radius-lg` | `1.5rem` (24px) | Cards hero, sections | +| `radius-xl` | `2.5rem` (40px) | Cards premium, modals | +| `radius-full` | `9999px` | Pills, avatars | + +--- + +### 1.3 Shadows + +| Token | Valeur | Usage | +|-------|--------|-------| +| `shadow-sm` | `0 1px 2px 0 rgb(0 0 0 / 0.05)` | Cards au repos | +| `shadow-md` | `0 4px 6px -1px rgb(0 0 0 / 0.1)` | Cards hover | +| `shadow-lg` | `0 10px 15px -3px rgb(0 0 0 / 0.1)` | Modals, dropdowns | +| `shadow-hero` | `0 40px 100px -20px rgb(0 0 0 / 0.08)` | Hero sections, CTAs majeurs | + +--- + +### 1.4 Typography + +| Token | Taille | Line Height | Usage | +|-------|--------|-------------|-------| +| `text-micro` | 10px | 1.4 | Badges, labels uppercase | +| `text-xs` | 12px | 1.4 | Captions, metadata | +| `text-sm` | 14px | 1.5 | Body small, UI elements | +| `text-base` | 16px | 1.5 | Body default | +| `text-lg` | 18px | 1.6 | Body large, lead | +| `text-xl` | 20px | 1.5 | Subheadings | +| `text-2xl` | 24px | 1.4 | H4 | +| `text-3xl` | 30px | 1.3 | H3 | +| `text-4xl` | 36px | 1.2 | H2 | +| `text-5xl` | 48px | 1.1 | H1 | +| `text-6xl` | 60px | 1.1 | Hero mobile | +| `text-7xl` | 72px | 1.0 | Hero desktop | + +#### Font Families + +``` +fontFamily: + sans: ['Bornia', 'Inter', 'sans-serif'] + display: ['Bermia', 'Inter', 'sans-serif'] +``` + +--- + +## 2. Architecture Composants + +### 2.1 Pattern Composition (Style Park UI) + +Tous les composants suivent le pattern de composition : + +```tsx + + + + + + + +``` + +### 2.2 Props Uniformes + +| Prop | Valeurs | Description | +|------|---------|-------------| +| `variant` | `default`, `outlined`, `ghost`, `filled`, `elevated` | Style visuel | +| `size` | `sm`, `md`, `lg` | Dimensions (padding, fonts) | +| `colorPalette` | `yellow`, `mint`, `sky`, `coral`, `dark` | Thème couleur | + +--- + +## 3. Composants Core (5 essentiels) + +### 3.1 Container + +```tsx +interface ContainerProps { + size?: 'sm' | 'md' | 'lg' | 'full' + children: React.ReactNode +} + +// Sizes +sm: max-w-3xl +md: max-w-5xl +lg: max-w-7xl +full: max-w-full +``` + +### 3.2 Button + +```tsx +interface ButtonProps { + variant?: 'primary' | 'secondary' | 'outline' | 'ghost' + size?: 'sm' | 'md' | 'lg' + colorPalette?: 'yellow' | 'mint' | 'sky' | 'coral' | 'dark' +} +``` + +### 3.3 Badge + +```tsx +interface BadgeProps { + variant?: 'solid' | 'outline' | 'subtle' + size?: 'sm' | 'md' + colorPalette?: 'yellow' | 'mint' | 'sky' | 'coral' | 'dark' +} +``` + +### 3.4 Input / Form + +```tsx +interface InputProps { + variant?: 'outline' | 'filled' | 'flushed' + size?: 'sm' | 'md' | 'lg' +} +``` + +### 3.5 Card (Primitives) + +``` +components/Card/ +├── index.ts +├── CardRoot.tsx +├── CardHeader.tsx +├── CardTitle.tsx +├── CardDescription.tsx +├── CardBody.tsx +├── CardFooter.tsx +├── CardMedia.tsx +├── CardBadge.tsx +└── CardAvatar.tsx +``` + +```tsx +interface CardRootProps { + variant?: 'default' | 'outlined' | 'ghost' | 'filled' | 'elevated' + size?: 'sm' | 'md' | 'lg' + colorPalette?: 'yellow' | 'mint' | 'sky' | 'coral' | 'dark' +} +``` + +--- + +## 4. Composants Section + +### 4.1 Section (Base) + +```tsx +interface SectionProps { + spacing?: 'sm' | 'md' | 'lg' // py-16, py-24, py-32 + background?: 'white' | 'gray' | 'dark' | 'yellow' | 'mint' | 'sky' +} +``` + +### 4.2 HeroSection + +```tsx +interface HeroSectionProps { + variant?: 'centered' | 'split' | 'animated' + background?: 'white' | 'dark' +} +``` + +### 4.3 CtaSection + +```tsx +interface CtaSectionProps { + colorPalette?: 'yellow' | 'dark' | 'mint' | 'sky' + variant?: 'simple' | 'with-form' +} +``` + +### 4.4 FeatureSection + +```tsx +interface FeatureSectionProps { + background?: 'dark' | 'light' + withBlobs?: boolean +} +``` + +### 4.5 GridSection + +```tsx +interface GridSectionProps { + columns?: 2 | 3 | 4 + gap?: 'md' | 'lg' +} +``` + +### 4.6 TestimonialSection + +```tsx +interface TestimonialSectionProps { + variant?: 'single' | 'carousel' +} +``` + +### 4.7 StatsSection + +```tsx +interface StatsSectionProps { + columns?: 3 | 4 +} +``` + +### 4.8 DecorativeBlob + +```tsx +interface DecorativeBlobProps { + position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'center' + colorPalette?: 'yellow' | 'mint' | 'sky' | 'coral' + size?: 'sm' | 'md' | 'lg' + opacity?: 10 | 20 | 30 +} +``` + +--- + +## 5. Inventaire Cards Existantes + +| Type | Usage | Composant cible | +|------|-------|-----------------| +| Article cards | Blog, Podcast, Stories | `CardRoot variant="default"` + `CardMedia` | +| Profile cards | Team, Authors | `CardRoot` + `CardAvatar` | +| Job cards | Offres emploi | `CardRoot variant="outlined"` | +| Callouts | Mise en valeur | `CardRoot variant="filled"` | +| Section items | Grilles 3-4 cols | `CardRoot variant="ghost"` | +| Tool cards | Outils/Features | `CardRoot variant="elevated"` | +| Contact form | Formulaires | `CardRoot` + Form components | + +--- + +## 6. Migration Notes (Panda CSS / Park UI) + +### Compatibilité confirmée +- React 19 ✅ +- TypeScript ✅ +- Nomenclature Park UI adoptée ✅ +- Props système aligné ✅ + +### À faire lors migration +- Mapping tokens Tailwind → Panda CSS +- Conversion classes inline → CSS-in-JS +- Adoption recipes `cva()` + +--- + +*Document généré automatiquement - Session brainstorming 2026-01-12* diff --git a/_bmad-output/planning-artifacts/prd.md b/_bmad-output/planning-artifacts/prd.md new file mode 100644 index 0000000..5431bbd --- /dev/null +++ b/_bmad-output/planning-artifacts/prd.md @@ -0,0 +1,416 @@ +--- +stepsCompleted: [step-01-init, step-02-discovery, step-03-success, step-04-journeys, step-05-domain-skipped, step-06-innovation, step-07-project-type, step-08-scoping, step-09-functional, step-10-nonfunctional, step-11-polish] +classification: + projectType: "Web App (SPA React) - Design System Rationalization" + domain: "General (Agency Website)" + complexity: "Medium" + projectContext: "Brownfield - Cleanup AI-generated prototype" + objective: "Blueprint pour refactoring repo prod" +inputDocuments: + - _bmad-output/analysis/brainstorming-session-2026-01-12.md + - _bmad-output/analysis/design-system-spec.md + - _bmad-output/analysis/action-plan.md + - docs/index.md + - docs/project-overview.md + - docs/architecture.md + - docs/component-inventory.md + - docs/data-models.md + - docs/api-architecture.md + - docs/source-tree-analysis.md + - docs/development-guide.md +documentCounts: + briefs: 0 + research: 0 + brainstorming: 1 + analysis: 2 + projectDocs: 8 +workflowType: 'prd' +--- + +# Product Requirements Document - prototype + +**Author:** jerome +**Date:** 2026-01-12 + +## Executive Summary + +**Project:** Design System Rationalization for Ocobo Prototype +**Objective:** Clean up AI-generated prototype to create an AI-readable blueprint for production migration + +**What:** Rationalize the Ocobo prototype by extracting tokens, consolidating components, and refactoring pages to use a consistent Design System. + +**Why:** Enable agentic migration to production stack (Panda CSS / Park UI) by making the codebase clean, consistent, and AI-readable. + +**Who:** Primary user is an AI agent that will read and convert the code. Secondary user is Jerome for review and validation. + +**Key Deliverables:** +- Rationalized prototype with centralized tokens in `tailwind.config.js` +- Reusable component library (Card, Button, Badge, Section components, etc.) +- 15 pages refactored using DS components only +- CLAUDE.md + DS documentation for AI navigation + +**Out of Scope:** +- Migration to Panda CSS / Park UI (separate project) +- Automated tests +- Production repo refactoring +- Wording extraction for localization +- Accessibility (deferred to migration project) +- Performance optimization + +## Success Criteria + +### User Success (Developer Experience) + +**When opening the rationalized prototype, the developer sees:** +- A clear component catalog with well-defined, reusable components +- Documented and limited design tokens (colors, radius, shadows, typography) +- Pages that compose Design System components (no inline/page-specific declarations) +- Visual result very similar to current prototype (minor intentional adjustments acceptable: border radius harmonization, card consolidation) + +**Success "aha!" moment:** "This is clean, I can work with this for the prod repo refactoring." + +### Business Success (Project Goals) + +| Metric | Target | +|--------|--------| +| Card components | 1 CardRoot with composition primitives (from ~7 variants) | +| Border-radius tokens | 4 (sm, md, lg, xl) - down from 12+ | +| Shadow tokens | 4 (sm, md, lg, hero) | +| Typography scale | 12 sizes (harmonized) | +| Pages refactored | 15/15 (100%) | +| Component documentation | Clean code + inventory with props (nice-to-have) | + +### Technical Success + +- **Visual validation:** Manual page-by-page comparison with current prototype +- **Build:** Passes without errors +- **No regressions:** All pages render correctly with new components + +### Measurable Outcomes + +**Zero tolerance (failure if present):** +- Inline hardcoded colors remaining +- Buttons implemented in different ways +- Multiple card component variants (should be 1 composable Card) +- Tokens not centralized in tailwind.config.js + +## Product Scope + +### MVP - Minimum Viable Product + +1. **Phase 1 - Foundations:** Centralized tokens in `tailwind.config.js` + - Colors (primitives + semantic) + - Border-radius (4 tokens) + - Shadows (4 tokens) + - Typography (12 sizes) + - Migrate from CDN to local Tailwind config + +2. **Phase 2 - Core Components:** All reusable components extracted + - Card (composition architecture) + - Button (rationalized) + - Badge, Input, Container + - Section components (Hero, CTA, Feature, Grid, etc.) + +3. **Phase 3 - Pages Refactoring:** All 15 pages using DS components + - No inline declarations + - Consistent component usage + +4. **Deliverables:** + - Rationalized prototype (code) + - Component inventory with props (nice-to-have) + +### Vision (Future) + +- Use this rationalized prototype as blueprint for prod repo refactoring +- Future migration to Panda CSS / Park UI will be simplified + +## User Journeys + +**Primary User:** AI Agent (for automated migration to prod stack) +**Secondary User:** Jerome (for review and validation) + +**Key Insight:** The prototype must be optimized for AI readability - clean structure, consistent patterns, no ambiguity. + +### Journey 1: AI Agent - Component Extraction + +**Context:** An AI agent analyzes the prototype to extract and convert components to the prod stack (Panda CSS / Park UI). + +**Opening Scene:** The agent receives instructions to convert the `Card` component to Panda CSS. + +**Rising Action:** +1. Agent opens `components/Card/index.ts` and finds a clear export +2. Reads `CardRoot.tsx` and identifies typed props: `variant`, `size`, `colorPalette` +3. Finds well-structured Tailwind classes mapped to config tokens +4. Understands the composition pattern (CardHeader, CardBody, etc.) + +**Climax:** Agent generates the equivalent Panda CSS recipe without ambiguity. + +**Resolution:** Component converted cleanly, ready for Jerome's review. + +### Journey 2: AI Agent - Page Conversion + +**Context:** An AI agent must convert a complete page. + +**Opening Scene:** Agent opens `pages/Home.tsx`. + +**Rising Action:** +1. Easily identifies sections (imported Section components) +2. Each section uses DS components (no complex inline JSX) +3. Props are explicit and typed +4. No business logic mixed with rendering + +**Climax:** Agent understands the page structure in seconds. + +**Resolution:** Page converted with the same visual rendering. + +### Journey 3: Jerome - Review & Validation + +**Context:** Jerome verifies the AI agent's work. + +**Opening Scene:** The agent has converted 3 pages. Jerome opens the diff. + +**Rising Action:** +1. Visual comparison between original prototype vs converted prod +2. Verifies token mapping is correct +3. Identifies minor adjustments needed + +**Climax:** Rendering is nearly identical, a few minor tweaks. + +**Resolution:** Jerome validates and moves to next pages. + +### Journey Requirements Summary + +| Requirement | For | Priority | +|-------------|-----|----------| +| Predictable file structure | AI Agent | Critical | +| Typed and explicit props | AI Agent | Critical | +| Tailwind tokens (no hardcoded values) | AI Agent | Critical | +| Clear composition pattern | AI Agent | High | +| Pages = DS component composition only | AI Agent | High | +| Human-readable code for review | Jerome | Medium | + +## Innovation: AI-Optimized Codebase + +### Concept + +**Objective:** Create a prototype with Markdown documentation that enables an AI agent to: +1. Quickly understand the Design System and its usage +2. Navigate efficiently through the codebase +3. Generate equivalents in the prod stack (Panda CSS / Park UI) +4. Map tokens to the prod stack + +### AI-Readability Strategy + +| Element | Role | +|---------|------| +| **CLAUDE.md / agent.md** | Main entry point for AI - navigation guide | +| **DS Documentation (Markdown)** | Explains Design System usage | +| **Clean, readable code** | Clear structure, explicit naming | +| **Documented tokens** | Clear mapping in config + docs | + +### Target Documentation Structure + +``` +docs/ +├── CLAUDE.md (or agent.md) # AI entry point +├── design-system/ +│ ├── tokens.md # Colors, radius, shadows, typography +│ ├── components.md # Catalog + usage +│ └── patterns.md # How to compose pages +``` + +**Focus:** AI must understand **how to use** the Design System, not just its technical structure. + +### Validation + +**Success if:** +- An AI agent reads CLAUDE.md and knows where to go +- Agent understands DS usage (not just code) +- Token mapping to Panda CSS / Park UI is obvious +- Little ambiguity about patterns to follow + +### Innovation Deliverables + +1. **Rationalized prototype** (clean code) +2. **Updated Markdown documentation** for AI consumption +3. **CLAUDE.md** as agent entry point + +## Web App (Design System) Specific Requirements + +### Project-Type Overview + +**Type:** SPA React - Design System Rationalization +**Focus:** Code cleanliness and AI-readability, not performance optimization + +### Technical Architecture Considerations + +| Aspect | Decision | +|--------|----------| +| **Browser Support** | Modern only (Chrome, Firefox, Safari, Edge - latest versions) | +| **Responsive Design** | All breakpoints covered | +| **Mobile Strategy** | Mobile-first conserved | +| **Breakpoints** | Keep current prototype breakpoints (rationalization deferred to migration) | +| **Accessibility** | Deferred to AI migration project | +| **Performance** | Not a priority - focus on code cleanliness | + +### Responsive Design Requirements + +**Components must:** +- Work across all existing breakpoints +- Follow mobile-first CSS patterns +- Use Tailwind responsive utilities consistently (`sm:`, `md:`, `lg:`, `xl:`) + +**Breakpoints (preserved from prototype):** +- Default (mobile) +- `sm` (640px) +- `md` (768px) +- `lg` (1024px) +- `xl` (1280px) + +### Implementation Considerations + +**In Scope:** +- Clean, well-structured components +- Consistent responsive patterns +- Mobile-first approach maintained +- AI-readable code structure + +**Deferred to Migration Project:** +- Accessibility (WCAG compliance) +- Performance optimization +- Breakpoint rationalization +- Browser polyfills (not needed for modern browsers) + +## Project Scoping & Phased Development + +### MVP Strategy & Philosophy + +**MVP Approach:** Complete Design System Rationalization +**Objective:** Clean, AI-readable prototype ready for agentic migration + +**Everything is MVP** - All 3 phases are interdependent: +- Without tokens → no coherent components +- Without components → no refactored pages +- Without AI docs → no agentic migration possible + +### MVP Feature Set + +**Phase 1 - Foundations (MVP)** +- Tokens centralized in `tailwind.config.js` +- CDN → local config migration +- Colors, radius, shadows, typography rationalized + +**Phase 2 - Core Components (MVP)** +- All components extracted and rationalized +- Card (composition architecture) +- Button, Badge, Input, Container +- Section components (Hero, CTA, Feature, Grid...) +- **Navbar refactored** (split into sub-components) + +**Phase 3 - Pages Refactoring (MVP)** +- 15 pages refactored with component approach +- No complex inline JSX +- DS component composition only + +**Phase 4 - AI Documentation (MVP)** +- CLAUDE.md as agent entry point +- DS documentation in Markdown (tokens, components, patterns) +- Clear structure for AI navigation + +### Risk Mitigation Strategy + +| Risk | Impact | Mitigation | +|------|--------|------------| +| **Scope creep** | Refactor more than necessary | Clearly define "rationalized" vs "improved" | +| **Visual deviation** | Prototype validated by stakeholders | Systematic visual validation, minor changes only | +| **Complex Navbar** | 17KB, hard to split | Progressive split into sub-components, visual tests | +| **Over-engineering** | Create unnecessary abstractions | Keep it simple, Tailwind inline, no recipes | + +### Guardrails + +**What we DO:** +- Rationalize (reduce variants) +- Extract (create reusable components) +- Document (for AI) + +**What we DON'T do:** +- Improve design (except minor radius/shadow adjustments) +- Add features +- Change behavior + +## Functional Requirements + +### Token Management + +- **FR1:** Developer can access all color tokens from a centralized `tailwind.config.js` +- **FR2:** Developer can use 4 border-radius tokens (sm, md, lg, xl) consistently across components +- **FR3:** Developer can use 4 shadow tokens (sm, md, lg, hero) consistently across components +- **FR4:** Developer can use 12 typography size tokens consistently across components +- **FR5:** Developer can access semantic color tokens (not just primitive colors) + +### Core Component Extraction + +- **FR6:** Developer can import a single Card component with composition primitives (CardRoot, CardHeader, CardBody, CardFooter) +- **FR7:** Developer can import a rationalized Button component with consistent variants +- **FR8:** Developer can import Badge, Input, and Container components from the DS +- **FR9:** Developer can import Section components (Hero, CTA, Feature, Grid, etc.) +- **FR10:** All components use tokens from tailwind.config.js (no hardcoded values) + +### Navbar Rationalization + +- **FR11:** Developer can import Navbar as a composition of sub-components +- **FR12:** Navbar sub-components are reusable independently +- **FR13:** Navbar maintains current responsive behavior across breakpoints + +### Page Composition + +- **FR14:** Developer can compose pages using only DS components (no inline JSX) +- **FR15:** All 15 pages are refactored to use DS components +- **FR16:** Pages follow consistent import and composition patterns +- **FR17:** Pages maintain current responsive behavior (mobile-first) + +### AI Documentation + +- **FR18:** AI Agent can read CLAUDE.md and understand navigation entry points +- **FR19:** AI Agent can access tokens documentation in Markdown format +- **FR20:** AI Agent can access components catalog with props documentation +- **FR21:** AI Agent can understand DS usage patterns from documentation +- **FR22:** Documentation structure enables efficient AI navigation + +### Visual Fidelity + +- **FR23:** Rationalized prototype renders visually similar to current prototype +- **FR24:** Minor adjustments (radius, shadow harmonization) are acceptable +- **FR25:** No functional or behavioral changes from current prototype + +## Non-Functional Requirements + +### Code Quality + +- **NFR1:** All components use tokens from tailwind.config.js (0 hardcoded values) +- **NFR2:** Consistent naming conventions across all components +- **NFR3:** TypeScript types defined for all component props +- **NFR4:** No duplicate component implementations (1 source of truth per component) +- **NFR5:** Build passes without errors or warnings + +### AI-Readability + +- **NFR6:** File structure follows predictable patterns (easy AI navigation) +- **NFR7:** Component names are explicit and descriptive +- **NFR8:** CLAUDE.md provides clear navigation entry points +- **NFR9:** Documentation uses consistent Markdown structure +- **NFR10:** Token-to-class mapping is unambiguous + +### Maintainability + +- **NFR11:** Component composition patterns are consistent across the codebase +- **NFR12:** Import patterns follow a single convention +- **NFR13:** Responsive utilities usage is consistent (sm:, md:, lg:, xl:) +- **NFR14:** Mobile-first approach consistently applied + +### Visual Fidelity + +- **NFR15:** Rationalized prototype is visually indistinguishable from current prototype at first glance +- **NFR16:** Only intentional minor adjustments (radius, shadow harmonization) are visible +- **NFR17:** No layout shifts or broken responsive behavior +- **NFR18:** All animations and transitions preserved