roi-theme/_planificacion/01-design-system/02-FILOSOFIA-DE-DISENO.md

# 🎯 FILOSOFÍA DE DISEÑO

## Principios Clave

### 1. Consistencia Visual
Todos los componentes deben verse parte del mismo sistema.

**Implementación:**
- Paleta de colores unificada (Navy + Orange)
- Tipografía consistente (Poppins)
- Iconos del mismo sistema (Bootstrap Icons)
- Espaciado coherente entre componentes

### 2. Espaciado Compacto
Diseño eficiente que maximiza el espacio sin sacrificar usabilidad.

**Implementación:**
- Uso de `.form-control-sm` y `.btn-sm`
- Padding ajustado en cards (`.p-3`)
- Margins reducidos entre campos (`.mb-2`)
- Grid compacto con `.g-3`

### 3. Jerarquía Clara
Uso de colores, tamaños y pesos para guiar la atención.

**Jerarquía visual:**
1. Header del Tab (Navy gradient + Orange icon)
2. Títulos de Card (Navy + Bold)
3. Labels de Campos (Neutral + Semibold + Orange icon)
4. Texto de ayuda (Muted + Small)

### 4. Feedback Instantáneo
Vista previa en tiempo real de todos los cambios.

**Implementación:**
- Event listeners en todos los campos
- Función `updatePreview()` conectada
- Preview con HTML idéntico al front-end
- Sin delay en la actualización

### 5. Mobile-First
Diseño responsive que funciona en todos los dispositivos.

**Implementación:**
- Grid con breakpoint `col-lg-6`
- Stack vertical en mobile (<992px)
- Headers responsive con `flex-wrap`
- Botones full-width en mobile

---

## Características Comunes

Todos los componentes admin DEBEN incluir:

- ✅ **Vista previa en tiempo real**
  - Card con border-left orange
  - HTML idéntico al front-end
  - Botones Desktop/Mobile

- ✅ **Validación de formularios**
  - Campos requeridos marcados con `*`
  - Validación en JavaScript
  - Mensajes de error claros

- ✅ **Contador de caracteres en campos de texto**
  - Display: `<span id="fieldCount">0</span>/250`
  - Progress bar orange
  - Actualización en tiempo real

- ✅ **Botón de reseteo a valores por defecto**
  - En el header del tab
  - Confirmación con `confirm()`
  - Restaura todos los campos

- ✅ **Tooltips informativos**
  - Links a documentación externa
  - Hints con `<small class="text-muted">`
  - Badges para información adicional

- ✅ **Iconos descriptivos en cada campo**
  - Color orange (#FF8600)
  - Bootstrap Icons
  - Clase `.me-2` para espaciado

- ✅ **Feedback visual inmediato**
  - Cambios reflejados sin delay
  - Console.logs informativos
  - Notificaciones de guardado

---

## Flujo de Interacción

### 1. Carga Inicial
```
Usuario abre admin panel
    ↓
loadConfig() carga valores guardados
    ↓
updatePreview() renderiza preview
    ↓
Panel listo para edición
```

### 2. Edición de Campo
```
Usuario modifica campo
    ↓
Event listener detecta cambio
    ↓
updatePreview() actualiza preview
    ↓
saveConfig() guarda en localStorage (opcional)
```

### 3. Guardado Final
```
Usuario confirma cambios (si hay botón guardar)
    ↓
validateForm() verifica datos
    ↓
saveConfig() guarda en config.json
    ↓
showNotification() confirma guardado
```

### 4. Reset
```
Usuario presiona "Restaurar valores por defecto"
    ↓
confirm() pide confirmación
    ↓
resetToDefaults() aplica valores default
    ↓
updatePreview() actualiza preview
    ↓
saveConfig() guarda cambios
```

---

## Principios de Accesibilidad

### Labels y Formularios
- Todos los inputs tienen `<label for="id">`
- Labels descriptivos y claros
- Campos requeridos marcados visualmente

### Navegación por Teclado
- Tab order lógico
- Focus visible en elementos interactivos
- Enter para submit (si aplica)

### Contraste de Color
- Texto principal: #495057 sobre fondo blanco (AAA)
- Texto en headers: Blanco sobre navy (#0E2337) (AAA)
- Links: Orange (#FF8600) con hover (#FF6B35)

### ARIA Attributes
- Progress bars con `role="progressbar"`, `aria-valuenow`, etc.
- Button groups con `role="group"`
- Inputs con `aria-label` o `<label>`

---

## Mensajes y Comunicación

### Console.logs
```javascript
// ✅ USAR para debugging
console.log('✅ [ComponentName] Admin Panel cargado');
console.log('💾 Configuración guardada:', config);
console.log('📂 Configuración cargada:', config);
console.log('🔄 Valores por defecto restaurados');

// ❌ NO USAR en producción excesivamente
console.log('Campo actualizado'); // Demasiado verboso
```

### Notificaciones al Usuario
```javascript
// Success
showNotification('Cambios guardados', 'success');

// Error
showNotification('Error al guardar cambios', 'error');

// Confirmaciones
if (!confirm('¿Estás seguro de restaurar los valores por defecto?')) {
    return;
}
```

---

## Volver al Índice

[← Volver al README](README.md)