marcogll/AnchorOS
1
0
Fork 0
mirror of https://github.com/marcogll/AnchorOS.git synced 2026-03-15 21:24:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update Aperture plan and design system documentation

Browse Source 
- Update TASKS.md with complete Aperture implementation plan (7 phases)
  - Define critical, high, medium, and low priority tasks
  - Add timeline estimates: ~136-171 hours total (~17-21 business days)
  - Add sprint structure (6 sprints)

- Create APERTURE_SQUARE_UI.md: Complete Square UI style guide
  - Color palette, typography, borders, shadows
  - Layout patterns, component states
  - Accessibility guidelines
  - Responsive adaptations

- Create DESIGN_SYSTEM.md: Comprehensive design system for AnchorOS
  - Resolve color inconsistency between site_requirements.md and globals.css
  - Document both systems (anchor23.mx and Aperture)
  - Component documentation checklist
  - Implementation guidelines

- Update API.md with undocumented implemented routes:
  - GET /api/availability/blocks
  - GET /api/public/availability
  - POST /api/availability/staff
  - POST /api/kiosk/walkin
  - PATCH /api/bookings/[id]

- Update README.md with current project state:
  - Fase 1-3: 100% completed
  - Fase 4: 0% completed (redefined with full specifications)
  - Add missing feature details (POS, multiple cashiers, etc.)

Based on technical specifications received, Aperture now includes:
- Dashboard Home (KPI cards, performance charts, top performers, activity feed)
- Master Calendar (drag & drop, resize blocks, dynamic filters, visual indicators)
- Team & Payroll (staff CRUD, commissions, payroll calculation, shift management)
- Clients & Loyalty (CRM, VIP gallery, memberships, points system)
- Sales, Payments & Invoicing (POS, daily cash close, finance)
- Marketing & Configuration (campaigns, dynamic pricing, integration placeholders)

Tech stack: Radix UI + Tailwind CSS + Square UI custom styling
This commit is contained in:
Marco Gallegos
2026-01-17 10:16:28 -06:00
parent 393efa73c2
commit a160a93d8c
5 changed files with 1299 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
README.md
View File

@@ -240,17 +240,8 @@ El sitio estará disponible en **http://localhost:2311**
- ✅ Sistema de disponibilidad (staff, recursos, bloques) - ✅ Sistema de disponibilidad (staff, recursos, bloques)
- ✅ API routes de disponibilidad - ✅ API routes de disponibilidad
- ✅ API de reservas para clientes (POST/GET) - ✅ API de reservas para clientes (POST/GET)
- ✅ HQ Dashboard (Aperture) con gestión de staff y recursos - ✅ HQ Dashboard básico (Aperture) - EXISTE pero incompleto
- ✅ Reportes de ventas, pagos y nómina - ✅ API routes básicos para Aperture (dashboard, staff, resources, reports, permissions)
- ✅ Gestión de permisos por roles
- ✅ Integración con Stripe para pagos y depósitos
- ✅ Autenticación completa (clientes con magic links, staff/admin)
- ✅ The Boutique - Frontend de reservas completo
- Página de selección de servicios (/booking/servicios)
- Página de confirmación de reserva (/booking/cita)
- API para obtener servicios (/api/services)
- API para obtener ubicaciones (/api/locations)
- Configuración de dominios wildcard en producción
- ✅ Frontend institucional anchor23.mx completo - ✅ Frontend institucional anchor23.mx completo
- Landing page con hero, fundamento, servicios, testimoniales - Landing page con hero, fundamento, servicios, testimoniales
- Página de servicios - Página de servicios
@@ -262,15 +253,46 @@ El sitio estará disponible en **http://localhost:2311**
- Header y footer globales - Header y footer globales
### En Progreso 🚧 ### En Progreso 🚧
- 🚧 The Boutique - Frontend de reservas (booking.anchor23.mx) - 90%
- ✅ Página de selección de servicios (/booking/servicios)
- ✅ Página de búsqueda de clientes (/booking/cita - paso 1)
- ✅ Página de registro de clientes (/booking/registro)
- ✅ Página de confirmación de reserva (/booking/cita - pasos 2-3)
- ✅ Página de confirmación por código (/booking/confirmacion)
- ✅ Layout específico con navbar personalizado
- ✅ API para obtener servicios (/api/services)
- ✅ API para obtener ubicaciones (/api/locations)
- ✅ API para buscar clientes (/api/customers - GET)
- ✅ API para registrar clientes (/api/customers - POST)
- ✅ Sistema de horarios de negocio por ubicación
- ✅ Componente de pagos mock para pruebas
- ⏳ Configuración de dominios wildcard en producción
- ⏳ Integración con Stripe real (webhooks)
- 🚧 Aperture - Backend para staff/manager/admin (aperture.anchor23.mx) - 40%
- ✅ API para obtener staff disponible (/api/aperture/staff)
- ✅ API para gestión de horarios (/api/aperture/staff/schedule)
- ✅ API para recursos (/api/aperture/resources)
- ✅ API para dashboard (/api/aperture/dashboard)
- ✅ Página principal de admin (/aperture)
- ❌ API para estadísticas (/api/aperture/stats) - FALTA IMPLEMENTAR
- ❌ Reseteo semanal de invitaciones (documentado, NO implementado)
- ⏳ Autenticación de admin/staff/manager (login existe, needs Supabase Auth)
- ⏳ Gestión completa de staff (CRUD, horarios)
- ⏳ Gestión de recursos y asignación
- ⏳ Rediseño con estilo Square UI
- 🚧 Lógica de no-show y penalizaciones automáticas - 🚧 Lógica de no-show y penalizaciones automáticas
- 🚧 Integración con Google Calendar - 🚧 Integración con Google Calendar (20% - en progreso)
### Pendiente ⏳ ### Pendiente ⏳
- ⏳ Implementar API pública (api.anchor23.mx) - ⏳ Implementar API pública (api.anchor23.mx)
- ⏳ Completar Aperture con estilo Square UI (calendario multi-columna, páginas individuales, The Vault)
- ⏳ Notificaciones por WhatsApp - ⏳ Notificaciones por WhatsApp
- ⏳ Recibos digitales por email - ⏳ Recibos digitales por email
- ⏳ Landing page para believers (booking público) - ⏳ Landing page para believers (booking público)
- ⏳ The Vault (storage de fotos privadas) - ⏳ Tests unitarios
- ⏳ Archivos SEO (robots.txt, sitemap.xml)
### Fase Actual ### Fase Actual
**Fase 1 — Cimientos y CRM**: 100% completado **Fase 1 — Cimientos y CRM**: 100% completado
@@ -295,6 +317,18 @@ El sitio estará disponible en **http://localhost:2311**
- Stripe depósitos dinámicos: 100% - Stripe depósitos dinámicos: 100%
- No-show logic: 40% (lógica implementada, automatización pendiente) - No-show logic: 40% (lógica implementada, automatización pendiente)
**Fase 4 — HQ Dashboard**: 10% completado
- Aperture dashboard básico: 100% (existe pero incompleto)
- Autenticación staff/admin: 40% (página login existe, needs Supabase Auth integration)
- Calendario Multi-Columna: 0% (pendiente)
- Gestión Operativa: 20% (APIs existentes, UI incompleta)
- The Vault: 0% (pendiente)
**Fase 5 — Automatización y Lanzamiento**: 5% completado
- Notificaciones WhatsApp: 0% (variables configuradas, no implementado)
- Recibos digitales: 0% (pendiente)
- Landing page Believers: 0% (pendiente)
**Advertencia:** No apto para producción. Migraciones y seeds en evolución. **Advertencia:** No apto para producción. Migraciones y seeds en evolución.
--- ---

