commitea/docs/design/design_system_readme.md

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 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).