# Hoa Mặt Trời — Design System

Design system & component library for **Quỹ Hoa Mặt Trời** ("Sunflower Fund") — *Trung tâm điều hành* (the **HMT Foundation Management Hub**), an internal operations console for a small Vietnamese education charity.

> The brand feeling: **warm, human, uplifting, high-quality, dignified.** A well-crafted nonprofit back-office — not a flashy marketing site, not a cold enterprise SaaS. The logo is a sunflower turning toward light. The interface is entirely in Vietnamese and handles real children's/beneficiary data and donor finances, so it must read **trustworthy and respectful above all.**

---

## What this product is

One coordinator logs in and runs the whole charity from a single web app:
- approving social-media posts before they go out,
- tracking field activities,
- managing beneficiary students (sensitive data),
- reviewing donor contributions & finances,
- planning content.

It is **server-rendered HTML** (Python / FastAPI + Jinja templates). The right deliverable is therefore **one shared CSS design system + a reusable layout shell + restyled, flow-optimized page templates** — plain modern CSS / CSS variables, a little vanilla JS for menus / modals / inline actions / mobile-nav. No JS framework, no Tailwind.

### The areas (sidebar sitemap — Vietnamese labels are canonical)
1. **Tổng quan** — Overview / launchpad (KPI tiles + "Cần bạn xử lý hôm nay")
2. **Hoạt động** — Activities ledger
3. **Khảo sát** — Survey / candidate selection (read-only)
4. **Quản lý học sinh** — Beneficiary students (roster, profiles, watchlist, reports)
5. **Kế hoạch nội dung** — Content calendar
6. **Hàng đợi duyệt** — Approval queue *(the operational heart)*
7. **Hiện diện xã hội** — Social presence / impact
8. **Tài trợ & tài chính** — Donor & finance (own secondary tab bar)
9. **Đăng xuất** — Logout

### Core UX principles (the flow rethink, baked into the components)
- **One persistent shell.** A single sidebar + top bar stays on screen across every area; the current area is just the highlighted nav item. No more "sub-app islands". Finance's internal tabs become a *secondary tab bar inside the shell*, never a replacement nav. Breadcrumbs everywhere (Khu vực ▸ Trang ▸ Mục).
- **Overview is a launchpad, not dead numbers.** KPI tiles are clickable and carry a mini-preview of what's behind them; the action list links straight to the item to act on.
- **Approval = fewest steps to a safe yes.** Decision controls live in a **sticky action bar**; the required **`dignity_ok`** confirmation is an explicit human checkbox that **gates Approve** (disabled until ticked); captions are fixable inline; request-changes notes surface back on the queue card as a "Cần sửa: …" chip.
- **No dead ends.** Finance thank-you queue is actionable in-row/in-modal (Soạn lời cảm ơn / Đánh dấu đã cảm ơn). Cross-area jumps where work connects (post → student profile, contribution → donor).
- **Consistent empty / loading / mock-data states** everywhere, with a gentle sunflower motif and a subtle "demo data" badge.

---

## Sources given

These were provided by the client and stored under `assets/` and `fonts/`:
- **`assets/branding-guideline.png`** — one-page brand sheet (logo, typeface, color palette).
- **`assets/hmt-logo-on-dark.png`** — master logo, transparent PNG (sunflower mark + "hoa mặt trời / QUỸ TỪ THIỆN" wordmark). *Note: despite the filename, the wordmark is dark gray and does **not** read on a dark surface, so light/mark variants were derived (see Iconography).*
- **`assets/stream-a-chrome-target.png`** — example "story chrome" social post (full-bleed photo + warm yellow wash + white Playfair caption + small logo).
- **`assets/stream-b-quote-card-target.png`** — example "quote card" social post (cream bg, navy Playfair question in an ellipse, yellow/teal sparkle accents, 3-petal motif).
- **`fonts/PlayfairDisplay-SemiBold.ttf`**, **`fonts/RobotoCondensed-SemiBold.ttf`** — the two brand fonts.

There was **no live codebase or Figma** attached — only the brand sheet, fonts and two reference social posts. The visual language below is derived from those assets plus the written brief.

---

## CONTENT FUNDAMENTALS

The UI is **100% Vietnamese**, with clean diacritics (both brand fonts support Vietnamese). Tone is **warm, human, dignified, hopeful** — never cold/corporate, never startup-playful, never childish.

**Voice & person.** The product speaks *to* the coordinator as a calm colleague. Second person is implied, gentle and direct: section headers are plain nouns ("Tổng quan", "Hàng đợi duyệt"); the action list addresses the user — **"Cần bạn xử lý hôm nay"** ("Things you need to handle today"). Buttons are imperative verbs: **"Duyệt ngay"**, **"Soạn lời cảm ơn"**, **"Đánh dấu đã cảm ơn"**, **"Yêu cầu sửa"**.

