---
version: alpha
name: Toshi
description: >
  Design system for toshi.com.au (Toshi Shopify theme, base: Symmetry).
  Machine-readable mirror of the theme's live tokens — see "Source of truth"
  in the Overview before editing anything here.
colors:
  background: "#FFFFFF"
  ink: "#5F5956"
  heading: "#5F5956"
  primary: "#736860"
  primary-hover: "#5F564F"
  on-primary: "#FFFFFF"
  link: "#916E4C"
  link-on-cream: "#82623F"
  cream: "#F8F5EE"
  taupe-soft: "#B7A6A1"
  sale-accent: "#807471"
  gold-soft: "#CFB091"
  success: "#52774A"
  overlay-scrim: "#000000"
typography:
  body:
    fontFamily: "Nunito, sans-serif"
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
  heading:
    fontFamily: "Merriweather, serif"
    fontSize: 40px
    fontWeight: 300
    fontStyle: italic
    letterSpacing: -0.04em
  heading-mobile:
    fontFamily: "Merriweather, serif"
    fontSize: 32px
    fontWeight: 300
    fontStyle: italic
    letterSpacing: -0.04em
  display:
    fontFamily: "Merriweather, serif"
    fontSize: 70px
    fontWeight: 300
    fontStyle: italic
    letterSpacing: -0.04em
  logo:
    fontFamily: "Nunito, sans-serif"
    fontSize: 24px
    fontWeight: 400
  nav:
    fontFamily: "Nunito, sans-serif"
    fontSize: 16px
    fontWeight: 400
  small:
    fontFamily: "Nunito, sans-serif"
    fontSize: 14px
    fontWeight: 400
  caption:
    fontFamily: "Nunito, sans-serif"
    fontSize: 12px
    fontWeight: 400
rounded:
  none: 0px
  tile: 6px
  card: 12px
  soft: 3px
  pill: 1.8em
spacing:
  pair: 6px
  label: 8px
  group: 14px
  gutter-mobile: 16px
  gutter-desktop: 20px
  gutter-large: 30px
  section: 50px
  section-large: 40px
  section-large-mobile: 60px
  section-largest: 110px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.pill}"
    typography: "{typography.body}"
  button-secondary:
    backgroundColor: "{colors.background}"
    textColor: "{colors.primary}"
    borderColor: "{colors.primary}"
    rounded: "{rounded.pill}"
    typography: "{typography.body}"
  link:
    textColor: "{colors.link}"
  input:
    backgroundColor: "{colors.background}"
    textColor: "{colors.ink}"
    rounded: "{rounded.soft}"
  size-tile:
    rounded: "{rounded.tile}"
  card:
    rounded: "{rounded.card}"
  footer:
    backgroundColor: "{colors.cream}"
    textColor: "{colors.ink}"
---

# Toshi Design System

## Overview

Toshi is an Australian D2C brand for organic baby and children's essentials
(sun hats, knitwear, clothing). The visual language is warm, calm and
editorial: white space, a muted taupe-and-cream palette drawn from the logo,
a light italic serif for headings against a rounded humanist sans for body
copy, and generous photography. Nothing is loud; buttons and accents sit
inside the same warm neutral family as the product imagery.

**Source of truth — read before editing.** These values are a *mirror*, not
a master. Colours and fonts are set in Shopify **Theme settings** (Admin →
Online Store → Themes → Customize) and rendered into CSS custom properties
by `snippets/doc-head-styles.liquid`; net-new custom tokens live in
`assets/toshi-custom.css` (`:root` block, `--sf-*`). If this file disagrees
with those, *those win* — and this file must be updated in the same change
that turns any Theme settings dial. Values here reflect the **Dev theme**
as of 2026-07-11 (LIVE untouched; see AGENTS.md).

