Contrato de tokens y variables CSS

Studio Arcana publica un contrato de tokens estable para que los embeds de app y bloques personalizados hereden el lenguaje visual del comerciante.

Versión del contrato

• v1.0.0 — Texto canónico y reglas de estabilidad: comentario Liquid al inicio de layout/theme.liquid. Implementación y comentario espejo breve: snippets/studio-arcana-head-after-content.liquid (:root, id de estilo studio-arcana-theme-tokens).
• Cambios aditivos: nuevas variables --sa-* pueden llegar en versiones menores o parches sin romper a quien ignore claves desconocidas.
• Cambios disruptivos: renombrar o eliminar variables publicadas requiere una nueva versión mayor del contrato y una entrada en el changelog del hub de documentación Arcanum.
• Los valores se actualizan cuando el comerciante cambia Ajustes del tema (colores, tipografía, forma y espaciado, movimiento).

Tokens principales

Color

• --sa-color-primary, --sa-color-primary-contrast
• --sa-color-accent
• --sa-color-surface, --sa-color-surface-alt
• --sa-color-text, --sa-color-text-muted
• --sa-color-border, --sa-focus-ring (variantes claro/oscuro según data-sa-theme en :root)

Tipografía

• --sa-font-heading-family, --sa-font-heading-weight, --sa-font-heading-style
• --sa-font-body-family, --sa-font-body-weight, --sa-font-body-style
• --sa-heading-scale — Valor sin unidad 80–150 desde Ajustes del tema → Tipografía → Escala del tamaño del título; usar como calc(<rem> * var(--sa-heading-scale) / 100) (los títulos del tema ya lo hacen).

Forma y espaciado

• --sa-button-radius, --sa-card-radius
• --sa-spacing-density — Numérico 1 (compacto) / 1.15 (cómodo) / 1.3 (espacioso) para densidad de UI de terceros; corresponde a Ajustes del tema → Forma y espaciado → Densidad de espaciado.
• --sa-spacing-density-mode — Cadena compact | comfortable | spacious (mismo ajuste, para depuración o lógica condicional).
• --sa-section-padding-scale — Multiplicador interno del tema para ritmo vertical (distinto de --sa-spacing-density; usado en el padding del andamio de sección).

Movimiento

• --sa-motion-duration, --sa-motion-easing, --sa-motion-distance

Dónde montar la UI de reservas o upsell

• Carrito lateral — La sección Cart drawer admite bloques de App: debajo de los upsells del tema y encima del subtotal cuando hay artículos (sections/cart-drawer.liquid).
• Producto, hero, menú de servicios, equipo de especialistas, CTA fijo — Otras secciones exponen bloques de App según el editor de temas.

Guía de integración

• Lee desde los tokens; no sobrescribas globalmente desde el código de la app.
• Respeta --sa-heading-scale y --sa-spacing-density al dimensionar UI incrustada.
• Mantén contraste y visibilidad del foco tras estilos personalizados.