SrRusian/atomic-page-builder

Atomic Page Builder

Composer des pages à partir de composants existants. Cette compétence assemble ; atomic-design crée.

Règles

À faire	À ne pas faire
Importer des composants depuis le système de design	Créer de nouveaux atomes, molécules ou organismes
Prendre les valeurs de mise en page depuis la source de design (Figma, spécification, maquette)	Deviner les grilles, espacements ou marges
Utiliser des styles limités au composant qui lisent depuis les tokens	Coder en dur des valeurs (#333, 24px)
Correspondre exactement au design, y compris le comportement responsive	Arrondir les valeurs ou ajouter des "améliorations"
Utiliser uniquement la bibliothèque de composants du projet	Importer une bibliothèque UI externe que le projet n'utilise pas

Passage à atomic-design

Basculer vers atomic-design lorsque :

• un atome, une molécule ou un organisme nécessaire n'existe pas ;
• un nouveau token est requis ;
• une valeur de token a changé dans le design et doit d'abord être mise à jour.

Flux de travail

1. Obtenir la spécification de mise en page. Si une source de design existe (Figma via MCP, une spécification, une capture d'écran), en extraire la grille, les espacements, les marges et les points de rupture. Si aucune n'existe, en demander une ou énoncer explicitement les hypothèses. Noter les surcharges spécifiques à la page.
2. Inventaire. Lister les composants que le projet possède déjà (atomes, molécules, organismes, templates) avec leurs props.
3. Analyse des écarts. Mapper chaque région de la page à un composant existant. Lister tout élément non apparié.
4. Construire ou s'arrêter.
   • Tout existe : composer la page, en respectant la spécification à 100%.
   • Quelque chose manque : s'arrêter, signaler les écarts, et basculer vers atomic-design.
5. Vérifier. Comparer avec le design aux largeurs mobile, tablette et desktop.

Modèle de page

/** Page Dashboard. Mise en page depuis : <lien design ou id de nœud> */
import { DashboardLayout } from '@/design-system/templates/DashboardLayout';
import { Card } from '@/design-system/molecules/Card';
import { DataTable } from '@/design-system/organisms/DataTable';
import styles from './Dashboard.module.css';

export const Dashboard = () => (
  <DashboardLayout>
    <div className={styles.statsGrid}>
      <Card title="Revenu">$12 450</Card>
    </div>
    <DataTable columns={columns} data={data} />
  </DashboardLayout>
);

.statsGrid {
  display: grid;
  grid-template-columns: 1fr;
  gap: var(--spacing-4);
}
@media (min-width: 768px) {
  .statsGrid { grid-template-columns: repeat(3, 1fr); gap: var(--spacing-6); }
}

Adapter les chemins d'import et l'approche de style au projet.

Vérification

Afficher la page dans un vrai navigateur (playwright-cli) à 375, 768 et 1440 px en mode clair et sombre, lire la console, et comparer avec la source de design. Vérifier également l'ordre des titres, les points de repère, la navigation au clavier, et les états de chargement, vide et d'erreur.

Fonctionne avec

Besoin	Compétence ou outil
Composant ou token manquant	atomic-design (compagnon requis)
Critique ou polissage au niveau de la page	impeccable
Audit d'accessibilité	fixing-accessibility, design:accessibility-review
Métadonnées de page, titres, Open Graph	fixing-metadata
Transfert à l'ingénierie	design:design-handoff

Règles supplémentaires

• Composer dans les slots du template ; ne pas accéder à l'intérieur d'un composant ni surcharger ses styles.
• Les styles spécifiques à la page se limitent à la mise en page (grille, espacements, placement) ; tout ce qui est visuel appartient à un composant ou un token.
• Ne jamais copier-coller un composant pour le modifier ; demander une variante via atomic-design.
• Transmettre un contenu réel et représentatif (noms longs, listes vides, erreurs) lors de la vérification de la page.
• Définir le titre du document et un h1 par page.
• Un fichier de page contient uniquement la composition et le câblage des données ; pas de logique UI réutilisable.

Références

Fichier	Lire lorsque
references/design-source-extraction.md	Extraction des valeurs de mise en page et rédaction de la spécification de page
references/inventory-and-gaps.md	Inventaire des composants et recherche des écarts
references/composition-patterns.md	Mises en page, slots, états des données, ordre des imports

Liste de vérification de sortie

• Les valeurs de mise en page proviennent de la source de design, pas de suppositions
• Le comportement responsive correspond au design
• Toutes les imports proviennent du système de design du projet
• Aucune valeur codée en dur
• Aucun nouveau composant
• Lien de design documenté dans le fichier de page