# GoingsOn Design System — Charter This is the **canonical primitive list** for the GoingsOn frontend. Every JS module that renders markup MUST use the primitive named here. If a render need does not match a primitive, the fix is to extend the primitive — not to fork it locally. For visual specs (colors, sizes, shadows, hover behavior) see `styleguide.md`. This file is the inventory and the rules. **Stack:** Tauri 2 webview, vanilla HTML / CSS / JS. CSS in `src-tauri/frontend/css/styles.css`. JS modules under `src-tauri/frontend/js/` in IIFE `GoingsOn.*` namespace. Runtime themes in `src-tauri/frontend/themes/helix/`. --- ## Token layer — `styles.css :root` The only place hex literals are allowed (besides `themes/`). Every JS render path consumes these via CSS classes; never via `var(--…)` in a JS string and never via fallback hex. | Axis | Tokens | Notes | |---|---|---| | Surface color | `--bg-primary`, `--bg-secondary`, `--bg-tertiary`, `--bg-card`, `--bg-hover` | Themeable | | Text color | `--text-primary`, `--text-secondary`, `--text-muted`, `--text-on-accent` | Themeable | | Accent color | `--accent-yellow`, `--accent-green`, `--accent-blue`, `--accent-purple`, `--accent-red`, `--accent-cyan` | Themeable | | Accent alias | `--accent-color`, `--accent-primary` | Themeable | | Border | `--border-width` (2px), `--border-width-sm`, `--border-color`, `--border-light` | `--border-color` themeable; widths invariant | | Shadow | `--shadow-offset-xs/sm/md/lg/xl`, `--shadow-brutal-xs/md/lg/xl` | Theme-invariant (Neobrute signature) | | Radius | `--radius-xs/sm/md/lg/xl/full` | Invariant | | Spacing | `--space-1` … `--space-6` (0.25 → 1.5rem) | Invariant | | Type size | `--font-size-xxs` … `--font-size-4xl` | Invariant | | Line height | `--line-height-tight/normal/relaxed` | Invariant | | Font family | `--font-sans`, `--font-serif`, `--font-mono`, `--font-display` | Invariant | | Layout width | `--width-container`, `--width-modal`, `--width-sidebar` | Invariant | | Motion | `--transition-fast/normal/slow` | Invariant | | Cross-layer | `--timeline-slot-h` | Read by `js/day-planning-*` | **Rule:** every CSS property `js/themes.js` maps must exist in `:root`. Every property in `:root` that uses color must appear in `js/themes.js`'s mapping or carry a `/* theme-invariant */` comment. --- ## Component primitives — canonical class is the contract Each primitive below lists its **canonical class** (use this, only this). Modifier classes follow `--modifier` or `state-*` patterns. If you find yourself wanting a new modifier, add it here first. ### Button — `.btn` Variants: `.btn-primary`, `.btn-secondary`, `.btn-danger`, `.btn-icon`, `.btn-text`, `.btn-link`. Sizes: `.btn-sm` (default size is medium). State: `.btn-loading`. **Never** style a ``. Render via `GoingsOn.ui.renderEmptyState(message, buttonLabel?, onClick?)`. The non-canonical classes `.empty-dashboard-list`, `.kanban-empty`, `.virtual-scroller-empty` are **deprecated**; consolidate to `.empty-state` with size modifiers in remediation. ### Skeleton / loading Classes: `.skeleton-shimmer`, `.skeleton-row`, `.skeleton-lines`, `.skeleton-line.long | .medium | .short`, `.spinner`, `.loading`. Canonical helper (**to be added**): `GoingsOn.ui.renderSkeleton(kind, rows)`. No view uses skeletons today; once the helper exists, list views should switch on by default for the first paint after `invoke()`. ### Context menu — `.context-menu` State: `.visible`. Items: `.context-menu-item` (+ `--danger`), `.context-menu-separator`, `.context-menu-header`. Open via `GoingsOn.ui.showContextMenu(x, y, items)`. ### Tab / pill nav — `.tab-navigation` / `.pill-nav` Active state: `.tab.active` / `.pill.active`. Used in shell (`index.html`) only — feature modules should not introduce new tab styles. ### Filter bar — `.filter-bar` Children: `.filter-select`, `.filter-checkbox`. Used in tasks and emails filter rows. ### Progress bar — `.progress-bar-container` + `.progress-bar` Used in tasks (subtask completion) and reviews. ### Row primitives | Kind | Canonical class | Render helper (today) | |---|---|---| | Task row | `.task-row` (in `.task-table`) | `renderTaskRow(t, index)` — `tasks-render.js` | | Event row | `.event-row-virtual` (in `.event-table-virtual`) | inline in `events.js` | | Project card | `.card` (in `.cards-grid`) | inline in `projects-render.js` | | Contact card | `.card.contact-card` | inline in `contacts-render.js` | | Email row | `.email-item` (in `.email-list`) | inline in `emails.js` | **Canonical helper (to be added):** `GoingsOn.ui.renderRow(kind, model, opts)`. Each `renderXxx` above becomes a thin adapter that maps the model to the shared "icon · primary · secondary · meta · actions" slot layout. Surface audits in Phase 1+ assume this exists. ### Task row state classes (composed onto `.task-row`) `.task-overdue`, `.task-completed`, `.task-started`, `.task-snoozed`, `.task-timer-active`, `.priority-high | -medium | -low`, plus badges `.task-badge.has-items`, `.task-time-badge.over-estimate`. ### Bulk selection Bar: `.bulk-actions-bar`. Controls: `.bulk-checkbox`, `.bulk-select-all`, `.bulk-count`. Row state: `.selected`, `.keyboard-selected`. ### Kanban — `.kanban-board` Children: `.kanban-column`, `.kanban-card`, `.kanban-card-empty`. Used only by tasks-kanban view. ### Day-plan timeline — `.timeline-slot` Blocks: `.time-block`, `.block-focus`, `.block-personal`. Slot height read from `--timeline-slot-h`. ### Weekly review grid — `.weekly-grid` Cells: `.weekly-cell`, `.weekly-day-header`. ### Subtasks — `.subtask-item` Variant: `.subtask-item-linked` (left-border indicator for linked task). Children: `.subtask-checkbox`, `.subtask-text-done`. ### Shell — `.app-header` / `.app-body` / `.main-content` / `.page-header` / `.page-title` Feature modules do not redefine shell classes. --- ## Theme contract — `js/themes.js` Every theme is a TOML file under `themes/helix/` with a `[palette]` block (Helix-style names) and UI-key references. At runtime, `js/themes.js` maps 13 dotted TOML paths to CSS custom properties; selection persists to `localStorage` (`goingson-theme`). **Rules:** 1. A theme overrides **color tokens only**. Spacing, radius, shadow offsets, type are theme-invariant. 2. Every color token in `:root` either has a mapping in `js/themes.js` or is annotated `/* theme-invariant */`. Adding a new color token requires updating the mapping in the same PR. 3. JS rendering paths never read theme values directly — they use CSS classes that consume `var(--…)`. No JS string should contain `var(--accent-…, #fallback)` because the fallback bypasses the theme. --- ## Inline-style rules 1. `style="display:none"` in HTML is allowed only on the modal overlay and similar shell-level slots; feature views use `.hidden`. 2. No `style.cssText` in JS that contains a color, shadow, or border value. Layout-only inline styles (`flex`, `gap`, `min-width`) are tolerated during remediation; the goal is zero. 3. No hex literal in any file outside `styles.css` and `themes/*.toml`. 4. No `var(--token, #fallback)` — the fallback defeats theming. --- ## Cross-cutting rules These apply across every surface. Violations caught by reviewer checklist or `scripts/lint-frontend.sh`. Derived from the internal Phase 7 UX audit roll-up. ### State communication Every visual state — active, selected, running, error, success — must pair color with a second non-color signal: shape, position, weight, icon, or text. Color alone is not sufficient. (Phase 7 Pattern 1 — 6 surfaces affected.) ### Filter & view state in the URL Every filter, sort, and view-mode setting that changes what the user sees must be mirrored to `location.search` on change and restored on init. Filter state must not live only in the DOM or in module-level JS. A shared `js/query-state.js` helper covers all surfaces. (Pattern 2 — 5 surfaces affected.) ### Bulk operations always undoable Every bulk operation (any action touching more than one record at once) must wrap its API call in `GoingsOn.ui.showUndoToast` with a captured pre-state and an inverse operation. Use the shared `bulkActionWithUndo(action, inverse, ids, prevState)` helper. (Pattern 3 — 3 surfaces affected.) ### Native dialogs forbidden `window.confirm`, `window.prompt`, and `window.alert` are banned. Use `GoingsOn.ui.showConfirmDialog`, `GoingsOn.ui.showPromptDialog`, and `GoingsOn.ui.showToast`. Native dialogs are disabled on iOS WKWebView and unstyled on all platforms. Lint rule `no-native-dialogs` enforces this. ### Mobile is responsive CSS by default JS branches on `GoingsOn.touch.isTouchDevice` (or media-query equivalents) require explicit justification documented here. Default is shared component + CSS layout reflow. (Pattern 5 — Phase 6 architectural finding.) ### Multi-step flows show progress Any flow with more than two sequential modal steps shows a "Step N of M" indicator in the modal header. Applies to OAuth, encryption setup, plugin import wizards. ### Action bars cap at 5 visible A horizontal action bar has at most 5 visible actions; the rest live in an overflow `Actions ▾` menu. Primary actions get `.btn-primary`; destructive actions go in the overflow. ### Justified touch branches Modules with `isTouchDevice` branches must include a top-of-file comment naming what the branch does and why CSS-only isn't sufficient. --- ## Success criteria for remediation (input to the pre-Phase-1 plan) Phase 1 surface audits start when **all** of the following are true: - `GoingsOn.ui.renderRow(kind, model, opts)` exists, and `tasks-render.js`, `projects-render.js`, `contacts-render.js`, `events.js`, `emails.js` all call it (adapters allowed, parallel markup not). - `GoingsOn.ui.renderFormField({ … })` exists, and every form field in `form-modal.js`, `settings.js`, `email-accounts.js`, `settings-sync.js` is built through it. Error variant works. - `showToast` injects no `style.cssText`. All toast positioning, color, and shadow live on `.toast` + variant classes in `styles.css`. - Grep `\bstyle="` across `src-tauri/frontend/` returns no color, shadow, border, or font value; only visibility / layout micro-tweaks (and ideally none of those). - Grep `#[0-9a-fA-F]{3,8}` across `src-tauri/frontend/js/` and `src-tauri/frontend/*.html` returns zero matches. - Empty states: deprecate `.empty-dashboard-list`, `.kanban-empty`, `.virtual-scroller-empty`; consolidate to `.empty-state` with `--compact` / `--dashboard` modifiers, or keep them with explicit "use X when Y" rules documented in this charter. - Every color custom property in `styles.css :root` is either mapped in `js/themes.js` or carries a `/* theme-invariant */` comment. - `window.confirm()` calls: zero. All confirms route through `GoingsOn.ui.showConfirmDialog`. When all criteria hold, Phase 1 (Shell & navigation) may begin.