# CommiTea Design System

**CommiTea** is an AI-project-manager built on Gitea: a lightweight Electron app (one window, React + Tailwind) where a local-ish LLM agent captures work via interview, maps capacity, and forecasts deadlines with Monte Carlo honesty. Gitea holds human-authored intent (issues, milestones, labels); a sidecar holds machine-derived state (forecasts, calibration). The agent talks; a deterministic scheduler does the math.

**Sources:** `uploads/commitea.md` — the product plan (concept, architecture decisions, UI intents, phases) — and `uploads/commitea.jpeg`, the app-icon logo (green tea cup on slate-teal). No Figma or codebase was provided; this system was designed from scratch against the brand brief: *"High-class British tea drinking experience, with intelligent professionalism — a 140-IQ assistant. The wit in the copy is what reminds you you're working professionally and playfully."*

**Product surfaces** (from the plan): Focus card (Now/Next/Later), burn-up chart with forecast cone, runway view, kanban + dependency drill-ins, and agent chat (chat = write-path, UI = read-path).

**Logo:** the provided app icon lives at `assets/logo.jpeg` (original, white margin) and `assets/logo-icon.png` (cropped, rounded). In UI chrome, pair the icon at 24px with the typographic wordmark — "CommiTea" in Libre Caslon Display. Never redraw the mark.

---

## CONTENT FUNDAMENTALS

The agent is **Reginald** — a brilliant, unflappable English gentleman of a project manager. Dry wit, never silly. Wit level ~7/10: almost every surface has one line with a raised eyebrow, and everything else is crisp and factual. He is "Reginald" in the UI and in copy — never "the AI", never "the assistant".

**Rules**

- **Reginald speaks in first person, addresses you as "you".** He has opinions and states them: "I'd take the parser bug first; it blocks three others."
- **Numbers are sacred, phrasing is warm.** Forecasts are always ranges, never point dates: "80% chance this lands Mar 3–12." Reginald never hedges the math, only decorates it: "The cone has narrowed. I'm quietly pleased."
- **Wit lives in complete sentences,** usually the last one. Never in buttons, labels, or data. Buttons are plain verbs: "Approve", "Brew plan", "Defer".
- **Tea vocabulary is a seasoning, not a theme park.** Sanctioned terms: *brew* (generate/plan), *steep* (work in progress), *service* (the daily standup — "Morning service"), *the pot* (backlog). Use at most one per screen. Never "tea-rrific", never puns on "oolong".
- **Sentence case everywhere** — titles, buttons, headers. No Title Case, no ALL CAPS except tiny overline labels.
- **No emoji. Ever.**
- **No exclamation marks** except in genuine celebration (milestone closed early).
- Machine data renders in mono, verbatim: `est/3d`, `p/2`, `deadline/hard`, `#142`.

**Specimen copy**

- Empty backlog: "The pot is empty. Tell me what you're planning and I'll draw up the tickets."
- Morning standup: "Morning service. Two things drifted overnight; one needs your opinion."
- Consequence diff: "Done — X ships today. Milestone Beta moves +6 days. Shall I make it so?"
- Blocked nag: "#87 has been steeping for four days. It blocks #91 and #92. Worth a look."
- Forecast: "80% this lands Mar 3–12. The estimate history says you're optimists — I've adjusted."
- Error: "Gitea isn't answering. I'll keep trying and say nothing more about it."
- Destructive confirm: "This deletes the milestone and unhouses 12 issues. I'd like to hear you say yes."

---

## VISUAL FOUNDATIONS

The aesthetic: **fine stationery meets instrument panel, poured as green tea.** Cool porcelain, slate-green ink, a hairline of jade. The interface should feel like a beautifully typeset letter that happens to compute Monte Carlo forecasts.

