CSS token and variable contract

Studio Arcana publishes a stable token contract so app embeds and custom blocks can inherit the merchant's visual language.

Contract version

• v1.0.0 — Canonical text and stability rules: Liquid comment at the top of layout/theme.liquid. Implementation and a short mirror comment: snippets/studio-arcana-head-after-content.liquid (:root, style id studio-arcana-theme-tokens).
• Additive changes: new --sa-* variables may ship in minor/patch docs releases without breaking consumers that ignore unknown keys.
• Breaking changes: renaming or removing published variables requires a new major contract version and a changelog entry in the Arcanum docs hub.
• Values update when the merchant changes Theme settings (colors, typography, shape & spacing, motion).

Core tokens

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 (light/dark variants switch with data-sa-theme on :root)

Typography

• --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 — Unitless 80–150 from Theme settings → Typography → Heading size scale; use as calc(<rem> * var(--sa-heading-scale) / 100) (theme headings already do this).

Shape & spacing

• --sa-button-radius, --sa-card-radius
• --sa-spacing-density — Numeric 1 (compact) / 1.15 (comfortable) / 1.3 (spacious) for third-party UI density; maps to Theme settings → Shape & spacing → Spacing density.
• --sa-spacing-density-mode — String compact | comfortable | spacious (same setting, for debugging or conditional logic).
• --sa-section-padding-scale — Theme-internal vertical rhythm multiplier (differs from --sa-spacing-density; used by section scaffold padding).

Motion

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

Where to mount booking or upsell UI

• Cart drawer — Cart drawer section supports App blocks: rendered below theme upsells and above subtotal when the cart has items (sections/cart-drawer.liquid).
• Product, hero, service menu, specialist team, sticky CTA — Other sections expose App blocks as documented in the theme editor.

Integration guidance

• Read from tokens; do not override globally from app code.
• Respect --sa-heading-scale and --sa-spacing-density when sizing embedded UI.
• Keep contrast and focus visibility intact after custom styling.