| DESIGN.md token | CSS custom property | Theme setting key |
| --- | --- | --- |
| `colors.background` | `--body-bg-color` | `bg_col` |
| `colors.ink` | `--text-color` | `font_col_base` |
| `colors.heading` | `--heading-color` | `font_col_heads` |
| `colors.primary` | `--btn-bg-color` | `btn_color` |
| `colors.on-primary` | `--btn-text-color` | `btn_color_text` |
| `colors.link` | `--link-color` | `font_col_link` |
| `colors.cream` | `--footer-bg-col` / scheme 1 | `foot_bg_col`, `color_scheme_1_col` |
| `colors.taupe-soft` | `--footer-divider-col` | `foot_divider_col` |
| `colors.sale-accent` | `--product-label-sale-text` | `prod_label_sale_text` |
| `colors.gold-soft` | `--rating-star-color`, `--main-nav-link-featured-col` | `prod_rating_star`, `nav_featured_col` |
| `colors.success` | `--success-text-color` (RGB triple `82 119 74`) | theme token; value overridden in `toshi-custom.css` |
| `rounded.tile` / `rounded.card` | `--sf-tile-radius` / `--sf-card-radius` | — net-new, `toshi-custom.css` |
| `rounded.pill` | `--btn-border-radius` | `button_shape: fullyround` |
| typography sizes | `--base-text-size` … `--super-large-text-size` | `font_size_*_int` |
| spacing (gutters/sections) | `--gutter-*`, `--*-section-padding` | static in `doc-head-styles.liquid` |

## Colors

The palette is the logo, expanded. Everything sits on white.

> [!CAUTION]
> **UPF BADGE COLOUR REQUIRES CHANGE BEFORE APPROVAL.** The current UPF badge
> background is hardcoded `#FFB236` in `snippets/upf-badge.liquid`, with white
> `#FFFFFF` text. That pairing is only **1.80:1** and fails WCAG AA's **4.5:1**
> requirement for the smaller "sun safety" copy. Existing brand ink
> `#5F5956` also fails on this orange at **3.83:1**. Do not add `#FFB236` as an
> approved design token or reuse it for text-bearing UI. The badge needs a new,
> approved background/text pairing that reaches at least 4.5:1; once selected,
> replace the hardcoded colour with a named token and update this document.

- **Background `#FFFFFF`** — the page. All contrast ratios below are
  measured against it unless stated.
- **Ink `#5F5956`** — body text *and* headings (6.9:1). One ink; hierarchy
  comes from the typeface change, not colour.
- **Primary `#736860` (logo taupe)** — buttons and primary actions only,
  always with white text (5.4:1). Decided 2026-07-07: the exact logo taupe
  `#999089` fails white text (3.13:1), so this is the same hue darkened
  just enough to pass.
- **Primary hover `#5F564F`** — the taupe darkened ~8% (the theme's own
  tertiary-derivation step); white text 6.8:1. Added 2026-07-11: hover had
  been set equal to the base, leaving primary buttons with no hover
  feedback at all (`.btn:hover` relies entirely on the hover tokens).
- **Link `#916E4C` (gold)** — inline links and nav hover. **Deliberately
  different from buttons** (4.6:1) so links keep a distinct accent. Do not
  re-unify links and buttons — that decision was made and reversed once
  already.
- **Link on cream `#82623F`** — the gold darkened until it passes on the
  cream surface (5.1:1; the standard gold only reaches 4.25:1 there).
  Minted 2026-07-11 for colour scheme 1's links, replacing the retired
  pink-taupe `#B7A6A1`; currently dormant (no page uses scheme 1). It is
  the approved value for any future links-on-cream need.
- **Cream `#F8F5EE`** — the brand's quiet supporting surface: announcement
  bar, footer background, breadcrumb bar, callout panels, tertiary buttons,
  and selected size-finder cards. Cream does not mean "selected" by itself;
  component context, labels, borders, check marks and control state communicate
  meaning. (The near-duplicate warm-white `#FBF9F4` that scheme-1's
  secondary-button background carried was collapsed into cream on 2026-07-13 —
  cream is the only quiet surface.)
- **Taupe-soft `#B7A6A1`** — decorative only: the footer divider (its last
  remaining job as of 2026-07-11 — sale text and scheme-1 links moved off
  it). Fails text contrast (2.3:1); never use it for copy that must be read.
- **Sale-accent `#807471`** — sale/"was" price text and the price-label
  "Sale" flag (`prod_label_sale_text`): the old taupe-soft darkened until
  it passes (4.5:1). Applied 2026-07-11 after sitting as the style guide's
  oldest open proposal since 2026-07-05.
- **Gold-soft `#CFB091`** — the original brand gold, now decorative only:
  rating stars (aria-hidden), featured-nav accent, and (since 2026-07-11)
  the size-finder selected-card border and "size up" status dot — all read
  `--rating-star-color`, so the review stars and the selection tan share
  one Theme settings dial (`prod_rating_star`). Turning that dial moves
  all of them together. Fails text contrast (2.0:1); never for copy, and
  never the sole indicator of a state (the selected card also gets the
  cream fill and a check mark).
