theme-management

name: theme-management description: "Add, update, validate and verify theme files using built-in package.json commands and utilities." user-invocable: true

Theme Management Skill

Purpose: Add, update, validate and verify theme files using built-in package.json commands and utilities.

Target Users: Frontend developers managing Daedalus theme CSS variables and styling system.

Related Components:

• source/renderer/app/themes/ — Theme definitions and utilities
• source/renderer/app/themes/daedalus/ — Theme output files (cardano.ts, light-blue.ts, etc.)
• source/renderer/app/themes/utils/ — Theme creation and validation scripts
• gulpfile.js — Build tasks for themes

Overview

Daedalus uses a CSS custom properties (CSS variables) theme system built with TypeScript. All themes are generated from a centralized createTheme object and validated against existing theme files to ensure consistency across the application.

Key Theme Files

Core Commands

All commands use Gulp build system and TypeScript compilation before execution.

1. Validate Theme Creation (themes:check:createTheme)

Purpose: Validate that the createTheme object contains all CSS custom properties defined in existing theme files.

Command:

yarn themes:check:createTheme

What It Does:

• Builds themes via gulp build:themes
• Compiles and runs source/renderer/app/themes/scripts/check.ts
• Compares createTheme object against all existing theme outputs
• Logs missing definitions in each theme with color-coded output
• Exit Code: 0 if valid, 1 if missing definitions found

Output Example:

createTheme.js is missing the following definitions that exist in the cardano.ts theme:

{
  "--theme-wallet-address-copy-tooltip-background-color": "#2cbb69",
  "--theme-wallet-address-copy-tooltip-text-color": "#fafafa"
}

When to Use:

• After adding new CSS variables to an existing theme
• Before committing theme changes to verify consistency
• When implementing new UI components that need theme variables

Note: This command does NOT modify files; it only reports differences.

2. Update Theme Files (themes:update)

Purpose: Update theme files based on changes in the createTheme object, then auto-format with Prettier.

Command:

yarn themes:update

What It Does:

• Builds themes via gulp build:themes
• Runs source/renderer/app/themes/utils/updateThemesCLI.ts (interactive CLI)
• Presents available updates to existing theme files
• Applies selected updates to theme files
• Auto-formats all updated files with Prettier (--loglevel warn)
• Modifies files in: source/renderer/app/themes/daedalus/*.ts

Interactive CLI Usage:

1. Command prompts you to select which theme(s) to update
2. Displays summary of changes to be applied
3. Confirms before writing changes to disk

Output Example:

Updating cardano.ts...
✓ Added 3 new CSS variables
✓ Updated 2 existing variables
✓ Formatted with Prettier

When to Use:

• After adding new CSS variables to createTheme object
• When propagating color/style changes across all themes
• Part of the standard workflow when defining new theme variables

Result: Updated TypeScript theme files with auto-formatting applied.

3. Copy Theme Properties (themes:copy)

Purpose: Interactive CLI tool to quickly duplicate CSS properties between all theme files.

Command:

yarn themes:copy

What It Does:

• Runs source/renderer/app/themes/utils/copyTheme.ts (interactive CLI)
• Launches CLI interface to select source and target CSS variables
• Copies property value from one theme to all other theme files
• Auto-formats updated files with Prettier

Interactive CLI Steps:

1. Select Property: Prompts for CSS variable name (e.g., --theme-button-primary-color)
2. Select Source Theme: Choose which theme to copy value FROM
3. Select Target Themes: Choose which theme(s) to copy value TO
4. Confirm: Review changes before applying

Usage Example:

? Which CSS variable do you want to copy?
> --theme-button-primary-background

? Copy from which theme?
> cardano.ts

? Copy to which themes? (select multiple with Space)
> [x] light-blue.ts
> [ ] dark-cardano.ts
> [x] light-cardano.ts

✓ Applied to 2 themes
✓ Running Prettier...

When to Use:

• When adding a new theme and need to copy color values from existing theme
• After creating new CSS variables and need to propagate to multiple themes
• When updating a color value that should be consistent across themes
• Quick reference for comparing CSS variable values across themes

Result: All selected theme files updated with copied property; auto-formatted.

4. Build Themes (gulp build:themes)

Purpose: Internal build step that compiles theme TypeScript files for use by check/update/copy commands.

Command:

gulp build:themes

What It Does:

• Cleans dist/ directory
• Runs Webpack to compile theme files
• Outputs to dist/

When It Runs: Automatically executed before themes:check:createTheme, themes:update, and themes:copy.

Note: You typically don't need to run this directly; it's a dependency of other theme commands.

Workflow Examples

Example 1: Adding a New Theme Variable

Scenario: You need to add a new CSS variable --theme-mithril-card-background for the Mithril feature.

Steps:

1. Add to createTheme object:

   // source/renderer/app/themes/utils/constants.ts
   export const CREATE_CARDANO_THEME_PARAMS = {
     // ... existing vars
     'mithril-card-background': {
       light: '#ffffff',
       dark: '#0f1822',
     },
   };
   

2. Validate:

   yarn themes:check:createTheme
   

   • If valid output: ✓ Proceed to step 3
   • If missing definitions: Add missing variables to createTheme

3. Update theme files:

   yarn themes:update
   

   • Select themes to update (usually all)
   • Confirm changes
   • Prettier auto-formats output

4. Verify:

   yarn prettier:check
   yarn compile
   

Example 2: Copying a Property to a New Theme

Scenario: You created a new theme variant and need to copy all color values from the Cardano theme.

Steps:

1. Create new theme file: source/renderer/app/themes/daedalus/my-theme.ts

2. Export output constant in source/renderer/app/themes/daedalus/index.ts:

   export const MY_THEME_OUTPUT = { /* ... */ };
   export const EXISTING_THEME_OUTPUTS = [
     // ... existing
     ['my-theme.ts', MY_THEME_OUTPUT],
   ];
   

3. Copy properties iteratively:

   yarn themes:copy
   

   • Select property from cardano.ts
   • Apply to my-theme.ts
   • Repeat for each variable needed

4. Or update in batch (if createTheme supports new theme):

   yarn themes:update
   

   • Select my-theme.ts
   • Apply all updates at once

Example 3: Verifying Theme Consistency Before Commit

Scenario: You've made changes to theme files and want to ensure everything is consistent.

Steps:

# 1. Check createTheme validity
yarn themes:check:createTheme

# 2. Run full code quality checks
yarn compile        # TypeScript check
yarn prettier:check # Formatting check
yarn lint           # ESLint check

Theme File Structure

Theme Output Object Format

Each theme file exports a TypeScript object mapping CSS variable names to color values:

// source/renderer/app/themes/daedalus/cardano.ts
export const CARDANO_THEME_OUTPUT = {
  '--theme-about-window-background-color': 'rgba(15, 24, 34, 0.96)',
  '--theme-button-primary-background': '#2cbb69',
  '--theme-button-primary-text-color': '#ffffff',
  // ... 200+ more CSS variables
};

Theme Parameters Format

The createTheme object uses parameter format:

// source/renderer/app/themes/utils/constants.ts
export const CREATE_CARDANO_THEME_PARAMS = {
  'property-name': {
    light: '#color-for-light-theme',
    dark: '#color-for-dark-theme',
  },
  // ...
};

Validation and Quality Checks

Pre-Commit Checklist

Before committing theme changes:

# 1. Validate theme creation object
yarn themes:check:createTheme

# 2. Verify TypeScript compilation
yarn compile

# 3. Check code formatting
yarn prettier:check

# 4. Run full checks
yarn lint

Automated Checks (CI/CD)

Theme changes are validated in CI via:

• yarn check:all — Runs all quality checks including theme validation
• Theme files must have consistent formatting
• No missing CSS variables between createTheme and existing themes

Common Patterns

Adding a Feature's Theme Variables

1. Create variables in createTheme with both light and dark values
2. Run yarn themes:check:createTheme to validate
3. Run yarn themes:update to sync to all theme files
4. Verify with yarn prettier:check && yarn compile
5. Use variables in SCSS: color: var(--theme-feature-color);

Creating a New Theme Variant

1. Create new theme file in source/renderer/app/themes/daedalus/
2. Add export to source/renderer/app/themes/daedalus/index.ts
3. Add to EXISTING_THEME_OUTPUTS array
4. Run yarn themes:copy or yarn themes:update to populate
5. Register in theme selection UI

Updating Color Values Across All Themes

1. Modify createTheme parameters in constants.ts
2. Run yarn themes:update and select all themes
3. Review changes in generated .ts files
4. Commit diff alongside any component changes

Tips & Best Practices

Do's ✓

• Run themes:check:createTheme after any theme-related changes
• Use themes:copy for one-off variable propagation
• Use themes:update for bulk changes affecting multiple files
• Always run prettier:check after theme updates (auto-run by update command)
• Keep CSS variable names consistent (kebab-case, semantic prefix)

Don'ts ✗

• Don't manually edit theme .ts files if template exists (use tools instead)
• Don't commit unformatted theme files (Prettier is required)
• Don't add CSS variables only to one theme (use createTheme for all)
• Don't skip validation before committing (run themes:check:createTheme)

Color Value Guidelines

• Use hex format for consistency: #2cbb69
• Use rgba for transparency: rgba(255, 255, 255, 0.8)
• Follow naming pattern: --theme-[feature]-[element]-[property]
  • Example: --theme-wallet-address-copy-tooltip-background-color
• Light theme variants should use lighter/brighter colors
• Dark theme variants should use darker/lower-contrast colors

Troubleshooting

"Missing definitions" Error

Problem: yarn themes:check:createTheme reports missing definitions

Solution:

1. Add missing variables to CREATE_*_THEME_PARAMS in constants.ts
2. Ensure both light and dark values are provided
3. Run yarn themes:check:createTheme again to verify

Prettier Formatting Issues

Problem: Theme files aren't formatted after update

Solution:

• Prettier is auto-run by themes:update command
• If formatting is missing, run: yarn prettier --loglevel warn --write source/renderer/app/themes/daedalus/*.ts

TypeScript Compilation Errors

Problem: yarn compile fails after theme changes

Solution:

1. Verify all new variables are exported in daedalus/index.ts
2. Check createTheme object matches theme file structure
3. Run yarn themes:update to auto-sync files

CLI Tool Not Responding

Problem: themes:copy or themes:update hangs

Solution:

• Ensure gulp build:themes completed successfully
• Check dist/ directory exists after build
• Try clearing cache: yarn clear:cache && yarn themes:update

Related Documentation

• Theme Architecture: System Architecture - Theme System
• Component Development: Storybook Workflow
• Best Practices: BESTPRACTICES.md
• Theme Tutorial Series: Theme Tutorial Videos

Video Tutorials

The Daedalus project includes comprehensive video tutorials on theme management:

• Part 1: Creating a new theme using createTheme utility
• Part 2: Using the themes:update script
• Part 3: Writing theme CSS variables to output objects
• Part 4: Using themes:check:createTheme for validation

See Theme README for video links.

Quick Reference Card

For Copilot Agents

When working with theme files:

1. New theme variable: Add to createTheme → validate → update files → verify
2. Theme property copy: Use themes:copy CLI for single operations
3. Batch theme updates: Use themes:update CLI for multiple variables
4. Before commits: Run themes:check:createTheme && yarn compile && yarn prettier:check
5. Modify theme colors: Edit constants.ts then sync with themes:update

Always ensure theme files remain in sync with validation tools and auto-formatted.