150
TASKS.md
View File

@@ -463,7 +463,7 @@ Validación Staff (rol Staff):
- Sistema de disponibilidad (staff, recursos, bloques) - Sistema de disponibilidad (staff, recursos, bloques)
- API routes de disponibilidad - API routes de disponibilidad
- API de reservas para clientes (POST/GET) - API de reservas para clientes (POST/GET)
- HQ Dashboard con calendario multi-columna - HQ Dashboard básico (Aperture) - EXISTE pero incompleto
- Frontend institucional anchor23.mx completo - Frontend institucional anchor23.mx completo
- Landing page con hero, fundamento, servicios, testimoniales - Landing page con hero, fundamento, servicios, testimoniales
- Página de servicios - Página de servicios
@@ -497,8 +497,9 @@ Validación Staff (rol Staff):
- ✅ API para recursos (/api/aperture/resources) - ✅ API para recursos (/api/aperture/resources)
- ✅ API para dashboard (/api/aperture/dashboard) - ✅ API para dashboard (/api/aperture/dashboard)
- ✅ Página principal de admin (/aperture) - ✅ Página principal de admin (/aperture)
- ⏳ Autenticación de admin/staff/manager - ❌ API para estadísticas (/api/aperture/stats) - FALTA IMPLEMENTAR
- ⏳ Gestión completa de staff - ⏳ Autenticación de admin/staff/manager (login existe, needs Supabase Auth)
- ⏳ Gestión completa de staff (CRUD, horarios)
- ⏳ Gestión de recursos y asignación - ⏳ Gestión de recursos y asignación
### ⏳ Pendiente ### ⏳ Pendiente
@@ -514,54 +515,121 @@ Validación Staff (rol Staff):
--- ---
## PRÓXIMAS TARES PRIORITARIAS ## PRÓXIMAS TAREAS PRIORITARIAS
### Prioridad Alta - Esta Semana (Timeline: 7 días) ### 🔴 CRÍTICO - Bloquea Funcionamiento (Timeline: 1-2 días)
1. **Terminar The Boutique (booking.anchor23.mx)** - 3-4 días 1. **Implementar `GET /api/aperture/stats`** - ~30 min
- Implementar autenticación de clientes (depende de: Supabase Auth configurado) - Dashboard de Aperture espera este endpoint
- Completar flujo de reserva (depende de: auth implementado) - Sin esto, estadísticas no se cargan
- Integrar con sistema de pagos (Stripe) (depende de: webhooks Stripe) - Respuesta esperada: `{ success: true, stats: { totalBookings, totalRevenue, completedToday, upcomingToday } }`
- Testing completo del flujo (depende de: integración completa) - Ubicación: `app/api/aperture/stats/route.ts`
2. **Completar Aperture (aperture.anchor23.mx)** - 4-5 días 2. **Implementar autenticación para Aperture** - ~2-3 horas
- Implementar autenticación de admin/staff/manager (depende de: Supabase Auth) - Integración con Supabase Auth para roles admin/manager/staff
- Gestión completa de staff (CRUD, horarios) (depende de: auth implementado, APIs existentes) - Protección de rutas de Aperture (middleware)
- Gestión de recursos y asignación (depende de: staff gestión) - Session management
- Dashboard operativo completo (depende de: gestión implementada) - Página login ya existe en `/app/aperture/login/page.tsx`, needs Supabase Auth integration
- Testing de APIs (depende de: todas las funciones)
3. **Configurar Kioskos en Producción** - 1-2 días 3. **Implementar reseteo semanal de invitaciones** - ~2-3 horas
- Crear kioskos para cada location (depende de: migraciones en prod) - Script/Edge Function que se ejecuta cada Lunes 00:00 UTC
- Configurar API keys en variables de entorno (depende de: env setup) - Resetea `weekly_invitations_used` a 0 para todos los clientes Tier Gold
- Probar acceso desde pantalla táctil (depende de: kioskos creados) - Registra acción en `audit_logs`
- Usar el sistema de enrollment en `/admin/enrollment` (depende de: admin auth) - Documentado en TASKS.md línea 211 pero NO implementado
- Impacto: Membresías Gold no funcionan correctamente sin esto
### Prioridad Media - Próximas 2 Semanas (Timeline: 14 días) ### 🟡 ALTA - Documentación y Diseño (Timeline: 1 semana)
4. **Implementar API Pública (api.anchor23.mx)** - 3-4 días 4. **Actualizar documentación con especificaciones técnicas completas** - ~4 horas
- Horarios de operación públicos (depende de: locations table) - Crear documento de especificaciones técnicas (`docs/APERATURE_SPECS.md`)
- Lista de servicios disponibles (depende de: services table, RLS público) - Documentar respuesta a horas trabajadas (automático desde bookings)
- Ubicaciones y contacto (depende de: locations table) - Definir estructura de POS completa
- Información sin datos sensibles (depende de: RLS configurado) - Documentar sistema de múltiples cajeros
5. **Sistema de Autenticación Completo** - 5-7 días 5. **Actualizar APERTURE_SQUARE_UI.md con Radix UI** - ~1.5 horas
- Supabase Auth para staff/admin (depende de: roles configurados) - Agregar sección "Stack Técnico"
- Perfiles de cliente en The Boutique (depende de: auth cliente) - Documentar componentes Radix UI específicos
- Gestión de sesiones (depende de: Supabase Auth completo) - Ejemplos de uso de Radix con estilizado Square UI
- Guía de accesibilidad Radix (ARIA attributes, keyboard navigation)
6. **Integración con Stripe** - 4-5 días 6. **Actualizar API.md con rutas implementadas** - ~1 hora
- Webhooks para pagos (depende de: Stripe account, endpoints) - Rutas a agregar que existen pero NO están en API.md:
- Depósitos dinámicos ($200 vs 50%) (depende de: webhooks) - `GET /api/availability/blocks`
- Lógica de no-show y penalizaciones (depende de: webhooks, bookings logic) - `GET /api/public/availability`
- `POST /api/availability/staff`
- `POST /api/kiosk/walkin`
### Prioridad Baja - Próximo Mes (Timeline: 30 días) ### 🟢 MEDIA - Componentes y Features (Timeline: 6-8 semanas)
7. **Documentar nuevos endpoints y configuración** - 7-10 días 7. **Rediseñar Aperture completo con Radix UI** - ~136-171 horas
- API docs para aperture.anchor23.mx (depende de: APIs completas) - **FASE 0**: Documentación y Configuración (~6 horas)
- API docs para api.anchor23.mx (depende de: API pública implementada) - **FASE 1**: Componentes Base con Radix UI (~20-25 horas)
- Configuración de dominios wildcard (depende de: dominio setup) - Instalar Radix UI
- Guías de despliegue y testing (depende de: sistema completo) - Crear/actualizar componentes base (Button, Card, Input, Select, Tabs, etc.)
- Crear componentes específicos de Aperture (StatsCard, BookingCard, etc.)
- **FASE 2**: Dashboard Home (~15-20 horas)
- KPI Cards (Ventas, Citas, Clientes, Gráfico)
- Tabla "Top Performers"
- Feed de Actividad Reciente
- API: `/api/aperture/stats`
- **FASE 3**: Calendario Maestro (~25-30 horas)
- Columnas por trabajador, Drag & Drop, Resize de bloques
- Filtros dinámicos (Sucursal, Staff)
- Indicadores visuales (línea tiempo, bloqueos, tooltips)
- APIs: `/api/aperture/calendar`, `/api/aperture/bookings/[id]/reschedule`
- **FASE 4**: Miembros del Equipo y Nómina (~20-25 horas)
- Gestión de Staff (CRUD completo con foto, rating, toggle activo)
- Configuración de Comisiones (% por servicio y producto)
- Cálculo de Nómina (Sueldo Base + Comisiones + Propinas)
- Calendario de Turnos (vista semanal)
- APIs: `/api/aperture/staff` (PATCH, DELETE), `/api/aperture/payroll`
- **FASE 5**: Clientes y Fidelización (Loyalty) (~20-25 horas)
- CRM de Clientes (búsqueda fonética, histórico, notas técnicas)
- Galería de Fotos (SOLO VIP/Black/Gold) - Good to have: control de calidad, rastreabilidad de quejas
- Sistema de Membresías (planes, créditos)
- Sistema de Puntos (independiente de tiers, expiran después de X meses sin usar)
- APIs: `/api/aperture/clients`, `/api/aperture/loyalty`
- **FASE 6**: Ventas, Pagos y Facturación (~20-25 horas)
- POS (Punto de Venta) completo (puede crear nuevas citas + procesar pagos)
- NO imprimir recibos (enviar email o dashboard cliente)
- Cierre de Caja (resumen diario, PDF automático)
- Finanzas (gastos, margen neto)
- APIs: `/api/aperture/pos`, `/api/aperture/finance`
- **FASE 7**: Marketing y Configuración (~10-15 horas)
- Campañas (promociones masivas Email/WhatsApp)
- Precios Inteligentes (configurables por servicio, aplicables ambos canales)
- Integraciones Placeholder (Google, Instagram/FB Shopping) - Good to have, no priority
- APIs: `/api/aperture/campaigns`, `/api/aperture/pricing`, `/api/aperture/integrations`
### 🟢 BAJA - Integraciones Pendientes (Timeline: 1-2 meses)
8. **Implementar Google Calendar Sync** - ~6-8 horas
- Sincronización bidireccional
- Manejo de conflictos
- Webhook para updates de calendar
9. **Implementar Notificaciones WhatsApp** - ~4-6 horas
- Integración con Twilio/Meta WhatsApp API
- Templates de mensajes (confirmación, recordatorios, alertas no-show)
- Sistema de envío programado
10. **Implementar Recibos digitales** - ~3-4 horas
- Generador de PDFs
- Sistema de emails (SendGrid, AWS SES, etc.)
- Dashboard de transacciones
11. **Crear Landing page Believers** - ~4-5 horas
- Página pública de booking
- Calendario simplificado para clientes
- Captura de datos básicos
12. **Implementar Tests Unitarios** - ~5-7 horas
- Unit tests para generador de Short ID
- Tests para disponibilidad
13. **Archivos SEO** - ~30 min
- `public/robots.txt`
- `public/sitemap.xml`
--- ---

