Actualités

Atomic Design, de la théorie au code

20/02/2026

architecture css developpment atomic design

Comme nous l'avions vu au cours au cours d'un précédent article appelé "L'approche Atomic Design", l’objectif est maintenant de vous montrer comment nous nous organisons, côté développement front-end, pour l’intégrer concrètement. Si l’Atomic Design ne vous parle pas encore, nous vous invitons d’abord à lire l’article ci-dessous pour en comprendre les principes.

À propos

On en parle plus en détail par ici

L'approche Atomic Design

Style

Structurer le SCSS pour un style maintenable

Pour intégrer cette approche à notre CSS, nous nous sommes inspirés de la structure de fichiers 7-1, très répandue, que nous avons légèrement adaptée afin d’y intégrer l’organisation proposée par l’Atomic Design.

root: sources/styles
  .
  ├── atoms            # UI primitives (Tags, Link, ...)
  ├── blocks           # Editor blocks (Text, Image, Quote, TextImage, ...)
  ├── common           # Global base (Grid, Typography, Accessibility, Animations, ...)
  ├── critical         # Above-the-fold CSS (Header, Button,)
  ├── forms            # Form-related styles (Fields, Errors, Labels, ...)
  ├── molecules        # Small assemblies (ArticleCard, ) 
  ├── organisms        # Complex sections (Footer, Pagination, Hero, ...)
  ├── pages            # Template specific styles 
  ├── styleguide       # Styles for the styleguide page/template (internal docs)
  ├── tools            # Sass helpers (mixins, functions)
  ├── utils            # All utils
  ├── critical.scss    # Root file for critical inline style
  ├── site.scss        # Root file for main site CSS bundle
  └── styleguide.scss  # Root file for specific styleguide template

L’essentiel à retenir : on retrouve trois dossiers, Atoms, Molecules et Organisms, dans lesquels viennent se ranger nos différents fichiers SCSS. Nos fichiers sont ensuite importés dans l’un de nos fichiers racine selon leur usage (généralement chez nous site.scss).

// styles/site.scss

// Utils
@use 'utils/styleguide';
@use 'utils/config';
@use 'utils/ease';

// Tools
@use 'tools/query';
@use 'tools/grid';
@use 'tools/responsive';

// Common
@use 'common/animations';
@use 'common/icons';
@use 'common/mixins';

// Atoms
@use 'atoms/button';
@use 'atoms/link';

// Molecules
@use 'molecules/article-card';

// Organisms
@use 'organisms/articles-list';

// Blocks
@use 'blocks/wysiwyg';

// Pages
@use 'pages/page';

Au niveau des fichiers CSS en eux-même, nous utilisons une variante de l’A-BEM: on conserve le principe des préfixes “atomiques” (atom / molecule / organism), et on a simplement ajusté 2–3 règles pour coller à nos besoins et à notre codebase.

// Atomic Prefixes
[a] - Atom
[b] - Block
[m] - Molecule
[o] - Organism
[t] - Template
[u] - Utility

// Pattern
[a/b/m/o/t/u]-blockName_elementName -modifierName

// Exemples
.a-button {
  //...code

  &_icon {
    //...code
  }
  &.-big {
    //...code
  }
}

.m-articleCard {
  //...code
}

.o-articlesList {
  //...code
}

Markup

La gestion du templating avec TWIG

Côté rendu HTML, nous utilisons Twig, un moteur de templates pour PHP. Il nous permet de mieux séparer la vue de la logique dans une structure de type MVC.
Nos différents fichiers, appelés snippets, sont regroupés dans un dossier dédié. Ils peuvent ensuite être appelés dans nos pages, composants ou blocks, selon les besoins.

root: snippets
  .
  ├── atoms            # UI primitives (Image, Tag, Link, Icon, ...)
  ├── blocks           # Editor blocks (Text, Image, Quote, TextImage, ...)
  ├── layout           # Base page layout(s) (default, single, ...)
  ├── molecules        # UI components (Card, Breadcrumb, Accordion, ...)
  └── organisms        # Complex components (Header, Menu, Footer, ...)

Ainsi, nos différents fichiers sont triés par fonction. L’avantage de cette approche, c’est qu’elle clarifie l’organisation, facilite la réutilisation des composants et rend le code plus maintenable au fil du temps. Si je modifie mon atome Button, la mise à jour se répercute automatiquement sur toutes les molécules et organismes qui l’utilisent.

Exemple concret

L'approche par l'exemple

