christian/commitea
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
feat/sqlite-cache
commitea/docs/design/design_system_readme.md
Christian LeDoux 7a5cacc54c Scaffold CommiTea: yarn workspaces, Electron shell, core label schema, design system 
- apps/desktop: electron-vite + React + Tailwind mapped onto design tokens
  (preflight off; tokens/base.css owns the reset); boots to a Reginald
  placeholder proving fonts/tokens/core wiring
- packages/core: pure TS; gitea label schema (est/*, p/*, deadline/hard)
  with pessimistic conflict resolution + 15 unit tests
- docs/design: full design handoff (tokens, 16 component contracts,
  interactive 14-screen prototype, Reginald voice rules)
- docs/PLAN.md: product plan (purity rule, pm-state repo, deterministic
  scheduler + Monte Carlo, directive log)
- Deliberate deviation from novelpad stack: no ElectricSQL/PGlite — local
  store is a rebuildable cache over gitea REST/webhooks (better-sqlite3
  in main process, arriving in P1)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-07 20:42:46 -04:00

85 lines
8.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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`).
Reference in New Issue View Git Blame Copy Permalink