Guide Penpot UI/UX Design

Créez des designs professionnels centrés sur l'utilisateur dans Penpot en utilisant le serveur MCP penpot/penpot-mcp et les principes UI/UX éprouvés.

Outils MCP Disponibles

Configuration du serveur MCP

Les outils Penpot MCP nécessitent le serveur penpot/penpot-mcp exécuté localement. Pour une installation détaillée et le dépannage, consultez setup-troubleshooting.md.

Avant la configuration : Vérifier si déjà en cours d'exécution

Vérifiez toujours si le serveur MCP est déjà disponible avant de tenter une configuration :

1. Essayer d'abord d'appeler un outil : Tentez mcp__penpot__penpot_api_info - s'il réussit, le serveur est en cours d'exécution et connecté. Aucune configuration nécessaire.

2. Si l'outil échoue, demandez à l'utilisateur :

   « Le serveur MCP Penpot ne semble pas être connecté. Le serveur est-il déjà installé et en cours d'exécution ? Si c'est le cas, je peux vous aider à résoudre les problèmes. Sinon, je peux vous guider tout au long de la configuration. »

3. Procédez aux instructions de configuration uniquement si l'utilisateur confirme que le serveur n'est pas installé.

Démarrage rapide (uniquement si non installé)

# Clone et installation
git clone https://github.com/penpot/penpot-mcp.git
cd penpot-mcp
npm install

# Build et démarrage des serveurs
npm run bootstrap

Ensuite dans Penpot :

1. Ouvrez un fichier de design
2. Allez à Plugins → Load plugin from URL
3. Entrez : http://localhost:4400/manifest.json
4. Cliquez sur "Connect to MCP server" dans l'interface du plugin

Configuration VS Code

Ajoutez à settings.json :

{
  "mcp": {
    "servers": {
      "penpot": {
        "url": "http://localhost:4401/sse"
      }
    }
  }
}

Dépannage (Si le serveur est installé mais ne fonctionne pas)

Référence rapide

Principes de design fondamentaux

Les règles d'or

1. La clarté plutôt que la ruse : Chaque élément doit avoir un objectif
2. La cohérence établit la confiance : Réutilisez les motifs, les couleurs et les composants
3. Les objectifs de l'utilisateur d'abord : Concevez pour les tâches, pas pour les fonctionnalités
4. L'accessibilité n'est pas optionnelle : Concevez pour tout le monde
5. Testez avec de vrais utilisateurs : Validez les hypothèses tôt

Hiérarchie visuelle (ordre de priorité)

1. Taille : Plus grand = plus important
2. Couleur/Contraste : Le contraste élevé attire l'attention
3. Position : En haut à gauche (LTR) est vu en premier
4. Espace blanc : L'isolement souligne l'importance
5. Épaisseur de la typographie : Le gras se distingue

Flux de travail de design

1. Vérifier d'abord le système de design : Demandez à l'utilisateur s'il a des tokens/spécifications existants, ou découvrez-les à partir du fichier Penpot actuel
2. Comprendre la page : Appelez mcp__penpot__execute_code avec penpotUtils.shapeStructure() pour voir la hiérarchie
3. Trouver les éléments : Utilisez penpotUtils.findShapes() pour localiser les éléments par type ou nom
4. Créer/modifier : Utilisez penpot.createBoard(), penpot.createRectangle(), penpot.createText() etc.
5. Appliquer la mise en page : Utilisez addFlexLayout() pour les conteneurs réactifs
6. Valider : Appelez mcp__penpot__export_shape pour vérifier visuellement votre travail

Gestion du système de design

Avant de créer des designs, déterminez si l'utilisateur a un système de design existant :

1. Demandez à l'utilisateur : « Avez-vous un système de design ou des directives de marque à suivre ? »
2. Découvrez à partir de Penpot : Vérifiez les composants, couleurs et motifs existants

// Découvrir les motifs de design existants dans le fichier actuel
const allShapes = penpotUtils.findShapes(() => true, penpot.root);

// Trouver les couleurs existantes en utilisation
const colors = new Set();
allShapes.forEach(s => {
  if (s.fills) s.fills.forEach(f => colors.add(f.fillColor));
});

// Trouver les styles de texte existants (tailles de police, poids)
const textStyles = allShapes
  .filter(s => s.type === 'text')
  .map(s => ({ fontSize: s.fontSize, fontWeight: s.fontWeight }));

// Trouver les composants existants
const components = penpot.library.local.components;

return { colors: [...colors], textStyles, componentCount: components.length };

Si l'utilisateur A un système de design :

• Utilisez ses couleurs, espacements et typographies spécifiés
• Faites correspondre les motifs de composants existants
• Suivez ses conventions de nommage

Si l'utilisateur N'A PAS de système de design :

• Utilisez les tokens par défaut ci-dessous comme point de départ
• Offrez d'aider à établir des motifs cohérents
• Consultez les spécifications dans component-patterns.md

Pièges clés de l'API Penpot

• width/height sont READ-ONLY → utilisez shape.resize(w, h)
• parentX/parentY sont READ-ONLY → utilisez penpotUtils.setParentXY(shape, x, y)
• Utilisez insertChild(index, shape) pour l'ordre z (pas appendChild)
• L'ordre du tableau des enfants flex est INVERSÉ pour dir="column" ou dir="row"
• Après text.resize(), réinitialisez growType à "auto-width" ou "auto-height"

