@digicreon/mucss 1.0.0 → 1.2.0

package/documentation/mu.colors.md

@@ -0,0 +1,307 @@
+# µColors
+
+**µColors** describes the color system in [µCSS](.). The framework provides 11 semantic color roles, each with 7 CSS variable variants, color classes for the main visual components, and utility classes for text, background, and border colors.
+
+---
+
+## Color roles
+
+µCSS defines 11 color roles. Each role is mapped to a color family via the theme file (`build/mu.theme.json`).
+
+| Role | Purpose |
+|------|---------|
+| `primary` | Main action color — links, buttons, active states |
+| `secondary` | Supporting color — secondary buttons, muted elements |
+| `tertiary` | Accent color — additional highlights |
+| `contrast` | High-contrast color — strong emphasis |
+| `accent` | Eye-catching color — chromatically distant from primary |
+| `success` | Positive feedback — validation, confirmations |
+| `info` | Informational — notices, tips |
+| `warning` | Caution — alerts requiring attention |
+| `error` | Negative feedback — errors, destructive actions |
+| `pop` | Lighter variant of accent — derived from the accent color family with brighter shades |
+| `spark` | Lighter variant of contrast — derived from the contrast color family with brighter shades |
+
+> **Note:** `pop` and `spark` are derived roles — `pop` uses the same color family as `accent`, and `spark` uses the same color family as `contrast`, both with lighter shade values. They do not appear in the theme JSON.
+
+---
+
+## CSS variables per role
+
+Each role generates 7 CSS variables, automatically adapted for light and dark modes:
+
+| Variable | Description |
+|----------|-------------|
+| `--mu-{role}` | Base color |
+| `--mu-{role}-background` | Tinted background (light tint in light mode, dark tint in dark mode) |
+| `--mu-{role}-hover` | Hover state color |
+| `--mu-{role}-hover-background` | Hover background |
+| `--mu-{role}-focus` | Focus ring color (semi-transparent) |
+| `--mu-{role}-inverse` | Text color on a filled background (`#fff` or `#000`) |
+| `--mu-{role}-underline` | Semi-transparent underline |
+
+### Example
+
+```css
+.custom-banner {
+    color: var(--mu-info);
+    background-color: var(--mu-info-background);
+    border-left: 4px solid var(--mu-info);
+}
+
+.custom-banner:hover {
+    color: var(--mu-info-hover);
+}
+```
+
+---
+
+## Utility classes
+
+µCSS provides 34 utility classes in `css/mu.colors.css`:
+
+### Text color
+
+| Class | Effect |
+|-------|--------|
+| `.c-primary` … `.c-spark` | Sets `color` to the role's base color |
+
+### Text color (inverse)
+
+| Class | Effect |
+|-------|--------|
+| `.c-inverse` | Sets `color` to the primary inverse color (white or black, for readable text on filled backgrounds) |
+
+### Background color
+
+| Class | Effect |
+|-------|--------|
+| `.bg-primary` … `.bg-spark` | Sets `background-color` to the role's base color, `color` to inverse (white/black), and links inherit the inverse color |
+
+### Border color
+
+| Class | Effect |
+|-------|--------|
+| `.border-primary` … `.border-spark` | Sets `border-color` to the role's base color |
+
+```html
+<p class="c-error">Red text</p>
+<div class="bg-accent">Accent background — text and links are automatically white</div>
+<div class="border-success" style="border:2px solid">Green border</div>
+```
+
+> **Note:** On `<nav>` or on a parent of `<nav>` (e.g. `<header>`), `.bg-*` classes also apply a gradient (same as [µHero](mu.hero.md)). See [µNav](mu.nav.md#colored-navbars).
+
+---
+
+## Color classes by component
+
+The following components accept color classes for all 11 roles:
+
+### Button
+
+Filled buttons use the role color as background. Outline buttons use it as text and border only.
+
+| Class | Style |
+|-------|-------|
+| `.btn-primary` … `.btn-spark` | Filled background with inverse text |
+| `.btn-outline.btn-primary` … `.btn-outline.btn-spark` | Transparent background, colored text and border |
+| `.btn-link` | Link appearance using primary color |
+
+```html
+<button class="btn btn-success">Save</button>
+<button class="btn btn-outline btn-error">Delete</button>
+<button class="btn btn-accent">Highlight</button>
+<button class="btn btn-pop">Pop action</button>
+<button class="btn btn-spark">Spark action</button>
+```
+
+### Alert
+
+```html
+<div class="alert alert-warning">Caution: this action cannot be undone.</div>
+```
+
+| Class | Style |
+|-------|-------|
+| `.alert-primary` … `.alert-spark` | Colored text, tinted background |
+
+### Badge
+
+Solid badges use the role color as background. Outline badges use it as text and border only.
+
+```html
+<span class="badge badge-success">Active</span>
+<span class="badge badge-outline badge-error">Expired</span>
+```
+
+| Class | Style |
+|-------|-------|
+| `.badge-primary` … `.badge-spark` | Filled background with inverse text |
+| `.badge-outline.badge-primary` … `.badge-outline.badge-spark` | Transparent background, colored text and border |
+
+### Card
+
+```html
+<article class="card-info">
+    <header>Note</header>
+    <p>Card content with a colored left border and tinted background.</p>
+</article>
+```
+
+| Class | Style |
+|-------|-------|
+| `.card-primary` … `.card-spark` | Tinted background, shaded header/footer |
+
+### Hero
+
+```html
+<section class="hero hero-primary">
+    <h1>Welcome</h1>
+</section>
+```
+
+| Class | Style |
+|-------|-------|
+| `.hero-primary` … `.hero-spark` | Gradient background with inverse text |
+
+### Spinner
+
+```html
+<div class="spinner spinner-success"></div>
+```
+
+| Class | Style |
+|-------|-------|
+| `.spinner-primary` … `.spinner-spark` | Colored spinning border |
+
+### Progress
+
+```html
+<progress class="progress-success" value="75" max="100"></progress>
+```
+
+| Class | Style |
+|-------|-------|
+| `.progress-primary` … `.progress-spark` | Colored progress bar |
+
+### Forms
+
+Form validation uses a subset of roles:
+
+| Class | Style |
+|-------|-------|
+| `.input-success` | Green border and focus ring |
+| `.input-warning` | Amber border and focus ring |
+| `aria-invalid="true"` | Red border and focus ring (built-in) |
+
+---
+
+## Link color variants
+
+Links support 3 color variants via CSS classes:
+
+```html
+<a href="#">Primary link (default)</a>
+<a href="#" class="secondary">Secondary link</a>
+<a href="#" class="contrast">Contrast link</a>
+```
+
+| Class | Color variable |
+|-------|----------------|
+| *(default)* | `--mu-primary` |
+| `.secondary` | `--mu-secondary` |
+| `.contrast` | `--mu-contrast` |
+
+---
+
+## Components with implicit colors
+
+These components use color roles internally but do not expose color classes:
+
+| Component | Colors used |
+|-----------|-------------|
+| Pagination | `--mu-primary` (active), `--mu-secondary` (borders, disabled) |
+| Tabs | `--mu-primary` (active tab), `--mu-secondary` (inactive) |
+| Breadcrumb | `--mu-primary` (links), `--mu-secondary` (dividers, last item) |
+| Accordion | `--mu-secondary-background` (borders) |
+| Table | `--mu-secondary-background` (stripes, hover, borders) |
+| Skeleton | `--mu-secondary-background` (placeholder background) |
+| Modal | `--mu-secondary` (close button) |
+| Toast | Inherits alert colors via `.alert-{role}` |
+
+---
+
+## Base theme colors
+
+These variables define the overall page appearance and adapt between light and dark modes:
+
+| Variable | Light | Dark |
+|----------|-------|------|
+| `--mu-background-color` | `#fff` | `rgb(19, 22.5, 30.5)` |
+| `--mu-color` | `#373c44` | `#c2c7d0` |
+| `--mu-muted-color` | `#646b79` | `#8891a4` |
+| `--mu-muted-border-color` | `rgb(231, 234, 239.5)` | `rgb(48, 54.5, 69)` |
+| `--mu-mark-background-color` | `rgb(252.5, 230.5, 191.5)` | `rgb(252.5, 230.5, 191.5)` |
+| `--mu-h1-color` … `--mu-h6-color` | Graded shades from dark to muted | Graded shades from light to muted |
+
+The full variable reference is available in [µVariables](mu.variables.md).
+
+---
+
+## Pre-built themes
+
+µCSS includes 20 pre-built color themes, each generating a dedicated CSS file (`mu.{name}.css`). The default theme is **azure** (`mu.css`).
+
+Each theme is named after its `primary` color family and remaps the 11 roles accordingly. Most themes share the same defaults for secondary (slate), tertiary (sand), success (green), info (cyan), warning (amber), and error (red) — the `primary`, `contrast`, and `accent` roles vary per theme. The `pop` role always derives from `accent` with lighter shades, and the `spark` role always derives from `contrast` with lighter shades.
+
+Available themes: **azure** (default), **red**, **pink**, **fuchsia**, **purple**, **violet**, **indigo**, **blue**, **cyan**, **jade**, **green**, **lime**, **yellow**, **amber**, **pumpkin**, **orange**, **sand**, **grey**, **zinc**, **slate**.
+
+To use a theme, load its CSS file instead of the default:
+
+```html
+<link rel="stylesheet" href="dist/mu.pink.css">
+```
+
+Themes are defined in `build/mu.theme.json`. Each entry maps the 9 configurable roles (all except `pop` and `spark`) to color families from a palette of 20 colors.
+
+---
+
+## Customization
+
+Override role colors on `:root` to change them globally:
+
+```css
+:root {
+    --mu-primary: #e63946;
+    --mu-primary-hover: #c5303b;
+    --mu-primary-focus: rgba(230, 57, 70, 0.375);
+    --mu-primary-inverse: #fff;
+}
+```
+
+For theme-based color generation, edit `build/mu.theme.json` and rebuild:
+
+```json
+{
+    "primary": "red",
+    "secondary": "slate",
+    "tertiary": "sand",
+    "contrast": "indigo",
+    "accent": "jade",
+    "success": "green",
+    "info": "azure",
+    "warning": "amber",
+    "error": "pink"
+}
+```
+
+```bash
+php build/mu-build.php
+```
+
+---
+
+> See also : [µVariables](mu.variables.md) · [µDark Mode](mu.dark-mode.md) · [µButton](mu.button.md) · [µAlert](mu.alert.md)
+
+→ [See example](../examples/colors.html)

package/documentation/mu.container.md

@@ -0,0 +1,87 @@
+# µContainer
+
+**µContainer** provides the `.container` and `.container-fluid` layout classes in [µCSS](.). The container centers content horizontally and applies a responsive maximum width adapted to each breakpoint.
+
+---
+
+## Usage
+
+Wrap the main content in an element with the `.container` class:
+
+```html
+<main class="container">
+    <h1>Mon contenu</h1>
+    <p>Centre et contraint en largeur.</p>
+</main>
+```
+
+---
+
+## `.container` — Constrained width
+
+The container is fluid (100%) on mobile, then constrained to a maximum width at each breakpoint:
+
+| Breakpoint | Minimum width | `max-width` |
+|------------|---------------|-------------|
+| XS | < 576px | 100% (fluid) |
+| SM | ≥ 576px | 510px |
+| MD | ≥ 768px | 700px |
+| LG | ≥ 1024px | 950px |
+| XL | ≥ 1280px | 1200px |
+| XXL | ≥ 1536px | 1450px |
+
+In fluid mode (< 576px), a horizontal padding of `var(--mu-spacing)` (1rem) is applied. From 576px onward, the padding is removed and the maximum width takes over.
+
+---
+
+## `.container-fluid` — Full width
+
+The fluid container always occupies 100% of the width, with constant horizontal padding:
+
+```html
+<section class="container-fluid">
+    <p>Contenu pleine largeur avec marges laterales.</p>
+</section>
+```
+
+---
+
+## Typical page structure
+
+µCSS recommends the `<body> > <header> + <main> + <footer>` structure, each containing a `.container`:
+
+```html
+<body>
+    <header>
+        <nav class="container">
+            <ul><li><strong>Mon site</strong></li></ul>
+            <ul><li><a href="#">Lien</a></li></ul>
+        </nav>
+    </header>
+    <main class="container">
+        <h1>Titre</h1>
+        <p>Contenu principal.</p>
+    </main>
+    <footer class="container">
+        <p>Pied de page</p>
+    </footer>
+</body>
+```
+
+The `<body> > header`, `<body> > main`, and `<body> > footer` elements receive a vertical padding of `var(--mu-block-spacing-vertical)`.
+
+---
+
+## Customization
+
+The `--mu-spacing` variable (default: `1rem`) controls the horizontal padding of the container in fluid mode:
+
+```css
+:root {
+    --mu-spacing: 1.5rem;
+}
+```
+
+---
+
+> See also : [µGrid](mu.grid.md)

package/documentation/mu.dark-mode.md

@@ -0,0 +1,96 @@
+# µDark Mode
+
+**µDark Mode** manages the toggle between light and dark themes in [µCSS](.). Dark mode is activated either automatically via the user's system preference (`prefers-color-scheme`), or manually via the `data-theme` attribute on the root element.
+
+---
+
+## Usage
+
+No configuration is required for automatic mode. µCSS detects the system preference and adapts colors accordingly.
+
+To force a theme, add `data-theme` on `<html>`:
+
+```html
+<html data-theme="dark">
+```
+
+---
+
+## Available modes
+
+| Mode | Trigger | CSS Selector |
+|------|---------|--------------|
+| Light (default) | System preference or `data-theme="light"` | `:root:not([data-theme="dark"])` |
+| Auto dark | `prefers-color-scheme: dark` without `data-theme` | `@media (prefers-color-scheme: dark) { :root:not([data-theme]) }` |
+| Forced dark | `data-theme="dark"` | `[data-theme="dark"]` |
+
+---
+
+## Manual toggle
+
+A JavaScript button allows the user to toggle between themes:
+
+```html
+<button id="theme-toggle">Basculer le theme</button>
+
+<script>
+const btn = document.getElementById('theme-toggle');
+btn.addEventListener('click', () => {
+    const html = document.documentElement;
+    const current = html.getAttribute('data-theme');
+    html.setAttribute('data-theme', current === 'dark' ? 'light' : 'dark');
+});
+</script>
+```
+
+---
+
+## Affected color variables
+
+All µCSS color variables adapt to the theme. The main ones:
+
+| Variable | Light theme | Dark theme |
+|----------|-------------|------------|
+| `--mu-background-color` | `#fff` | `rgb(19, 22.5, 30.5)` |
+| `--mu-color` | `#373c44` | `#c2c7d0` |
+| `--mu-primary` | `#0172ad` | `#01aaff` |
+| `--mu-muted-color` | `#646b79` | `#8891a4` |
+| `--mu-card-background-color` | `#fff` | `rgb(24, 28.5, 38)` |
+
+The full list is available in [mu.variables.md](mu.variables.md).
+
+---
+
+## `color-scheme` property
+
+µCSS sets `color-scheme: light` or `color-scheme: dark` depending on the active theme. This native CSS property informs the browser of the color scheme, which affects scrollbars, native form fields, and other browser UI elements.
+
+---
+
+## Color customization
+
+To override the colors of a theme, target the corresponding selector:
+
+```css
+/* Surcharge du fond en mode sombre */
+[data-theme="dark"] {
+    --mu-background-color: #1a1a2e;
+}
+
+/* Surcharge en mode clair */
+:root:not([data-theme="dark"]) {
+    --mu-primary: #e63946;
+}
+```
+
+---
+
+## Accessibility
+
+- Theme toggling must not modify the content or structure of the page.
+- Color contrasts comply with WCAG AA recommendations in both themes.
+- Using `prefers-color-scheme` as the default mode respects user preferences.
+
+---
+
+> See also : [µVariables](mu.variables.md)

package/documentation/mu.dropdown.md

@@ -1,12 +1,12 @@
 # µDropdown
 
-**µDropdown** fournit des menus deroulants CSS purs via l'element `<details class="dropdown">`, styles par [PicoCSS](https://picocss.com) au sein du framework [µCSS](.). Aucun JavaScript n'est necessaire : l'ouverture et la fermeture sont gerees nativement par le navigateur.
+**µDropdown** provides pure CSS dropdown menus via the `<details class="dropdown">` element, styled by [µCSS](.). No JavaScript is required: opening and closing are handled natively by the browser.
 
 ---
 
-## Utilisation de base
+## Basic usage
 
-Un dropdown est construit avec `<details class="dropdown">`. Le `<summary>` sert de declencheur et la liste `<ul>` contient les options.
+A dropdown is built with `<details class="dropdown">`. The `<summary>` serves as the trigger and the `<ul>` list contains the options.
 
 ```html
 <details class="dropdown">
@@ -21,9 +21,9 @@ Un dropdown est construit avec `<details class="dropdown">`. Le `<summary>` sert
 
 ---
 
-## Style bouton
+## Button style
 
-Ajoutez `role="button"` sur le `<summary>` pour lui donner l'apparence d'un bouton.
+Add `role="button"` to the `<summary>` to give it the appearance of a button.
 
 ```html
 <details class="dropdown">
@@ -39,13 +39,13 @@ Ajoutez `role="button"` sur le `<summary>` pour lui donner l'apparence d'un bout
 
 ---
 
-## Variantes natives PicoCSS
+## Native variants
 
-PicoCSS fournit des variantes de style via des classes sur le `<summary role="button">` :
+µCSS provides style variants via classes on the `<summary role="button">`:
 
-| Classe | Apparence |
-|--------|-----------|
-| *(aucune)* | Primary (defaut) |
+| Class | Appearance |
+|-------|------------|
+| *(none)* | Primary (default) |
 | `.secondary` | Secondary |
 | `.contrast` | Contrast |
 | `.outline` | Outline |
@@ -86,20 +86,23 @@ PicoCSS fournit des variantes de style via des classes sur le `<summary role="bu
 
 ---
 
-## Variantes de couleur µCSS
+## µCSS color variants
 
-µCSS etend les dropdowns avec les classes `.btn-*` sur le `<summary>` pour les 8 roles de couleur :
+µCSS extends dropdowns with `.btn-*` classes on the `<summary>` for the 11 color roles:
 
-| Classe | Couleur |
-|--------|---------|
+| Class | Color |
+|-------|-------|
 | `.btn-primary` | Primary |
 | `.btn-secondary` | Secondary |
 | `.btn-tertiary` | Tertiary |
 | `.btn-contrast` | Contrast |
+| `.btn-accent` | Accent |
 | `.btn-success` | Success |
 | `.btn-info` | Info |
 | `.btn-warning` | Warning |
 | `.btn-error` | Error |
+| `.btn-pop` | Pop |
+| `.btn-spark` | Spark |
 
 ```html
 <details class="dropdown">
@@ -129,9 +132,9 @@ PicoCSS fournit des variantes de style via des classes sur le `<summary role="bu
 
 ---
 
-## Remplacement de select
+## Select replacement
 
-Un dropdown peut servir d'alternative stylee a un `<select>` natif en le placant dans un `<label>`.
+A dropdown can serve as a styled alternative to a native `<select>` by placing it inside a `<label>`.
 
 ```html
 <label>Choose a fruit
@@ -148,7 +151,7 @@ Un dropdown peut servir d'alternative stylee a un `<select>` natif en le placant
 </label>
 ```
 
-**Note :** contrairement a un `<select>` natif, la valeur selectionnee n'est pas geree automatiquement. Un minimum de JavaScript applicatif est necessaire pour mettre a jour le texte du `<summary>` apres selection.
+**Note:** unlike a native `<select>`, the selected value is not managed automatically. A minimum of application JavaScript is required to update the `<summary>` text after selection.
 
 ---
 
@@ -166,18 +169,20 @@ Un dropdown peut servir d'alternative stylee a un `<select>` natif en le placant
 
 | Element | Role |
 |---------|------|
-| `<details class="dropdown">` | Conteneur du dropdown |
-| `<summary>` | Declencheur (texte ou bouton) |
-| `<summary role="button">` | Declencheur avec apparence bouton |
-| `<ul>` | Liste des options |
-| `<li><a>` | Element de menu cliquable |
+| `<details class="dropdown">` | Dropdown container |
+| `<summary>` | Trigger (text or button) |
+| `<summary role="button">` | Trigger with button appearance |
+| `<ul>` | Options list |
+| `<li><a>` | Clickable menu item |
 
 ---
 
-## Accessibilite
+## Accessibility
 
-- Le composant repose sur l'element natif `<details>`/`<summary>`, accessible par defaut au clavier (ouverture via `Enter` ou `Space`).
-- L'attribut `role="button"` sur `<summary>` informe les technologies d'assistance que l'element agit comme un bouton.
-- Le menu se ferme automatiquement lorsque l'utilisateur clique en dehors (comportement natif de `<details>`).
+- The component relies on the native `<details>`/`<summary>` element, which is keyboard accessible by default (opens via `Enter` or `Space`).
+- The `role="button"` attribute on `<summary>` informs assistive technologies that the element acts as a button.
+- The menu closes automatically when the user clicks outside (native `<details>` behavior).
 
-→ [Voir l'exemple](../examples/dropdown.html)
+> See also : [µNav](mu.nav.md) · [µButton](mu.button.md)
+
+> [See example](../examples/dropdown.html)