Design Tokens

Design tokens are the visual atoms of our design system. They are named entities that store visual design attributes, such as colors, typography, and spacing. This system ensures consistency across the application while allowing for high levels of customization and theming.

Core Concepts

The system is built on a layered architecture:

1. Primitives: Raw values (e.g., hex codes, pixel values).
2. Semantic Tokens: Tokens with specific meaning (e.g., primary, background, success).
3. Themes: Bundles of semantic tokens that define a specific look and feel (e.g., Modern, Retro, Cozy, Paper).

Usage in Flutter

To access design tokens in your widgets, use the designTokensProvider.

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import '../providers/theme_provider.dart';

class MyWidget extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final tokens = ref.watch(designTokensProvider);

    return Container(
      color: tokens.background,
      padding: EdgeInsets.all(tokens.spacingMd),
      child: Text(
        'Hello World',
        style: tokens.bodyPrimary.copyWith(color: tokens.primary),
      ),
    );
  }
}

Theme Variants

Our system supports multiple themes, each with its own personality:

Dynamic Customization

The design tokens system is highly dynamic and responds to user preferences:

Accent Colors

Users can choose a custom accent color (Emerald, Blue, Indigo, etc.) which overrides the theme's default primary color. In the Paper theme, this also influences the surface and border tints.

Appearance Modes

• Light Mode: High-key color schemes.
• Dark Mode: Low-key, battery-saving color schemes.
• System: Automatically follows the device's brightness setting.

Spacing Modes

• Comfortable: Default spacing for a relaxed, airy UI.
• Compact: Approximately 70-80% of comfortable spacing, ideal for data-dense interfaces.

Typography Adjustments

• Bold Text: A global toggle that adds FontWeight.bold to all primary and secondary text styles.
• Text Scale: Adjusts the global font scale factor.

Implementation Details

The core logic resides in lib/components/utils/design_tokens.dart and lib/providers/theme_provider.dart.

• DesignTokens: The data class holding all token values.
• AppThemeRegistry: Handles the mapping between themes/brightness and specific DesignTokens instances.
• designTokensProvider: A Riverpod provider that computes the final tokens based on all active modifiers (theme, brightness, accent color, compact mode, etc.).

Adding New Tokens

To add a new token:

1. Add the field to the DesignTokens class.
2. Update the constructor and copyWith method.
3. Provide values for all theme instances (e.g., modernLightTokens, modernDarkTokens, etc.) in design_tokens.dart.
4. If it's a spacing token, update _applyCompactSpacing in AppThemeRegistry.