| 1 |
# GoingsOn Design System — Charter |
| 2 |
|
| 3 |
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. |
| 4 |
|
| 5 |
For visual specs (colors, sizes, shadows, hover behavior) see `styleguide.md`. This file is the inventory and the rules. |
| 6 |
|
| 7 |
**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/`. |
| 8 |
|
| 9 |
--- |
| 10 |
|
| 11 |
## Token layer — `styles.css :root` |
| 12 |
|
| 13 |
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. |
| 14 |
|
| 15 |
|
| 16 |
|
| 17 |
| Surface color | `--bg-primary`, `--bg-secondary`, `--bg-tertiary`, `--bg-card`, `--bg-hover` | Themeable | |
| 18 |
| Text color | `--text-primary`, `--text-secondary`, `--text-muted`, `--text-on-accent` | Themeable | |
| 19 |
| Accent color | `--accent-yellow`, `--accent-green`, `--accent-blue`, `--accent-purple`, `--accent-red`, `--accent-cyan` | Themeable | |
| 20 |
| Accent alias | `--accent-color`, `--accent-primary` | Themeable | |
| 21 |
| Border | `--border-width` (2px), `--border-width-sm`, `--border-color`, `--border-light` | `--border-color` themeable; widths invariant | |
| 22 |
| Shadow | `--shadow-offset-xs/sm/md/lg/xl`, `--shadow-brutal-xs/md/lg/xl` | Theme-invariant (Neobrute signature) | |
| 23 |
| Radius | `--radius-xs/sm/md/lg/xl/full` | Invariant | |
| 24 |
| Spacing | `--space-1` … `--space-6` (0.25 → 1.5rem) | Invariant | |
| 25 |
| Type size | `--font-size-xxs` … `--font-size-4xl` | Invariant | |
| 26 |
| Line height | `--line-height-tight/normal/relaxed` | Invariant | |
| 27 |
| Font family | `--font-sans`, `--font-serif`, `--font-mono`, `--font-display` | Invariant | |
| 28 |
| Layout width | `--width-container`, `--width-modal`, `--width-sidebar` | Invariant | |
| 29 |
| Motion | `--transition-fast/normal/slow` | Invariant | |
| 30 |
| Cross-layer | `--timeline-slot-h` | Read by `js/day-planning-*` | |
| 31 |
|
| 32 |
**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. |
| 33 |
|
| 34 |
--- |
| 35 |
|
| 36 |
## Component primitives — canonical class is the contract |
| 37 |
|
| 38 |
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. |
| 39 |
|
| 40 |
### Button — `.btn` |
| 41 |
Variants: `.btn-primary`, `.btn-secondary`, `.btn-danger`, `.btn-icon`, `.btn-text`, `.btn-link`. |
| 42 |
Sizes: `.btn-sm` (default size is medium). |
| 43 |
State: `.btn-loading`. |
| 44 |
**Never** style a `<button>` without `.btn`. **Never** inline a hex color on a button. |
| 45 |
|
| 46 |
### Card — `.card` |
| 47 |
Sub-parts: `.card-header`, `.card-title`, `.card-description`, `.card-meta`, `.card-badge`. |
| 48 |
Container: `.cards-grid`. |
| 49 |
Used by: projects-render, contacts-render, dashboard tiles. |
| 50 |
|
| 51 |
### Form field — `.form-group` |
| 52 |
Sub-parts: `.form-label`, `.form-input | .form-select | .form-textarea`, `.form-actions`, `.form-row`. |
| 53 |
Canonical render helper (**to be added**): `GoingsOn.ui.renderFormField({ kind, label, value, error, help })`. Until it exists, hand-rolled `.form-group` blocks are tolerated; once it lands they are not. |
| 54 |
|
| 55 |
### Badge / Tag — `.badge`, `.tag` |
| 56 |
Color variant: `[data-color="green|yellow|red|cyan|purple|muted"]`. |
| 57 |
Status variant on `.tag`: `.status-active | .status-onhold | .status-archived | .status-inactive | .status-completed`. |
| 58 |
|
| 59 |
### Modal — `.modal-overlay` (single global) |
| 60 |
Open via `GoingsOn.ui.openModal(title, html, opts)`. Sub-parts: `.modal-container` (+ `.modal-large`), `.modal-header`, `.modal-title`, `.modal-content`, `.modal-close`. Visibility via `.hidden` / `.closing`. **There is only one modal overlay in the DOM** (`#modal-overlay` in `index.html`); never create another. |
| 61 |
|
| 62 |
### Toast — `.toast` |
| 63 |
Variants: `.toast-info`, `.toast-success`, `.toast-error`, `.toast-undo`. |
| 64 |
Undo sub-parts: `.undo-message`, `.undo-btn`, `.undo-countdown`. |
| 65 |
Show via `GoingsOn.ui.showToast(msg, type, opts)` or `GoingsOn.ui.showUndoToast(...)`. |
| 66 |
**Rule (to be enforced):** positioning, shadow, and color belong on these classes in CSS — `showToast` MUST NOT inject `style.cssText`. Today's helper violates this; fix in remediation. |
| 67 |
|
| 68 |
### Confirm dialog |
| 69 |
Render via `GoingsOn.ui.showConfirmDialog(title, message, opts)` or `GoingsOn.ui.confirmDelete(name, action)`. Uses the global modal. **Never** call `window.confirm()` (one offender remains in `contacts.js` — fix in remediation). |
| 70 |
|
| 71 |
### Empty state — `.empty-state` |
| 72 |
Canonical: `<div class="empty-state"><div class="empty-state-icon">…</div><p class="empty-state-text">…</p><button class="btn btn-primary">…</button></div>`. |
| 73 |
Render via `GoingsOn.ui.renderEmptyState(message, buttonLabel?, onClick?)`. |
| 74 |
The non-canonical classes `.empty-dashboard-list`, `.kanban-empty`, `.virtual-scroller-empty` are **deprecated**; consolidate to `.empty-state` with size modifiers in remediation. |
| 75 |
|
| 76 |
### Skeleton / loading |
| 77 |
Classes: `.skeleton-shimmer`, `.skeleton-row`, `.skeleton-lines`, `.skeleton-line.long | .medium | .short`, `.spinner`, `.loading`. |
| 78 |
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()`. |
| 79 |
|
| 80 |
### Context menu — `.context-menu` |
| 81 |
State: `.visible`. Items: `.context-menu-item` (+ `--danger`), `.context-menu-separator`, `.context-menu-header`. |
| 82 |
Open via `GoingsOn.ui.showContextMenu(x, y, items)`. |
| 83 |
|
| 84 |
### Tab / pill nav — `.tab-navigation` / `.pill-nav` |
| 85 |
Active state: `.tab.active` / `.pill.active`. Used in shell (`index.html`) only — feature modules should not introduce new tab styles. |
| 86 |
|
| 87 |
### Filter bar — `.filter-bar` |
| 88 |
Children: `.filter-select`, `.filter-checkbox`. Used in tasks and emails filter rows. |
| 89 |
|
| 90 |
### Progress bar — `.progress-bar-container` + `.progress-bar` |
| 91 |
Used in tasks (subtask completion) and reviews. |
| 92 |
|
| 93 |
### Row primitives |
| 94 |
|
| 95 |
|
| 96 |
|
| 97 |
| Task row | `.task-row` (in `.task-table`) | `renderTaskRow(t, index)` — `tasks-render.js` | |
| 98 |
| Event row | `.event-row-virtual` (in `.event-table-virtual`) | inline in `events.js` | |
| 99 |
| Project card | `.card` (in `.cards-grid`) | inline in `projects-render.js` | |
| 100 |
| Contact card | `.card.contact-card` | inline in `contacts-render.js` | |
| 101 |
| Email row | `.email-item` (in `.email-list`) | inline in `emails.js` | |
| 102 |
|
| 103 |
**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. |
| 104 |
|
| 105 |
### Task row state classes (composed onto `.task-row`) |
| 106 |
`.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`. |
| 107 |
|
| 108 |
### Bulk selection |
| 109 |
Bar: `.bulk-actions-bar`. Controls: `.bulk-checkbox`, `.bulk-select-all`, `.bulk-count`. Row state: `.selected`, `.keyboard-selected`. |
| 110 |
|
| 111 |
### Kanban — `.kanban-board` |
| 112 |
Children: `.kanban-column`, `.kanban-card`, `.kanban-card-empty`. Used only by tasks-kanban view. |
| 113 |
|
| 114 |
### Day-plan timeline — `.timeline-slot` |
| 115 |
Blocks: `.time-block`, `.block-focus`, `.block-personal`. Slot height read from `--timeline-slot-h`. |
| 116 |
|
| 117 |
### Weekly review grid — `.weekly-grid` |
| 118 |
Cells: `.weekly-cell`, `.weekly-day-header`. |
| 119 |
|
| 120 |
### Subtasks — `.subtask-item` |
| 121 |
Variant: `.subtask-item-linked` (left-border indicator for linked task). Children: `.subtask-checkbox`, `.subtask-text-done`. |
| 122 |
|
| 123 |
### Shell — `.app-header` / `.app-body` / `.main-content` / `.page-header` / `.page-title` |
| 124 |
Feature modules do not redefine shell classes. |
| 125 |
|
| 126 |
--- |
| 127 |
|
| 128 |
## Theme contract — `js/themes.js` |
| 129 |
|
| 130 |
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`). |
| 131 |
|
| 132 |
**Rules:** |
| 133 |
1. A theme overrides **color tokens only**. Spacing, radius, shadow offsets, type are theme-invariant. |
| 134 |
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. |
| 135 |
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. |
| 136 |
|
| 137 |
--- |
| 138 |
|
| 139 |
## Inline-style rules |
| 140 |
|
| 141 |
1. `style="display:none"` in HTML is allowed only on the modal overlay and similar shell-level slots; feature views use `.hidden`. |
| 142 |
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. |
| 143 |
3. No hex literal in any file outside `styles.css` and `themes/*.toml`. |
| 144 |
4. No `var(--token, #fallback)` — the fallback defeats theming. |
| 145 |
|
| 146 |
--- |
| 147 |
|
| 148 |
## Cross-cutting rules |
| 149 |
|
| 150 |
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. |
| 151 |
|
| 152 |
### State communication |
| 153 |
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.) |
| 154 |
|
| 155 |
### Filter & view state in the URL |
| 156 |
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.) |
| 157 |
|
| 158 |
### Bulk operations always undoable |
| 159 |
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.) |
| 160 |
|
| 161 |
### Native dialogs forbidden |
| 162 |
`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. |
| 163 |
|
| 164 |
### Mobile is responsive CSS by default |
| 165 |
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.) |
| 166 |
|
| 167 |
### Multi-step flows show progress |
| 168 |
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. |
| 169 |
|
| 170 |
### Action bars cap at 5 visible |
| 171 |
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. |
| 172 |
|
| 173 |
### Justified touch branches |
| 174 |
Modules with `isTouchDevice` branches must include a top-of-file comment naming what the branch does and why CSS-only isn't sufficient. |
| 175 |
|
| 176 |
--- |
| 177 |
|
| 178 |
## Success criteria for remediation (input to the pre-Phase-1 plan) |
| 179 |
|
| 180 |
Phase 1 surface audits start when **all** of the following are true: |
| 181 |
|
| 182 |
- `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). |
| 183 |
- `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. |
| 184 |
- `showToast` injects no `style.cssText`. All toast positioning, color, and shadow live on `.toast` + variant classes in `styles.css`. |
| 185 |
- Grep `\bstyle="` across `src-tauri/frontend/` returns no color, shadow, border, or font value; only visibility / layout micro-tweaks (and ideally none of those). |
| 186 |
- Grep `#[0-9a-fA-F]{3,8}` across `src-tauri/frontend/js/` and `src-tauri/frontend/*.html` returns zero matches. |
| 187 |
- 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. |
| 188 |
- Every color custom property in `styles.css :root` is either mapped in `js/themes.js` or carries a `/* theme-invariant */` comment. |
| 189 |
- `window.confirm()` calls: zero. All confirms route through `GoingsOn.ui.showConfirmDialog`. |
| 190 |
|
| 191 |
When all criteria hold, Phase 1 (Shell & navigation) may begin. |
| 192 |
|