• pnpm : gestionnaire de paquets
• Vite : gestion du build, compilation
• Handlebars : templates HTML
• CSS vanilla

Annexes :

• Stylelint : bonnes pratiques CSS
• Prettier : formatage du code
• prettier-plugin-css-order : pour réordonner les propriétés CSS

• Développement local : pnpm dev
• Compilation et mise en prod git push (Github Actions déploie et publie le site sur Google Pages)

1. Suivre pas à pas les étapes de la Routine d'initialisation de projet d'Alsacréations.
2. Installer vite-plugin-handlebars

pnpm install --save-dev stylelint stylelint-config-standard stylelint-config-html stylelint-order stylelint-config-property-sort-order-smacss

Dans stylelint.config.js :

/** @type {import('stylelint').Config} */
export default {
  extends: [
    "stylelint-config-standard",
    "stylelint-config-html",
    "stylelint-config-property-sort-order-smacss",
  ],
  plugins: ["stylelint-order"],
}

Dans VS Code : installer l'extension stylelint.vscode-stylelint et modifier les settings :

{
  "stylelint.validate": [
      ...,
      // ↓ Add "html" language.
      "html",
      // ↓ Add "vue" language.
      "vue"
  ]

Redémarrer VS Code.

Site hébergé, compilé et déployé sous Github Pages.

• Configuration générale dans Settings > Pages
• "Build and deployment" via Github Actions
• Fichier de tâches de déploiement : static.yml
• Domaine personnalisé dans Settings > Pages

• CSS Vanilla : Nous écrivons les règles CSS dans les feuilles de styles et nous n'utilisons pas de classes utilitaires, sauf exceptions.
• Base et Reset : Les fichier bretzel-*.css contiennent le Reset CSS Alsacréations ainsi que diverses classes "layouts" spécifiques à nos projets (visually-hidden, liquid/splash, autogrid, repel, switcher, etc.)
• Qualité du code : Prettier formatte le CSS, prettier-plugin-css-order réordonner les propriétés CSS.

Cette base utilise les CSS Custom Media pour écrire des media queries lisibles et cohérentes à l’échelle du projet, grâce au plugin PostCSS postcss-custom-media.

Le plugin est déjà présent dans package.json.

{
  "devDependencies": {
    "postcss-custom-media": "^11.0.6"
  }
}

Si nécessaire:

pnpm add -D postcss-custom-media

La configuration PostCSS active le plugin (fichier postcss.config.mjs). Aucun réglage spécifique n’est requis par défaut.

export default {
  plugins: {
    "postcss-custom-media": {
      /* plugin options */
    },
  },
}

Les breakpoints du projet sont déclarés dans assets/css/theme.css via @custom-media.

/* assets/css/theme.css */
@custom-media --sm (width >= 40rem); /* 640px */
@custom-media --lg (width >= 64rem); /* 1024px */
@custom-media --xl (width >= 80rem); /* 1280px */

Ces alias deviennent utilisables dans toutes les feuilles CSS importées par assets/css/app.css.

Référencer les custom media par leur nom dans les règles, en profitant de la syntaxe moderne des plages:

.card {
  gap: var(--spacing-16);

  @media (--sm) {
    gap: var(--spacing-24);
  }

  @media (--lg) {
    gap: var(--spacing-36);
  }
}

Autre exemple issu du projet (extrait adapté):

.toc {
  padding: var(--spacing-s);
  border-radius: var(--radius-md);

  @media (--lg) {
    position: fixed;
    top: var(--spacing-m);
    left: var(--spacing-s);
    width: 16rem;
  }
}

postcss-custom-media remplace automatiquement les références @media (--sm) par la requête sous-jacente. Par exemple:

@media (--sm) {
  /* … */
}

devient à la compilation:

@media (width >= 40rem) {
  /* … */
}

Avantages:

• Centralisation des seuils: changer la valeur d’un breakpoint se fait dans un seul fichier (theme.css).
• Lisibilité: des noms explicites (--sm, --lg, --xl).
• Cohérence: mêmes breakpoints partout dans le projet.

• Privilégier une approche mobile-first: styles par défaut, puis élargir avec @media (--sm), @media (--lg), etc.
• Utiliser la syntaxe moderne des ranges (width >= …) plutôt que min-width/max-width.
• Définir les custom media une seule fois dans theme.css et les consommer ailleurs (ne pas redéclarer localement).
• Documenter les choix de seuils en commentaires (déjà en place dans theme.css).

• Si une @media (--sm) ne s’applique pas, vérifier:
  • que theme.css est bien importé dans assets/css/app.css via un @import en couche config;
  • que la chaîne --sm est correctement orthographiée côté usage et déclaration;
  • que PostCSS est exécuté (via Vite) et que vous n’éditez pas un CSS livré non transformé dans public/.

.