**Casing.** Sentence case for everything — labels, buttons, headings. NOT Title Case. Eyebrow/overline labels are the only UPPERCASE element (small, letter-spaced, e.g. area label in the top bar). Status pills use lowercase-ish Vietnamese phrases ("chờ duyệt", "đã đăng", "từ chối").

**Dignity in copy.** Because the hub holds children's and donor data, copy is respectful and never sensational. Beneficiary screens avoid cutesy treatment. The safeguarding confirmation is phrased as a human promise, e.g. *"Tôi xác nhận nội dung tôn trọng nhân phẩm của người được hỗ trợ."*

**Empty states are reassuring, not broken.** They use a warm, complete-the-loop tone with a single restrained sunflower 🌻, e.g. **"Tất cả đóng góp đã được cảm ơn 🌻"**, **"Chưa có hoạt động nào — thêm hoạt động đầu tiên của bạn."**

**Mock/unwired data is labelled honestly.** A subtle badge **"DỮ LIỆU MẪU"** and a one-line banner **"Số liệu đang ở chế độ MẪU"** mark numbers that aren't wired yet — trust over polish.

**Emoji.** Essentially none, with **one** sanctioned exception: a single sunflower 🌻 in friendly empty states. No other emoji. Iconography carries meaning instead (see below).

**Numbers, dates, IDs.** Vietnamese number/date conventions (e.g. `12/06`, `1.250.000 ₫`). Technical strings — event slugs, post IDs — render in **monospace** (e.g. `evt_2025_0142`, `posted_id: 1789…`).

**Examples pulled from brand assets:**
- Story caption (Playfair, white on photo): *"Không chỉ trao học bổng — chúng tôi trao cơ hội trưởng thành."*
- Quote card (Playfair, navy on cream): *"Một đứa trẻ cần điều gì để không cảm thấy một mình?"*
- The Fund's three values: **Tôn trọng · Đồng hành · Lan tỏa** (Respect · Accompany · Spread).

---

## VISUAL FOUNDATIONS

**Palette.** A four-color brand system over warm neutrals:
- **Sunflower #FED138** — primary accent, key CTAs, highlights, soft radial washes. Pressed: `#F2B705`. Tint: `#FFE9A3`.
- **Navy/indigo #2A2A72** — headlines, sidebar, top dark surfaces, emphasis. The sidebar is a subtle vertical navy gradient (`#2A2A72 → #232361`).
- **Teal #0D9098** — links, the **active nav state**, secondary accent. Hover: `#0A7378`.
- **Cream #FAF8D1** — warm card/banner fills, the dignity-gate background.
- Neutrals: ink `#1c2430`, muted `#6b7686`, faint `#98a1b0`, hairline `#e4e8ef`, **app bg `#f7f6ef` (warm, never pure gray)**, card white `#fff`.
- **Six-state workflow ramp** (kept exactly): chờ-upload (gray) · đang xử lý (blue) · chờ duyệt (amber) · đã duyệt (green) · đã đăng (teal-green) · từ chối (red). This ramp also powers banners/toasts.

**Type.** **Playfair Display SemiBold** (warm editorial serif) for page titles, section headings, card titles, and **big KPI numbers**. **Roboto Condensed** for all UI/body/tables/nav/labels — condensed, so it stays legible at small sizes and scans well in dense tables. Monospace (SF Mono/Consolas) for technical strings. Scale runs 11→44px; the display 44px is reserved for KPI values and hero titles. Headings use `text-wrap: balance`, body uses `text-wrap: pretty`.

**Spacing & density.** 4px base rhythm (`--s1…--s10`). Deliberately a **calm, comfortable density** — table rows ~13px vertical padding, 24–32px gaps between sections — comfortable to scan all day, not cramped, not airy-marketing. Content frame caps at ~1180px and centers.

**Backgrounds.** Flat warm `#f7f6ef` app field; white cards. No big gradient fills. The **only** gradient is the navy sidebar and a faint sunflower **radial wash** in the top-right corner of KPI tiles. Photographic content (social posts) uses a **warm yellow protection wash** sweeping from a bottom corner (see `stream-a` reference) so white Playfair captions stay legible.

**Cards.** White, **1px hairline `#e4e8ef`** border, **soft warm shadow `0 1px 2px rgba(13,27,62,.04)`** (elevation ramp goes to `--sh-3`/`--sh-pop` for popovers/modals), **10–12px radius** (rounded-but-not-bubbly). Cream variant for warm callouts/banners.

