# Skyfeed UI API Reference
Leak Technologies — Developer Visual Reference

This document defines how Skyfeed renders Unicode icons and text using the
skyfeed_default theme (black terminal aesthetic). It ensures visual
consistency between the CLI mode and the graphical UI.

----------------------------------------------------------------------
Base Theme Mapping
----------------------------------------------------------------------

Role               | Colour     | Usage
-------------------|------------|---------------------------------------
Background         | #000000    | Terminal canvas, alert frame background
Foreground Text    | #E0E0E0    | General text, city name, data values
Primary Accent     | #00BFFF    | Weather icons, temperature emphasis
Secondary Accent   | #FFD300    | Headings, highlights, sun indicators
Advisory / Alert   | #FF4040    | Red border and alert messages
Advisory Text      | #FFA500    | Amber warning for travel/advisory notices

Font: assets/fonts/Modeseven.ttf  (Teletext-style monospace, ~20pt nominal)
Icon scale: Display.IconScale in config (default 4x)

----------------------------------------------------------------------
Layout Overview
----------------------------------------------------------------------

Minimal View

+-------------------------------------------------------------------+
| Cornwall, ON                                   ☀                  |
| Updated: 14:05 EST                              21°C               |
| Clear Sky                                                          |
| Feels: 22°C  Wind: W 10 km/h  RH: 55%                              |
| Pressure: 101.3 kPa  Visibility: 24 km                             |
+-------------------------------------------------------------------+

- Left column: text data
- Right column: enlarged Unicode weather icon
- Border: red (#FF4040) if an alert is active; black otherwise

Fullscreen View (planned)

Fullscreen will display extended conditions, forecasts, and alerts in a
Teletext-inspired grid using the same colour mapping.

----------------------------------------------------------------------
Weather Icon Colours
----------------------------------------------------------------------

Condition           | Symbol | Foreground | Example note
--------------------|--------|-------------|------------------------------
Clear / Sunny       | ☀      | #FFD300     | Bright yellow on black
Mostly Cloudy       | 🌥      | #00BFFF     | Sky blue on black
Rain / Showers      | 🌧      | #00BFFF     | Blue icon, white text
Snow / Flurries     | ❄      | #E0E0E0     | White icon
Freezing Rain       | 🧊      | #00FFFF     | Cyan tint
Fog / Mist          | 🌫      | #AAAAAA     | Soft grey
Wind / Gale         | 💨      | #00BFFF     | Blue accent
Thunderstorm        | ⛈      | #FFD300     | Yellow lightning emphasis
Tornado / Funnel    | 🌪      | #FF4040     | Red icon
Hail / Ice Pellets  | 🧊      | #00FFFF     | Cyan tint

----------------------------------------------------------------------
Alert Level Rendering
----------------------------------------------------------------------

Severity  | Symbol | Border   | Text Colour | Meaning
-----------|--------|----------|--------------|-----------------------------
Warning    | ⚠      | #FF4040  | White        | Action likely required
Watch      | 👁     | #FFA500  | White        | Conditions favourable
Advisory   | ⚡      | #FFD300  | White        | Minor / travel risk
Statement  | ℹ      | #00BFFF  | White        | Informational
None / OK  | ✓      | #00FF00  | White        | Normal conditions

When an alert is active:
  - The frame border colour reflects severity.
  - Alert text appears below the main conditions in the same hue.

----------------------------------------------------------------------
Time and Refresh
----------------------------------------------------------------------

- The window title updates each second, e.g.  Skyfeed — 14:27:05
- Weather refresh interval defaults to 15 minutes (RefreshMinutes in config)

----------------------------------------------------------------------
Design Goals
----------------------------------------------------------------------

Principle          | Description
-------------------|---------------------------------------------------------
No Branding in UI  | Skyfeed presents pure data; branding stays in backend.
MS-DOS Safe        | Colours and Unicode symbols render in text-only environments.
Retro-Futuristic   | Ceefax / MS-DOS-inspired clarity.
Zero-Distraction   | No animations, no bitmap icons; Unicode glyphs only.
B&W Readable       | Icons remain legible without colour.

----------------------------------------------------------------------
Developer Integration
----------------------------------------------------------------------

Access icons programmatically:
    from src.utils.weather_symbols import get_icon
    symbol = get_icon("rain")

Use with theme:
    from src.ui.theme import get_color
    fg = get_color("fg_primary")
    bg = get_color("bg")

Localization:
    from src.localization.localization_manager import LocalizationManager
    loc = LocalizationManager("fr_CA")
    label = loc.get_label("temperature")

----------------------------------------------------------------------
Maintainer: Leak Technologies
Revision: v0.1.0 (November 2025)