Helix StudioGenome IDE
← Docs
Helix CLI docs
Browse Helix CLI docs

Helix UI + Theme Instructions

This document is the source of truth for UI theming, icon resources, snapshots, and color-lint policy.

Theme system (authoritative)

  • Tokens live in helix/theme/tokens.json.
  • Generated outputs live in helix/theme/out/:
    • theme_generated.qss
    • theme_palette_generated.py
  • Generation command:
    • python helix/theme/generate_theme.py --tokens helix/theme/tokens.json --out helix/theme/out --theme dark
  • App startup must apply the generated palette + QSS (no hand-edited hex in code).

Icon resources

  • SVGs live in helix/theme/icons/.
  • Qt resource file is helix/theme/icons.qrc.
  • Generated module: helix/theme/icons_rc.py.
  • Regenerate with:
    • pyside6-rcc helix/theme/icons.qrc -o helix/theme/icons_rc.py
  • CI verifies icons_rc.py is in sync via tools/check_icons_rc.py.

Color lint policy

  • Strict dirs (no raw literals if touched): src/helix/gui, src/helix/studio.
  • Elsewhere: legacy literals are allowed only if untouched; new literals are blocked.
  • Ratchet: strict literal count must not exceed tools/lint_colors_baseline.json.
  • Commands:
    • python tools/lint_colors.py (changed files)
    • python tools/lint_colors.py --staged (pre-commit)
    • python tools/lint_colors.py --report artifacts/lint/colors.json (inventory strict literals)
    • python tools/lint_colors.py baseline update (rewrite baseline; clean git required unless --force)

Lint exit codes:

  • 0: clean
  • 2: new literals introduced
  • 3: strict ratchet increased
  • 4: both

Snapshot validation

  • Use headless snapshots for UI polish:
    • QT_QPA_PLATFORM=offscreen python tools/snap_ui.py --chrome-extras --sizes 1440x900 --welcome-size 1100x760

Welcome dialog controls

  • Skip welcome on startup:
    • HELIX_STUDIO_SKIP_WELCOME=1 or python -m helix.studio.app --skip-welcome

Window sizing controls

  • Ignore saved geometry and force maximize:
    • HELIX_STUDIO_FORCE_MAXIMIZED=1 or python -m helix.studio.app --force-maximized
  • Force window to a specific screen (maximized):
    • HELIX_STUDIO_FORCE_SCREEN=cursor|primary|<screen_name> or python -m helix.studio.app --screen cursor
  • WSL/XWayland users: native chrome is enabled by default for stability. Override with:
    • HELIX_NATIVE_CHROME=0 to force frameless (not recommended on WSL)