- **Color.** Cool porcelain surfaces (`--paper-0/1/2`, green-tinted whites), slate-green ink scale (`--ink-1/2/3`), one brand green (spruce — the logo's slate-teal, `--accent`), one gem (jade `--jade`, the tea's mint — used only in hairlines and small accents, never large fills). Status colors are muted (moss, oolong amber, madder red, wedgwood blue). Two themes: light "morning service" (default) and dark "evening service" via `[data-theme="dark"]`.
- **Type.** Four voices, strictly cast: **Libre Caslon Display** for headlines and hero numerals; **Libre Caslon Text (upright)** exclusively for Reginald's speech (if it's serif body text, Reginald said it — italics are reserved for occasional emphasis inside his sentences); **Instrument Sans** for all UI; **IBM Plex Mono** for machine data — labels, estimates, dates, issue ids, counts. Never let voices bleed: no serif UI copy, no sans forecasts.
- **Backgrounds.** Flat paper colors. No gradients, no textures, no imagery. Depth comes from paper-on-paper (card on app bg) plus hairlines.
- **Borders & rules.** 1px hairlines (`--line-1`) everywhere; a `3px double` rule (`--rule-double`) tops major sections like fine stationery. Key cards take a 2px inset jade top rule (`--shadow-jade-line`).
- **Cards.** `--surface-card` on `--surface-app`, 1px hairline border, `--radius-3` (10px), `--shadow-1`. Elevation is whispered, not shouted; `--shadow-3` is reserved for dialogs/popovers.
- **Corner radii.** Crisp: 4/6/10px. Pills only for chips and status dots. Nothing bubbly.
- **Hover states.** Surfaces: one porcelain step darker (`--paper-2`). Buttons: darker fill (`--accent-hover`). Links: jade underline appears. Never opacity fades on text.
- **Press states.** One step darker again (`--accent-pressed`); no shrink transforms.
- **Focus.** 2px `--focus-ring` outline, 2px offset, everywhere.
- **Motion.** Settled and gentlemanly: 120–320ms, `--ease-out`, fades and small translates (4–8px). No bounces, no springs, no infinite loops. The forecast cone may draw itself in once (~320ms).
- **Transparency & blur.** Almost never. Only dialog scrims (`rgba` ink at 40%). No glassmorphism.
- **Data visualization.** The cone is geometry, not decoration: filled band `--cone-fill`, edge `--cone-line`, actuals in ink. Ahead/behind reads as position, not color alone.
- **Layout.** Generous headers (Caslon breathes), compact data rows (dev-tool density in tables/boards, 32–36px rows). Fixed left rail navigation in-app; content column max ~1120px on wide screens.
- **Imagery.** None beyond the logo. No stock photos, no illustrations. The typography is the decoration.

---

## ICONOGRAPHY

- **System:** [Lucide](https://lucide.dev) at 1.5px stroke — copied locally into `assets/icons/*.svg` (69 icons, lucide-static v0.462.0). Use these files; do not hand-draw SVGs.
- **Usage:** 16px inline with text, 18–20px in buttons/nav. Stroke inherits `currentColor`. Icons always accompany a label except in `IconButton` (which requires a tooltip/aria-label).
- **Domain mapping:** issues `circle-dot`, milestones `milestone`, board `square-kanban`, forecast `chart-line`, gantt `chart-no-axes-gantt`, deps `network`, agent `sparkles`, standup `coffee`, capacity `gauge`, directives `flag`, git events `git-branch/git-commit-horizontal/git-pull-request/git-merge`.
- **No emoji, no unicode-chars-as-icons.** The only glyph liberty: mono `·` as a list separator and `—` in agent prose.
- **No icon font.** Inline the SVG or reference the file.

---

## INDEX

- `styles.css` — global entry; imports everything under `tokens/`
- `tokens/` — `colors.css`, `typography.css`, `spacing.css`, `fonts.css`, `base.css`
- `assets/fonts/` — self-hosted woff2 (Libre Caslon Display/Text, Instrument Sans, IBM Plex Mono)
- `assets/icons/` — Lucide SVGs (local copies); `assets/logo.jpeg` + `assets/logo-icon.png` — brand mark
- `guidelines/` — foundation specimen cards (Design System tab)
- `components/core/` — Button, IconButton, Badge, Tag, Card, Tabs
- `components/forms/` — Input, Select, Checkbox, Radio, Switch
- `components/feedback/` — Dialog, Toast, Tooltip
- `ui_kits/app/` — CommiTea Electron app recreation (Focus, Board, Agent chat, Runway)
- `SKILL.md` — agent-facing entry point

**Intentional additions:** `Icon` (wrapper that inlines local Lucide SVGs — needed because icons ship as files); `Tag` doubles as the gitea label chip (`est/*`, `p/*`, `deadline/hard`).
