---
title: "Design system"
description: "Stage 2: where the system lives (tokens.css, tokens.md, base.css) and the token source."
source: "design/system/design-system.md"
---

> Part of [Brand and design](/design/llms.txt). Every page: [llms.txt](/llms.txt).

# Design system: Shuke

Stage 2 of the design process (botgumi ADR-0004). The system exists and is in use by every board in the gallery;
it was chosen before the botgumi gates existed, so its design-system gate is retroactive and pending
(`../README.md`). This page points at the files that hold it.

- Values: [`../tokens.css`](/design/tokens.css), the source the HTML boards use.
- Explanation and the SwiftUI mapping, 1:1: [`../tokens.md`](/design/tokens/index.md).
- Template shape: `tokens.source.json`, the same values in the four groups `design/check.mjs` and
  `@botgumi/design-tokens` read. Generated by `python3 design/tools/tokens_source.py` from `tokens.css`; the two must
  stay in step (`--check` verifies it). Names map from the CSS custom properties: `--color-accent-primary` →
  `color.accentPrimary`, `--space-4` → `space.s4`, `--size-cta-height` → `space.sizeCtaHeight`, `--radius-card` →
  `radius.card`, `--type-headline-*` → `typography.headline`.
- Components: [`../base.css`](/design/base.css) and [`../base.js`](/design/base.js) (the shared components and the viewer),
  with the SwiftUI component map in [`../ios-handoff.md`](/design/ios-handoff/index.md).

## Options shown at the gate

None were drawn as alternatives: the visual language was carried over from the product prototype and polished
(`../README.md`, "Visual language"). The retroactive gate reviews the system as it is.

## Colour

`../tokens.md` §1: roles and their limits (coral only for the primary action and live recording, lime only for
rewards), text contrast on every ground, score bands that are never red, dimension and topic colours. Light and
dark values per token; the Increase Contrast overrides live only in `tokens.css`.

## Type

`../tokens.md` §2: fourteen text styles mapped to iOS text styles, Avenir Next for UI and PingFang SC for article
bodies (Latin bodies switch family and leading per article language), Dynamic Type rules tested at 100, 120 and
135 %. `tokens.source.json` carries each style's family, size, weight and line height; the `eyebrow` style is
described in `tokens.md` only.

## Space and radius

`../tokens.md` §3–4: the 4 pt grid (`s1` to `s16`, `gutter`, `section`), the sizes (hit target, CTA, record button
and ring, bars, safe areas) and the radius scale (`xs` to `xl`, `pill`, with `card` = `lg` and `button` = `md`).

## Components

`../base.css` holds the components; `../ios-handoff.md` maps each to SwiftUI with its states. The per-screen
"Tokens used" tables in `../hifi/<ID>/screen.md` are derived from the classes each board uses.

| Component | States | Tokens |
|---|---|---|
| see `../ios-handoff.md` | default, pressed, disabled, loading (per component there) | derived per screen in `../hifi/<ID>/screen.md` |

## Motion

`../tokens.md` §6–7: durations, curves, the recording breath, what reduced motion turns off, and the haptic per
moment. Motion tokens have no group in `tokens.source.json`; they live in `tokens.css` and `tokens.md`.