uttrflow / uttrflow/uttrflow-swift
Home greeting and shortcut instructions become nearly invisible in Light appearance
- Dominant language
- Swift
- Stars
- 4
- Forks
- 17
- Avg merge
- 3h 32m
- Merged PRs (30d)
- 277
Description
## Problem
Home uses a deliberately dark hero background in both appearances, but its greeting, subtitle and shortcut hint use `Color.mainText`, which becomes dark ink in Light appearance. The result is dark text on the dark hero, making the first instructions difficult to read.
Verified on main `5c310667cd35c44abd8bbd26c19b0905471287b4`.
## Code path
- `Sources/Uttrflow/Main/OrbitStage.swift`: `ground` uses fixed `stagePanel` / `stageGround`; their definitions explicitly select `BrandPalette.Surface.card.dark` and `.ground.dark`.
- The same view's `words` and `hint` use `Color.mainText`, with opacity 0.78 for the subtitle and 0.72 for the shortcut instructions.
- `Sources/Uttrflow/Main/OrbitPalette.swift`: `mainText` is the appearance-dependent `BrandPalette.Text.primary`.
- `Sources/Uttrflow/Brand/BrandPalette.swift`: that text tone changes from `#F4F4F6` in Dark to `#171320` in Light, while the hero background remains around `#0B0C10` / `#0E1016` plus its teal radial gradient.
- `AppDelegate.applyAppearance()` sets `NSApplication.shared.appearance` to Aqua for Light. Neither the stage nor its Home wrapper overrides the text appearance for the dark surface.
## Verification
Rendered the unmodified production `OrbitStage`, including its real palette, ring and shared components, using SwiftUI `ImageRenderer` at width 800 and scale 1. The same production `HomePresenter` generated a synthetic page for Alex with granted microphone/accessibility permissions and a fixed clock.
For each render, set both NSApplication appearance and the SwiftUI color scheme consistently:
```swift
NSApplication.shared.appearance = NSAppearance(named: .aqua)
let renderer = ImageRenderer(
content: OrbitStage(presentation: page)
.frame(width: 800)
.environment(\.colorScheme, .light))
```
Repeat with `.darkAqua` and `.dark` as a control.
Visual inspection of both PNGs confirmed:
- Light: the greeting is nearly black; the subtitle and shortcut sentence are barely visible on the dark surface.
- Dark: the same greeting and instructions are clearly visible in light text.
- The background and microphone/ring remain dark in both renders, as intended by their fixed palette.
This is a production-view rendering test with synthetic inputs, not a screenshot of a running signed app or a full Settings interaction test. No exact rendered contrast ratio is claimed.
## Expected / acceptance criteria
- Give the deliberately dark stage an appropriate text treatment in both application appearances. Keep the rest of Home responsive to the selected appearance.
- Cover greeting, subtitle, key labels, and lead/trailing hint text in Light and Dark, including high-contrast appearances.
- Add a visual or resolved-color regression check that tests the foreground against this actual fixed-background use, rather than only checking that dynamic palette colors switch correctly.
Priority P2: this obscures the main page's introductory text and instructions whenever Light appearance is selected or inherited.
## Existing issues checked
#518 addresses fixed semantic warning/success/error colors on light surfaces; #519 addresses the dim text tone. This defect uses the primary text tone on an intentionally fixed dark surface, so correcting those tones does not repair this appearance mismatch. #807 concerns initials consistency.
Contributor guide
Research direction
Start with Sources/Uttrflow/Main/OrbitStage.swift and trace its words, hint, ground, stagePanel, and stageGround usage into OrbitPalette.swift and BrandPalette.swift. Reproduce the documented ImageRenderer cases at width 800 with light and dark appearance settings, then add the resolved-color or visual regression coverage described in the issue. Done means greeting, subtitle, key labels, and both hint areas remain readable on the fixed dark stage in Light, Dark, and high-contrast appearances while the rest of Home follows its selected appearance.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- macos, swift
- Domain
- accessibility, desktop
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 76/100