# Chan Compass · Spectrum 2 Design System

A design system for **Chan Compass · US** — a multi-timeframe 缠论 (Chan theory)
stock-signal engine — rendered in **Adobe Spectrum 2**, Adobe's design language.
It exists to give design agents a single, accurate source of truth for building
beautiful, on-brand Chan Compass interfaces (the live Gradio app, mocks, slides,
marketing) without re-deriving Spectrum 2 every time.

> **Spectrum 2** is Adobe's open design system. This project recreates its
> visual foundations (color, type, spacing, elevation, motion) and a set of
> React components, then applies them to the Chan Compass product surfaces.

---

## What the product is

Chan Compass is an **educational US-equities signal tool** that runs entirely
locally. It has six surfaces (Gradio tabs):

| Surface | What it does |
|---|---|
| **Signals** | Runs the Chan engine over a ticker pool; returns next-session **BUY / SELL / HOLD / WAIT / WATCH** with confidence, suggested weight, stop, and a full multi-timeframe ruling chain (monthly → weekly → daily → 60m → 30m → 15m → 5m nested-interval confirmation). |
| **Sector Rotation** | Where capital is flowing across the 11 SPDR sector ETFs; flow proxy = change % × dollar volume, plus relative strength vs SPY, over 1 / 5 / 20 days. |
| **Watchlist News** | Checks **today's** news per holding; pushes an AI brief only when news exists. |
| **Auto Research** | A local multi-step agent: PLAN → 5 evidence tools → sectioned report, with a saved JSON trace. |
| **Automation** | Daily pipeline at 18:10 America/New_York. |
| **Model** | Loads Qwen3 GGUF weights through llama.cpp — everything runs locally, nothing leaves the machine. |

The AI is a **local sub-agent pool** (Qwen3-1.7B translator/narrator + a deeper
analyst), served via `llama-cpp-python`. Data comes from Yahoo Finance.

## Sources this system was built from

- **Codebase:** `chan-compass-us-v1.7/` (attached) — a Gradio app (`app.py`)
  plus the Chan engine (`chan_engine.py`, `chan_multilevel.py`, `chan_enhance.py`),
  signal/rotation/news/research/automation modules. The app already ships an
  *approximation* of Spectrum 2 in Gradio CSS; this system replaces it with the
  real thing. The product deploys as a **Hugging Face Gradio Space**.
- **Design language — Adobe Spectrum 2 / React Spectrum:**
  <https://github.com/adobe/react-spectrum> (the `@react-spectrum/s2` package —
  `style/spectrum-theme.ts`, `style/tokens.ts` — was read for exact spacing,
  radii, easing, weights and the type scale). Token values were cross-checked
  against <https://spectrum.adobe.com/page/color-palette/>.
  Explore that repo to go deeper on component behavior and accessibility.

> **Deploying the live app?** See `gradio/` — a ready-to-paste Spectrum 2 Gradio
> theme (`theme.py` = `THEME` + `CSS`), a guaranteed-green standalone demo Space,
> and an HF deploy checklist (`gradio/INTEGRATE.md`).

---

## Content fundamentals

How Chan Compass writes. Match this voice in any UI copy.

- **Voice:** expert, terse, instrument-panel. Copy reads like a trading desk
  tool, not a consumer app. Short noun phrases over sentences: *"Tomorrow's
  plan"*, *"Where capital is flowing"*, *"Buy/sell zone"*.
- **Person:** mostly impersonal/imperative. Buttons are verbs — *"Run analysis"*,
  *"Check today's news"*, *"Load model"*. When it addresses the user it's second
  person and possessive — *"My holdings"*, *"your ticker pool"*.
- **Casing:** **Sentence case** everywhere — labels, buttons, headings
  (*"Run analysis"*, not "Run Analysis"). Ticker symbols and ETF codes are
  **UPPERCASE monospace** (NVDA, XLK). Signal verbs render UPPERCASE in pills
  (BUY/SELL/HOLD).
- **Bilingual register:** the engine's internal ruling chain is **Chinese**
  (缠论 terms: 中枢, 背驰, 区间套, 买卖点 B1/B2/B3/S1/S2/S3); user-facing summaries
  are **English**, produced by the local translator sub-agent. Keep Chinese for
  authentic engine output; keep English for everything the user reads first.
- **Numbers carry meaning, not decoration.** Every percent, confidence score,
  weight and stop price is real signal. No vanity stats. Percentages are signed
  (+2.43% / −3.08%) and color-coded.
- **Honesty & disclaimers:** always frames itself as *"educational tool — not
  investment advice."* States its data limits plainly (*"Yahoo only keeps 7 days
  of 1-minute bars, so the 1m level is skipped"*). No hype, no guarantees.
- **AI is labeled.** Anything model-generated is prefixed with the sub-agent and
  model — *"🤖 Translator sub-agent (Qwen3-1.7B · llama.cpp)"* — and notes
  latency honestly (*"first words in ~5–15s"*).
- **Emoji:** the live app uses tab emoji (📈 🔄 📰 🧪 ⏰ 🧠) and the 🧭 brand mark.
  In the **polished design system we prefer Spectrum line icons** for UI chrome
  and reserve emoji for the brand mark / casual chips. Don't scatter emoji into
  data or buttons.

---

## Visual foundations

The Spectrum 2 look, as applied here.

