@volcraft/composants-nextjs

Design system et composants e-commerce pour les sites Next.js 16 (App Router, rendu serveur) : mobile d'abord (360 px), accessible (WCAG 2.2 AA), pensé pour le SEO.

Installation

pnpm add @volcraft/composants-nextjs

Dépendances attendues : next ^16, react ^19, react-dom ^19.

// next.config.ts — n'embarque que les composants client réellement utilisés par chaque page
const nextConfig = { experimental: { optimizePackageImports: ['@volcraft/composants-nextjs'] } };

// app/layout.tsx
import '@volcraft/composants-nextjs/styles.css';
import './theme.css';
import { ToastProvider } from '@volcraft/composants-nextjs';

export default function RootLayout({ children }) {
  return (
    // data-scroll-behavior : les styles posent scroll-behavior: smooth, Next le coupe pendant les navigations
    <html lang="fr" data-scroll-behavior="smooth">
      <body>
        <ToastProvider>{children}</ToastProvider>
      </body>
    </html>
  );
}

Thème

Redéfinir les propriétés --ui-* (liste : specs/001-ecommerce-design-system/contracts/tokens.md) :

:root {
  --ui-color-brand: #0f5c4a;
  --ui-color-brand-strong: #0a4337;
}

Les polices système sont le choix par défaut : une police web ajoutait environ 300 ms au LCP mobile de la démo (budget 2,5 s).

Points d'entrée

| Import | Contenu | | ---------------------------------------- | -------------------------------------------------------------------------------- | | @volcraft/composants-nextjs | composants, modèles de pages, fonctions et types | | @volcraft/composants-nextjs/lib | fonctions pures sans React (prix, panier, variantes, critères de recherche, SEO) | | @volcraft/composants-nextjs/styles.css | fondations + styles de tous les composants | | @volcraft/composants-nextjs/scss | mixins et points de rupture (@use '@volcraft/composants-nextjs/scss' as ui;) |

Skill Claude

Le paquet publie un skill pour Claude Code dans skill/ : mise en place, règles, tokens, thèmes, composants et règles d'usage de chacun. Pour l'activer dans un site :

cp -r node_modules/@volcraft/composants-nextjs/skill .claude/skills/volcraft-ui

Le skill est généré depuis le code (src/docs/skill.ts) : corepack pnpm --filter @volcraft/composants-nextjs skill:update. Le hook pre-commit le régénère dès qu'un fichier du paquet est commité, et test:unit échoue s'il n'est pas à jour.

Publication sur npm

La version est calculée par semantic-release (release.config.mjs) à partir des commits conventionnels : fix: → patch, feat: → minor, ! ou BREAKING CHANGE: → major (props, exports, noms de tokens --ui-*). Les commits de scope demo ne publient rien.

À chaque push sur main, le workflow Release publie @volcraft/composants-nextjs sur npm (prepublishOnly lance le build), commite la nouvelle version et le skill, puis crée le tag vX.Y.Z et la release GitHub.

Prérequis : l'organisation npm @volcraft et un jeton d'automatisation dans le secret GitHub NPM_TOKEN. Le paquet est publié en accès restricted (défaut npm d'un paquet scopé) : ajouter "publishConfig": { "access": "public" } dans package.json pour un paquet ouvert.

Simulation locale : corepack pnpm release --dry-run --no-ci.

Catalogue

pnpm --filter @volcraft/composants-nextjs storybook (http://localhost:6006) : fondations, composants, e-commerce, modèles de pages, règles d'usage et d'accessibilité de chaque composant. Une application complète se trouve dans apps/demo.

Version en ligne : https://volcraft-git.github.io/nextjs-ui/, déployée par la CI à chaque push sur main (réglage du dépôt : Settings → Pages → Source « GitHub Actions »).

Développement

corepack pnpm install
corepack pnpm --filter @volcraft/composants-nextjs test:unit     # fonctions pures, couverture ≥ 90 %
corepack pnpm --filter @volcraft/composants-nextjs test:stories  # stories + axe (WCAG 2.2 AA)
corepack pnpm --filter @volcraft/composants-nextjs build         # dist/ (ESM, .d.ts, styles.css)