# Chanora Design Tokens — Material 3 Baseline

**Version:** 0.9.2
**Status:** Baseline Candidate  
**Language:** English

**Repo path:** `docs/ui-ux/material3-design-tokens.md`  ---

## 1. Token Strategy

Chanora uses Material 3 tokens as the foundation and adds Chanora semantic tokens for voice-client-specific states.

```text
Material 3 ColorScheme / TextTheme / Shape / Motion
  -> Chanora Semantic Tokens
  -> Chanora Components
  -> Feature Screens
```

## 2. Token Groups

| Group | Purpose |
|---|---|
| `chanora.color.connection.*` | Connection status |
| `chanora.color.voice.*` | Voice states |
| `chanora.color.latency.*` | Latency and packet-loss status |
| `chanora.color.diagnostics.*` | Diagnostic severity |
| `chanora.spacing.*` | Layout spacing |
| `chanora.shape.*` | Corners and component shapes |
| `chanora.motion.*` | Motion duration and reduced-motion behavior |
| `chanora.density.*` | Mobile, tablet, desktop density |
| `chanora.typography.*` | Product role mapping to Material type roles |

## 3. Color Tokens

| Token | Purpose |
|---|---|
| `chanora.color.connection.connected` | Connected state |
| `chanora.color.connection.connecting` | Connection in progress |
| `chanora.color.connection.reconnecting` | Recovering connection |
| `chanora.color.connection.disconnected` | Disconnected state |
| `chanora.color.connection.error` | Connection failure |
| `chanora.color.voice.speaking` | User is speaking |
| `chanora.color.voice.muted` | Microphone muted |
| `chanora.color.voice.deafened` | Output deafened |
| `chanora.color.voice.pttActive` | Push-to-talk active |
| `chanora.color.latency.good` | Good latency |
| `chanora.color.latency.warning` | Warning latency |
| `chanora.color.latency.bad` | Bad latency |
| `chanora.color.diagnostics.info` | Informational diagnostic |
| `chanora.color.diagnostics.warning` | Warning diagnostic |
| `chanora.color.diagnostics.error` | Error diagnostic |

## 4. Typography Mapping

| Product role | Material 3 type role |
|---|---|
| App title | `headlineSmall` |
| Server name | `titleLarge` |
| Channel name | `bodyLarge` |
| Client nickname | `bodyLarge` |
| Status secondary text | `bodyMedium` |
| Diagnostic metadata | `bodySmall` |
| Button label | `labelLarge` |
| Badge label | `labelMedium` |

## 5. Spacing Tokens

| Token | Value |
|---|---:|
| `chanora.spacing.xs` | 4 |
| `chanora.spacing.sm` | 8 |
| `chanora.spacing.md` | 12 |
| `chanora.spacing.lg` | 16 |
| `chanora.spacing.xl` | 24 |
| `chanora.spacing.2xl` | 32 |

## 6. Shape Tokens

| Token | Use |
|---|---|
| `chanora.shape.sm` | Small chips, compact controls |
| `chanora.shape.md` | Cards and list containers |
| `chanora.shape.lg` | Panels and navigation surfaces |
| `chanora.shape.xl` | Dialogs and sheets |
| `chanora.shape.full` | Pills, badges, icon buttons |

## 7. Motion Tokens

| Token | Purpose |
|---|---|
| `chanora.motion.quick` | Small feedback |
| `chanora.motion.standard` | Normal UI transition |
| `chanora.motion.emphasized` | Major layout transition |
| `chanora.motion.reduced` | Reduced-motion fallback |

## 8. Flutter Implementation Requirement

Tokens should be exposed through `ThemeData`, `ColorScheme`, component themes, and `ThemeExtension`. Feature screens shall not hardcode product semantic token values.

## 9. Change History

| Version | Date | Description |
|---|---|---|
| 0.1.0 | 2026-05-14 | Initial design token baseline. |


## Baseline Candidate 0.9.1 Update

| Version | Date | Description |
|---|---|---|
| 0.9.1 | 2026-05-14 | Updated baseline after product decision closure: Apple App Store SDK gate uses Xcode 26+ and iOS 26 / iPadOS 26 SDK+ since 2026-04-28, platform baselines and decision traceability propagated across the document set. |


## Baseline Candidate 0.9.2 Update

| Version | Date | Description |
|---|---|---|
| 0.9.2 | 2026-05-14 | Corrected Apple App Store Connect upload gate to 2026-04-28 and checked full-package naming, references, and coverage. |