- **Success `#52774A`** — the only "system" colour, for the size finder
  and delivery ladder plus the theme's own success states (pickup icons,
  signup alerts). Lives on the *theme's* token `--success-text-color`
  (stock Symmetry ships Shopify green `16 128 67`; `toshi-custom.css`
  overrides it to the brand sage — one success token everywhere). An RGB
  triple, so it composes: `rgb(var(--success-text-color) / 0.08)` for
  tints. Reuse it for any success state; do not mint another green.
- **Muted text** is not a colour — it's opacity on ink:
  `rgb(var(--text-color) / 0.85)`. 0.85 (`--muted-text-alpha`) is the WCAG
  floor on white; 0.7 measured 3.38:1 and fails. Dividers use the same
  recipe at `--divider-opacity` (0.14).

Both alternate colour schemes are currently **unused** (decided
2026-07-11: the Returns page — scheme 1's last user — moved to the
default scheme). Scheme 1 (cream) was harmonised with the main palette
the same day and left dormant: buttons on the primary taupe, links on
`{colors.link-on-cream}` — so if a section is ever set to scheme 1 in
the editor it renders on-brand. Scheme 2 (`#FCFAF6` / `#232323` /
`#BF570A` orange link) is untouched legacy; don't use it. Prefer the
default scheme; use the cream `{colors.cream}` as a *surface* (footer,
callouts) rather than via a scheme.

## Typography

Two families, strongly contrasted:

- **Body — Nunito 400**, 16px, line-height 1.6. Also the logo (24px) and
  nav (16px) face. Bold weights (600–700) for emphasis, price, labels.
- **Headings — Merriweather Light Italic (300)**, 40px desktop / 32px
  mobile, letter-spacing −0.04em. The italic serif *is* the brand voice;
  headings are not uppercased (`capitalize_headings: false`).

Size scale (derived from the 16px base in `doc-head-styles.liquid` —
change `font_size_base_int` and the scale moves together):

| Step | Size | Use |
| --- | --- | --- |
| display | 70px | hero overlays (`--super-large-text-size`) |
| heading | 40px | section/page headings |
| heading-mobile | 32px | headings under 768px |
| body / input / button / nav | 16px | default; inputs never below 16px (iOS zoom) |
| small | 14px | secondary copy (`--smaller-text-size-2`) |
| 13px | 13px | fine print (`--smaller-text-size-1/3`) |
| caption | 12px | the floor (`--smaller-text-size-4`); nothing below 12px |

## Layout

- **Page container 2200px** (`max_page_width`), full-width layout enabled;
  long-form copy constrained to **720px** (`--reading-container-width`).
- **Gutters:** 16px mobile / 20px desktop / 30px large
  (`--gutter-mobile/desktop/large`).
- **Vertical rhythm:** section padding 50px default; 40px "larger" desktop /
  60px mobile; 110px "largest" (`--*-section-padding`).
- **Micro-spacing** (size-finder rule, reuse for any dense component):
  **6px** between paired elements, **8px** label→control, **14px** between
  groups. Compose these from the theme spacing variables (`--gutter-*`,
  `--input-btn-padding-*`) rather than adding one-off component spacing
  values.
- **Breakpoint:** one seam at **768px** (mobile ↔ desktop). Full-bleed
  imagery on mobile becomes inset (and rounded) from 768px up.

## Elevation & Depth

Toshi is flat. There is no shadow scale — hierarchy comes from whitespace,
the cream-vs-white surface swap, and hairline dividers
(`rgb(var(--text-color) / 0.14)`). The only depth effects are photographic:
text-over-image overlays use a black scrim at 24% opacity
(`--image-overlay-bg`), a 32% gradient shadow for edge legibility, and 88%
opacity boxed text panels. Do not introduce drop shadows on cards, buttons
or modals; use a divider or a cream surface instead.

## Shapes

Four active shapes in one site-wide rounding ladder (user decision
2026-07-09) — pick by role, never by taste:

| Radius | Token | Role |
| --- | --- | --- |
| 0 | — | full-bleed media (mobile PDP gallery, hero images) |
| 6px | `--sf-tile-radius` | interactive tiles: age chips, size cards, swatch tiles, modal images |
| 12px | `--sf-card-radius` | inset imagery & card surfaces: tip cards, PDP gallery ≥768px, homepage inset images |
| pill (1.8em) | `--btn-border-radius` | CTA buttons only (from `button_shape: fullyround`) |

