feat(unified-mobile-material-design): Complete US-116 - Actualizare DESIGN_TOKENS.md cu MD3 Tokens

Implemented by Ralph autonomous loop. Iteration: 5 Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-12 11:19:21 +00:00
parent fdec2ae81d
commit 4d656e89af
3 changed files with 222 additions and 4 deletions
--- a/docs/DESIGN_TOKENS.md
+++ b/docs/DESIGN_TOKENS.md
@@ -570,14 +570,226 @@ Each color has a full scale (50-900) that inverts appropriately in dark mode:

 ---

+## Material Design 3 Tokens
+
+ROA2WEB implementează **Material Design 3 (MD3)** color tokens pentru componente mobile și touch-friendly. Aceste tokens urmează convenția de denumire MD3 și se mapează la token-urile existente pentru consistență.
+
+**Location:** `src/assets/css/core/md3-tokens.css`
+
+**Reference:** [Material Design 3 Color System](https://m3.material.io/styles/color/system/overview)
+
+### MD3 Color Token Overview
+
+MD3 folosește un sistem de culori bazat pe **roluri semantice** în loc de valori specifice. Fiecare culoare principală are variante asociate:
+
+| Prefix | Purpose |
+|--------|---------|
+| `--md-sys-color-{name}` | Culoarea principală pentru acel rol |
+| `--md-sys-color-on-{name}` | Text/iconițe PE acea culoare (contrast garantat) |
+| `--md-sys-color-{name}-container` | Background mai subtle pentru componente |
+| `--md-sys-color-on-{name}-container` | Text pe container (contrast garantat) |
+
+### Primary Colors
+
+| MD3 Token | Light Mode Maps To | Dark Mode Maps To | Use Case |
+|-----------|-------------------|-------------------|----------|
+| `--md-sys-color-primary` | `--color-primary` | `--primary-300` | FAB, prominent buttons, active states |
+| `--md-sys-color-on-primary` | `--color-text-inverse` | `--primary-900` | Text/icons on primary color |
+| `--md-sys-color-primary-container` | `--primary-100` | `--primary-700` | Chips, cards with primary tint |
+| `--md-sys-color-on-primary-container` | `--primary-900` | `--primary-100` | Text on primary container |
+
+### Secondary Colors
+
+| MD3 Token | Light Mode Maps To | Dark Mode Maps To | Use Case |
+|-----------|-------------------|-------------------|----------|
+| `--md-sys-color-secondary` | `--color-secondary` | `--gray-300` | Less prominent components |
+| `--md-sys-color-on-secondary` | `--color-text-inverse` | `--gray-900` | Text/icons on secondary |
+| `--md-sys-color-secondary-container` | `--gray-100` | `--gray-700` | Secondary component backgrounds |
+| `--md-sys-color-on-secondary-container` | `--gray-900` | `--gray-100` | Text on secondary container |
+
+### Surface Colors
+
+| MD3 Token | Light Mode Maps To | Dark Mode Maps To | Use Case |
+|-----------|-------------------|-------------------|----------|
+| `--md-sys-color-surface` | `--surface-card` | `--surface-card` | Cards, sheets, dialogs |
+| `--md-sys-color-on-surface` | `--color-text` | `--color-text` | Primary text on surface |
+| `--md-sys-color-surface-variant` | `--surface-50` | `--surface-200` | Alternate surface |
+| `--md-sys-color-on-surface-variant` | `--color-text-secondary` | `--color-text-secondary` | Secondary text |
+
+### Background & Outline
+
+| MD3 Token | Light Mode Maps To | Dark Mode Maps To | Use Case |
+|-----------|-------------------|-------------------|----------|
+| `--md-sys-color-background` | `--surface-ground` | `--surface-ground` | Base page layer |
+| `--md-sys-color-on-background` | `--color-text` | `--color-text` | Text on background |
+| `--md-sys-color-outline` | `--surface-border` | `--surface-border` | Component borders |
+| `--md-sys-color-outline-variant` | `--color-border-light` | `--surface-300` | Subtle dividers |
+
+### Error Colors
+
+| MD3 Token | Light Mode Maps To | Dark Mode Maps To | Use Case |
+|-----------|-------------------|-------------------|----------|
+| `--md-sys-color-error` | `--color-error` | `--red-300` | Error states, destructive actions |
+| `--md-sys-color-on-error` | `--color-text-inverse` | `--red-900` | Text on error |
+| `--md-sys-color-error-container` | `--red-100` | `--red-800` | Error state backgrounds |
+| `--md-sys-color-on-error-container` | `--red-900` | `--red-100` | Text on error container |
+
+### Surface Elevation Levels (Tonal Surfaces)
+
+MD3 înlocuiește shadowurile cu **suprafețe tonale** - culorile devin mai deschise/închise pentru a indica elevația:
+
+| MD3 Token | Light Mode | Dark Mode | Elevation Level |
+|-----------|------------|-----------|-----------------|
+| `--md-sys-color-surface-dim` | `--surface-100` | `--surface-0` | Below surface |
+| `--md-sys-color-surface-bright` | `--surface-0` | `--surface-200` | Above surface |
+| `--md-sys-color-surface-container-lowest` | `--surface-0` | `--surface-0` | Level 0 |
+| `--md-sys-color-surface-container-low` | `--surface-50` | `--surface-50` | Level 1 |
+| `--md-sys-color-surface-container` | `--surface-100` | `--surface-100` | Level 2 (default) |
+| `--md-sys-color-surface-container-high` | `--surface-200` | `--surface-200` | Level 3 |
+| `--md-sys-color-surface-container-highest` | `--surface-300` | `--surface-300` | Level 4 |
+
+### Inverse & Scrim
+
+| MD3 Token | Light Mode | Dark Mode | Use Case |
+|-----------|------------|-----------|----------|
+| `--md-sys-color-inverse-surface` | `--surface-800` | `--surface-800` | Snackbars, tooltips |
+| `--md-sys-color-inverse-on-surface` | `--surface-50` | `--surface-100` | Text on inverse surface |
+| `--md-sys-color-inverse-primary` | `--primary-300` | `--primary-600` | Primary accent on inverse |
+| `--md-sys-color-scrim` | `rgba(0,0,0,0.32)` | `rgba(0,0,0,0.64)` | Modal/sheet overlays |
+
+### MD3 Token Mapping Quick Reference
+
+Pentru referință rapidă, iată mapping-ul complet între MD3 tokens și tokens-urile existente ROA2WEB:
+
+| MD3 Token | ROA2WEB Equivalent |
+|-----------|-------------------|
+| `--md-sys-color-primary` | `--color-primary` |
+| `--md-sys-color-on-primary` | `--color-text-inverse` |
+| `--md-sys-color-surface` | `--surface-card` |
+| `--md-sys-color-on-surface` | `--color-text` / `--text-color` |
+| `--md-sys-color-background` | `--surface-ground` |
+| `--md-sys-color-outline` | `--surface-border` |
+| `--md-sys-color-error` | `--color-error` |
+
+### Dark Mode Examples
+
+**Exemplu 1: Card cu MD3 tokens**
+
+```css
+/* Light mode: fundal alb, text închis */
+/* Dark mode: fundal închis, text deschis */
+.md3-card {
+  background: var(--md-sys-color-surface);
+  color: var(--md-sys-color-on-surface);
+  border: 1px solid var(--md-sys-color-outline);
+}
+
+.md3-card-header {
+  background: var(--md-sys-color-surface-container-high);
+  color: var(--md-sys-color-on-surface);
+}
+```
+
+**Exemplu 2: Button primary cu MD3 tokens**
+
+```css
+/* Light: background albastru (#2563eb), text alb */
+/* Dark: background albastru deschis (--primary-300), text închis */
+.md3-button-filled {
+  background: var(--md-sys-color-primary);
+  color: var(--md-sys-color-on-primary);
+}
+
+.md3-button-filled:hover {
+  background: var(--md-sys-color-primary-container);
+  color: var(--md-sys-color-on-primary-container);
+}
+```
+
+**Exemplu 3: Error state cu MD3 tokens**
+
+```css
+/* Light: fundal roșu deschis, text roșu închis */
+/* Dark: fundal roșu închis, text roșu deschis */
+.md3-error-message {
+  background: var(--md-sys-color-error-container);
+  color: var(--md-sys-color-on-error-container);
+  border: 1px solid var(--md-sys-color-error);
+}
+```
+
+**Exemplu 4: Elevated surface cu tonal levels**
+
+```css
+/* Folosește suprafețe tonale în loc de shadow pentru elevație */
+.md3-bottom-sheet {
+  background: var(--md-sys-color-surface-container-low);
+}
+
+.md3-dialog {
+  background: var(--md-sys-color-surface-container-high);
+}
+
+.md3-navigation-drawer {
+  background: var(--md-sys-color-surface-container);
+}
+```
+
+**Exemplu 5: Scrim pentru modal overlay**
+
+```css
+.md3-modal-backdrop {
+  background: var(--md-sys-color-scrim);
+  /* Light: rgba(0,0,0,0.32) - semi-transparent */
+  /* Dark: rgba(0,0,0,0.64) - more opaque for better contrast */
+}
+```
+
+### When to Use MD3 Tokens vs Existing Tokens
+
+| Scenario | Recommended Tokens |
+|----------|-------------------|
+| Mobile-first components | MD3 tokens (`--md-sys-color-*`) |
+| Touch-friendly UI | MD3 tokens |
+| Desktop components | Existing tokens (`--color-*`, `--surface-*`) |
+| Legacy code | Existing tokens |
+| New cross-platform components | MD3 tokens (better dark mode support) |
+
+### CSS Priority for Dark Mode
+
+MD3 tokens urmează aceeași ordine de prioritate ca restul sistemului:
+
+```css
+/* 1. Manual override (highest priority) */
+[data-theme="dark"] {
+  --md-sys-color-primary: var(--primary-300);
+}
+
+/* 2. System preference (fallback when no manual theme) */
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme]) {
+    --md-sys-color-primary: var(--primary-300);
+  }
+}
+
+/* 3. Default light mode */
+:root {
+  --md-sys-color-primary: var(--color-primary);
+}
+```
+
+---
+
 ## Resources

 - **Pattern Library:** [CSS_PATTERNS.md](./CSS_PATTERNS.md)
 - **Component Guidelines:** [COMPONENT_STYLING.md](./COMPONENT_STYLING.md)
 - **Styling Guidelines:** [STYLING_GUIDELINES.md](./STYLING_GUIDELINES.md)
+- **Mobile Patterns:** [MOBILE_PATTERNS.md](./MOBILE_PATTERNS.md)
+- **MD3 Official Docs:** [Material Design 3](https://m3.material.io/)

 ---

-**Last Updated:** 2025-11-19
-**Version:** 2.0.0
+**Last Updated:** 2026-01-12
+**Version:** 2.1.0
 **Maintained By:** Frontend Team