Design System & Tokens
Relevant source files
The following files were used as context for generating this wiki page:
The Trackurr Design System is a centralized collection of reusable components, semantic tokens, and stylistic guidelines that ensure visual consistency across the application. It is primarily housed within the Packages/DesignSystem module and serves as the single source of truth for UI styling, replacing hardcoded values with structured tokens.
Sources: CLAUDE.md:12, Packages/DesignSystem/Sources/DesignSystem/Tokens/ColorTokens.swift:1-5
Architecture & Module Structure
The design system is built as a shared Swift Package to be consumed by both the main app target and individual feature modules. This architecture promotes a modular approach where UI concerns are separated from business logic.
The diagram shows how the Design System package acts as a foundation for both shared UI components and specific feature modules.
Sources: CLAUDE.md:12-13, Packages/DesignSystem/Sources/DesignSystem/Extensions/Color+DS.swift:3-7
Semantic Color Tokens
Trackurr utilizes a semantic naming convention for colors via the DSColor enum. This layer abstracts system colors (like .systemBackground or .label) into purpose-driven tokens, allowing for easier maintenance and theme support.
Color Categories
| Token Category | Usage Description |
|---|---|
| Backgrounds | Layering surfaces (primary, secondary, tertiary, grouped). |
| Text | Hierarchy for labels (primary to quaternary). |
| Accent | Success, warning, destructive, and primary accent actions. |
| Components | UI elements like separators and various fill levels. |
Sources: Packages/DesignSystem/Sources/DesignSystem/Tokens/ColorTokens.swift:8-37
Implementation Detail
The system extends SwiftUI's Color type to provide a namespaced ds accessor, improving discoverability and call-site readability:
// Usage example
Text("Example")
.foregroundStyle(Color.ds.primaryText)
.background(Color.ds.secondaryBackground)
Sources: Packages/DesignSystem/Sources/DesignSystem/Extensions/Color+DS.swift:3-30
Typography & Spacing
Typography is standardized through the DSFont enum, which provides both standard Apple system scales and custom weighted variants.
Typography Scale
- Standard Scale: Maps directly to system styles like
.largeTitle,.headline, and.caption. - Weighted Variants: Provides pre-defined weights for specific UI needs, such as
titleBold(bold) andbodyBold(semibold).
Sources: Packages/DesignSystem/Sources/DesignSystem/Tokens/TypographyTokens.swift:6-26
Layout Tokens
Spacing and radius tokens follow a strict hierarchy to maintain rhythmic consistency:
- Spacing (
DSSpacing): Range fromxs(extra small) toxxl(extra-extra large). - Radius (
DSRadius): Fixed steps includingsmall,medium,large, andpillfor rounded components.
Sources: Packages/DesignSystem/Tests/DesignSystemTests/DesignSystemTests.swift:6-18
Design System Integrity
To ensure tokens remain correctly ordered and consistent, the project includes automated tests. These verify the logical progression of spacing and radius tokens, preventing accidental regressions in layout scale.
Verification flow for ensuring scale integrity in layout tokens.
Sources: Packages/DesignSystem/Tests/DesignSystemTests/DesignSystemTests.swift:6-18
Summary
The "Design System & Tokens" module provides the visual backbone for Trackurr. By utilizing semantic tokens for colors and typography, and strictly defined scales for layout, the system ensures that the application remains accessible, maintainable, and visually cohesive across its various feature modules.