Skip to content

Style Guide

The visual language of Tomoda — how the product looks, sounds, and feels. This section is the bridge between brand intent and implementation: design system tokens, component primitives, motion rules, accessibility commitments.

If you're shipping anything that a user will see — a new screen, an alert, an email template, a marketing page — start here.

  • Brand

    Design philosophy, voice and tone, the principles that drive every visual decision (asymmetry, the no-line rule, tonal layering).

  • Color

    Full palette with live swatches — semantic tokens, the warm-ember accent system, dark and light parities.

  • Typography

    Inter scale with rendered samples. Display, headline, body, label — when to use each, what letter spacing to apply.

  • Spacing & Elevation

    The spacing scale, surface tier ladder, shadow tokens, and the "tonal layering" approach to depth.

  • Components

    Every reusable UI primitive in components/ui/ — what it does, when to reach for it, what variants exist.

  • Motion

    Easing curves, durations, and the rules for transitions, hover states, and entrances.

  • Accessibility

    Contrast ratios on the actual palette, focus rules, tap targets, screen reader expectations.

Who this is for

Audience What to read first
Frontend engineer adding a component Components + Color
Designer or PM scoping a new flow Brand + Color + Typography
Anyone shipping an email or marketing page Brand + Color
Anyone reviewing a PR for "does this feel like Tomoda?" Brand

How this differs from the frontend docs

This section answers what — what the design language is, what tokens exist, what variants are sanctioned. The Frontend section answers how — how theming is wired, how the useTheme() hook works, how to compose a stylesheet factory. Read this section to decide what to build; read Frontend to find the API to build it with.

Single source of truth

Every concrete token on this page is derived from frontend/constants/Themes.ts and the file siblings (Colors.ts, MapStyles.ts). When you change a token in code, update the matching section here in the same PR — see CLAUDE.md for the rule.