archery-bookkeeper/lib/config/constants/_constants.md

constants configuration guide

This directory contains the application's centralized constants and configuration system, providing consistent theming and behavior across all components.

color scheme architecture

The archery bookkeeper uses a sophisticated color system built around the ScoringColorScheme class, which provides complete visual consistency for all scoring-related UI components.

available color schemes

traditional scheme (default):

• vibrant, high-contrast colors matching classic archery target rings
• bright gold for X/10/9 scores, vivid red for 8/7, bright blue for 6/5
• optimal for outdoor use and high visibility situations
• follows traditional archery color conventions

lowSaturation scheme:

• muted, eye-friendly colors for reduced strain during long sessions
• same color mapping but with reduced saturation and softer tones
• ideal for indoor use or extended practice sessions
• maintains accessibility while being easier on the eyes

color system architecture

Each color scheme defines explicit colors for:

• background colors: one for each score value (X, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, M, CLEAR)
• text colors: intentionally chosen for each background to ensure readability
• border colors: selection highlighting and default cell borders
• disabled states: greyed-out versions for inactive UI elements

This architecture ensures:

• visual consistency across all scoring widgets
• easy theme switching without code changes
• proper text contrast on all backgrounds
• seamless disabled state handling for conditional UI elements

switching color schemes

To change the active color scheme, edit the _currentScheme constant in scoring_colors.dart:

// Use traditional vibrant colors
static const ScoringColorScheme _currentScheme = traditional;

// Or switch to muted colors
static const ScoringColorScheme _currentScheme = lowSaturation;

The change applies instantly to all scoring components throughout the app.

disabled state system

The color system includes dedicated disabled state colors that automatically grey out inactive elements while maintaining visual hierarchy:

// Apply disabled styling to any widget
Container(
  decoration: BoxDecoration(
    color: ScoringColors.getDisabledBackground(),
    border: Border.all(
      color: ScoringColors.getDisabledBorder(),
      width: 1.0,
    ),
  ),
  child: Text(
    'Sum of 6',
    style: TextStyle(
      color: ScoringColors.getDisabledText(),
    ),
  ),
)

This is used extensively for the sum of 6 column, which remains visible but greyed out when in 3-arrow end mode.

usage patterns

basic color application

import 'package:archery_bookkeeper/config/constants/scoring_colors.dart';

// Get colors for any score value
Color backgroundColor = ScoringColors.getScoreBackgroundColor('X');
Color textColor = ScoringColors.getScoreTextColor('X');
bool shouldBeBold = ScoringColors.shouldUseBoldText('X');

// Apply to a widget
Container(
  decoration: BoxDecoration(
    color: backgroundColor,
    border: Border.all(
      color: ScoringColors.getBorderColor(isSelected),
      width: ScoringColors.getBorderWidth(isSelected),
    ),
  ),
  child: Text(
    'X',
    style: TextStyle(
      color: textColor,
      fontWeight: shouldBeBold ? FontWeight.bold : FontWeight.normal,
    ),
  ),
)

conditional disabled states

// Show as disabled when condition is false
Color bgColor = showColumn 
  ? ScoringColors.getScoreBackgroundColor('10')
  : ScoringColors.getDisabledBackground();

Color textColor = showColumn 
  ? ScoringColors.getScoreTextColor('10')
  : ScoringColors.getDisabledText();

accessing color schemes directly

// Get the current active scheme
ScoringColorScheme current = ScoringColors.currentScheme;

// Access specific schemes for comparison or settings UI
ScoringColorScheme traditional = ScoringColors.availableTraditional;
ScoringColorScheme lowSat = ScoringColors.availableLowSaturation;

// Use scheme properties directly
Color goldBackground = traditional.goldRing;
Color goldText = traditional.goldText;

adding new color schemes

To create additional color schemes (such as high contrast or colorblind-friendly variants):

1. define the new scheme in scoring_colors.dart:

static const ScoringColorScheme highContrast = ScoringColorScheme(
  // Background colors - use high contrast values
  goldRing: Color(0xFFFFFF00),        // Pure yellow
  redRing: Color(0xFFFF0000),         // Pure red
  blueRing: Color(0xFF0000FF),        // Pure blue
  blackRing: Color(0xFF000000),       // Pure black
  whiteRing: Color(0xFFFFFFFF),       // Pure white
  miss: Color(0xFF808080),            // Medium grey
  clear: Color(0xFFFF8000),           // Orange
  
  // Text colors - ensure maximum contrast
  goldText: Colors.black,
  redText: Colors.white,
  blueText: Colors.white,
  blackText: Colors.white,
  whiteText: Colors.black,
  missText: Colors.black,
  clearText: Colors.white,
  
  // Borders and disabled states
  selectedBorder: Color(0xFF0080FF),
  defaultBorder: Color(0xFF606060),
  disabledBackground: Color(0xFFE0E0E0),
  disabledText: Color(0xFF909090),
  disabledBorder: Color(0xFFC0C0C0),
);

2. add an accessor method:

static ScoringColorScheme get availableHighContrast => highContrast;

3. switch to the new scheme by updating _currentScheme:

static const ScoringColorScheme _currentScheme = highContrast;

future expansion possibilities

The color system is designed for easy extension:

• dark theme support: add dark background schemes with appropriate text colors
• accessibility themes: high contrast, large text, colorblind-friendly variants
• user customization: runtime scheme switching with settings persistence
• seasonal themes: holiday or event-specific color schemes
• tournament modes: competition-specific color coding

planned constants files

Other constants modules planned for the application:

• app_constants.dart: general app configuration (timeouts, limits, defaults)
• layout_constants.dart: UI spacing, sizing, and layout specifications
• scoring_rules.dart: archery scoring rules and validation constants
• export_constants.dart: file formats, templates, and export configurations

implementation notes

why explicit text colors?

Instead of calculating text colors automatically, each scheme defines explicit text colors because:

• ensures intentional design decisions for every color combination
• prevents unexpected contrast issues when colors change
• allows for creative text color choices beyond simple black/white
• provides complete design control for complex color schemes

disabled state philosophy

Disabled states maintain visual hierarchy while clearly indicating inactive status:

• elements remain visible to preserve layout and context
• consistent grey palette prevents confusion with active elements
• text remains readable while being clearly distinguished from active content
• used extensively in sum of 6 column when in 3-arrow end mode

performance considerations

The color system is designed for performance:

• all colors are compile-time constants
• no runtime color calculations or theme switching overhead
• minimal method call overhead for color lookups
• ready for hot reload during development