**Corners / radii.** 6 (chips/inputs) · 8 (buttons) · 10–12 (cards) · 16 (modals) · 999 (pills, avatars).

**Borders & dividers.** Hairlines everywhere (`#e4e8ef`); lighter inner dividers `#eef1f6`. The active nav item gets a 3px **teal** inset left-rail + teal tint.

**Shadows.** Low, soft, navy-cast (never neutral-gray) — `--sh-1` resting, `--sh-2` hover lift, `--sh-3` sticky bars, `--sh-pop` modals/drawers. No hard or colored drop-shadows.

**Hover / press.** Buttons darken on hover (yellow→`#F2B705`, teal→`#0A7378`) and nudge **down 1px** on press (no shrink/scale). KPI tiles **lift −2px** with a softer shadow on hover and reveal their CTA. Links shift to deeper teal + underline. Transitions are short (.14s ease) and unobtrusive.

**Animation.** Restrained and functional: short fades/slides for modals & drawers (.18–.22s ease), a shimmer skeleton + teal spinner for loading, no bounces, no decorative loops. All motion respects `prefers-reduced-motion`.

**Transparency / blur.** Used sparingly for the sticky top bar and sticky action bar (`backdrop-filter: blur` over translucent white) and modal scrims (`rgba(28,36,48,.42)` + slight blur). Not decorative elsewhere.

**Brand motifs (restrained).** (1) the **sunflower mark** (looping line + little hearts) as logo and as the empty-state glyph; (2) a **3-petal** mark in navy/yellow/teal (from the quote-card reference) for small brand accents; (3) **sparkle diamonds** (yellow + teal) as occasional decoration on quote/brand surfaces; (4) the corner **sunflower radial wash**. Petal/sunflower accents are welcome but always *restrained* — legibility > decoration.

**Imagery vibe.** Real documentary photography of students/field activity, warm-toned, treated with the yellow protection wash and Playfair captions (never cold or desaturated).

---

## Iconography

See **`assets/`** for logo derivatives. The product had no bundled icon set, so the system standardizes on **[Lucide](https://lucide.dev)** (CDN), an open MIT line-icon family with a **2px stroke, rounded joins** — calm, friendly, and dignified, matching Roboto Condensed's tone and the brand's gentle line-art logo. *(This is a chosen substitution; swap for a self-hosted sprite in production. Flagged for the client.)*

- **Style:** outline / line icons only, 2px stroke, 18px in nav, 16px inline/in-buttons, never filled, never multicolor. Inherit `currentColor` so they take nav/teal/navy color contextually.
- **Active nav** icon turns **sunflower yellow**; resting nav icons are low-opacity cream.
- **Status** is communicated by the **pill + dot** system, not by colored icons.
- **Emoji:** only the single 🌻 in empty states. No emoji as functional icons.
- **Unicode:** breadcrumb separator `▸`; otherwise avoided.
- **Logo assets:**
  - `assets/hmt-logo-on-dark.png` — original master (dark wordmark; for light backgrounds).
  - `assets/hmt-logo-light.png` — cream wordmark + yellow mark, **for the navy sidebar/top bar**.
  - `assets/hmt-mark.png` — the **sunflower mark alone** (used as the favicon-scale brand glyph, the empty-state art, and the collapsed-nav logo).

---

## Index — what's in this folder

| Path | What it is |
|---|---|
| `colors_and_type.css` | **Foundations.** All color, type, spacing, radius, shadow tokens + semantic element defaults. |
| `hmt.css` | **Component layer.** The full reusable component set (shell, breadcrumb, cards, KPI tiles, nav, tabs, buttons, pills, chips, tables, sticky action bar, modal/drawer, banners, badges, forms, dignity gate, empty/loading, toast, pagination). Maps to your Jinja `base.html`. |
| `design-system.html` | **Reference page** — palette, type scale, spacing, and every component with its states. Start here. |
| `assets/` | Logos (master / light / mark), brand sheet, social-post references. |
| `fonts/` | Brand font files (Playfair Display SemiBold, Roboto Condensed SemiBold). |
| `preview/` | Small cards that populate the Design System tab. |
| `ui_kits/management-hub/` | High-fidelity recreation of the Hub: the persistent shell + the priority flows (Overview launchpad, Approval queue + bundle detail, Finance + thank-you queue). See its own README. |
| `SKILL.md` | Agent-Skills manifest for reusing this system. |

> **Start here:** open `design-system.html` for the documented system, then `ui_kits/management-hub/index.html` for the working shell + flows.
