Guía de desarrollo.

El estándar cerouno.#

No envíes código que “hace lo que se pidió”. Envía código del que estés orgulloso, con interacciones refinadas, pensando en el camarero que lo usará un viernes por la noche con el restaurante lleno.

• 01
  Los detalles invisibles se acumulan

  Si el usuario no nota un detalle, lo hicimos bien. La suma de estados hover correctos, animaciones fluidas y tipografía perfecta crea una interfaz que se siente premium sin que el usuario sepa explicar por qué.

• 02
  El buen gusto se entrena

  No hagas que “simplemente funcione”. Estudia por qué las mejores interfaces se sienten bien. Haz ingeniería inversa de las interacciones. La curiosidad es parte del oficio.

• 03
  Feedback realista

  Las revisiones de código y diseño usan tablas Antes / Después / Por qué. Si algo se ve como plantilla SaaS genérica o hecho por IA, se rechaza y se rehace. Sin diplomacia innecesaria.

• 04
  El usuario manda, no el desarrollador

  Diseñamos para el cajero a las 9pm, no para nosotros en un escritorio limpio. Touch targets enormes, contrastes altos, latencia cero en lo que se repite.

Las dos verticales.#

Nuestros productos viven en dos mundos con requisitos opuestos. Tratarlos igual es la receta para que ambos fallen.

Productos activos.#

• POS
  Punto de venta

  Cero animaciones en acciones repetitivas. Atajos de teclado en todo. Offline-first. La latencia es el enemigo.

• Lumora
  Inventario

  Mermas, recetas y costos reales. Sabes cuánto te cuesta cada plato antes de cobrarlo.

• Qarta
  Menú QR

  Mobile-first, carga en 3G, sin login. El cliente escanea, ordena, paga. Pedidos por WhatsApp a la cocina.

• Fudi
  App de delivery

  GPS en tiempo real, múltiples pedidos por viaje, rutas optimizadas. Sin pánico en hora pico.

• Tasques
  Sistema escolar

  Calificaciones, asistencia y boletines MINERD. Roles para profesores, gestión y dirección.

Paleta.#

Siete tokens. Ni uno más sin justificación escrita. El naranja digital es sagrado: solo para llamados a la acción y superficies que deben gritar.

Tipografía.#

Display · PP Neue Corp Compact Ultrabold

Sustituto vía Google Fonts: Bebas Neue. Voz autoritaria, letras apretadas (letter-spacing: 0.02em), peso ultra. Para encabezados y números de impacto.

Body · DM Sans

Sustituto: Inter. Limpia, geométrica, legible incluso en pantallas con grasa. Para cuerpo, inputs, navegación.

Morfología.#

Solidez amigable. Bordes generosos. Padding amplio. Todo pensado para pantallas táctiles de POS y móviles.

Espaciado.

Padding amplio de 40px en cards. 16–24px en componentes interiores. Nunca menos de 10px entre elementos interactivos. La densidad cómoda es parte del estándar Caldera.

Motion.#

Antes de animar algo, pregúntate con qué frecuencia lo verá el usuario. La respuesta dicta la decisión.

Reglas técnicas.

• ≤300
  Duración máxima en ms

  Un dropdown de 180ms se siente más responsivo que uno de 400ms. Bajo techo, no piso.

• Out
  Easing por defecto

  Nunca ease-in en UI. Rápido al inicio, suave al final. Curvas personalizadas, no las débiles del navegador.

• .95
  Escala inicial mínima

  Nunca animes desde scale(0). Nada en el mundo real aparece de la nada. Inicia en scale(0.95) opacity:0.

• .97
  Estado :active de botones

  Todos los botones llevan transform: scale(0.97) en :active. Si tu PR no lo trae, será rechazado.

• CSS
  Transitions sobre keyframes

  Para elementos dinámicos que el usuario interrumpe. Las transitions retargetean suave; los keyframes reinician desde cero.

Curvas oficiales.

/* Caldera easings */
--ease-out:    cubic-bezier(0.23, 1, 0.32, 1);
--ease-out-q:  cubic-bezier(0.25, 1, 0.5, 1);
--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);
--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);

Prohibiciones absolutas.#

Stack oficial.#

Decidimos una vez, no en cada proyecto. La consistencia entre proyectos hace que cambiar de contexto sea barato.

• FE
  React + Vite

  Componentes funcionales con Hooks. Sin clases. Vite por velocidad de dev server.

• UI
  Tailwind CSS

  Configurado con tokens Caldera en tailwind.config.js. darkMode: 'class' donde aplique.

• DB
  Supabase

  Default. Postgres + Auth + Realtime + Edge Functions. Firebase solo si hay razón concreta.

