# Tomatesoft Design — POS (táctil)
> v0.1.0 · generado 2026-11-20. Generado desde docs/; no editar a mano.
# POS (táctil)
**TomatePOS**: aplicación de escritorio (Tauri + React) a **pantalla
completa 1920×1080**, en una pantalla táctil, usada **de pie, con el dedo y
a un brazo de distancia**, en medio del servicio.
Tokens: `tokens.css` + **`tokens-pos.css`**.
## Lo que la hace distinta
| Tema | En el POS |
|---|---|
| Entrada | **Dedo primero**. El teclado físico también funciona, siempre |
| Texto | Nunca debajo de 16 px. Cuerpo 18 px |
| Controles | 56 px de alto; teclas de 54 a 72 px |
| Campos de texto | **Cada uno trae el [teclado táctil](/markdown/components/touch-keyboard.md)** |
| Desplazamiento | **Sin barras de desplazamiento**: se arrastra con el dedo |
| Avisos | [Toasts](/markdown/components/toast.md) bajo la barra superior |
| Esquinas | Más redondas: tarjetas 40 px, controles 14 px |
| Gris secundario | Más claro (`#b4b4b8`): se lee de más lejos |
| Campos | Hundidos en la tarjeta (`#232427`) con borde |
| Horas | 24 h |
## Estructura de una pantalla
```text
┌──────────────────────────────────────────────────────────────┐
│ Barra superior (--ts-bar-bg): sucursal · usuario · hora │
├──────────────────────────────────────────────────────────────┤
│ │
│ Contenido, con --ts-screen-gap (16 px) al borde y │
│ entre paneles. Tarjetas con --ts-radius-card. │
│ │
├──────────────────────────────────────────────────────────────┤
│ Barra inferior: navegación y acciones de la pantalla │
└──────────────────────────────────────────────────────────────┘
```
- **Hojas** ([ventana](/markdown/components/dialog.md)): para acciones sobre algo
(una mesa), con lo que se toca a la derecha y el contexto (la tarjeta de
la mesa) a la izquierda.
- La **acción principal** va abajo a la derecha, en verde.
## Reglas
- **El POS vende, no administra.** Configuración y altas van en el panel web.
- El **PIN** se pide solo para acciones sensibles (caja, reportes), no para
navegar.
- Funciona **sin internet**: nada de fuentes, imágenes ni íconos de un CDN;
todo viene con la app.
- Textos **discretos**: el mesero no lee párrafos.
---
# Instrucciones para agentes
Eres un agente que crea o cambia interfaz en un producto de Tomatesoft. Estas
reglas no se negocian. Si una tarea te pide romper una, detente y explícale a
la persona por qué.
## Antes de escribir código
1. Identifica la **plataforma**: **POS** (táctil, pantalla completa,
Tauri + React) o **web** (paneles con mouse, Vite + React).
2. Lee la página de esa plataforma y solo las de los componentes que vas a
tocar.
3. Busca en el [catálogo](/markdown/components/overview.md) antes de crear un componente.
Si existe, úsalo.
## Reglas
- **Tokens siempre** (`var(--ts-*)`). Nunca un color, radio, peso o tamaño
de texto suelto. No inventes tokens: si falta uno, dilo como propuesta.
- **Archivo** es la única familia tipográfica. No agregues otra.
- **Verde** (`--ts-primary`) para la acción principal, **una por pantalla o
ventana**. **Rojo** (`--ts-accent`) solo para lo irreversible, con
confirmación. Nunca rojo para decorar.
- **Avisos como [toast](/markdown/components/toast.md)**, no cajas fijas en la página.
- **Cargas con [skeleton](/markdown/components/skeleton.md)** del mismo tamaño que el
contenido.
- **Animaciones de 300 ms o menos**, y respeta `prefers-reduced-motion`.
- **Textos en español de México, de tú, cortos**, en el archivo de idioma
(`es.ts`), nunca dentro del componente. Código y nombres en inglés.
- **Accesibilidad**: foco visible, áreas táctiles de 44 px o más, estados con
texto además de color, `aria-label` en botones de solo ícono.
### Solo en el POS
- Todo lo que se toca mide **56 px o más** (mínimo 44 px).
- Texto **nunca menor a 16 px**.
- **Todo campo de texto con teclado táctil** (`data-keyboard="text|numeric"`
o ``).
- **Sin barras de desplazamiento.**
- Nada que dependa de internet (fuentes, íconos, imágenes de un CDN).
- El POS vende, no administra: si es configuración, va en el panel web.
## Si algo no cuadra
Si la tarea pide algo que este sistema no cubre (un componente nuevo, un
color nuevo), no lo improvises en silencio: hazlo con lo más cercano que
exista y repórtalo como desviación.
## Checklist de salida
Al terminar, reporta esto a la persona:
```text
Tomatesoft Design — resumen
- Plataforma: POS | web
- Componentes usados: …
- Componentes nuevos o cambiados: ninguno | cuáles y por qué
- Tokens usados: …
- Valores sueltos: ninguno | cuáles y por qué
- Textos: en es.ts, de tú, cortos (sí/no)
- Accesibilidad: foco, tamaños táctiles, estados con texto (sí/no)
- POS: teclado táctil en cada campo, sin barras de desplazamiento (sí/no/no aplica)
- Desviaciones del sistema: ninguna | cuáles y por qué
```
---
# Principios
## 1. El servicio no espera a la pantalla
En un restaurante lleno, cada segundo frente al POS es un segundo sin
atender a alguien. Las pantallas se abren al instante, las animaciones son
cortas y nada pide un paso de más.
- Animaciones de 100 a 200 ms. Nunca una animación que haya que esperar.
- Mientras algo carga, se ve su forma ([skeleton](/markdown/components/skeleton.md)),
no un círculo girando en medio de la nada, y la pantalla no brinca cuando
llega.
## 2. Hecho para el dedo (en el POS)
El POS se usa de pie, con prisa y a veces con las manos mojadas.
- Todo lo que se toca mide **al menos 56 px**; las teclas, 54 a 72 px.
- **Nada de barras de desplazamiento**: las listas se arrastran con el dedo.
- Cada campo de texto trae el [teclado táctil](/markdown/components/touch-keyboard.md).
El teclado físico también funciona, siempre.
## 3. Oscuro, sobrio, sin ruido
Fondo de **grafito**, tarjetas grandes con un degradado suave, texto claro.
Se lee bien en un comedor con poca luz y cansa menos en un turno largo.
- **Un solo color de acción: verde** para confirmar y avanzar.
- **El rojo es para lo que no tiene vuelta atrás** (borrar, cancelar una
mesa) y para el logo. Nunca para decorar.
- Textos **discretos**: lo justo para entender, sin explicaciones que nadie
lee.
## 4. Los avisos no estorban
Un aviso es un **[toast](/markdown/components/toast.md)**: aparece, se lee y se va. No
empuja el contenido, no tapa el trabajo y no pide un clic para cerrarse.
## 5. Una sola marca, dos plataformas
El POS y los paneles comparten **color, tipografía, voz y componentes**.
Cambian las **medidas**, porque uno se usa con el dedo a un brazo de
distancia y el otro con el mouse y de cerca. Esa diferencia se resuelve con
tokens de plataforma, nunca con colores o piezas distintas.
## 6. Español claro, de tú
Toda la interfaz en español de México, hablando de tú, con palabras del
restaurante (mesa, comensal, cuenta, mesero), no de sistemas
([Voz y textos](/markdown/brand/voice.md)). El código, en inglés.
## 7. Se administra en la web
El POS **vende**; el panel web **administra**. Si una pantalla del POS
empieza a parecer un formulario de configuración, va en el panel.
---
# Logo
El logo es la palabra **tomatesoft** en minúsculas, en blanco (`#F9F9F9`),
con el punto rojo de la marca. Archivo SVG:
[`/brand/tomatesoft-logo.svg`](/brand/tomatesoft-logo.svg).
## Uso
- **Siempre sobre fondo oscuro** (grafito o las tarjetas). Es la versión que
existe; no hay versión para fondo claro todavía ✍️.
- **Espacio libre** alrededor: al menos la altura de la "t" en cada lado.
- **Tamaño mínimo**: 18 px de alto en pantalla.
- En el POS va en la **tarjeta del logo** de la pantalla de entrada; en los
paneles, arriba a la izquierda.
## No
- No estirar, girar ni cambiar el color de las letras.
- No rehacerlo con una fuente: es un dibujo, no texto en Archivo.
- No ponerle sombras, contornos ni degradados.
- No cambiar el rojo del punto.
## Rojo de marca
| | Valor | Dónde |
|---|---|---|
| Rojo de marca | `--ts-brand-red: #99000F` | El color de marca en la interfaz y en piezas de la marca |
| Punto del logo (el tomate) | `#E20D18` | Solo dentro del SVG del logo |
--ts-brand-red#99000F · marca
logo#E20D18 · solo el tomate
✅ Son dos rojos distintos a propósito (2026-11-20): el **tomate** del logo
conserva su rojo vivo, y **`#99000F`** es el rojo de la marca. El rojo del
tomate no se usa fuera del logo.
---
# Voz y textos
## Cómo suena Tomatesoft
**Claro, cercano y breve.** Como un gerente con experiencia que te explica
algo en medio del servicio: sin rodeos y sin tecnicismos.
| Sí | No |
|---|---|
| Tú: "Elige la mesa" | Usted: "Seleccione la mesa" |
| Palabras del restaurante: mesa, comensal, cuenta, mesero, turno | Palabras de sistemas: registro, entidad, recurso, usuario final |
| "No se pudo guardar. Intenta de nuevo." | "Error 500: falló la operación" |
| "Mesa 34 cambiada a Terraza" | "La operación se ha completado exitosamente" |
| Español de México | Mezclar inglés: "Hacer login", "Editar el item" |
## Reglas
- **Botones con verbo**: "Guardar", "Cambiar mesa", "Cobrar". No "Aceptar"
ni "OK" cuando se puede decir qué pasa.
- **Títulos cortos, sin punto final**. Mayúscula solo al inicio: "Cambiar de
mesa", no "Cambiar De Mesa".
- **Errores en dos partes**: qué pasó y qué hacer. "No hay conexión con el
servidor. Revisa la red e intenta de nuevo."
- **Cantidades con su unidad y formato de México**: `$1,284.50`, `42 min`,
`4 comensales`. Fechas: "20 nov 2026", horas en 24 h en el POS.
- **Discreto**: si el texto no ayuda a decidir o a actuar, sobra.
- **Sin culpar**: "No encontramos esa mesa", no "Escribiste mal la mesa".
- **El silencio también es respuesta**: una acción que salió bien y se ve
en pantalla no necesita aviso. Avisa solo cuando el resultado no se ve.
## Avisos ([toast](/markdown/components/toast.md))
| Tono | Ejemplo |
|---|---|
| Éxito | "Mesa 34 reasignada a Ana" |
| Error | "No se pudo reasignar la mesa. Intenta de nuevo." |
| Información | "Hay una versión nueva; se instala al cerrar." |
## En el código
Los textos viven en un archivo de idioma (`es.ts`), nunca escritos dentro de
los componentes. Las llaves, en inglés: `keyboard.done: 'Listo'`.
---
# Color
Grafito para el fondo, verde para actuar, rojo solo para lo irreversible.
Los colores se usan **siempre por su token** (`var(--ts-primary)`), nunca con
el valor suelto.
## Fondos
Del más profundo al más alto. Cada capa es un poco más clara que la de abajo.
--ts-page-bg#17181a · página
--ts-bg#1d1e21 · pantalla
--ts-bar-bg#222326 · barras
--ts-surface#26272a · superficie
--ts-surface-hover#2d2e31
--ts-card-from → to#3a3b3f → #2a2b2e · tarjeta
--ts-dialog-bg#1f2023 · ventanas
## Acciones
--ts-primary#3d7a37 · confirmar
--ts-primary-hover#468a40
--ts-secondary#55565b · secundaria
--ts-accent#a00f16 · irreversible
--ts-disabled-bg#4a4b50 · deshabilitado
--ts-focus#6aa863 · foco
| Token | Para qué | No para |
|---|---|---|
| `--ts-primary` | La acción principal: guardar, confirmar, cobrar, "Listo" | Decorar, marcar estados |
| `--ts-secondary` | Acciones de apoyo: cancelar, volver, filtros | La acción que el usuario vino a hacer |
| `--ts-accent` | Lo **irreversible o destructivo**: borrar, cancelar una mesa, dar de baja | Llamar la atención; botones normales |
| `--ts-focus` | El anillo de foco del teclado | Fondos |
**Una acción primaria por pantalla o ventana.** Si hay dos verdes, una de
las dos no es primaria.
## Estados
--ts-success-soft#9fd497 · texto/ícono
--ts-success-bg#243a22 · fondo
--ts-warning-soft#f2c97d · texto/ícono
--ts-danger#ff6a55 · texto de error
--ts-danger-soft#f2a19c · ícono de error
--ts-danger-bg#4a2a28 · fondo
--ts-accent-violet#8b80d8 · resaltar
- Un estado **nunca se comunica solo con color**: va con ícono o texto
("Ocupada", "Por pagar").
- Los estados usan la versión **suave** sobre fondo oscuro (`-soft` para
texto e ícono, `-bg` para el fondo). Los colores puros son para acciones.
- `--ts-accent-violet` resalta lo seleccionado o lo que está en vivo; no es
una acción ni un estado.
## Texto
--ts-text-strong#f4f4f5 · títulos
--ts-text#ececee · cuerpo
--ts-text-soft#c9c9cc · secundario
--ts-mutedPOS #b4b4b8 · web #a4a4a8
--ts-placeholder#9c9da2
`--ts-muted` es más claro en el POS porque se lee de más lejos
([Plataformas](/markdown/platforms/pos.md)).
## Líneas
| Token | Valor | Para |
|---|---|---|
| `--ts-line` | `#3a3b3f` | Divisiones dentro de una superficie |
| `--ts-border` | `#5c5d62` | Bordes de campos y controles |
## Modo claro
No hay. Los productos son oscuros a propósito ([Principios](/markdown/start/principles.md)).
Un modo claro se decidiría por producto ✍️, no por preferencia.
---
# Tipografía
**Archivo**, en todo: el POS, los paneles, la tienda y este sitio. Una sola
familia, variable (100–900), cargada con la app para que funcione sin
internet.
```sh
npm install @fontsource-variable/archivo
```
```ts
// main.tsx, antes que cualquier CSS
import '@fontsource-variable/archivo';
```
```css
font-family: var(--ts-font); /* 'Archivo Variable', 'Segoe UI', system-ui, sans-serif */
```
## Pesos
Bold 600 · Mesa 34 · Terraza
Medium 480 · Cambiar de mesa
Regular 380 · Abierta hace 42 min · 4 comensales · $1,284.50
Light 300 · Motivo del cambio (máximo 200 caracteres)
| Token | Valor | Para |
|---|---|---|
| `--ts-weight-bold` | 600 | Títulos, cifras importantes |
| `--ts-weight-medium` | 480 | Botones, etiquetas, subtítulos |
| `--ts-weight-regular` | 380 | Cuerpo |
| `--ts-weight-light` | 300 | Notas y ayudas, en tamaño grande |
Archivo se ve más pesada que otras fuentes al mismo número; por eso los
pesos no son los redondos (400, 500…). **Usa siempre el token.**
## Tamaños
Cambian por plataforma: el POS se lee a un brazo de distancia.
| Token | POS | Web | Para |
|---|---|---|---|
| `--ts-text-caption` | 16 px | 12 px | Notas, fechas, detalles. **Nada más chico** |
| `--ts-text-small` | 17 px | 13 px | Controles, tablas |
| `--ts-text-body` | 18 px | 14 px | Texto normal |
| `--ts-text-title` | — | 20 px | Título de página o ventana |
| `--ts-text-hero` | — | 28 px | Título principal de una pantalla de entrada |
En el POS, títulos y cifras grandes (nombre de la mesa, total) se definen en
su pantalla, entre 22 y 44 px 🔜 (falta su token).
## Reglas
- **Interlineado** 1.3 en textos cortos y controles; 1.5 en párrafos.
- **Cifras alineadas** en tablas y totales: `font-variant-numeric:
tabular-nums`.
- **Mayúscula solo al inicio**. Nada en mayúsculas completas salvo
etiquetas muy cortas de estado, como "NO ASIGNADA" en la tarjeta de mesa.
- **Monoespaciada** (`--ts-font-mono`) solo para códigos que se copian o se
dictan: IPs, claves de equipo.
- **No** usar otra familia, ni bold sintético, ni cursivas para resaltar.
---
# Forma y elevación
Esquinas **generosas y suaves**: tarjetas muy redondeadas, controles un poco
menos. En el POS, todo es más grande y más redondo porque se toca con el
dedo.
## Radios
| Token | POS | Web | Para |
|---|---|---|---|
| `--ts-radius-card` | 40 px | 36 px | Tarjetas grandes (la del logo, los paneles de una pantalla) |
| — | 28 px | 28 px | Ventanas ([modal y hoja](/markdown/components/dialog.md)) |
| — | 24 px | — | Teclado flotante |
| `--ts-radius-control` | 14 px | 8 px | Botones, campos, filas |
| `--ts-radius-key` | 12 px | — | Teclas del [teclado táctil](/markdown/components/touch-keyboard.md) (14 px en el grande) |
| `--ts-radius-pill` | 999 px | 999 px | [Chips, filtros](/markdown/components/chip.md), [toasts](/markdown/components/toast.md) |
| — | 6 px | 6 px | Barras del [skeleton](/markdown/components/skeleton.md) |
🔜 El radio de ventana (28 px) aún no tiene token.
## Elevación
Pocas capas y bien separadas. La profundidad viene del **color de fondo**
(cada capa más clara) más que de las sombras.
| Capa | Fondo | Sombra |
|---|---|---|
| Página | `--ts-page-bg` | — |
| Superficie, barras | `--ts-surface`, `--ts-bar-bg` | — |
| Tarjeta | degradado `--ts-card-from` → `--ts-card-to` | `--ts-card-shadow` (`0 30px 60px rgba(0,0,0,.35)`) |
| Toast | `rgba(38,39,42,.94)` + desenfoque 8 px | `0 14px 36px rgba(0,0,0,.45)` |
| Ventana | `--ts-dialog-bg`, sobre `--ts-overlay` | — |
## Bordes
- **1 px**, siempre. `--ts-line` adentro de una superficie, `--ts-border`
en controles.
- Una tarjeta no lleva borde: la separa su degradado y su sombra.
---
# Espacio y medidas
## Medidas que se tocan
| Token | POS | Web | Para |
|---|---|---|---|
| `--ts-control-height` | 56 px | 36 px | Botones y campos |
| `--ts-key-height` | 54 px | — | Teclas del teclado táctil |
| `--ts-key-height-large` | 72 px | — | Teclas del teclado grande (motivos, notas largas) |
| — | 44 px | 36 px | Botón de cerrar una ventana (círculo) |
En el POS, **nada que se toque mide menos de 44 px**, y lo que se toca mucho
(acciones, teclas) va de 56 px para arriba.
## Espacio entre cosas
| Token | Valor | Para |
|---|---|---|
| `--ts-screen-gap` | 16 px (POS) | Borde de la ventana y entre los paneles de una pantalla |
| `--ts-shell-gap` | 8 px (web) | Entre tarjetas y con el borde del panel |
Para el resto, una escala de 4 px:
| Paso | Valor | Ejemplo |
|---|---|---|
| 1 | 4 px | Ícono y su texto pegado |
| 2 | 8 px | Entre botones de un grupo; entre teclas (teclado grande) |
| 3 | 12 px | Entre ícono y texto de un toast; dentro de un campo |
| 4 | 16 px | Entre campos de un formulario |
| 6 | 24 px | Relleno de una ventana pequeña |
| 8 | 32 px | Relleno de una tarjeta o ventana |
| 12 | 48 px | Márgenes de una pantalla de entrada |
🔜 La escala aún no tiene tokens (`--ts-space-1` … `--ts-space-12`); hoy cada
componente usa el valor.
## Pantallas
- **POS**: 1920×1080, pantalla completa, sin barras de desplazamiento. Una
pantalla se diseña para que **quepa**; si una lista no cabe, se arrastra
con el dedo.
- **Web**: de 1280 px en adelante. El contenido se centra con un máximo de
ancho por pantalla (formularios ~720 px, tablas a todo lo ancho).
---
# Movimiento
**Rápido y discreto.** El movimiento explica de dónde sale algo; nunca hace
esperar.
| Token | Valor | Para |
|---|---|---|
| `--ts-motion-hover` | 120 ms | Cambios de color al pasar o presionar |
| `--ts-motion-enter` | 180 ms | Entrada de toasts y avisos |
| `--ts-motion-dialog` | 200 ms | Entrada de una ventana (el fondo oscuro, 100–160 ms) |
| `--ts-ease-out` | `cubic-bezier(.2, .8, .2, 1)` | Lo que entra: arranca rápido y se asienta |
🔜 Los tokens de movimiento son nuevos: las apps aún escriben los valores.
## Reglas
- **Nada pasa de 300 ms**, salvo lo que se repite mientras algo carga
(skeleton 1.4 s, el ícono de "en proceso" 0.9 s por vuelta).
- **Entrar sí, salir rápido**: lo que se va desaparece sin ceremonia.
- **Sin rebotes ni efectos de resorte.**
- **Movimiento reducido**: con `prefers-reduced-motion: reduce`, las
animaciones se quitan (skeleton quieto, ventanas sin subir). La interfaz
funciona igual.
```css
.ts-toast {
animation: ts-toast-in var(--ts-motion-enter) ease-out;
}
@media (prefers-reduced-motion: reduce) {
.ts-toast {
animation: none;
}
}
```
---
# Accesibilidad
Meta: **WCAG 2.2 AA**. En un restaurante, accesible también quiere decir
"se usa con prisa, con poca luz y con un dedo".
## Contraste
- Texto normal: **4.5:1** contra su fondo. Texto grande (24 px, o 19 px en
bold): **3:1**.
- Las combinaciones de los tokens ya cumplen sobre los fondos de grafito:
`--ts-text` sobre `--ts-bg`, `--ts-muted` sobre `--ts-surface`, `--ts-text-strong` sobre `--ts-primary`.
- `--ts-placeholder` es solo para el texto de ejemplo de un campo, nunca
para información.
## Foco
- Todo lo que se toca se alcanza también con teclado (`Tab`) y muestra su
foco: **anillo de 2 px `--ts-focus` separado 2 px**.
```css
:focus-visible {
outline: 2px solid var(--ts-focus);
outline-offset: 2px;
}
```
- No quitar el anillo de foco sin poner otro igual de visible.
## Tamaños
- Áreas táctiles: **44 × 44 px mínimo** (WCAG pide 24); en el POS, 56 px
para lo que se toca seguido ([Espacio y medidas](/markdown/foundations/spacing.md)).
- Texto: nunca por debajo de `--ts-text-caption` (16 px POS, 12 px web).
## No depender del color
Un estado se dice con texto o ícono además del color: "Ocupada", ✓, ⚠.
## Lectores de pantalla
- Botones de solo ícono con `aria-label` ("Cerrar").
- Los [skeletons](/markdown/components/skeleton.md) llevan un "Cargando…" oculto
visualmente.
- Los [toasts](/markdown/components/toast.md) se anuncian (`role="status"`; los errores,
`role="alert"`).
- Las ventanas atrapan el foco mientras están abiertas y lo regresan al
cerrar.
## Movimiento
Se respeta `prefers-reduced-motion` ([Movimiento](/markdown/foundations/motion.md)).
---
# Catálogo de componentes
Las piezas que comparten los productos. Antes de crear una nueva, **busca
aquí**: si existe, se usa; si le falta algo, se propone el cambio en este
sistema, no una copia en tu app.
| Componente | POS | Web | Para |
|---|---|---|---|
| [Botón](/markdown/components/button.md) | ✅ | ✅ | Acciones |
| [Campo de texto](/markdown/components/field.md) | ✅ | ✅ | Escribir un dato |
| [Teclado táctil](/markdown/components/touch-keyboard.md) | ✅ | — | Escribir sin teclado físico |
| [Tarjeta](/markdown/components/card.md) | ✅ | ✅ | Agrupar contenido |
| [Ventana](/markdown/components/dialog.md) | ✅ (modal y hoja) | ✅ (diálogo) | Una tarea encima de la pantalla |
| [Aviso (toast)](/markdown/components/toast.md) | ✅ | ✅ | Resultado de una acción |
| [Chip y filtro](/markdown/components/chip.md) | ✅ | ✅ | Estados y filtros |
| [Skeleton](/markdown/components/skeleton.md) | ✅ | ✅ | Mientras carga |
## Convenciones
- **Clases** con prefijo `ts-` y estilo BEM: `ts-button`,
`ts-button--primary`, `ts-toast__icon`. El teclado táctil usa `tk-`.
- **Colores y medidas por token**, nunca valores sueltos.
- Cada componente de React vive en `src/modules/shared/ui/` de cada app, con
su CSS al lado (`Button.tsx` + `components.css`). 🔜 Se mudarán a un
paquete compartido ([React](/markdown/implementation/react.md)).
- **Textos fuera del componente**, en el archivo de idioma.
## Proponer un componente nuevo
1. Que lo necesiten **dos pantallas o más**.
2. Documentarlo aquí: para qué es, sus variantes, medidas por plataforma,
estados y reglas, con el formato de las demás páginas.
3. Después, el código.
---
# Botón
Arriba, web (36 px). Abajo, POS (56 px).
## Variantes
| Variante | Clase | Para | POS | Web |
|---|---|---|---|---|
| Primaria | `ts-button--primary` | La acción principal. **Una por pantalla o ventana** | ✅ | ✅ |
| Secundaria | `ts-button--secondary` | Cancelar, volver, acciones de apoyo | ✅ | ✅ |
| Irreversible | `ts-button--accent` | Borrar, dar de baja, cancelar una mesa | 🔜 | ✅ |
| Discreta | `ts-button--ghost` | Acciones de bajo peso dentro de tablas o tarjetas | — | ✅ |
## Medidas
| | POS | Web |
|---|---|---|
| Alto | 56 px | 36 px |
| Relleno lateral | 28 px | 16 px |
| Radio | 14 px | 8 px |
| Texto | 18 px, medium | 13 px, medium |
| Ancho completo | `ts-button--block` | `ts-button--block` |
## Estados
- **Hover / presionado**: el tono `-hover` de su color, 120 ms.
- **Deshabilitado**: `--ts-disabled-bg` y `--ts-disabled-text`, sin
cursor de mano. Si el usuario no entiende por qué está deshabilitado, di
por qué cerca del botón.
- **Trabajando**: deshabilitado y con el verbo en gerundio ("Guardando…").
No cambia de tamaño.
## Reglas
- **Verbo que dice qué pasa**: "Cambiar mesa", no "Aceptar".
- En una ventana, la primaria va **a la derecha**; la secundaria, a su
izquierda.
- El rojo **no** se usa para "importante": solo para lo que no se deshace, y
siempre con confirmación.
## React
```tsx
```
El POS hoy tiene `primary | secondary`; los paneles, además, `accent` y
`ghost`.
---
# Campo de texto
Arriba, web: elevado y más claro. Abajo, POS: hundido en la tarjeta y con
borde.
## Anatomía
1. **Etiqueta** arriba, en `--ts-text-small`, medium. Siempre visible: el
texto de ejemplo no la sustituye.
2. **Campo**.
3. **Ayuda o error** abajo, en `--ts-text-caption`. El error, en
`--ts-danger` con su ícono.
## Medidas
| | POS | Web |
|---|---|---|
| Alto | 56 px (64 px junto al teclado grande) | 36 px |
| Radio | 14 px | 8 px |
| Fondo | `--ts-input-bg` `#232427` + borde `--ts-border` | `--ts-input-bg` `#4a4b50`; al enfocar, `--ts-input-bg-focus` |
| Texto | 18 px | 13 px |
## Estados
- **Foco**: anillo `--ts-focus` ([Accesibilidad](/markdown/foundations/accessibility.md)).
- **Error**: `aria-invalid="true"`, borde y mensaje en rojo de error.
- **Deshabilitado**: opacidad reducida y sin teclado.
## En el POS: siempre con teclado
Todo campo de texto del POS se marca con `data-keyboard` y el
[teclado táctil](/markdown/components/touch-keyboard.md) aparece al tocarlo:
```html
```
## Reglas
- Una **acción dentro del campo** (mostrar contraseña, limpiar) va a la
derecha, como botón de 36 px (web).
- Validar **al salir del campo o al enviar**, no con cada tecla.
- Los textos de error dicen cómo arreglarlo: "Escribe un correo, por
ejemplo ana@restaurante.mx".
---
# Tarjeta
Mesa 34
Terraza · 4 comensales · 42 min
La pieza que agrupa: el degradado de grafito, la sombra profunda y las
esquinas grandes son lo más reconocible de Tomatesoft.
## Medidas
| | POS | Web |
|---|---|---|
| Radio | 40 px (`--ts-radius-card`) | 36 px |
| Relleno | 32–48 px | 24–32 px |
| Fondo | `linear-gradient(180deg, var(--ts-card-from), var(--ts-card-to))` | igual |
| Sombra | `--ts-card-shadow` | igual |
```css
.ts-card {
border-radius: var(--ts-radius-card);
background: linear-gradient(180deg, var(--ts-card-from), var(--ts-card-to));
box-shadow: var(--ts-card-shadow);
}
```
## Reglas
- **Sin borde**: la separan el degradado y la sombra.
- **No anidar tarjetas** grandes. Dentro de una tarjeta, las divisiones son
`--ts-surface` o una línea `--ts-line`.
- En el POS, las tarjetas de una pantalla se separan con `--ts-screen-gap`
(16 px); en la web, con `--ts-shell-gap` (8 px).
- Una tarjeta que se toca entera (una mesa en el mapa) se oscurece un poco al
presionarla y no necesita botón.
---
# Ventana (modal y hoja)
Una tarea encima de la pantalla, sobre un fondo oscuro (`--ts-overlay`).
## Tipos
| Tipo | Plataforma | Para |
|---|---|---|
| **Diálogo** | Web | Crear, editar, confirmar. Ancho `md` 720 px o `lg` 920 px |
| **Confirmación** | Web | "¿Borrar a Ana?": texto corto y dos botones |
| **Modal** | POS | Avisos y decisiones cortas, con ícono rojo de marca en la cabecera |
| **Hoja** | POS | Acciones sobre algo (una mesa): **contexto a la izquierda** (la tarjeta de la mesa) y **lo que se toca a la derecha**. Con teclado grande, crece a 1400 px |
## Medidas
| | POS | Web |
|---|---|---|
| Radio | 28 px | 28 px |
| Relleno | 32 px | 32 px |
| Cerrar | Círculo de 44 px arriba a la derecha | Círculo de 36 px |
| Fondo | Degradado de grafito | `--ts-dialog-bg` |
| Entrada | Fondo 100 ms + ventana 140 ms `--ts-ease-out` | Fondo 160 ms + ventana sube 200 ms |
## Anatomía
1. **Cabecera**: título (y subtítulo si hace falta) y el botón de cerrar.
2. **Contenido**.
3. **Acciones** abajo a la derecha: secundaria, luego primaria.
## Reglas
- **Una tarea por ventana.** No abrir una ventana desde otra; si hace falta
un paso más, es un paso dentro de la misma (como el motivo en la hoja de
la mesa).
- Se cierra con el botón, con `Esc` y tocando fuera, **salvo** si hay
cambios sin guardar o una acción en curso.
- El foco entra a la ventana al abrir y vuelve a donde estaba al cerrar.
- Lo **irreversible** se confirma con el botón rojo y un texto que dice
qué se pierde: "Se borrará a Ana y sus huellas. No se puede deshacer."
---
# Aviso (toast)
✓ Mesa 34 reasignada a Ana
! No se pudo cambiar la mesa. Intenta de nuevo.
i Hay una versión nueva; se instala al cerrar.
**Todos los avisos de resultado son toasts.** No hay cajas de aviso fijas en
la página.
## Cómo es
- Una **píldora** centrada arriba, bajo la barra superior, encima de todo.
- Fondo grafito translúcido con desenfoque, borde `--ts-line`, sombra
profunda.
- Ícono de color según el tono; el texto, siempre `--ts-text-strong`.
- Entra en 180 ms. Se apilan con 8 px de separación.
| Tono | Ícono | Para |
|---|---|---|
| `success` | `--ts-success-soft` | Algo salió bien y no se ve en pantalla |
| `error` | `--ts-danger-soft` | Algo falló: qué pasó y qué hacer |
| `info` | `--ts-muted` | Información que no pide nada |
## Medidas
| | POS | Web |
|---|---|---|
| Texto | 18 px | 14 px |
| Cerrar | Botón de 36 px, para el dedo | Más chico |
| Ancho máximo | 640 px | 640 px |
## Reglas
- **Corto**: una línea. Si necesita más, no es un toast.
- Se **va solo** (unos segundos); los errores se quedan un poco más y se
pueden cerrar.
- **No** para pedir una decisión (eso es una [ventana](/markdown/components/dialog.md)).
- **No** avisar lo que ya se ve: si la mesa cambió de color en el mapa, no
hace falta "Mesa actualizada".
- `role="status"` (éxito, info) o `role="alert"` (error).
---
# Chip y filtro
MeseroActivoSin huella
## Chip
Una etiqueta de estado o categoría. **No se toca.**
| Variante | Clase | Para |
|---|---|---|
| Neutral | `ts-chip` | Roles, categorías |
| Bien | `ts-chip--ok` | Activo, conectado, completo |
| Atención | `ts-chip--warn` | Falta algo, por vencer |
Medidas (web): 24 px de alto, píldora, texto `--ts-text-caption`.
## Filtro
Un chip que **sí se toca** para filtrar una lista: 34 px de alto (web),
píldora, fondo `--ts-surface`. Activo: `aria-pressed="true"` y fondo más
claro. Puede llevar una "x" para quitarlo.
## Reglas
- El chip dice el estado **con texto**; el color solo lo refuerza.
- Máximo dos o tres palabras.
- No usar chips como botones.
---
# Skeleton
Mientras algo carga, se ve **la forma de lo que viene**, para que la
pantalla no brinque cuando llega.
## Piezas
| Componente | Para |
|---|---|
| `SkeletonBlock lines={4}` | Texto o un bloque de contenido |
| `SkeletonRows cols={5} rows={5}` | Filas de una tabla (dentro de `tbody`) |
| `SkeletonTiles count={12} height={200}` | Cuadrícula de tarjetas (mesas, planes) |
## Cómo es
- Barras de 14 px de alto, radio 6 px.
- Un brillo suave que cruza de derecha a izquierda cada 1.4 s.
- Con movimiento reducido, quietas.
- Llevan un **"Cargando…" oculto** para lectores de pantalla.
```css
.ts-skeleton {
height: 14px;
border-radius: 6px;
background: linear-gradient(90deg,
rgba(255, 255, 255, 0.05) 0%,
rgba(255, 255, 255, 0.11) 40%,
rgba(255, 255, 255, 0.05) 80%);
background-size: 300% 100%;
animation: ts-skeleton-sweep 1.4s ease-in-out infinite;
}
```
## Reglas
- **Mismo tamaño** que lo que reemplaza: mismas filas, mismas tarjetas,
mismo alto. Si al llegar el contenido algo se mueve, el skeleton está mal.
- Solo para la **primera carga**. Al refrescar, se queda lo anterior hasta
que llega lo nuevo.
- No para acciones (guardar, enviar): ahí el botón dice "Guardando…".
---
# Tokens CSS
Tres archivos: la base, que comparten todos, y uno por plataforma con lo que
cambia.
| Archivo | Contiene |
|---|---|
| [`/ts/tokens.css`](/ts/tokens.css) | Color, tipografía (familia y pesos), radio de píldora, movimiento |
| [`/ts/tokens-pos.css`](/ts/tokens-pos.css) | Tamaños de texto, radios y medidas táctiles del POS, colores de teclas y barras |
| [`/ts/tokens-web.css`](/ts/tokens-web.css) | Tamaños de texto, radios y medidas de los paneles |
## Usarlos
La fuente está en el monorepo, en **`design/tokens/`**. Las apps del
monorepo los **importan desde ahí**, nunca los copian:
```css
/* web/admin/src/modules/shared/ui/tokens.css */
@import '../../../../../../design/tokens/tokens.css';
@import '../../../../../../design/tokens/tokens-web.css'; /* o tokens-pos.css */
```
Vite los resuelve y los incluye en el CSS de la app al compilar; no hace
falta configurar nada. Una app fuera del monorepo los toma del sitio
(`/ts/tokens.css`) o del paquete de su plataforma (`npm run bundle`).
```css
.mi-componente {
padding: 16px;
border-radius: var(--ts-radius-control);
background: var(--ts-surface);
color: var(--ts-text);
font-size: var(--ts-text-body);
font-weight: var(--ts-weight-medium);
}
```
## Reglas
- **Nunca un valor suelto** de color, radio, peso o tamaño de texto. Si
falta un token, se propone aquí.
- Los nombres son los mismos que ya usan las apps (`--ts-*`): adoptarlos no
pide renombrar nada.
- Un token de plataforma **nunca cambia de significado** entre POS y web,
solo de valor (`--ts-text-body` es "el texto normal" en los dos).
- No se crean tokens por componente (`--ts-toast-bg`) mientras el valor se
use en un solo lugar.
## De dónde salen
v0.1.0 se armó a partir de los `tokens.css` del POS y de los tres paneles
(`web/admin`, `web/platform`, `web/store`), que eran copias que se habían
separado. Lo unificado:
- **Archivo** en todo (antes el POS usaba Geist) ✅.
- **Pesos** iguales en todo: 300 / 380 / 480 / 600 ✅.
- **Rojo de acción** (`--ts-accent`) para lo irreversible en las dos
plataformas; el violeta queda solo para resaltar.
- **Nuevos** 🔜: movimiento (`--ts-motion-*`), medidas
(`--ts-control-height`, `--ts-key-height*`), `--ts-font-mono`.
## En las apps ✅
El POS y los tres paneles importan `design/tokens/` desde su `tokens.css`.
En el `tokens.css` de cada app solo quedan las medidas propias de sus
pantallas (por ejemplo, el ancho de la tarjeta del logo del POS).
Pendiente 🔜: cambiar por su token los valores sueltos que todavía quedan en
el CSS de cada app.
---
# React
Todos los productos son **React 19** (el POS dentro de Tauri; los paneles con
Vite). Los componentes son funciones sencillas que ponen las clases `ts-` y
dejan el estilo al CSS.
## Hoy
Cada app tiene sus componentes en `src/modules/shared/ui/`:
| Componente | POS | Paneles |
|---|---|---|
| `Button` | `primary`, `secondary` | `primary`, `secondary`, `accent`, `ghost` |
| `TextField` / `Field` | ✅ | ✅ |
| `TouchKeyboard`, `KeyboardHost` | ✅ | — |
| `Toast` | ✅ | ✅ |
| `Dialog`, `ConfirmDialog` | modal y hoja propios | ✅ |
| `SkeletonBlock`, `SkeletonRows`, `SkeletonTiles` | ✅ | ✅ |
| `Logo` | ✅ | ✅ |
## Cómo se escribe un componente
```tsx
import type { ButtonHTMLAttributes } from 'react';
interface ButtonProps extends ButtonHTMLAttributes {
variant?: 'primary' | 'secondary' | 'accent' | 'ghost';
}
export function Button({ variant = 'primary', className, type = 'button', ...props }: ButtonProps) {
const classes = ['ts-button', `ts-button--${variant}`, className].filter(Boolean).join(' ');
return ;
}
```
- **Props del elemento nativo** (`...props`): un `Button` acepta todo lo que
acepta un `