fission-theme 0.1.0

Design tokens and theming for the Fission UI framework
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

# fission-theme

Design token system and component themes for the Fission UI framework.

This crate defines the complete visual language for Fission applications: colors, spacing, typography, corner radii, elevations (box shadows), and per-component theme overrides. It follows the Material Design 3 token architecture, where a small set of primitive tokens cascade into component-specific values.

## Architecture

```
Tokens (primitive design tokens)
  +-- ColorTokens       (primary, surface, error, text, border)
  +-- SpacingTokens      (none, xs, s, m, l, xl)
  +-- TypographyTokens   (label, body, heading sizes)
  +-- RadiusTokens       (small, medium, large, full)
  +-- ElevationTokens    (level0..level5 box shadows)
       |
       v
ComponentTheme (derived per-widget themes)
  +-- ButtonTheme
  +-- TextInputTheme
  +-- ModalTheme
  +-- TabsTheme
  +-- TooltipTheme
  +-- ... (13 component themes total)
       |
       v
Theme (top-level struct combining tokens + components)
```

Every component theme provides a `from_tokens()` constructor that derives all values from the primitive tokens. This means switching from light to dark mode is a single call to `Theme::dark()` -- all component values update automatically.

## Design tokens

### `ColorTokens`

| Token | Light default | Dark default | Purpose |
|-------|--------------|-------------|---------|
| `primary` | Purple 40 | Purple 80 | Primary interactive color |
| `on_primary` | White | Black | Text/icon on primary surfaces |
| `secondary` | Gray-purple | Teal | Secondary interactive color |
| `surface` | Near-white | Dark gray (30) | Card and container backgrounds |
| `background` | Near-white | Near-black (18) | Page background |
| `error` | Red | Pink-red | Error states |
| `border` | Light gray | Dark gray (60) | Borders and dividers |
| `text_primary` | Near-black | Light gray | Primary text color |
| `text_secondary` | Medium gray | Medium gray | Secondary/helper text |

### `SpacingTokens`

Standard spacing scale: `none` (0), `xs` (4), `s` (8), `m` (16), `l` (24), `xl` (32).

### `TypographyTokens`

Font size scale: `label_large_size` (15), `body_medium_size` (15), `body_large_size` (17), `heading_size` (28).

### `RadiusTokens`

Corner radius scale: `small` (4), `medium` (8), `large` (12), `full` (9999 -- fully rounded).

### `ElevationTokens`

Six elevation levels (0-5). Levels 0, 4, and 5 are `None` (no shadow). Levels 1-3 provide progressively stronger `BoxShadow` values with increasing blur and offset.

## Component themes

Each component theme struct holds the visual parameters that a specific widget reads during rendering. All are constructed from `Tokens` via `from_tokens()`.

| Theme struct | Used by | Key fields |
|-------------|---------|------------|
| `ButtonTheme` | `Button` | height, padding, radius, text size, elevation states, focus stroke |
| `TextInputTheme` | `TextInput` | height, padding, radius, font size, border/focus/text/placeholder colors |
| `ModalTheme` | `Modal` | background color, radius, shadow, max width |
| `TabsTheme` | `Tabs` | active/inactive colors, indicator height, background, divider |
| `BadgeTheme` | `Badge` | radius, font size |
| `AlertTheme` | `Alert` | per-severity background colors, radius |
| `ProgressTheme` | `ProgressBar` | height, track color, bar color |
| `TooltipTheme` | `Tooltip` | background, text color, radius, font size |
| `CalendarTheme` | `Calendar` | background, border, radius, selected/today colors |
| `PaginationTheme` | `Pagination` | spacing, active background/text |
| `TimelineTheme` | `Timeline` | dot size, line width, dot/line colors |
| `SegmentedControlTheme` | `SegmentedControl` | background, border, radius, active colors |
| `TreeViewTheme` | `TreeView` | indent, selected/hover backgrounds |

## Bundled fonts

The `fonts` module embeds two font files at compile time:

- `NOTO_SANS_REGULAR_TTF` -- Noto Sans Regular (the default)
- `INTER_24PT_REGULAR_TTF` -- Inter 24pt Regular

`default_font_bytes()` returns the Noto Sans bytes, used by the desktop shell to initialize the text measurement system.

## Usage

```rust
use fission_theme::{Theme, Tokens};

// Light theme (default)
let light = Theme::default();

// Dark theme
let dark = Theme::dark();

// Custom theme from modified tokens
let mut tokens = Tokens::default();
tokens.colors.primary = Color { r: 0, g: 120, b: 212, a: 255 }; // Blue
let custom = Theme {
    tokens: tokens.clone(),
    components: ComponentTheme::from_tokens(&tokens),
};
```

## Serialization

All types implement `Serialize` and `Deserialize` (via serde), so themes can be stored in JSON or any other serde-compatible format.