• RLS
  Row Level Security siempre

  Multi-tenant sin RLS es un incidente de seguridad esperando. Política por tabla, sin excepciones.

• JS
  TypeScript en sistemas nuevos

  JS vanilla solo para landings o prototipos rápidos. Backend siempre tipado.

• PKG
  pnpm

  Lockfile commiteado. Versiones exactas en dependencias críticas.

Convenciones.#

Nombres.

Estructura de carpetas.

// Proyecto cerouno estándar
src/
├── components/      // reutilizables, sin lógica de negocio
├── features/        // agrupado por dominio (orders, inventory)
├── hooks/           // custom hooks compartidos
├── lib/             // supabase, fetch wrappers, utils
├── pages/           // rutas (o app/ en Next)
└── styles/          // tokens, globals

Antes / Después.

El formato de revisión es siempre tabla. No vale “esto está mal”, vale qué cambia y por qué.

Git y Pull Requests.#

Branches.

• main
  Producción

  Protegida. Solo merge desde PR aprobado.

• dev
  Integración

  Donde se mergea trabajo en curso. Despliega al entorno de staging.

• feat/
  Features

  Una rama por feature. Vida corta. feat/multi-order-driver.

• fix/
  Bugs

  fix/cierre-totals-overflow. Descriptivo, no fix/bug.

Commits.

Conventional Commits. El historial es documentación.

feat(pos): atajo de teclado F2 para cobrar
fix(kome): RLS faltante en panel_pedidos
refactor(maps): extraer AddressAutocomplete a componente
style(lumora): aplicar tokens Caldera al sidebar
docs(readme): instrucciones de setup local

PR checklist.

Si tu PR no cumple esto, no se revisa.

Rendimiento real.#

No optimices a ciegas. Mide. Pero hay no negociables.

• 3G
  Menús QR cargan en 3G

  Lighthouse mobile ≥ 90. Sin esto, el cliente final cierra la pestaña.

• Off
  POS offline-first

  Cobrar no puede depender de la red. Cola local, sync cuando vuelva.

• 100
  Acción del POS ≤ 100ms

  De clic a feedback visual. Si tarda más, el cajero pierde confianza.

• Lzy
  Lazy loading por defecto

  Rutas, imágenes, componentes pesados. React.lazy + Suspense.

Accesibilidad.#

En el mundo real de los restaurantes hay ruido, prisa y pantallas con grasa. No es accesibilidad por diversidad, es accesibilidad por realidad operativa.

• 4.5
  Contraste mínimo WCAG AA

  Texto sobre fondo. Más alto en POS por las pantallas sucias.

• 44
  Touch target ≥ 44×44 px

  En POS y QR. Dedos grandes con prisa no apuntan fino.

• ⌨
  Navegable por teclado

  Especialmente el POS. Atajos para todo lo repetitivo.

• A11y
  Lectores de pantalla en SaaS

  aria-label en iconos sueltos, role correcto en regiones.

Entornos.#

• Dev
  Local

  Cada dev con su .env.local. Supabase project propio o branch. Datos seed.

• Stg
  Staging

  Auto-deploy desde dev. Datos de prueba realistas. Aquí prueba el cliente.

• Prd
  Producción

  Auto-deploy desde main. Manual approval en cambios de schema. Backups diarios.

Hosting.#

Release checklist.#

No se mergea a main sin pasar esto. Sin excepciones, ni para hotfixes.

• 01
  Build pasa sin warnings

  Warning de hoy es bug de producción mañana.

• 02
  Probado en staging por el cliente

  O por un dev distinto al que escribió el código.

• 03
  Migraciones aplicadas en orden

  SQL versionado. Nada manual en la consola de Supabase.

• 04
  Variables de entorno verificadas

  Keys de Stripe, Supabase, WhatsApp. Las equivocadas son incidentes silenciosos.

• 05
  Rollback plan documentado

  Si esto falla a las 2am, ¿cómo volvemos atrás? Tiene que estar escrito antes del deploy.

• 06
  Smoke test post-deploy

  Cinco minutos verificando los flujos críticos. No te vayas a dormir sin esto.

Observabilidad.#

Si no lo mides, no existe. Lo que rompe en producción nadie te lo va a reportar a tiempo.

• Err
  Sentry o equivalente

  En todos los productos en producción. Alertas a Slack/WhatsApp para errores recurrentes.

• Lat
  Métricas de latencia

  P95 de endpoints críticos. POS endpoint > 200ms es una alerta.

• DB
  Supabase logs y slow queries

  Revisión semanal. Una query lenta a las 12pm el viernes tumba el restaurante.

• UX
  Feedback directo del cliente

  Canal de WhatsApp con cada cliente. Lo que se quejan vale más que cualquier dashboard.

Seguridad mínima.#