EJS UI-KIT - Theming

1. Workflow

Identifier le bon niveau de personnalisation

tokens.css

Identité globale

Couleurs, typographie, radius, ombres, overlay et scrollbars.

input.css

Composants

Dimensions, espacements, densité, animations et styles .ui-*.

tailwind.config.js

Échelle Tailwind

Nouvelles utilities, breakpoints, espacements et extensions du thème.

Source de vérité : ne modifiez jamais public/app.css. Ce fichier est remplacé à chaque compilation.

Boucle de compilation Bash

# Développement : recompilation continue
npm run dev:css

# Production : CSS minifié
npm run build:css

2. Couleurs

Modifier les rôles sémantiques

Les composants utilisent des rôles comme primary, muted ou destructive, jamais une couleur métier codée en dur. Conservez ce principe lorsque vous changez la palette.

Primary

Secondary

Success

Warning

Danger

Info

Muted

Accent

Écrivez les couleurs en HSL sans virgule et sans fonction hsl().
Définissez toujours la paire rôle / rôle-foreground.
Vérifiez séparément les contrastes du thème clair et du thème sombre.

Palette claire complète Css

/* assets/css/tokens.css */
:root {
  --background: 42 33% 98%;
  --foreground: 222 47% 11%;
  --card: 0 0% 100%;
  --card-foreground: 222 47% 11%;
  --popover: 0 0% 100%;
  --popover-foreground: 222 47% 11%;

  --primary: 198 89% 32%;
  --primary-foreground: 0 0% 100%;
  --secondary: 198 28% 92%;
  --secondary-foreground: 198 89% 20%;
  --muted: 42 20% 93%;
  --muted-foreground: 220 9% 38%;
  --accent: 198 35% 90%;
  --accent-foreground: 198 89% 20%;

  --destructive: 0 72% 42%;
  --destructive-foreground: 0 0% 100%;
  --success: 142 72% 27%;
  --success-foreground: 0 0% 100%;
  --warning: 38 92% 50%;
  --warning-foreground: 26 83% 14%;
  --info: 217 78% 42%;
  --info-foreground: 0 0% 100%;

  --border: 38 18% 82%;
  --input: 38 18% 82%;
  --ring: 198 89% 32%;
}

3. Typographie

Choisir les familles et les charger

Les variables publiques --ui-font-* séparent le chargement physique des polices de leur application dans le kit.

Tokens typographiques Css

/* assets/css/tokens.css */
:root {
  --ui-font-sans: "Public Sans", ui-sans-serif, system-ui, sans-serif;
  --ui-font-mono: "JetBrains Mono", ui-monospace, monospace;
  --ui-font-body: var(--ui-font-sans);
  --ui-font-heading: "Manrope", var(--ui-font-sans);
}

Exemple auto-hébergé Css

/* public/fonts/ui-fonts.css */
@font-face {
  font-family: "Public Sans";
  src: url("/fonts/public-sans/PublicSans-Variable.woff2") format("woff2");
  font-weight: 100 900;
  font-style: normal;
  font-display: swap;
}

:root {
  --ui-font-sans: "Public Sans", ui-sans-serif, system-ui, sans-serif;
}

Chargez ensuite /fonts/ui-fonts.css dans le layout, avant ou après /app.css. Utilisez du WOFF2 et font-display: swap.

4. Forme et profondeur

Radius et ombres

--radius alimente les variantes Tailwind rounded-lg, rounded-md et rounded-sm. Les quatre ombres alimentent les classes shadow-*.

rounded-sm

rounded-md

rounded-lg

Tokens de forme Css

/* assets/css/tokens.css */
:root {
  --radius: 0.875rem;
  --shadow-sm: 0 1px 2px rgb(15 23 42 / 0.06);
  --shadow: 0 2px 6px rgb(15 23 42 / 0.10);
  --shadow-md: 0 8px 20px rgb(15 23 42 / 0.12);
  --shadow-lg: 0 18px 40px rgb(15 23 42 / 0.16);
}

5. Composants

Ajuster la densité et les styles internes

Pour une modification ciblée, surchargez les classes canoniques .ui-* dans un bloc @layer components placé après les définitions du kit.

Surcharges ciblées Css

/* À la fin de assets/css/input.css */
@layer components {
  .ui-btn-md {
    @apply h-10 px-5;
  }

  .ui-card {
    @apply shadow-md;
  }

  .ui-table-compact .ui-td {
    @apply px-3 py-2;
  }
}

Privilégiez d’abord les paramètres publics du composant. Une surcharge CSS ne doit servir qu’à modifier son apparence globale, pas à contourner son API.

6. Tailwind

Étendre les utilities

Partez toujours du fichier exporté et ajoutez vos extensions sans remplacer les mappings colors, borderRadius, fontFamily et boxShadow. Conservez aussi les chemins content : sans eux, Tailwind peut retirer du build les classes présentes dans les partials EJS ou les modules JavaScript.

tailwind.config.js Js

// tailwind.config.js
export default {
  darkMode: 'class',
  content: [
    './src/views/**/*.ejs',
    './public/ui/**/*.js',
    './assets/css/**/*.css',
  ],
  theme: {
    extend: {
      // Conservez ici colors, borderRadius, fontFamily et boxShadow du kit.
      spacing: {
        18: '4.5rem',
      },
      screens: {
        '3xl': '1920px',
      },
    },
  },
};

7. Mode sombre

Définir une palette dédiée

Le mode sombre est activé par la classe dark sur html. Ne déduisez pas automatiquement toute la palette sombre depuis la palette claire : contrôlez chaque surface et chaque foreground.

Palette sombre Css

/* assets/css/tokens.css */
.dark {
  --background: 222 47% 7%;
  --foreground: 210 40% 98%;
  --card: 222 47% 9%;
  --card-foreground: 210 40% 98%;
  --popover: 222 47% 10%;
  --popover-foreground: 210 40% 98%;

  --primary: 196 94% 67%;
  --primary-foreground: 222 47% 7%;
  --secondary: 217 33% 17%;
  --secondary-foreground: 210 40% 98%;
  --muted: 217 33% 17%;
  --muted-foreground: 215 20% 68%;
  --accent: 217 33% 20%;
  --accent-foreground: 210 40% 98%;

  --border: 217 33% 20%;
  --input: 217 33% 20%;
  --ring: 196 94% 67%;
}

Prévenir le flash de thème Html

<!-- Dans <head>, avant le rendu de la page -->
<script>
  (function () {
    const stored = localStorage.getItem('ui-theme');
    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
    if (stored === 'dark' || (!stored && prefersDark)) {
      document.documentElement.classList.add('dark');
    }
  })();
</script>

8. Finalisation

Compiler et contrôler le thème

Build de production Bash

npm run build:css

Checklist visuelle

• textes et contrôles contrastés en clair et sombre
• focus visible avec la couleur ring
• états success, warning, danger et info lisibles
• bordures visibles sur cards, tables et champs
• popovers et modales distincts du fond
• fonts chargées sans décalage majeur
• composants testés aux breakpoints principaux
• aucun changement manuel dans public/app.css

Tester sur les démos Vérifier les paramètres