Comme dans l’article précédent, l’idée est de vous montrer, à travers l'exemple de la liste d’articles, comment concevoir des éléments isolés et réutilisables. Il s'agit d'un cas courant, simple et très parlant pour illustrer les avantages de l’Atomic Design.

Cet organisme incarne parfaitement la logique modulaire : il se construit à partir d’atomes (titres, images, métadonnées, boutons), puis s’assemble via une molécule qui regroupe ces éléments en une carte d’article cohérente. Cette carte est ensuite réutilisée pour composer une liste complète, déclinable selon les contextes (page blog, résultats de recherche, catégorie, ...).

Schéma de création d'un organisme liste d'article

Schéma de création d'une molecule carte article

Atômes

Mise en place des différents atomes

Nous allons commencer par créer les éléments primaires, à savoir les atomes. Ils sont la base de tous les autres composants et ne nécessitent aucune, ou très peu, de dépendances. Ils serviront ensuite à construire des molécules, qui elles-mêmes permettront de composer des organismes.

Voici ci-dessous un exemple de composants de type « atome » pour la gestion des images et des boutons. Ces fichiers Twig sont volontairement très légers, comme des coquilles vides, destinées à être utilisées par des composants parents. Les données passées en paramètres viennent ensuite “donner vie” à ces atomes.

