Skip to content

Gotchas

Brian Jr edited this page Nov 17, 2026 · 1 revision

4 · Gotchas (read these — they are where themes break)

Palettes & contrast

  • A Look must look right on dark (pure-black/AMOLED) and light palettes, and follow the user's accent. Colors come from palette in resolveLookColors — don't hard-code a single background/text color. Test both themes.
  • Selected nav label color: the nav renderer's textColor must contrast with the panel (the label sits below the highlight), not reuse the on-highlight icon tint — otherwise the selected label becomes invisible. Override textColor(p, selected) explicitly.
  • Light-theme faint labels: thin/low-contrast label colors can disappear on light palettes. Check both.

Fonts & sizing (the #1 source of clipping)

  • Wide or tall display fonts (e.g. Michroma, 7-segment, rounded-bold, serif) overflow the small telemetry cards. Tune, per Look, in SettingsTabLookSpec: ringValueScale, ringTitleScale, ringUnitScale, ringDiameterRatio, and infoValueScale (TEMP/FAN). Shrink until nothing clips.
  • tccTextStyle() = the label font; tccDisplayTextStyle() = the display/number font. Use the display font for big numerals.
  • The big FPS number is drawn with a native Paint using traits.canvasFontRes — set it if your Look has a display font, or the FPS number falls back to the default face.

Layout realities

  • The hardware cards are adaptive: the telemetry rings render 2×2 in a tall card and 1×4 in a wide strip; TEMP/FAN shows two stat columns when tall and stacked rows when short; the FPS counter grows in a big card. If you write custom gauge/card renderers, make sure they look right both large and small.
  • Nav selection shapes should be centered on the icon box (size.height / 2), not a fixed offset, or the highlight floats above the icon.

Assets & licensing (this is open source — take it seriously)

  • Fonts: bundle only SIL OFL / permissively-licensed fonts, named tcc_*.ttf, and add an attribution block to assets/THIRD_PARTY_NOTICES.txt. No fonts you don't have the right to ship.
  • Icons are NOT bundled. The overlay loads AYN's stock drawables at runtime from the installed stock app (com.odin.dualscreen.assistant); your renderers just tint them via ColorFilter. Do not add AYN icon art to the repo. (See docs/reference/LICENSE_COMPLIANCE.md.)
  • Only contribute colors/fonts/code you have the right to.

Mechanics

  • StockLookSpec (the AUTO Look) is the baseline — copy() it and override only differences.
  • Adding a style enum value without wiring its .renderer() case is a compile error (exhaustive when) — that's your reminder to add the renderer.
  • E-Ink deliberately ignores the accent (stays monochrome); some Looks intentionally diverge from the "follow the accent" rule — that's fine, just be deliberate.
  • Changing TccUiLook's set doesn't need a migration: saved looks resolve by name and fall back to AUTO.

Next: Verification Checklist