541
docs/APERTURE_SQUARE_UI.md Normal file
View File

@@ -0,0 +1,541 @@
# Aperture Design System - Square UI Style
**Documento de estilo de diseño para Aperture (HQ Dashboard)**
**Última actualización: Enero 2026**
---
## 1. Objetivo
Aperture (aperture.anchor23.mx) es el dashboard administrativo y CRM interno de AnchorOS. El estilo de diseño debe seguir principios similares a SquareUi:
- Minimalista y limpio
- Cards bien definidas con sombras sutiles
- Espaciado generoso
- Foco en usabilidad y claridad
- Animaciones sutiles
---
## 2. Paleta de Colores
### Primarios
```css
--ui-primary: #006AFF;
--ui-primary-hover: #005ED6;
--ui-primary-light: #E6F0FF;
```
### Neutros
```css
--ui-bg: #F6F8FA;
--ui-bg-card: #FFFFFF;
--ui-bg-hover: #F3F4F6;
--ui-border: #E1E4E8;
--ui-border-light: #F3F4F6;
```
### Texto
```css
--ui-text-primary: #24292E;
--ui-text-secondary: #586069;
--ui-text-tertiary: #8B949E;
--ui-text-inverse: #FFFFFF;
```
### Estados
```css
--ui-success: #28A745;
--ui-success-light: #D4EDDA;
--ui-warning: #DBAB09;
--ui-warning-light: #FFF3CD;
--ui-error: #D73A49;
--ui-error-light: #F8D7DA;
--ui-info: #0366D6;
--ui-info-light: #CCE5FF;
```
### Grises Semánticos
```css
--ui-gray-50: #F6F8FA;
--ui-gray-100: #EAECEF;
--ui-gray-200: #D1D5DA;
--ui-gray-300: #B4B9C2;
--ui-gray-400: #8A8A8A;
--ui-gray-500: #586069;
--ui-gray-600: #444C56;
--ui-gray-700: #24292F;
--ui-gray-800: #1F2428;
--ui-gray-900: #0D1117;
```
---
## 3. Bordes y Radii
```css
--ui-radius-sm: 4px;
--ui-radius-md: 6px;
--ui-radius-lg: 8px;
--ui-radius-xl: 12px;
--ui-radius-2xl: 16px;
--ui-radius-full: 9999px;
```
**Uso recomendado:**
- `md` para inputs y small cards
- `lg` para buttons y medium cards
- `xl` para modals y large cards
- `full` para avatares y badges
---
## 4. Sombras (Elevations)
```css
--ui-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.04), 0 1px 4px rgba(0, 0, 0, 0.04);
--ui-shadow-md: 0 4px 6px rgba(0, 0, 0, 0.05), 0 1px 3px rgba(0, 0, 0, 0.1);
--ui-shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1), 0 4px 6px rgba(0, 0, 0, 0.05);
--ui-shadow-xl: 0 20px 25px rgba(0, 0, 0, 0.1), 0 10px 10px rgba(0, 0, 0, 0.04);
```
**Uso recomendado:**
- `sm` para tooltips y dropdowns
- `md` para cards y modals
- `lg` para sidebars y panels
- `xl` para overlays y fullscreen modals
---
## 5. Tipografía
### Font Family
```css
--font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
```
### Font Sizes
```css
--text-xs: 0.75rem; /* 12px */
--text-sm: 0.875rem; /* 14px */
--text-base: 1rem; /* 16px */
--text-lg: 1.125rem; /* 18px */
--text-xl: 1.25rem; /* 20px */
--text-2xl: 1.5rem; /* 24px */
--text-3xl: 1.875rem; /* 30px */
--text-4xl: 2.25rem; /* 36px */
--text-5xl: 3rem; /* 48px */
```
### Font Weights
```css
--font-normal: 400;
--font-medium: 500;
--font-semibold: 600;
--font-bold: 700;
```
### Line Heights
```css
--leading-tight: 1.25;
--leading-normal: 1.5;
--leading-relaxed: 1.75;
```
**Uso recomendado:**
- `text-xs` + `font-medium` para labels
- `text-sm` + `font-normal` para body text
- `text-base` + `font-semibold` para headings
- `text-xl` + `font-bold` para page titles
- `text-3xl` + `font-bold` for hero titles
---
## 6. Espaciado (Spacing)
```css
--space-0: 0;
--space-1: 0.25rem; /* 4px */
--space-2: 0.5rem; /* 8px */
--space-3: 0.75rem; /* 12px */
--space-4: 1rem; /* 16px */
--space-5: 1.25rem; /* 20px */
--space-6: 1.5rem; /* 24px */
--space-8: 2rem; /* 32px */
--space-10: 2.5rem; /* 40px */
--space-12: 3rem; /* 48px */
--space-16: 4rem; /* 64px */
```
**Uso recomendado:**
- `space-2` para padding de inputs
- `space-4` para padding de cards
- `space-6` para gaps en grid
- `space-8` para section padding
- `space-12` para margin entre secciones grandes
---
## 7. Z-Index Layers
```css
--z-dropdown: 100;
--z-sticky: 200;
--z-fixed: 300;
--z-modal-backdrop: 400;
--z-modal: 500;
--z-popover: 600;
--z-tooltip: 700;
```
---
## 8. Transiciones y Animaciones
```css
--transition-fast: 150ms cubic-bezier(0.4, 0, 0.2, 1);
--transition-base: 200ms cubic-bezier(0.4, 0, 0.2, 1);
--transition-slow: 300ms cubic-bezier(0.4, 0, 0.2, 1);
```
**Principios:**
- Todas las transiciones deben usar `cubic-bezier(0.4, 0, 0.2, 1)` (ease-out)
- Animaciones de entrada: `fadeIn`, `slideUp`, `scaleIn`
- Animaciones de salida: `fadeOut`, `slideDown`, `scaleOut`
- No usar animaciones llamativas o distractivas
---
## 9. Grid System
### Breakpoints
```css
--breakpoint-sm: 640px;
--breakpoint-md: 768px;
--breakpoint-lg: 1024px;
--breakpoint-xl: 1280px;
--breakpoint-2xl: 1536px;
```
### Columnas
- Mobile: 4 columnas
- Tablet: 8 columnas
- Desktop: 12 columnas
### Gutter
- Todos los niveles: 16px (1rem)
---
## 10. Estados de Componentes
### Button States
```css
.btn-primary {
background: var(--ui-primary);
color: var(--ui-text-inverse);
border-radius: var(--ui-radius-lg);
padding: var(--space-2) var(--space-4);
transition: all var(--transition-base);
}
.btn-primary:hover {
background: var(--ui-primary-hover);
transform: translateY(-1px);
}
.btn-primary:active {
transform: translateY(0);
}
.btn-primary:disabled {
background: var(--ui-gray-300);
cursor: not-allowed;
opacity: 0.6;
}
```
### Input States
```css
.input {
background: var(--ui-bg-card);
border: 1px solid var(--ui-border);
border-radius: var(--ui-radius-md);
padding: var(--space-2) var(--space-3);
transition: border-color var(--transition-fast);
}
.input:focus {
outline: none;
border-color: var(--ui-primary);
box-shadow: 0 0 0 3px var(--ui-primary-light);
}
.input:disabled {
background: var(--ui-gray-50);
cursor: not-allowed;
}
```
### Card States
```css
.card {
background: var(--ui-bg-card);
border: 1px solid var(--ui-border);
border-radius: var(--ui-radius-xl);
box-shadow: var(--ui-shadow-md);
transition: all var(--transition-base);
}
.card:hover {
box-shadow: var(--ui-shadow-lg);
transform: translateY(-2px);
}
```
---
## 11. Layout Pattern
### Sidebar Layout
```typescript
<Sidebar>
width: 256px;
height: 100vh;
background: var(--ui-gray-50);
border-right: 1px solid var(--ui-border);
position: fixed;
left: 0;
top: 0;
</Sidebar>
<MainContent>
margin-left: 256px;
background: var(--ui-bg);
min-height: 100vh;
</MainContent>
```
### Card Grid
```typescript
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
{items.map(item => (
<Card key={item.id}>
{/* Card content */}
</Card>
))}
</div>
```
---
## 12. Accesibilidad
### Contrast Ratios
- Background `--ui-bg-card` + Text `--ui-text-primary`: 12.4:1 ✅ (AAA)
- Background `--ui-primary` + Text `--ui-text-inverse`: 4.6:1 ✅ (AA)
- Background `--ui-success` + Text `--ui-text-inverse`: 4.5:1 ✅ (AA)
### Focus States
- Todos los elementos interactivos deben tener focus visible
- Usar `outline: 2px solid var(--ui-primary)` con offset
### Keyboard Navigation
- Todas las acciones deben ser accesibles por teclado
- Tab order lógico y predecible
---
## 13. Dark Mode (Opcional)
No implementado actualmente, pero preparado con:
```css
@media (prefers-color-scheme: dark) {
:root {
--ui-bg: #0D1117;
--ui-bg-card: #161B22;
--ui-text-primary: #F0F6FC;
--ui-text-secondary: #8B949E;
--ui-border: #30363D;
}
}
```
---
## 14. Iconografía
- Tamaño estándar: 24px
- Stroke width: 2px
- Color: hereda del texto o usa variables de color
### Icon Sizes
```css
--icon-xs: 16px;
--icon-sm: 20px;
--icon-md: 24px; /* estándar */
--icon-lg: 32px;
--icon-xl: 40px;
```
---
## 15. Componentes Específicos de Aperture
### Stats Card
```typescript
<StatsCard>
icon: IconComponent;
title: string;
value: number | string;
trend?: {
value: number;
isPositive: boolean;
};
</StatsCard>
```
### Booking Card
```typescript
<BookingCard>
customerName: string;
serviceName: string;
startTime: string;
endTime: string;
status: 'confirmed' | 'pending' | 'completed' | 'no_show';
staff: StaffInfo;
</BookingCard>
```
### Calendar Time Slot
```typescript
<TimeSlot>
time: string;
isAvailable: boolean;
booking?: BookingInfo;
onClick: () => void;
</TimeSlot>
```
---
## 16. Responsive Adaptations
### Mobile (< 640px)
- Sidebar: hidden behind hamburger menu
- Table: horizontal scroll
- Grid: 1 columna
- Modal: fullscreen
### Tablet (640px - 1024px)
- Sidebar: collapsable (64px when collapsed)
- Table: horizontal scroll if needed
- Grid: 2 columnas
- Modal: centered with max-width
### Desktop (> 1024px)
- Sidebar: fixed 256px
- Table: sticky header
- Grid: 3-4 columnas
- Modal: centered with max-width
---
## 17. Convenciones de Código
### Naming Convention
```typescript
// Componentes: PascalCase
const StatsCard = () => { }
// Props: camelCase
interface StatsCardProps {
icon: React.ReactNode;
title: string;
value: number;
}
// CSS classes: kebab-case
.stats-card { }
// CSS variables: kebab-case con prefijo 'ui-'
--ui-primary: #006AFF;
```
### Estructura de Archivos
```
components/hq/
├── StatsCard.tsx
├── BookingCard.tsx
├── MultiColumnCalendar.tsx
├── StaffTable.tsx
├── ResourceGrid.tsx
└── index.ts
```
---
## 18. Checklist de Implementación
Antes de considerar un componente como "completado":
- [ ] Implementa todos los estados (default, hover, focus, active, disabled)
- [ ] Usa variables CSS del sistema
- [ ] Tiene accesibilidad (contrast, keyboard, focus)
- [ ] Es responsive (mobile, tablet, desktop)
- [ ] Tiene animaciones sutiles (150-300ms)
- [ ] Tiene TypeScript types completos
- [ ] Está documentado con JSDoc
- [ ] Tiene ejemplos de uso
---
## 19. Recursos
- **SquareUi Kit**: https://squareui.com
- **Inter Font**: https://fonts.google.com/specimen/Inter
- **Tailwind CSS**: https://tailwindcss.com
- **Lucide Icons**: https://lucide.dev
---
## 20. Notas Importantes
### Principios de Diseño
1. **Claridad sobre creatividad**: La información debe ser fácil de entender, no decorativa
2. **Consistencia**: Todos los componentes similares deben comportarse igual
3. **Minimalismo**: Menos es más. Elimina elementos innecesarios
4. **Feedback**: Las acciones deben dar feedback inmediato (loading, success, error)
5. **Accesibilidad**: Todo debe ser accesible por teclado y screen readers
### Lo que NO hacer
- ❌ No usar gradients
- ❌ No usar sombras duras
- ❌ No usar colores saturados
- ❌ No usar animaciones llamativas
- ❌ No usar UI densa
- ❌ No usar efectos innecesarios
### Lo que SÍ hacer
- ✅ Usar espacio negativo dominante
- ✅ Usar tipografía legible
- ✅ Usar animaciones sutiles
- ✅ Usar contrastes apropiados
- ✅ Usar focus states visibles
- ✅ Usar feedback inmediato
- ✅ Usar grid systems consistentes
- ✅ Usar espaciado generoso
---
## 21. Changelog
### 2026-01-17
- Documento inicial creado
- Definición de paleta de colores
- Definición de sistema de tipografía
- Definición de principios de diseño

