Core Kit Mini CSS

Mini framework CSS technique, grid-first, pour construire vite une UI simple et responsive avec des classes reutilisables.

Guide de build et publication npm:

• docs/core-kit-build-and-publish.md

Objectif

• Fournir une base CSS commune.
• Garder un systeme de classes explicite (sans prefixe technique).
• Proposer un noyau reutilisable pour les projets qui n utilisent pas de librairie comme Bootstrap.

Arborescence

src/styles/
  _core-kit-mini-css.scss
  README.md
  core-kit/
    _settings.scss
    _grid.scss
    _utilities.scss
    _utilities-generated.scss
    _utilities-static.scss
    _visual-utilities.scss

Architecture

• _settings.scss: configuration layout SCSS (breakpoints, container widths, spacing scale, mixin media).
• _grid.scss: systeme grid + container + spans.
• _utilities.scss: point d'entree des utilitaires layout neutres.
• _utilities-generated.scss: utilitaires generes depuis maps/scales/breakpoints.
• _utilities-static.scss: utilitaires fixes sans generation SCSS.
• _visual-utilities.scss: utilitaires visuels legers, pilotables via variables CSS.

Integration

Mode 1: chargement local des sources techniques

Tu peux charger uniquement:

@use "./styles/core-kit/settings";
@use "./styles/core-kit/grid";
@use "./styles/core-kit/utilities";

Dans ce mode, vous branchez vos propres variables CSS de marque ou de layout si besoin.

Mode 2: package reutilisable

Le framework peut etre distribue comme package CSS/SCSS sans copier-coller de fichiers. Dans le contexte actuel, le package publie expose volontairement le noyau technique settings, grid, utilities ainsi que visual-utilities, sans embarquer tokens, base ni components.

Build du package:

npm run build:core-kit

Sortie generee:

dist/core-kit-mini-css/
  core-kit-mini-css.css
  core-kit-mini-css.min.css
  README.md
  package.json
  scss/
    core-kit-mini-css.scss
    _core-kit-mini-css.scss
    core-kit/
      _settings.scss
      _grid.scss
      _utilities.scss
      _utilities-generated.scss
      _utilities-static.scss
      _visual-utilities.scss

Installation dans un autre projet:

npm install ../ng-core-kit/dist/core-kit-mini-css

Chargement via angular.json:

"styles": [
  "src/styles.scss",
  "node_modules/core-kit-mini-css/core-kit-mini-css.css"
]

Chargement via styles.scss:

@use "core-kit-mini-css/scss/core-kit-mini-css";

Configuration Layout (SCSS)

Fichier: src/styles/core-kit/_settings.scss

Breakpoints par defaut:

• sm: 576px
• md: 768px
• lg: 992px
• xl: 1200px
• xxl: 1400px

Spacing scale par defaut:

• 0 -> 0
• 1 -> 0.25rem
• 2 -> 0.5rem
• 3 -> 1rem
• 4 -> 1.5rem
• 5 -> 3rem
• 6 -> 4rem

Override possible avec @use ... with (...):

@use "./styles/core-kit/settings" with (
  $breakpoints: (
    sm: 640px,
    md: 768px,
    lg: 1024px,
    xl: 1280px,
    xxl: 1536px
  )
);

@use "./styles/core-kit/grid";
@use "./styles/core-kit/utilities";

Comment lire ce fichier:

• @use "sass:map": permet d'utiliser map.get(...).
• $breakpoints: nom -> largeur min pour le responsive.
• $container-max-widths: largeur max de .container par breakpoint.
• $space-scale: echelle reutilisee pour m-*, p-*, gap-*.
• !default: valeur surchargeable depuis un autre projet.
• @mixin media-up(...): helper pour generer un @media (min-width: ...).

Grille (grid-first)

Classes principales:

• Conteneurs: container, container-fluid
• Grille: grid, grid-1 a grid-12
• Alias moderne: grid-cols-1 a grid-cols-12
• Grille responsive: grid-md-6, grid-lg-12, md:grid-cols-2, lg:grid-cols-3, etc.
• Spans: span-1 a span-12, span-full
• Alias moderne: col-span-1 a col-span-12, col-span-full
• Spans responsive: span-md-6, span-lg-4, span-xl-full, md:col-span-1, lg:col-span-2
• Start column: start-2, start-lg-4, col-start-2, lg:col-start-4, etc.
• Gap grille: g-*, gx-*, gy-*

Exemple:

<div class="container py-4">
  <div class="grid grid-cols-1 lg:grid-cols-12 g-3">
    <main class="col-span-full lg:col-span-8">Contenu principal</main>
    <aside class="col-span-full lg:col-span-4">Sidebar</aside>
  </div>
</div>

Note:

• Le kit est pense pour grid.
• Pas de systeme row/col.
• La syntaxe historique (grid-lg-12, span-lg-4) reste supportee.

Comment lire le generateur SCSS de _grid.scss:

• @each sur s.$container-max-widths: genere les max-width de .container selon breakpoint.
• @for 1 through 12 sur .grid-#{$i}: genere grid-1 a grid-12.
• @for 1 through 12 sur .span-#{$i}: genere span-1 a span-12.
• @for 1 through 12 sur .start-#{$i}: genere start-1 a start-12.
• bloc @each $breakpoint ... @include s.media-up(...): genere les variantes responsive (grid-lg-12, span-md-6, start-xl-2).
• @each sur s.$space-scale: genere g-*, gx-*, gy-*.

Utilitaires

Display:

• d-none, d-block, d-inline-block, d-grid, d-inline-grid
• flex, inline-flex, hidden
• Responsive: d-md-grid, d-lg-none, md:flex, lg:grid, sm:hidden, etc.

Flex et alignement:

• flex-row, flex-col
• flex-1 a flex-12
• justify-start, justify-center, justify-end, justify-between
• items-start, items-center, items-end, items-stretch
• Variantes responsive: md:flex-row, lg:flex-col, md:items-center, md:justify-between

Spacing:

• m-*, p-*
• mx-*, my-*, px-*, py-*
• mt-*, mb-*, ml-*, mr-*, pt-*, pb-*, pl-*, pr-*
• variantes responsive recommandees: md:m-4, lg:px-3, md:p-4, etc.
• variantes historiques encore supportees: m-lg-4, px-md-3, etc.
• *-auto pour margins (mx-auto, mt-md-auto, etc.)

Recommandation responsive:

• Pour tout nouveau code, preferer la syntaxe moderne breakpoint:utility.
• Exemple: md:p-4 est a preferer a p-md-4.
• Exemple: md:px-4 est a preferer a px-md-4.
• Les deux syntaxes produisent le meme resultat CSS a partir du breakpoint cible.
• La syntaxe historique reste supportee pour la compatibilite et les migrations progressives.

Texte et dimensions:

• text-left, text-center, text-right
• text-sm, text-lg, text-xl
• w-100, h-100, max-w-sm, min-w-0
• shrink-0
• cursor-pointer
• overflow-auto, overflow-hidden

Helpers grid:

• grid-flow-row, grid-flow-col
• auto-cols-fr, auto-cols-max
• justify-start, justify-center, justify-between
• items-start, items-center, items-end
• place-items-center
• justify-items-start, justify-items-center, justify-items-end
• justify-self-start, justify-self-center, justify-self-end
• gap-0 a gap-6

Exemple syntaxe moderne:

<div class="flex flex-col md:flex-row md:items-center md:justify-between gap-3">
  <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-3 w-100">
    <article class="overflow-hidden cursor-pointer col-span-full lg:col-span-2">
      Contenu
    </article>
  </div>
</div>

Variables utiles pour les utilitaires layout:

• --layout-gutter (fallback 0.75rem) pour container et grid
• --utility-max-width-sm (fallback 480px) pour max-w-sm
• --utility-font-size-sm (fallback 0.875rem) pour text-sm
• --utility-font-size-lg (fallback 1.125rem) pour text-lg
• --utility-font-size-xl (fallback 1.25rem) pour text-xl

Exemple de surcharge dans un autre projet:

:root {
  --utility-font-size-sm: 0.8125rem;
  --utility-font-size-lg: 1rem;
  --utility-font-size-xl: 1.375rem;
}

Utilitaires visuels legers

Le package inclut aussi les utilitaires visuels suivants:

• text-primary, text-muted, text-success, text-danger
• bg-primary, bg-light, bg-dark
• fw-normal, fw-semibold, fw-bold
• rounded-0, rounded-sm, rounded, rounded-lg
• shadow-sm, shadow
• border, border-b

Ces classes restent neutres et s appuient sur des variables CSS pour s adapter a un autre projet.

Variables utiles:

• --utility-text-primary
• --utility-text-muted
• --utility-text-success
• --utility-text-danger
• --utility-bg-primary
• --utility-bg-primary-text
• --utility-bg-light
• --utility-bg-dark
• --utility-bg-dark-text
• --utility-radius-sm
• --utility-radius-md
• --utility-radius-lg
• --utility-shadow-sm
• --utility-shadow-md
• --utility-border-color

Regles de contribution

• Eviter les valeurs de design en dur dans grid et utilities.
• Ajouter toute nouvelle valeur globale dans votre design system ou via des variables d integration.
• Garder des noms de classes explicites et atomiques.
• Preferer des compositions grid plutot que des patterns row/col.

Verification locale

npm run build