**Legacy compatibility:** `--btn-inspired-border-radius` remains at 3px for
older theme swatches. Do not use it for new components.

**Nesting rule:** an element is never rounder than its container.
Don't hard-code radii; point at the tokens.

## Components

- **Primary button** — taupe `{colors.primary}` fill, white text, pill.
  Hover darkens to `{colors.primary-hover}` (`btn_color_hover`); the
  theme's `.btn:hover` relies entirely on the hover tokens, so hover must
  never be set equal to the base. Normal case, 16px, 13px vertical
  padding.
- **Secondary button** — white fill, taupe text *and* border, pill. (Theme
  settings: `btn_alt_bg` white, `btn_alt_text` `#736860`.)
- **Tertiary button** — solid cream `{colors.cream}` fill with ink text: a
  quiet filled action, not a ghost button. The PDP size finder reuses this
  surface for selected cards, where the border, check mark and control state
  communicate selection; cream alone does not. Hover stays cream and gains a
  gold-soft border rather than escalating to the primary taupe fill. Related
  collection navigation uses the compact 14px text step and reduced padding because
  it is a set of navigation chips, not a primary call to action.
- **Links** — gold `{colors.link}`, no underline change by default; nav
  links are ink with gold hover.
- **Inputs** — white, ink text, 3px radius, border from the ink-mix recipe
  (25% rest / 55% hover / 100% active); 16px text minimum.
- **Product-card labels** — sale text sale-accent, sold-out ink,
  pre-order cream on ink; positioned top-right (`prod_block_label_loc`).
- **Product-card chips (boxed overlay labels)** — all quiet, one volume
  (decided 2026-07-11): the sale "%‑off" chip uses sale-accent
  `{colors.sale-accent}` with white text (4.5:1 AA), so it reads as a status
  label rather than a white button on PDP media. Its responsive rounding
  matches the UPF badge. Never show both on the same image: UPF takes priority,
  while the price row continues to communicate the sale.
- **Rating stars** — gold-soft, `aria-hidden`; the visible "4.8 / 5" text
  carries the information (this is what makes the low contrast exempt).
- **Size finder (PDP v3)** — age chips + size cards on `rounded.tile`,
  tip card on `rounded.card`, success states on `{colors.success}`;
  data contract in AGENTS.md. The expanded chart/how-to panel is informational,
  so it uses the white page surface with the theme's `--input-border-color`;
  the current chart row uses cream to carry the same selected-size state as the cards.
  “Most common” is dark-gold text (`--color-scheme-1-link-color`) without a
  separate banner fill; the selected tick uses the same accessible dark gold.
  Gold-soft is decorative and must not carry either readable indicator.
- **Callouts** — sizing-tip style: cream-family panel, 13px text, one
  shared snippet (`snippets/sizing-tip.liquid`); do not copy-paste the
  markup.

## Do's and Don'ts

**Do**
- Change colours/fonts in **Theme settings** (or add a real token) — one
  dial, everything follows. Then update this file in the same change.
- Check contrast on any new pairing: **4.5:1** for text (WCAG AA, and the
  Australian DDA baseline). Muted text = ink at 0.85 alpha, never a new
  grey hex.
- Use the rounding ladder by role; reuse `{colors.success}` for any
  success state.
- Keep image sources ≥2× their largest display size (retina); note
  `snippets/image.liquid` emits no srcset while `image_quality: "1"` —
  hand-roll 2× `<img>` for logos.
- Prefix net-new files/classes/tokens with `toshi-` / `.sf-` / `--sf-`
  (see AGENTS.md naming rule).

**Don't**
- Never type a hex into a section, snippet, app dashboard or `style`
  attribute. Every hardcoded value is drift: the 2026-07-05/06 audit
  repointed ~65–70 of them across ~18 files. If no token fits, that's a
  conversation, not a workaround.
- Don't re-unify links and buttons on one accent (decided 2026-07-07:
  buttons taupe, links gold).
- Don't use taupe-soft `#B7A6A1` or gold-soft `#CFB091` for readable text —
  they fail contrast; they are decoration.
- Don't add drop shadows; don't uppercase headings; don't set text below
  12px; don't round a child more than its parent.
- Don't push any of this to the LIVE theme — Dev theme only, until
  published deliberately.