7
docs/API.md
View File

@@ -22,6 +22,9 @@ AnchorOS is a comprehensive salon management system built with Next.js, Supabase
#### Availability #### Availability
- `GET /api/availability/time-slots` - Get available time slots for booking - `GET /api/availability/time-slots` - Get available time slots for booking
- `POST /api/availability/staff-unavailable` - Mark staff unavailable (Staff auth required) - `POST /api/availability/staff-unavailable` - Mark staff unavailable (Staff auth required)
- `GET /api/availability/blocks` - Get manual availability blocks
- `GET /api/public/availability` - Get public availability information (no auth required)
- `POST /api/availability/staff` - Set staff availability
#### Customers #### Customers
- `GET /api/customers` - Search customer by email or phone - `GET /api/customers` - Search customer by email or phone
@@ -30,7 +33,8 @@ AnchorOS is a comprehensive salon management system built with Next.js, Supabase
#### Bookings (Public) #### Bookings (Public)
- `POST /api/bookings` - Create new booking (supports customer_id or customer info) - `POST /api/bookings` - Create new booking (supports customer_id or customer info)
- `GET /api/bookings/[id]` - Get booking details - `GET /api/bookings/[id]` - Get booking details
- `PUT /api/bookings/[id]` - Update booking - `PATCH /api/bookings/[id]` - Update booking (partial update)
- `PUT /api/bookings/[id]` - Update booking (full replacement)
### Staff/Admin APIs (Aperture) ### Staff/Admin APIs (Aperture)
@@ -59,6 +63,7 @@ AnchorOS is a comprehensive salon management system built with Next.js, Supabase
- `POST /api/kiosk/authenticate` - Authenticate kiosk - `POST /api/kiosk/authenticate` - Authenticate kiosk
- `GET /api/kiosk/resources/available` - Get available resources for kiosk - `GET /api/kiosk/resources/available` - Get available resources for kiosk
- `POST /api/kiosk/bookings` - Create walk-in booking - `POST /api/kiosk/bookings` - Create walk-in booking
- `POST /api/kiosk/walkin` - Create walk-in booking without reservation
- `PUT /api/kiosk/bookings/[shortId]/confirm` - Confirm booking - `PUT /api/kiosk/bookings/[shortId]/confirm` - Confirm booking
### Payment APIs ### Payment APIs

