android-stuff/archery-bookkeeper
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Documentation updates

Browse Source
This commit is contained in:
Mikkeli Matlock
2025-08-23 01:13:59 +09:00
parent d3a8a5c6da
commit 1aff6f9546
2 changed files with 264 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+56
View File
@@ -202,6 +202,62 @@ dev_dependencies:
json_serializable: ^6.7.1 json_serializable: ^6.7.1
``` ```
### color architecture system
The application features a sophisticated centralized color management system built around the `ScoringColorScheme` class, providing consistent visual theming across all scoring components.
**architecture overview**:
- centralized color definitions in `lib/config/constants/scoring_colors.dart`
- explicit background and text color pairs for every score value
- multiple color schemes: traditional (vibrant) and lowSaturation (muted)
- disabled state colors for conditional UI elements
- single source of truth for all score-related visual styling
**color scheme structure**:
```dart
class ScoringColorScheme {
// Background colors for each score value
final Color goldRing; // X, 10, 9
final Color redRing; // 8, 7
final Color blueRing; // 6, 5
final Color blackRing; // 4, 3
final Color whiteRing; // 2, 1
final Color miss; // M
final Color clear; // CLEAR button
// Explicit text colors for each background
final Color goldText; // Black on gold for traditional
final Color redText; // White on red
final Color blueText; // White on blue
// ... etc for all combinations
// Disabled state colors
final Color disabledBackground;
final Color disabledText;
final Color disabledBorder;
}
```
**usage patterns**:
```dart
// Get colors for any score value
Color bg = ScoringColors.getScoreBackgroundColor('X');
Color text = ScoringColors.getScoreTextColor('X');
// Apply disabled styling for inactive elements
Color disabledBg = ScoringColors.getDisabledBackground();
Color disabledText = ScoringColors.getDisabledText();
```
**scheme switching**:
Change the active color scheme globally by updating `_currentScheme` in `scoring_colors.dart`. The traditional scheme uses vibrant archery target colors for high visibility, while lowSaturation provides muted tones for reduced eye strain during extended use.
**disabled state implementation**:
The color system includes comprehensive disabled state support, used extensively for the sum of 6 column which remains visible but greyed out when in 3-arrow end mode. This maintains layout consistency while clearly indicating inactive functionality.
**extensibility**:
The architecture is designed for easy expansion with additional color schemes such as high contrast, colorblind-friendly, or dark theme variants. Each scheme defines all required colors explicitly, preventing contrast issues and ensuring intentional design decisions.
### code organization principles ### code organization principles
**separation of concerns**: **separation of concerns**:
lib/config/constants/_constants.md
+208 -31
View File
@@ -1,48 +1,225 @@
# Constants Directory # constants configuration guide
This directory contains application-wide constants and configuration. This directory contains the application's centralized constants and configuration system, providing consistent theming and behavior across all components.
## Files ## color scheme architecture
- **scoring_colors.dart**: Centralized color scheme system for all scoring-related UI components The archery bookkeeper uses a sophisticated color system built around the `ScoringColorScheme` class, which provides complete visual consistency for all scoring-related UI components.
- Provides multiple color schemes: `traditional` (vibrant) and `lowSaturation` (muted)
- Follows archery ring color conventions (gold, red, blue, black, white)
- Explicit text colors defined per scheme for intentional design control
- Disabled state colors for greying out inactive UI elements
- Single source of truth for all score-related colors with easy scheme switching
- Architecture ready for dark themes, high contrast, and colorblind-friendly schemes
## Future Expansion ### available color schemes
Planned constants files: **traditional scheme (default)**:
- `app_constants.dart`: General app configuration (timeouts, limits, defaults) - vibrant, high-contrast colors matching classic archery target rings
- `layout_constants.dart`: UI spacing, sizing, and layout specifications - bright gold for X/10/9 scores, vivid red for 8/7, bright blue for 6/5
- `scoring_rules.dart`: Archery scoring rules and validation constants - optimal for outdoor use and high visibility situations
- `export_constants.dart`: File formats, templates, and export configurations - follows traditional archery color conventions
## Usage **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`:
```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:
```dart
// 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
```dart ```dart
import 'package:archery_bookkeeper/config/constants/scoring_colors.dart'; import 'package:archery_bookkeeper/config/constants/scoring_colors.dart';
// Get background color for any score (uses current active scheme) // Get colors for any score value
Color bgColor = ScoringColors.getScoreBackgroundColor('X'); Color backgroundColor = ScoringColors.getScoreBackgroundColor('X');
// Get appropriate text color with automatic contrast calculation
Color textColor = ScoringColors.getScoreTextColor('X'); Color textColor = ScoringColors.getScoreTextColor('X');
bool shouldBeBold = ScoringColors.shouldUseBoldText('X');
// Check if score should be bold // Apply to a widget
bool isBold = ScoringColors.shouldUseBoldText('10'); 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,
),
),
)
```
// Access available schemes ### conditional disabled states
```dart
// 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
```dart
// Get the current active scheme
ScoringColorScheme current = ScoringColors.currentScheme;
// Access specific schemes for comparison or settings UI
ScoringColorScheme traditional = ScoringColors.availableTraditional; ScoringColorScheme traditional = ScoringColors.availableTraditional;
ScoringColorScheme lowSat = ScoringColors.availableLowSaturation; ScoringColorScheme lowSat = ScoringColors.availableLowSaturation;
// Get disabled state colors // Use scheme properties directly
Color disabledBg = ScoringColors.getDisabledBackground(); Color goldBackground = traditional.goldRing;
Color disabledText = ScoringColors.getDisabledText(); Color goldText = traditional.goldText;
Color disabledBorder = ScoringColors.getDisabledBorder(); ```
// Switch schemes by changing _currentScheme in scoring_colors.dart: ## adding new color schemes
// static const ScoringColorScheme _currentScheme = lowSaturation;
``` To create additional color schemes (such as high contrast or colorblind-friendly variants):
1. **define the new scheme** in `scoring_colors.dart`:
```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**:
```dart
static ScoringColorScheme get availableHighContrast => highContrast;
```
3. **switch to the new scheme** by updating `_currentScheme`:
```dart
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