{# 
    Button — Atome
    Path: atoms/button.twig
#}

{# Paramètres de l'atome #}
{% set class = class|default('') %}
{% set url = url|default('') %}
{% set content = content|default('') %}
{% set defaultTag = defaultTag|default('div') %}
{% set isButton = isButton is defined ? isButton : true %}
{% set attributes = attributes|default('') %}
{% set icon = icon is defined ? icon : '' %}
{% set isUrl = url != '' %}
{% set tag = isUrl ? 'a' : 'button' %}
{% set tag = isButton ? tag : defaultTag %}

{# Rendu HTML #}
<{{ tag }}
    class="a-button{{ class }}"

    {# Url du bouton #}
    {% if isUrl %} href="{{ url }}"{% endif %}
    {{ attributes|raw }}
>
    {# Label du bouton #}
    {{ content|raw }}
        
    {# On importe l'atome Icone (SVG) si le paramètre est renseigné #}
    {% if icon|length %}
        {{ snippet("atoms/svg", { 
            icon: icon 
        }) }}
    {% endif %}
</{{ tag }}>

{# 
    Image — Atome
    Path: atoms/image.twig
#}

{# Paramètres de l'atome #}
{% set class = class|default('') %}
{% set imgClass = imgClass|default('') %}
{% set attributes = attributes|default('') %}
{% set imgAttributes = imgAttributes|default('') %}
{% set sizes = sizes|default('') %}
{% set caption = caption is defined ? caption : false %}
{% set loaded = loaded is defined ? loaded : true %}
{% set figure = figure is defined ? figure : true %}
{% set lazy = lazy is defined ? lazy : not loaded %}

{# Rendu HTML #}
{% if file|length and file.url|length %}
    {% set url = file.thumb is defined ? file.thumb('tiny').url : file.url %}
        <img
            {% if loaded == false %}data-{% endif %}src="{{ url|raw }}"
            {% if lazy == true %}data-lazy{% endif %}
            {% if loaded == true and lazy == false %}fetchpriority="high"{% endif %}
            class="a-image {{ imgClass }}"
            alt="{% if file.alt is defined and file.alt|length %}{{ file.alt }}{% endif %}"
            {{ imgAttributes|raw }}
            {% if file.attributes is defined and file.attributes|length %} {{ file.attributes|raw }} {% endif %}
        >
    {% endif %}
{% endif %}

Dans ces exemples, plusieurs paramètres sont passés (URL et texte du bouton, URL de l’image, etc.), ce qui permet de rendre ces atomes entièrement dynamiques et réutilisables selon les contextes. Une fois vos atomes prêts, on peut passer à la création de la molécule.

Molécules

Création de la molécule carte article

Nous pouvons désormais nous atteler à l’élaboration de la molécule carte d’article. Celle-ci sera notamment composée des atomes que nous venons de créer.

Côté contenu, tout est fourni via un objet que nous appelons item par convention : il s’agit d’une page. Dans notre cas, c’est une page basée sur le template d’article de blog (blog-item), ce qui nous donne accès aux propriétés définies dans son modèle. On peut par exemple utiliser le champ thumbnail (que nous appelons plus couramment "cover" chez Troa) pour afficher l’image miniature via notre atome Image. Ensuite, d’autres champs permettent d’afficher la catégorie, le titre, l’auteur et un résumé de l’article. Enfin, l’URL menant à l’article est passée à notre atome Button, avec un paramètre icon pour afficher une icône de chevron droit, ainsi que le texte du CTA (ici "Lire la suite").

{# 
    Article Card Molecule
    Path: molecules/article-card.twig
#}

{# Paramètres de la molecule #}
{% set item = item|default(null) %} # Donnée de l'article qui sera fourni par un composant parent

{# Si l'objet est vide ou null alors ne pas afficher la carte #}
{% if item %}
<li class="m-articleCard">

    {# Thumbnail de l'article : Utilisation de l'atome "Image" #}
    {% set cover = item.cover.toFile %}
    {{ snippet("atoms/image", {
        file: item.cover.toFile
    }) }}

    <div class="m-articleCard_content p-sm">
        {# Catégorie de l'article #}
        <p class="tx-lab tx-700 -clrprimary500 mb-tiny">{{ item.parent.title }}</p>

        {# Titre de l'article #}
        <h3 class="tx-md mb-tiny">{{ item.title }}</h3>
        
        {# Auteur #}
        {% set authorPage = item.author.toPage %}
        <p class="tx-psm -clrgray500 mb-sm">{{ authorPage.title }}</p>
        
        {# Résumé #}
        <p class="m-articleCard_excerpt tx-plg">{{ item.excerpt }}</p>
 
        {# CTA : Utilisation de l'atome "Bouton" #}
        {{ snippet("atoms/button", {
            url: item.url,
            content: "Lire la suite",
            icon: "chevron-right"
        }) }}
    </div>
</li>
{% endif %}

Organisme

Assemblage des molecules pour générer l'organisme liste

Notre molécule carte article étant terminée, nous pouvons désormais l'utiliser dans un organisme liste d'article.

L’organisme, en soi, n’est qu’un gros wrapper : il se contente de mettre en forme et d’orchestrer les molécules et atomes enfants. Dans notre exemple, un paramètre optionnel title permet d’afficher (ou non) un titre au-dessus du listing, et un paramètre items correspond à notre collection d’articles de blog. Il suffit ensuite de boucler sur cette collection, d’englober les cartes dans une balise <ul>, et c’est parti.

Il ne vous reste plus qu’à styliser la classe CSS "o-articlesList__list" (par exemple en display: grid ou flex), puis à gérer les espacements de l’organisme (marges, gap, distance entre le titre et la liste) : votre organisme est prêt à l’emploi.

{# 
    Article List — Organisme
    Path: organismes/article-card.twig
#}

{# Paramètres de l'organisme #}
{% set title = title|default(null) %}       # Titre de l'organisme 
{% set titleTag = titleTag|default('h2') %} # Sémantique HTML du Titre (de base un h2, mais peut être modifié en modifiant ce paramètre)
{% set items = items|default({}) %}         # Liste des articles 

{# Si l'objet articles (items) est vide alors ne pas afficher l'organisme #}
{% if items|length %}
<section class="o-articlesList">

    {# Si le titre n'est pas passé en paramètre, alors ne rien afficher #}
    {% if title %}
        <{{ titleTag }} class="tx-lg">{{ title }}</{{ titleTag }}>
    {% endif %}

    <ul class="o-articlesList_list">
        {% for article in items %}
            {# Utilisation de la molécule "Carte Article" pour chacun des articles #}
            {{ snippet("molecules/article-card", {
                item: item
            }) }}
        {% endfor %}
    </ul>
</section>
{% endif %}

Et voilà : notre composant liste d’articles est prêt à être utilisé. Il peut être intégré tel quel dans un template de page, ou facilement adapté pour une utilisation dans une librairie de blocs au sein d’un CMS, par exemple.

{# 
    Template Homepage
    Path: templates/home.twig
#}

...code

{{ snippet("organisms/articles-list", {
    title: 'Articles mis en avant',
    items: page.selected_articles.toPages
}) }}

...code

La modularité de l'approche atomic design vous permet de proposer rapidement des compositions variées, tout en conservant une cohérence graphique et technique sur l’ensemble du projet.

Vous avez désormais les clés pour créer vous-même vos propres composants. Cette démarche permet, par exemple, de concevoir simplement un carrousel d’articles en réutilisant les molécules “carte d’article”, ou d’imaginer d’autres organismes basés sur d’autres molécules, comme un formulaire de contact ou un bloc de FAQ.

Encore plus ?