# /references — Patterns du projet

> **Synonymes** : references, patterns, conventions, standards, guidelines, règles, bonnes pratiques, best practices, design system, reusable, réutilisable

Tu es un design system curator. Ton rôle : maintenir les patterns réutilisables.

## Actions disponibles

### 1. Voir les références

Lire et afficher `references/index.md` avec aperçu de chaque section :

```
## Références projet

### Quick Reference
- Spacing base: 16px
- Radius: 4px
- Primary: #3B82F6

### Fichiers
- spacing.md — 5 tokens définis
- colors.md — 8 couleurs
- components.md — 3 patterns
- conventions.md — Nommage, structure
```

### 2. Ajouter une référence

Quand un pattern est détecté (manuellement ou pendant `/deliverable`) :

```
Nouveau pattern détecté : {nom}

Catégorie : spacing | colors | components | conventions
Valeur : {valeur}
Usage : {contexte où c'est utilisé}

Ajouter aux références ? [o/n]
```

Si oui :
1. Modifier `references/index.md` (quick reference)
2. Modifier ou créer le fichier de catégorie approprié

### 3. Éditer une référence

```
Référence à modifier : {nom}
Valeur actuelle : {valeur}
Nouvelle valeur : {input}

Mettre à jour ? [o/n]
```

Propager le changement si utilisé ailleurs.

### 4. Supprimer une référence

```
⚠ Suppression de référence

Référence : {nom}
Utilisée dans : {liste des fichiers}

Confirmer la suppression ? [o/n]
```

---

## Structure des références

### references/index.md (toujours chargé dans CLAUDE.md)

```markdown
# Références projet

Ce fichier est automatiquement inclus dans le contexte Claude.

## Quick Reference

| Token | Value | Usage |
|-------|-------|-------|
| spacing-base | 16px | Default padding/margin |
| radius | 4px | Corners |
| primary | #3B82F6 | Actions, focus |

## Files

- `spacing.md` — Règles d'espacement détaillées
- `colors.md` — Palette complète
- `components.md` — Patterns UI réutilisables
- `conventions.md` — Nommage, structure fichiers
```

### references/spacing.md

```markdown
# Spacing

Base unit: 16px

| Token | Value | Usage |
|-------|-------|-------|
| xs | 4px | Icon padding, tight spaces |
| sm | 8px | Compact spacing, button padding |
| md | 16px | Default spacing, container padding |
| lg | 24px | Section spacing |
| xl | 32px | Major sections, modal padding |

## Rules

- Toujours utiliser des multiples de 4px
- Margin externe > padding interne
- Espacement vertical > espacement horizontal
```

### references/colors.md

```markdown
# Colors

## Palette

| Name | Hex | Usage |
|------|-----|-------|
| primary | #3B82F6 | Actions, links, focus |
| primary-hover | #2563EB | Hover state |
| secondary | #6B7280 | Secondary text, borders |
| background | #1F2937 | Main background |
| surface | #374151 | Cards, panels |
| text | #F9FAFB | Primary text |
| text-muted | #9CA3AF | Secondary text |
| error | #EF4444 | Errors, destructive |
| success | #10B981 | Success, confirmation |

## Rules

- Contraste minimum 4.5:1 pour le texte
- Utiliser primary pour les actions principales uniquement
- error uniquement pour les états d'erreur, jamais décoratif
```

### references/components.md

```markdown
# Components

## Button

```gdscript
# Structure
Button (minimum_size: 120x44)
├── HBoxContainer (spacing: 8)
│   ├── Icon (16x16, optional)
│   └── Label

# Theme overrides
- padding: sm (8px)
- radius: 4px
- font: bold
```

## Card

```gdscript
# Structure
PanelContainer
├── MarginContainer (margins: md)
│   └── VBoxContainer (spacing: sm)
│       ├── Header
│       └── Content

# Theme
- background: surface
- radius: 4px
- border: 1px secondary
```

## Input

```gdscript
# Structure
VBoxContainer (spacing: xs)
├── Label (text-muted)
└── LineEdit (minimum_size: 0x44)

# States
- default: border secondary
- focus: border primary
- error: border error
```
```

### references/conventions.md

```markdown
# Conventions

## Nommage fichiers

| Type | Format | Exemple |
|------|--------|---------|
| Scene | snake_case.tscn | main_menu.tscn |
| Script | snake_case.gd | player_controller.gd |
| Resource | snake_case.tres | button_theme.tres |
| Autoload | PascalCase | EventBus, GameState |

## Nommage nodes

- PascalCase pour les nodes : `PlayerSprite`, `ScoreLabel`
- Préfixe par rôle si ambigu : `BtnPlay`, `LblScore`

## Structure scène

```
Root (type descriptif)
├── UI (CanvasLayer)
│   └── ...
├── World (Node2D/3D)
│   └── ...
└── Systems (Node)
    └── ...
```

## Signaux

- Nommés en past tense : `player_died`, `score_changed`
- Définis dans EventBus pour les signaux globaux
- Signaux locaux dans le script concerné
```

---

## Intégration automatique

Pendant l'implémentation (via `/deliverable` ou autre) :

1. **Détection** : quand une valeur hardcodée est utilisée
   ```
   Pattern détecté : margin 16px utilisé
   → Existe dans références : spacing-md
   → Utilisation automatique
   ```

2. **Proposition** : quand une nouvelle valeur apparaît
   ```
   Nouvelle valeur : #FF6B35 (orange)
   → Pas dans références
   → Proposer ajout ? [o/n]
   ```

3. **Cohérence** : quand une valeur proche existe
   ```
   Valeur utilisée : 15px
   → Référence proche : spacing-md (16px)
   → Utiliser la référence à la place ? [o/n]
   ```

---

## Initialisation

Si `references/` n'existe pas, créer la structure :

```
references/
├── index.md      # Quick reference + liens
├── spacing.md    # (vide, à remplir)
├── colors.md     # (vide, à remplir)
├── components.md # (vide, à remplir)
└── conventions.md # (template de base)
```
