fernctl/domain/tokens/typography.rs
1//! # Typography Tokens
2//!
3//! This module provides type-safe typography tokens for font families and
4//! size scales used throughout the Fern design system.
5//!
6//! ## Font Categories
7//!
8//! Fern uses three font categories:
9//!
10//! | Category | Purpose | Default |
11//! |----------|---------|---------|
12//! | Primary | UI text, labels | Inter |
13//! | Monospace | Code, terminal icons | JetBrainsMono Nerd Font |
14//! | Icon | Material icons | Material Symbols Rounded |
15//!
16//! ## Font Size Scale
17//!
18//! Font sizes follow a semantic scale rather than arbitrary pixel values:
19//!
20//! | Token | Pixels | Use Case |
21//! |-------|--------|----------|
22//! | `Xs` | 10px | Captions, legal text |
23//! | `Sm` | 12px | Labels, secondary text |
24//! | `Md` | 14px | Body text (default) |
25//! | `Lg` | 16px | Subheadings |
26//! | `Xl` | 20px | Headings |
27//! | `Xxl` | 24px | Large headings |
28
29use serde::{Deserialize, Serialize};
30use std::fmt;
31
32/// A font family specification.
33///
34/// `FontFamily` represents a font family name that can be used in the UI.
35/// It stores the family name as a string and provides validation.
36///
37/// # Example
38///
39/// ```rust
40/// use fernctl::domain::tokens::typography::FontFamily;
41///
42/// let font = FontFamily::new("Inter");
43/// assert_eq!(font.name(), "Inter");
44/// ```
45#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
46#[serde(transparent)]
47pub struct FontFamily {
48 name: String,
49}
50
51impl FontFamily {
52 /// Creates a new font family from a name.
53 ///
54 /// # Arguments
55 ///
56 /// * `name` — The font family name (e.g., "Inter", "JetBrainsMono Nerd Font")
57 ///
58 /// # Example
59 ///
60 /// ```rust
61 /// use fernctl::domain::tokens::typography::FontFamily;
62 ///
63 /// let font = FontFamily::new("Inter");
64 /// ```
65 #[must_use]
66 pub fn new(name: impl Into<String>) -> Self {
67 Self { name: name.into() }
68 }
69
70 /// Returns the font family name.
71 ///
72 /// # Example
73 ///
74 /// ```rust
75 /// use fernctl::domain::tokens::typography::FontFamily;
76 ///
77 /// let font = FontFamily::new("Inter");
78 /// assert_eq!(font.name(), "Inter");
79 /// ```
80 #[must_use]
81 pub fn name(&self) -> &str {
82 &self.name
83 }
84
85 /// Returns the default primary (UI) font family.
86 ///
87 /// # Example
88 ///
89 /// ```rust
90 /// use fernctl::domain::tokens::typography::FontFamily;
91 ///
92 /// let font = FontFamily::default_primary();
93 /// assert_eq!(font.name(), "Inter");
94 /// ```
95 #[must_use]
96 pub fn default_primary() -> Self {
97 Self::new("Inter")
98 }
99
100 /// Returns the default monospace font family.
101 ///
102 /// # Example
103 ///
104 /// ```rust
105 /// use fernctl::domain::tokens::typography::FontFamily;
106 ///
107 /// let font = FontFamily::default_mono();
108 /// assert_eq!(font.name(), "JetBrainsMono Nerd Font");
109 /// ```
110 #[must_use]
111 pub fn default_mono() -> Self {
112 Self::new("JetBrainsMono Nerd Font")
113 }
114
115 /// Returns the default icon font family.
116 ///
117 /// # Example
118 ///
119 /// ```rust
120 /// use fernctl::domain::tokens::typography::FontFamily;
121 ///
122 /// let font = FontFamily::default_icon();
123 /// assert_eq!(font.name(), "Material Symbols Rounded");
124 /// ```
125 #[must_use]
126 pub fn default_icon() -> Self {
127 Self::new("Material Symbols Rounded")
128 }
129}
130
131impl Default for FontFamily {
132 fn default() -> Self {
133 Self::default_primary()
134 }
135}
136
137impl fmt::Display for FontFamily {
138 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
139 write!(f, "{}", self.name)
140 }
141}
142
143impl From<&str> for FontFamily {
144 fn from(s: &str) -> Self {
145 Self::new(s)
146 }
147}
148
149impl From<String> for FontFamily {
150 fn from(s: String) -> Self {
151 Self::new(s)
152 }
153}
154
155/// Font size scale with semantic sizes.
156///
157/// This enum represents the available font sizes in the design system.
158/// Using semantic names rather than pixel values ensures consistency
159/// and makes it easy to adjust the entire scale.
160///
161/// # Example
162///
163/// ```rust
164/// use fernctl::domain::tokens::typography::FontSize;
165///
166/// let size = FontSize::Md;
167/// assert_eq!(size.pixels(), 14);
168/// ```
169#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
170#[serde(rename_all = "lowercase")]
171pub enum FontSize {
172 /// Extra-small (10px) — Captions, legal text
173 Xs,
174 /// Small (12px) — Labels, secondary text
175 Sm,
176 /// Medium (14px) — Body text (default)
177 Md,
178 /// Large (16px) — Subheadings
179 Lg,
180 /// Extra-large (20px) — Headings
181 Xl,
182 /// Double extra-large (24px) — Large headings
183 Xxl,
184}
185
186impl FontSize {
187 /// Returns the size in pixels.
188 ///
189 /// # Example
190 ///
191 /// ```rust
192 /// use fernctl::domain::tokens::typography::FontSize;
193 ///
194 /// assert_eq!(FontSize::Xs.pixels(), 10);
195 /// assert_eq!(FontSize::Sm.pixels(), 12);
196 /// assert_eq!(FontSize::Md.pixels(), 14);
197 /// assert_eq!(FontSize::Lg.pixels(), 16);
198 /// assert_eq!(FontSize::Xl.pixels(), 20);
199 /// assert_eq!(FontSize::Xxl.pixels(), 24);
200 /// ```
201 #[must_use]
202 pub const fn pixels(&self) -> u16 {
203 match self {
204 Self::Xs => 10,
205 Self::Sm => 12,
206 Self::Md => 14,
207 Self::Lg => 16,
208 Self::Xl => 20,
209 Self::Xxl => 24,
210 }
211 }
212
213 /// Returns the semantic name of this size.
214 ///
215 /// # Example
216 ///
217 /// ```rust
218 /// use fernctl::domain::tokens::typography::FontSize;
219 ///
220 /// assert_eq!(FontSize::Md.name(), "md");
221 /// ```
222 #[must_use]
223 pub const fn name(&self) -> &'static str {
224 match self {
225 Self::Xs => "xs",
226 Self::Sm => "sm",
227 Self::Md => "md",
228 Self::Lg => "lg",
229 Self::Xl => "xl",
230 Self::Xxl => "xxl",
231 }
232 }
233
234 /// Creates a font size from its name.
235 ///
236 /// # Example
237 ///
238 /// ```rust
239 /// use fernctl::domain::tokens::typography::FontSize;
240 ///
241 /// assert_eq!(FontSize::from_name("md"), Some(FontSize::Md));
242 /// assert_eq!(FontSize::from_name("invalid"), None);
243 /// ```
244 #[must_use]
245 pub fn from_name(name: &str) -> Option<Self> {
246 match name.to_lowercase().as_str() {
247 "xs" => Some(Self::Xs),
248 "sm" => Some(Self::Sm),
249 "md" => Some(Self::Md),
250 "lg" => Some(Self::Lg),
251 "xl" => Some(Self::Xl),
252 "xxl" => Some(Self::Xxl),
253 _ => None,
254 }
255 }
256
257 /// Returns all font sizes in order from smallest to largest.
258 #[must_use]
259 pub const fn all() -> &'static [FontSize] {
260 &[
261 Self::Xs,
262 Self::Sm,
263 Self::Md,
264 Self::Lg,
265 Self::Xl,
266 Self::Xxl,
267 ]
268 }
269}
270
271impl Default for FontSize {
272 fn default() -> Self {
273 Self::Md
274 }
275}
276
277impl fmt::Display for FontSize {
278 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
279 write!(f, "{}px", self.pixels())
280 }
281}
282
283/// Complete font size scale with pixel values.
284///
285/// While [`FontSize`] provides semantic names, `FontSizeScale` allows
286/// customizing the actual pixel values via configuration.
287///
288/// # Example
289///
290/// ```rust
291/// use fernctl::domain::tokens::typography::FontSizeScale;
292///
293/// let scale = FontSizeScale::default();
294/// assert_eq!(scale.md, 14);
295/// ```
296#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
297pub struct FontSizeScale {
298 /// Extra-small size in pixels.
299 #[serde(default = "default_xs")]
300 pub xs: u16,
301 /// Small size in pixels.
302 #[serde(default = "default_sm")]
303 pub sm: u16,
304 /// Medium size in pixels.
305 #[serde(default = "default_md")]
306 pub md: u16,
307 /// Large size in pixels.
308 #[serde(default = "default_lg")]
309 pub lg: u16,
310 /// Extra-large size in pixels.
311 #[serde(default = "default_xl")]
312 pub xl: u16,
313 /// Double extra-large size in pixels.
314 #[serde(default = "default_xxl")]
315 pub xxl: u16,
316}
317
318fn default_xs() -> u16 {
319 FontSize::Xs.pixels()
320}
321fn default_sm() -> u16 {
322 FontSize::Sm.pixels()
323}
324fn default_md() -> u16 {
325 FontSize::Md.pixels()
326}
327fn default_lg() -> u16 {
328 FontSize::Lg.pixels()
329}
330fn default_xl() -> u16 {
331 FontSize::Xl.pixels()
332}
333fn default_xxl() -> u16 {
334 FontSize::Xxl.pixels()
335}
336
337impl FontSizeScale {
338 /// Creates a new font size scale with default values.
339 #[must_use]
340 pub const fn new() -> Self {
341 Self {
342 xs: 10,
343 sm: 12,
344 md: 14,
345 lg: 16,
346 xl: 20,
347 xxl: 24,
348 }
349 }
350
351 /// Returns the pixel value for a given semantic size.
352 #[must_use]
353 pub const fn get(&self, size: FontSize) -> u16 {
354 match size {
355 FontSize::Xs => self.xs,
356 FontSize::Sm => self.sm,
357 FontSize::Md => self.md,
358 FontSize::Lg => self.lg,
359 FontSize::Xl => self.xl,
360 FontSize::Xxl => self.xxl,
361 }
362 }
363}
364
365impl Default for FontSizeScale {
366 fn default() -> Self {
367 Self::new()
368 }
369}
370
371/// Typography configuration combining fonts and sizes.
372///
373/// This struct contains all typography-related settings for the theme.
374///
375/// # Example
376///
377/// ```rust
378/// use fernctl::domain::tokens::typography::Typography;
379///
380/// let typography = Typography::default();
381/// assert_eq!(typography.family.name(), "Inter");
382/// assert_eq!(typography.size.md, 14);
383/// ```
384#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
385pub struct Typography {
386 /// Primary (UI) font family.
387 #[serde(default = "FontFamily::default_primary")]
388 pub family: FontFamily,
389 /// Monospace font family.
390 #[serde(default = "FontFamily::default_mono")]
391 pub mono: FontFamily,
392 /// Icon font family.
393 #[serde(default = "FontFamily::default_icon")]
394 pub icon: FontFamily,
395 /// Font size scale.
396 #[serde(default)]
397 pub size: FontSizeScale,
398}
399
400impl Typography {
401 /// Creates typography configuration with default values.
402 #[must_use]
403 pub fn new() -> Self {
404 Self {
405 family: FontFamily::default_primary(),
406 mono: FontFamily::default_mono(),
407 icon: FontFamily::default_icon(),
408 size: FontSizeScale::default(),
409 }
410 }
411}
412
413impl Default for Typography {
414 fn default() -> Self {
415 Self::new()
416 }
417}
418
419#[cfg(test)]
420mod tests {
421 use super::*;
422
423 #[test]
424 fn font_family_creation() {
425 let font = FontFamily::new("Test Font");
426 assert_eq!(font.name(), "Test Font");
427 }
428
429 #[test]
430 fn font_family_defaults() {
431 assert_eq!(FontFamily::default_primary().name(), "Inter");
432 assert_eq!(
433 FontFamily::default_mono().name(),
434 "JetBrainsMono Nerd Font"
435 );
436 assert_eq!(FontFamily::default_icon().name(), "Material Symbols Rounded");
437 }
438
439 #[test]
440 fn font_size_pixels() {
441 assert_eq!(FontSize::Xs.pixels(), 10);
442 assert_eq!(FontSize::Sm.pixels(), 12);
443 assert_eq!(FontSize::Md.pixels(), 14);
444 assert_eq!(FontSize::Lg.pixels(), 16);
445 assert_eq!(FontSize::Xl.pixels(), 20);
446 assert_eq!(FontSize::Xxl.pixels(), 24);
447 }
448
449 #[test]
450 fn font_size_from_name() {
451 assert_eq!(FontSize::from_name("md"), Some(FontSize::Md));
452 assert_eq!(FontSize::from_name("XL"), Some(FontSize::Xl));
453 assert_eq!(FontSize::from_name("invalid"), None);
454 }
455
456 #[test]
457 fn font_size_scale_get() {
458 let scale = FontSizeScale::default();
459 assert_eq!(scale.get(FontSize::Md), 14);
460 assert_eq!(scale.get(FontSize::Xl), 20);
461 }
462
463 #[test]
464 fn typography_serialization() {
465 let typography = Typography::default();
466 let json = serde_json::to_string(&typography).unwrap();
467 let restored: Typography = serde_json::from_str(&json).unwrap();
468 assert_eq!(typography.family, restored.family);
469 }
470}