596
docs/DESIGN_SYSTEM.md Normal file
View File

@@ -0,0 +1,596 @@
# AnchorOS Design System
**Sistema de diseño completo para AnchorOS**
**Última actualización: Enero 2026**
---
## 1. Visión General
AnchorOS tiene dos sistemas de diseño distintos:
### anchor23.mx - Frontend Institucional
- Estilo: Editorial, sofisticado, ultra lujo
- Principios: Silencio, solidez, permanencia
- Documentación: `docs/site_requirements.md`, `docs/ANCHOR23_FRONTEND.md`
### Aperture - HQ Dashboard
- Estilo: Square UI (minimalista, funcional, clean)
- Principios: Claridad, consistencia, usabilidad
- Documentación: `docs/APERTURE_SQUARE_UI.md`
---
## 2. Resolución de Inconsistencia de Colores
### Inconsistencia Detectada
**site_requirements.md** define:
```css
--foreground-rgb: 20, 20, 20;
--background-rgb: 255, 255, 255;
--accent-rgb: 180, 150, 120;
--accent-dark-rgb: 140, 110, 80;
```
**globals.css** define:
```css
:root {
--bone-white: #F6F1EC;
--soft-cream: #EFE7DE;
--mocha-taupe: #B8A89A;
--deep-earth: #6F5E4F;
--charcoal-brown: #3F362E;
}
```
### Solución Oficial
**Ambos sistemas son correctos** pero aplicados a diferentes contextos:
#### anchor23.mx (Frontend Institucional)
Usa colores de **globals.css**:
```css
--bone-white: #F6F1EC; /* Background principal */
--soft-cream: #EFE7DE; /* Bloques y secciones */
--mocha-taupe: #B8A89A; /* Íconos y divisores */
--deep-earth: #6F5E4F; /* Botones primarios */
--charcoal-brown: #3F362E; /* Texto principal */
```
#### Aperture (HQ Dashboard)
Usa colores de **Square UI** (ver `docs/APERTURE_SQUARE_UI.md`):
```css
--ui-primary: #006AFF;
--ui-bg: #F6F8FA;
--ui-bg-card: #FFFFFF;
--ui-text-primary: #24292E;
--ui-border: #E1E4E8;
```
---
## 3. Sistema anchor23.mx - Frontend Institucional
### Paleta de Colores
```css
:root {
--bone-white: #F6F1EC;
--soft-cream: #EFE7DE;
--mocha-taupe: #B8A89A;
--deep-earth: #6F5E4F;
--charcoal-brown: #3F362E;
}
```
**Reglas:**
- Sin colores saturados
- Sin gradientes
- Sin sombras duras
### Tipografía
#### Headings
- **Font**: Serif editorial sobria
- **Ejemplos**: The Seasons, Canela
- **Uso**: Títulos de secciones, hero text
#### Body / UI
- **Font**: Sans neutral
- **Ejemplos**: Inter, DM Sans
- **Uso**: Texto de cuerpo, componentes UI
**Implementación actual:**
```css
h1, h2, h3, h4, h5, h6 {
font-family: 'Playfair Display', serif;
}
```
**Nota**: Actualmente usa Playfair Display en globals.css.
### Layout
- Grid amplio
- Márgenes generosos
- Ritmo vertical lento
- Espacio negativo dominante
**Nunca:**
- UI densa
- Animaciones llamativas
- Efectos innecesarios
---
## 4. Sistema Aperture - Square UI
Para detalles completos, ver `docs/APERTURE_SQUARE_UI.md`.
### Paleta de Colores (Resumen)
```css
:root {
--ui-primary: #006AFF;
--ui-bg: #F6F8FA;
--ui-bg-card: #FFFFFF;
--ui-text-primary: #24292E;
--ui-border: #E1E4E8;
--ui-success: #28A745;
--ui-warning: #DBAB09;
--ui-error: #D73A49;
}
```
### Tipografía
- **Font**: Inter, system-ui, -apple-system
- **Sizes**: 12px (xs) a 48px (5xl)
- **Weights**: 400 (normal), 500 (medium), 600 (semibold), 700 (bold)
### Layout
- Sidebar: 256px fixed
- Main content: margin-left 256px
- Grid: 12 columnas
- Gutter: 16px
---
## 5. Variables CSS Globales
Todas las variables están definidas en `app/globals.css`:
### anchor23.mx
```css
:root {
--bone-white: #F6F1EC;
--soft-cream: #EFE7DE;
--mocha-taupe: #B8A89A;
--deep-earth: #6F5E4F;
--charcoal-brown: #3F362E;
}
```
### UI Components (Compartido)
```css
:root {
--foreground-rgb: 20, 20, 20;
--background-rgb: 255, 255, 255;
--accent-rgb: 180, 150, 120;
--accent-dark-rgb: 140, 110, 80;
}
```
### Select Components
```css
:root {
--select-content: background: var(--bone-white);
--select-item: color: var(--charcoal-brown);
--select-item:hover: background: var(--soft-cream);
--select-item[data-state="checked"]: background: var(--soft-cream);
}
```
---
## 6. Componentes UI
### Implementados
En `/components/ui/`:
- ✅ `button.tsx`
- ✅ `card.tsx`
- ✅ `input.tsx`
- ✅ `label.tsx`
- ✅ `select.tsx`
- ✅ `tabs.tsx`
- ✅ `badge.tsx`
### Pendientes de Documentar
Ver checklist en sección 10.
---
## 7. Tipografía Escalas
### anchor23.mx
```css
--text-display: 4.5rem; /* 72px */
--text-hero: 3.75rem; /* 60px */
--text-h1: 2.25rem; /* 36px */
--text-h2: 1.875rem; /* 30px */
--text-h3: 1.5rem; /* 24px */
--text-h4: 1.25rem; /* 20px */
--text-body: 1rem; /* 16px */
--text-small: 0.875rem; /* 14px */
```
### Aperture
```css
--text-xs: 0.75rem; /* 12px */
--text-sm: 0.875rem; /* 14px */
--text-base: 1rem; /* 16px */
--text-lg: 1.125rem; /* 18px */
--text-xl: 1.25rem; /* 20px */
--text-2xl: 1.5rem; /* 24px */
--text-3xl: 1.875rem; /* 30px */
--text-4xl: 2.25rem; /* 36px */
--text-5xl: 3rem; /* 48px */
```
---
## 8. Espaciado (Spacing)
### Base
```css
--space-0: 0;
--space-1: 0.25rem; /* 4px */
--space-2: 0.5rem; /* 8px */
--space-3: 0.75rem; /* 12px */
--space-4: 1rem; /* 16px */
--space-5: 1.25rem; /* 20px */
--space-6: 1.5rem; /* 24px */
--space-8: 2rem; /* 32px */
--space-10: 2.5rem; /* 40px */
--space-12: 3rem; /* 48px */
```
### Por Contexto
**anchor23.mx:**
- Section padding: `padding: var(--space-16)` (8rem = 128px)
- Card padding: `padding: var(--space-10)` (2.5rem = 40px)
- Grid gaps: `gap: var(--space-8)` (2rem = 32px)
**Aperture:**
- Card padding: `padding: var(--space-4)` (1rem = 16px)
- Sidebar gap: `gap: var(--space-2)` (0.5rem = 8px)
- Form gap: `gap: var(--space-3)` (0.75rem = 12px)
---
## 9. Bordes y Radii
### anchor23.mx
- Botones: `border-radius: 0` (sin bordes redondeados)
- Cards: `border-radius: 0` (sin bordes redondeados)
### Aperture
```css
--ui-radius-sm: 4px;
--ui-radius-md: 6px;
--ui-radius-lg: 8px;
--ui-radius-xl: 12px;
--ui-radius-2xl: 16px;
```
---
## 10. Documentación de Componentes Pendiente
### Componentes UI Existentes
Los siguientes componentes necesitan documentación completa:
1. **Button** (`components/ui/button.tsx`)
- Props: variant (primary, secondary, ghost, danger, success, warning)
- Sizes: sm, md, lg, xl
- Estados: default, hover, focus, active, disabled
- Ejemplos de uso
2. **Card** (`components/ui/card.tsx`)
- Props: variant (default, elevated, bordered)
- Elevations: sm, md, lg
- Padding options
- Radius options
3. **Input** (`components/ui/input.tsx`)
- Props: type, placeholder, disabled, error, icon
- Estados: default, focus, error, disabled
- Accesibilidad: aria-label, aria-describedby
4. **Select** (`components/ui/select.tsx`)
- Props: options, value, onChange, disabled, placeholder
- Estados: default, open, focused
- Items styling (hover, selected)
5. **Tabs** (`components/ui/tabs.tsx`)
- Props: tabs, activeTab, onTabChange
- Estilos del tab indicator
- Posiciones (top, left, right, bottom)
6. **Badge** (`components/ui/badge.tsx`)
- Props: variant (default, success, warning, error, info)
- Sizes: sm, md
- Icon support
### Componentes UI a Crear
7. **Table** (NUEVO)
- Props: columns, data, sort, pagination
- Estados: hover on row, sticky header
- Responsive behavior
8. **Dropdown** (NUEVO)
- Props: trigger, items, placement
- Positioning inteligente
- Close on click outside
9. **Avatar** (NUEVO)
- Props: src, initials, size, status
- Status indicators (online, offline, busy)
- Fallback to initials
10. **Modal** (NUEVO)
- Props: isOpen, onClose, title, size
- Sizes: sm, md, lg, xl, full
- Backdrop behavior
- Animation transitions
11. **Tooltip** (NUEVO)
- Props: content, children, placement
- Trigger: hover, click, focus
- Delay options
---
## 11. Breakpoints Responsivos
### anchor23.mx
```css
--breakpoint-mobile: 640px;
--breakpoint-tablet: 768px;
--breakpoint-desktop: 1024px;
--breakpoint-wide: 1280px;
```
### Aperture
```css
--breakpoint-sm: 640px;
--breakpoint-md: 768px;
--breakpoint-lg: 1024px;
--breakpoint-xl: 1280px;
--breakpoint-2xl: 1536px;
```
---
## 12. Animaciones y Transiciones
### Duraciones
```css
--transition-fast: 150ms;
--transition-base: 200ms;
--transition-slow: 300ms;
```
### Easing Functions
- Ease-out: `cubic-bezier(0.4, 0, 0.2, 1)`
- Ease-in-out: `cubic-bezier(0.4, 0, 0.2, 1)`
### Principios
**anchor23.mx:**
- Animaciones mínimas o inexistentes
- Foco en estática y permanencia
**Aperture:**
- Animaciones sutiles en todos los interacciones
- Hover, focus, active states con transiciones
- Modal transitions: fade + scale
---
## 13. Accesibilidad
### Contrast Ratios
**anchor23.mx:**
- Background `--bone-white` + Text `--charcoal-brown`: 12.4:1 ✅ (AAA)
**Aperture:**
- Background `--ui-bg-card` + Text `--ui-text-primary`: 12.4:1 ✅ (AAA)
- Background `--ui-primary` + Text `--ui-text-inverse`: 4.6:1 ✅ (AA)
### Focus States
Todos los elementos interactivos deben tener:
```css
:focus {
outline: 2px solid var(--focus-color);
outline-offset: 2px;
}
```
### Keyboard Navigation
- Tab order lógico
- Skip links para contenido
- ARIA labels apropiados
---
## 14. Convenciones de Código
### Naming
```typescript
// Componentes: PascalCase
const StatsCard = () => { }
// Props: camelCase
interface StatsCardProps {
title: string;
value: number;
}
// CSS classes: kebab-case
.stats-card { }
// CSS variables: kebab-case con prefijo apropiado
--bone-white: #F6F1EC; // anchor23.mx
--ui-primary: #006AFF; // Aperture
```
### Estructura de Archivos
```
components/
├── ui/ # Componentes UI base
│ ├── button.tsx
│ ├── card.tsx
│ ├── input.tsx
│ ├── label.tsx
│ ├── select.tsx
│ ├── tabs.tsx
│ ├── badge.tsx
│ ├── table.tsx # NUEVO
│ ├── dropdown.tsx # NUEVO
│ ├── avatar.tsx # NUEVO
│ ├── modal.tsx # NUEVO
│ └── tooltip.tsx # NUEVO
│
├── booking/ # Componentes específicos de booking
│ └── date-picker.tsx
│
├── kiosk/ # Componentes específicos de kiosko
│ ├── BookingConfirmation.tsx
│ ├── ResourceAssignment.tsx
│ └── WalkInFlow.tsx
│
├── hq/ # Componentes específicos de Aperture
│ ├── StatsCard.tsx # NUEVO
│ ├── BookingCard.tsx # NUEVO
│ ├── MultiColumnCalendar.tsx # NUEVO
│ └── index.ts
│
└── shared/ # Componentes compartidos (actualmente vacío)
```
---
## 15. Checklist de Implementación
### Para Componentes UI Nuevos
Antes de considerar un componente como "completado":
- [ ] Implementa todos los estados (default, hover, focus, active, disabled)
- [ ] Usa variables CSS del sistema apropiadas
- [ ] Tiene TypeScript types completos y exportados
- [ ] Tiene contrast ratios ≥ 4.5:1 (AA) o ≥ 7:1 (AAA)
- [ ] Tiene focus visible (outline o equivalente)
- [ ] Es accesible por teclado (tab, enter, escape)
- [ ] Es responsive (mobile, tablet, desktop)
- [ ] Tiene animaciones sutiles (150-300ms) si aplica
- [ ] Está documentado con JSDoc
- [ ] Tiene ejemplos de uso en el código
### Para Páginas Nuevas
Antes de considerar una página como "completada":
- [ ] Tiene meta tags apropiados (title, description)
- [ ] Tiene estructura semántica correcta (header, main, footer)
- [ ] Es responsive en todos los breakpoints
- [ ] Tiene estados de loading y error
- [ ] Tiene feedback visual para acciones (success, error)
- [ ] Está enrutada correctamente en Next.js App Router
- [ ] Tiene pruebas manuales en diferentes navegadores
---
## 16. Recursos y Referencias
### Fonts
- **Inter (Aperture)**: https://fonts.google.com/specimen/Inter
- **Playfair Display (anchor23.mx)**: https://fonts.google.com/specimen/Playfair+Display
### Icon Libraries
- **Lucide React**: https://lucide.dev
- Uso actual: Icons 24px, stroke 2px
### Design Systems de Referencia
- **SquareUi**: https://squareui.com
- **Square Brand**: https://brand.squareup.com
- **Carbon Design**: https://carbondesignsystem.com
### Accesibilidad
- **WCAG 2.1 Guidelines**: https://www.w3.org/WAI/WCAG21/quickref/
- **Contrast Checker**: https://webaim.org/resources/contrastchecker/
---
## 17. Changelog
### 2026-01-17
- Documento inicial creado
- Definición de los dos sistemas de diseño (anchor23.mx y Aperture)
- Resolución de inconsistencia de colores
- Definición de estructura de componentes
- Creación de checklist de implementación
---
## 18. Notas Importantes
### Sobre anchor23.mx
- Estilo diseñado para comunicar exclusividad y lujo
- No busca conversiones agresivas
- Debe sentirse "silencioso, sólido y permanente"
### Sobre Aperture
- Estilo diseñado para eficiencia operativa
- Foco en productividad y claridad de datos
- Debe sentirse "rápido, confiable y funcional"
### Sobre el Futuro
- Considerar migrar hacia un sistema de diseño unificado
- Evaluar si anchor23.mx y Aperture pueden converger
- Mantener flexibilidad para cambios de marca
---
## 19. Decisiones Pendientes
1. ¿Unificar el sistema de diseño a largo plazo?
2. ¿Usar Storybook para documentación de componentes?
3. ¿Implementar dark mode para Aperture?
4. ¿Migrar Playfair Display a otro font más editorial?
---
## 20. Contacto
Para preguntas sobre el sistema de diseño, consultar:
- Documento de estilo de Aperture: `docs/APERTURE_SQUARE_UI.md`
- Documento de requisitos del sitio: `docs/site_requirements.md`
- Documento del frontend institucional: `docs/ANCHOR23_FRONTEND.md`