Générer des fichiers Pencil avec Pencil Generator

Contexte

Vous avez un projet Next.js avec de nombreuses pages et vous voulez générer des fichiers Pencil (format .pen) pour prototypage, collaboration ou archivage. Pencil Generator (Jean-Marie) scanne exhaustivement chaque page, layout et composant, puis génère des fichiers .pen exploitables dans l’outil Pencil. Méthodique et fidèle à votre architecture, il reproduit exactement la structure et la hiérarchie de votre projet.

Prérequis

Projet Next.js (App Router ou Pages Router)
Composants shadcn/ui structurés
Tailwind CSS configuré
Design tokens documentés (optionnel, extrait de globals.css)
Outil Pencil installé localement (optionnel pour édition)
Accès à src/ et globals.css pour scanner les tokens

Étapes

1. Invoquer Pencil Generator

/ulk:frontend:pencil-generator
# ou
/ulk:pencil-generator
# ou
pencil-generator
# ou
génère les pencil

2. Phase 1 : Accueil et cadrage

L’agent accueille l’utilisateur :

Bonjour ! Je suis Jean-Marie, votre Pencil Page Generator.

Ma mission : analyser votre projet Next.js en profondeur,
identifier toutes les pages, layouts et composants,
puis générer des fichiers .pen pour chaque page.

Laissez-moi d'abord scanner votre projet...

Questions:
1. Portée? (toutes les pages / module spécifique)
2. Inclure annotations? (oui/non)
3. Format de tokens? (Tailwind / CSS custom)

3. Phase 2 : Scan exhaustif des pages

L’agent scanne :

🔍 Pencil Generator — Scan en cours
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Framework           : Next.js 15 (App Router)
Router type         : App Router (/app)
Pages détectées     : 18
Layouts détectés    : 4 (root, dashboard, auth, blog)
Composants total    : 156
Design tokens       : Tailwind (colors, spacing, typography)

Pages inventoriées:
  ✅ HomePage
  ✅ DashboardPage
  ✅ ProfilePage
  ✅ SettingsPage
  ✅ FormPage
  ✅ BlogListPage
  ⚠️  DynamicRoutes : [id], [slug]

Scan complété : 18 pages + 4 layouts

4. Phase 3 : Extraction des layouts et composants

L’agent détaille chaque page :

HomePage:
  Layout  : root.tsx
  Props   : title, description
  Deps    : Header, HeroSection, FeatureCards, Footer
  Colors  : bg-slate-50, text-slate-900
  Spacing : p-8, gap-4
  Typo    : H1 (text-4xl), Body (text-sm)

DashboardPage:
  Layout  : dashboard.tsx (with Sidebar)
  Props   : user, permissions
  Deps    : Sidebar, DataTable, Chart, Card
  Colors  : bg-white, border-slate-200
  Grid    : 12-column responsive
  Typo    : H2 (text-2xl), Label (text-xs)

5. Phase 4 : Génération des fichiers .pen

L’agent génère pour chaque page un fichier .pen :

docs/pencil-pages/
├── _index.md                          # MOC
├── HomePage.pen
├── HomePage-annotated.md
├── DashboardPage.pen
├── DashboardPage-annotated.md
├── ProfilePage.pen
├── ProfilePage-annotated.md
└── ...

Structure d’un fichier HomePage.pen :

<?xml version="1.0"?>
<pencil version="3.0">
  <page name="HomePage" width="1280" height="2400">
    <layer name="root" type="group">
      <!-- Header -->
      <shape type="rect" x="0" y="0" w="1280" h="80">
        <fill color="#ffffff"/>
        <stroke color="#e2e8f0"/>
      </shape>
      <!-- Hero Section -->
      <shape type="rect" x="0" y="80" w="1280" h="400">
        <fill color="#f8fafc"/>
        <text>Hero Title</text>
      </shape>
      <!-- Feature Cards -->
      <layer name="FeatureCards" type="group">
        <shape type="rect" x="0" y="480" w="400" h="250"/>
        <shape type="rect" x="440" y="480" w="400" h="250"/>
        <shape type="rect" x="880" y="480" w="400" h="250"/>
      </layer>
    </layer>
  </page>
</pencil>

Exemple de sortie

Catalogue Pencil généré :

📁 docs/pencil-pages/

HomePage.pen (1280x2400):
  ┌─ Header (80px)
  │  Logo | Nav Items | CTA Button
  ├─ Hero Section (400px)
  │  H1 "Welcome" | Subtext | CTA Button
  ├─ Feature Cards (3x 250px)
  │  Card 1 | Card 2 | Card 3
  └─ Footer (100px)
     Links | Copyright

DashboardPage.pen (1280x900):
  ┌─────────────────────────────────┐
  │ Sidebar (250px) │ Main Content  │
  │ [Nav] [Icons]   │ [Data Table]  │
  │ [User Profile]  │ [Chart]       │
  └─────────────────────────────────┘

HomePage-annotated.md:
## HomePage Annotations

**Viewport**: 1280x2400 (responsive)
**Layout**: Flex column, center-aligned
**Colors**:
  - Background: #f8fafc (Tailwind slate-50)
  - Text: #0f172a (Tailwind slate-900)
  - Accent: #2563eb (Tailwind blue-600)

**Typography**:
  - H1: 36px, bold, Inter
  - Body: 14px, regular, Inter

**Components**:
  - Button: Primary (blue), Secondary (outline)
  - Card: Default (white bg, border)
  - Header: Sticky, shadow

**Spacing**:
  - Page padding: 32px
  - Card gap: 16px

Variantes

Variante A : Pages seulement — --scope=pages/ pour générer .pen uniquement des pages (excluire layouts, composants)
Variante B : Avec annotations riches — --annotations=full pour inclure props, variants, interactions pour chaque composant
Variante C : Export HTML interactif — --format=html pour générer HTML preview des fichiers .pen (éditable dans navigateur)

Agents enchaînés

Flux typique :

pencil-generator (frontend/06)
  ├─ Phase 1 : Accueil (2 min)
  ├─ Phase 2 : Scan exhaustif (20 min)
  ├─ Phase 3 : Extraction des layouts (15 min)
  ├─ Phase 4 : Génération .pen (20 min)
  └─ Output : docs/pencil-pages/

Post-génération optionnel :

svg-analyzer (05) ─→ Générer également SVG des mêmes pages
vision (05) ─→ Audit visuel contre design Figma

Troubleshooting

Symptôme	Cause probable	Résolution
”Pages not detected”	Router type mal détecté ou structure non-standard	Vérifier App Router vs Pages Router, relancer
”No components found”	shadcn/ui non installé ou imports mal structurés	Vérifier `components/ui/` existe et contient composants
”.pen files malformed”	Encoding ou structure XML cassée	Relancer génération, vérifier format Pencil v3
”Design tokens not extracted”	globals.css non trouvé ou parsing échoué	Vérifier chemin globals.css, relancer avec `--manual-tokens`

Voir aussi

./04-brique-figma-to-code.md — Implémenter design Figma en code
./09-svg-analyzer.md — Générer SVG de pages
./08-backoffice-auditor.md — Audit cohérence Back Office
agents/frontend/06-pencil-generator.md — Documentation complète
Pencil Tool : https://pencil.evolus.vn/ — Prototypage avec fichiers .pen