Positionnement des nouveaux boards

Vérifiez toujours les boards existants avant d'en créer de nouveaux pour éviter le chevauchement :

// Trouver tous les boards existants et calculer la position suivante
const boards = penpotUtils.findShapes(s => s.type === 'board', penpot.root);
let nextX = 0;
const gap = 100; // Espace entre les boards

if (boards.length > 0) {
  // Trouver le bord droit du board le plus à droite
  boards.forEach(b => {
    const rightEdge = b.x + b.width;
    if (rightEdge + gap > nextX) {
      nextX = rightEdge + gap;
    }
  });
}

// Créer un nouveau board à la position calculée
const newBoard = penpot.createBoard();
newBoard.x = nextX;
newBoard.y = 0;
newBoard.resize(375, 812);

Directives d'espacement des boards :

• Utilisez un écart de 100 px entre les écrans connexes (même flux)
• Utilisez un écart de 200 px+ entre les sections/flux différents
• Alignez les boards verticalement (même y) pour une organisation visuelle
• Groupez les écrans connexes horizontalement dans l'ordre du flux utilisateur

Tokens de design par défaut

Utilisez ces paramètres par défaut uniquement lorsque l'utilisateur n'a pas de système de design. Préférez toujours les tokens de l'utilisateur s'ils sont disponibles.

Échelle d'espacement (base 8px)

Échelle typographique

Utilisation des couleurs

Mises en page courantes

Écran mobile (375×812)

┌─────────────────────────────┐
│ Barre d'état (44px)         │
├─────────────────────────────┤
│ En-tête/Nav (56px)          │
├─────────────────────────────┤
│                             │
│ Zone de contenu             │
│ (Défilement)                │
│ Remplissage : 16px horiz.   │
│                             │
├─────────────────────────────┤
│ Nav inférieure/CTA (84px)   │
└─────────────────────────────┘

Tableau de bord bureau (1440×900)

┌──────┬──────────────────────────────────┐
│      │ En-tête (64px)                   │
│ Bare │──────────────────────────────────│
│ lat. │ Titre page + Actions             │
│      │──────────────────────────────────│
│ 240  │ Grille de contenu                │
│ px   │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │
│      │ │Card │ │Card │ │Card │ │Card │ │
│      │ └─────┘ └─────┘ └─────┘ └─────┘ │
│      │                                  │
└──────┴──────────────────────────────────┘

Checklist des composants

Boutons

• [ ] Libellé clair et orienté action (2-3 mots)
• [ ] Cible tactile minimale : 44×44px
• [ ] États visuels : par défaut, survol, actif, désactivé, chargement
• [ ] Contraste suffisant (3:1 par rapport à l'arrière-plan)
• [ ] Rayon de bordure cohérent dans toute l'application

Formulaires

• [ ] Étiquettes au-dessus des entrées (pas seulement des placeholders)
• [ ] Indicateurs de champs obligatoires
• [ ] Messages d'erreur adjacents aux champs
• [ ] Ordre de tabulation logique
• [ ] Types d'entrée correspondent au contenu (e-mail, tél., etc.)

Navigation

• [ ] Localisation actuelle clairement indiquée
• [ ] Position cohérente sur tous les écrans
• [ ] Maximum 7±2 éléments de haut niveau
• [ ] Tactile sur mobile (cibles de 48px)

Vérifications d'accessibilité rapides

1. Contraste des couleurs : Texte 4.5:1, Texte large 3:1
2. Cibles tactiles : Minimum 44×44px
3. États de focus : Indicateurs de focus clavier visibles
4. Texte alternatif : Descriptions significatives des images
5. Hiérarchie : Niveaux de titre appropriés (H1→H2→H3)
6. Indépendance des couleurs : Ne jamais s'appuyer uniquement sur la couleur

Checklist d'examen du design

Avant de finaliser un design :

• [ ] La hiérarchie visuelle est claire
• [ ] Espacement et alignement cohérents
• [ ] La typographie est lisible (texte de corps 16px+)
• [ ] Le contraste des couleurs respecte WCAG AA
• [ ] Les éléments interactifs sont évidents
• [ ] Les cibles tactiles adaptées au mobile
• [ ] États de chargement/vides/erreur considérés
• [ ] Cohérent avec le système de design

Validation des designs

Utilisez ces approches de validation avec mcp__penpot__execute_code :

Export CSS

Utilisez penpot.generateStyle(selection, { type: 'css', includeChildren: true }) via mcp__penpot__execute_code pour extraire CSS des designs.

Conseils pour d'excellents designs

1. Commencez par le contenu : Le contenu réel révèle les besoins de mise en page
2. Concevez d'abord sur mobile : Les contraintes favorisent la créativité
3. Utilisez une grille : Une grille de base 8px garde les choses alignées
4. Limitez les couleurs : 1 primaire + 1 secondaire + neutres
5. Limitez les polices : 1-2 polices de caractères maximum
6. Embrassez l'espace blanc : L'espace respirable améliore la compréhension
7. Soyez cohérent : Même action = même apparence partout
8. Fournissez un retour : Chaque action a besoin d'une réponse