- **Color vibe:** calm, neutral, **light-first**. A near-white canvas
  (`gray-50 #F8F8F8`) with **white cards** (`gray-25`) and crisp hairline borders
  (`gray-100 #E6E6E6`). One disciplined accent — **Spectrum blue `#0265DC`** —
  carries all primary action and selection. Color is otherwise **semantic only**:
  green = positive/BUY, red = negative/SELL, blue = HOLD/accent, orange = WATCH/notice.
  No decorative color, no rainbow dashboards.
- **Type:** **Source Sans 3** for UI and headings (open stand-in for the
  proprietary Adobe Clean), **Source Serif 4** for editorial/report prose,
  **Source Code Pro** for tickers, prices and logs. Modular scale, ratio **1.125**,
  **14px UI base**. Headings are **bold (700)** and slightly tightened
  (`-0.015em`); body is **regular (400)** at a spacious **1.5** line height.
- **Spacing:** an **8px base rhythm** (2 · 4 · 8 · 12 · 16 · 24 · 32 · 48 · 64).
  Generous padding inside cards (24px), comfortable 24–32px gaps between regions.
- **Backgrounds:** **flat, layered surfaces** — no photographic imagery, no
  full-bleed art, no repeating textures. Depth comes from Spectrum's
  *background layering* (canvas → card → subtle well), not from shadows alone.
  The **only gradient** is a small one on the 🧭 brand mark
  (blue → indigo → purple), echoing the app's original hero; the rest is solid.
- **Corner radii:** soft but not pill-everything — **16px cards**, **8px inputs
  & square buttons**, **4px chips**, and **fully-rounded (pill) action buttons** —
  the single most recognizable Spectrum 2 signature here.
- **Elevation:** **soft, low-spread** drop shadows (`raised` = `0 1px 3px
  rgba(0,0,0,.06)`), never heavy. Cards sit barely off the canvas. The AI panel
  gets a faint **accent-tinted glow** instead of a darker shadow.
- **Borders:** 1px hairlines for structure; inputs use a **2px** border that
  turns accent-blue on focus. Tabs sit on a 2px track and the selected tab draws
  a 2px accent underline.
- **Hover / press:** Spectrum's **one-stop-darker** rule — hover bumps a button
  one color stop darker (`accent → accent-hover`), press goes one more and adds a
  **subtle `scale(.98)`**. Quiet/ghost controls fill with `gray-75` on hover.
  Rows highlight to `gray-75` on hover, `blue-100` when selected.
- **Focus:** a **2px solid accent ring with 2px offset** on every interactive
  element — visible, never removed.
- **Motion:** quick and restrained. Durations **130–220ms**; the house easing is
  Spectrum's `cubic-bezier(0.45, 0, 0.4, 1)` (with `ease-out` for entrances).
  Fades and one-stop color shifts; **no bounces**, one tasteful pulse for live
  status and the running pipeline step. Respect `prefers-reduced-motion`.
- **Transparency / blur:** used sparingly — not a glassmorphism system. Surfaces
  are opaque; selection tints use solid subtle fills (`blue-100`), not alpha.
- **Cards:** white surface, 16px radius, 1px hairline border, soft raised shadow,
  optional header with title + subtitle + a trailing action slot.

---

## Index — what's in this project

**Foundations (root)**
- `styles.css` — the single entry point consumers link (`@import`s only).
- `tokens/` — `colors.css` · `typography.css` · `spacing.css` · `elevation.css`
  · `fonts.css` · `base.css`. Primitives + semantic aliases.
- `guidelines/` — foundation specimen cards (Colors, Type, Spacing) shown in the
  Design System tab.

**Components** (`components/<group>/` — React primitives, bundled to `window.<Namespace>`)
- `actions/` — **Button** (pill, accent/secondary/negative/quiet)
- `forms/` — **Field**, **Checkbox**, **Switch**
- `status/` — **Badge**, **StatusLight**, **SignalBadge** (BUY/SELL/HOLD/WAIT/WATCH)
- `containers/` — **Card**, **InlineAlert** (incl. the signature `ai` panel)
- `navigation/` — **Tabs** (quiet tabs + accent underline)

**UI kit** (`ui_kits/chan-compass/`)
- `index.html` — full interactive Spectrum 2 recreation of the 6-tab app
  (Signals, Rotation, Research, News, Model). Composes the components above.

**Deploy bridge** (`gradio/`)
- `theme.py` (`THEME` + `CSS`), standalone demo `app.py`, `requirements.txt`,
  `README.md` (HF Space), `INTEGRATE.md` (port + deploy checklist).

**Meta**
- `SKILL.md` — makes this folder usable as an Agent Skill.

---

## Iconography

See the **Iconography** section below and the `assets/` README. In short: Chan
Compass has **no custom icon set** of its own — the live app leans on **emoji**
for tab affordances and the **🧭 compass** as its brand mark. Spectrum's own
**workflow-icons** are the canonical reference but aren't freely CDN-hosted, so
this system substitutes **[Lucide](https://lucide.dev)** — clean 2px line icons
whose weight and rounded joinery read as Spectrum-adjacent — loaded from CDN in
the UI kit. **Substitution flagged.** If you license Adobe's Spectrum workflow
icons, swap Lucide for them and the visual language tightens further.

*Educational tool — not investment advice.*