diff --git a/AI.md b/AI.md
index 2667f56..f4192fc 100644
--- a/AI.md
+++ b/AI.md
@@ -227,6 +227,7 @@ The core domain in `packages/core/src/domain/` covers the entities the plan call
- settings view is now a shell plus focused panels: `SettingsView.tsx` owns grouped tab navigation/tabpanel semantics only, while `GeneralSettings`, `AppearanceSettings`, `StorageSettings`, `ViewsSettings`, `MembersSettings`, `WorkflowSettings`, `LabelsMilestonesSettings`, `CustomFieldsSettings`, `PluginsSettings`, `AutomationSettings`, `ImportExportSettings`, and `BridgeSettings` own their own command wiring
- settings workflow, automation, and bridge sections should stay out of the shell; add future settings surfaces as focused files under `packages/ui/src/views/settings/` and register them through the shell tab list
- settings sections expose keyboard-accessible tab semantics with Arrow/Home/End navigation; inactive settings panels stay mounted with `hidden` instead of being unmounted so unsaved local form drafts survive section switches
+- the narrow Settings navigation recomposes into a single horizontally scrollable tab strip; keep `flex-direction: row` in the responsive rule because the base tab-list contract is column-oriented and otherwise pushes the active panel below the fold
- settings edit icons come from `lucide-react`, and import failures render as inline alerts instead of browser-native `alert()`
- `BridgeSettings.tsx` is truth-in-UI for future AI/MCP integration: it documents real core command coverage and explicitly says no installable bridge/server binary/client config is shipped yet, so do not add setup commands until a bridge runtime exists
- settings registry tables now follow a consistent edit flow for members/statuses/priorities/types:
@@ -286,6 +287,29 @@ The core domain in `packages/core/src/domain/` covers the entities the plan call
- docs use shared confirmation for document delete and lucide document icons instead of emoji UI markers
- `/item/:id` now renders through the shared modal shell instead of the legacy drawer route shell, with Archive/Trash/Duplicate/Done actions passed through `Modal`'s pinned footer slot
+## Visual system and appearance architecture
+
+- The color system is a finite semantic contract, not an open CSS editor. `packages/ui/src/theme/theme-contract.ts` owns every customizable `--color-*` role, its public types, grouped editor metadata, and the appearance/theme schema versions. Components should consume semantic roles; do not add route-local hex, rgb, named colors, or arbitrary user-authored CSS.
+- `packages/ui/src/theme/built-in-themes.ts` owns the immutable Grillo Adaptive, Graphite, Warm Sand, and High Contrast definitions. Every definition carries complete light and dark token records. `themeFromSeed()` clones a complete source palette and derives accent, hover, pressed, soft, focus, status-active, and readable foreground values for both modes.
+- `packages/ui/src/theme/color-utils.ts` is the dependency-free color boundary. It accepts only 3/4/6/8-digit hex, normalizes values, mixes colors, computes WCAG relative luminance/contrast, chooses a readable accent foreground, applies shared project accents, and strengthens muted text/borders for the explicit or system-derived high-contrast preference.
+- `packages/ui/src/theme/theme-storage.ts` owns device-local persistence and validation:
+ - `gph.appearance.v2` stores mode, selected theme, personal per-project theme bindings, contrast, and motion
+ - `gph.custom-themes.v1` stores sanitized custom theme definitions
+ - legacy `gph.theme` light/dark/system values migrate on read and are removed on the next save
+ - import/export is versioned JSON and requires every known semantic role in both modes; unknown objects cannot inject CSS
+- `ThemeProvider` combines built-ins plus custom themes, resolves system mode/contrast/motion media queries, applies the active complete token map to the root element, synchronizes preference/custom-theme changes across tabs through the `storage` event, updates `color-scheme` plus the browser theme-color meta value, and keeps a non-persisted preview layer for the editor. Its compatibility `theme`, `setTheme`, and `toggle` API remains available to existing shell controls.
+- Theme ownership is intentionally split:
+ - custom themes, default selection, and per-project theme binding are personal/device-local
+ - `ProjectMeta.accentColor` is shared project identity data
+ - `project.updateSettings.patch.accentColor` validates a six-digit hex value, writes it to `bundle.project`, and deliberately removes it from the `projectSettings` spread
+ - the provider overlays a shared project accent on the active personal palette, so collaborators can keep different themes while retaining the same project identity
+- Built-ins are immutable in the UI. Users clone a built-in or active theme before editing. Draft edits can preview across the running app, persist only on Save, and may be discarded; deletion uses inline confirmation. Contrast warnings inform but do not hard-block custom themes.
+- `tokens.css` is the first-paint fallback and shared non-color token layer. It declares matching Grillo light/dark values, rem-based type/spacing, motion timing, `color-scheme`, reduced-motion behavior, and forced-color focus handling. Runtime themes override only the semantic color variables.
+- `apps/web/index.html` and `apps/desktop/index.html` resolve the persisted light/dark/system choice before React starts to prevent the old light-mode flash. Full custom token application follows when `ThemeProvider` mounts.
+- `global.css` no longer authors component hex/rgb colors. Label colors, sidebar separators, shortcut/code surfaces, shadows, overlays, focus, feedback, and workflow colors all resolve through the theme contract. The CSS contract test fails on new component hex/rgb literals or unresolved custom-property references.
+- Accessibility guardrails include visible input focus rings, 4.5:1 text and 3:1 essential-boundary editor checks, readable generated accent foregrounds, system/explicit higher contrast, reduced motion, reduced transparency, and forced-colors handling. Low-contrast custom values remain possible by design and produce warnings rather than a lockout.
+- Responsive polish tied to this system includes a one-row horizontally scrollable Board toolbar, viewport-sized snap-aligned mobile board lanes, 44px narrow-screen button targets, a compact mobile Settings strip, consistent Overview metric hierarchy, and bordered work-item detail sections.
+
## Testing strategy
- TDD for the shared core: domain rules, command handlers, storage contract, and export/import
@@ -354,10 +378,11 @@ The core domain in `packages/core/src/domain/` covers the entities the plan call
- deep JSON import reference validation
- whole-card board-card link activation
- desktop storage adapter command wiring and shared adapter installation
+ - legacy theme-mode migration, malformed preference repair, safe custom-theme round trips, complete import validation, hex-only color parsing, WCAG contrast calculations, generated accent states, preset application, seed-theme creation, shared project accent validation, and semantic CSS completeness
- the Settings view test now always seeds a fresh project-store bundle per run instead of reusing any stale Zustand singleton state from prior tests
- UI test setup now installs a memory-backed `localStorage` shim when jsdom's storage implementation is unavailable or misconfigured, which keeps persistence-oriented tests deterministic
- `apps/desktop` now has a Vitest/jsdom test harness for the desktop storage adapter
-- Playwright e2e for hybrid parity, theme toggle, command palette, project creation, item creation with `C` shortcut, JSON export download, search, calendar day-cell work creation, docs create/save/edit-mode behavior, and mobile navigation
+- Playwright e2e for hybrid parity, theme toggle and Appearance preset persistence, command palette, project creation, item creation with `C` shortcut, JSON export download, search, calendar day-cell work creation, docs create/save/edit-mode behavior, mobile navigation, and a first-viewport check for the active mobile Settings panel
- `npm test` runs core, UI, and desktop adapter tests; `npm run test:e2e` runs `apps/web/scripts/run-e2e.mjs`, which starts Vite as an owned child process, waits for readiness, runs Playwright, and shuts Vite down before returning; `npm run typecheck` covers all packages and apps; `npm run lint` currently aliases typecheck until a dedicated lint stack is added
- `apps/web/scripts/run-e2e.mjs` owns the e2e base URL and passes it through `PLAYWRIGHT_BASE_URL`; `apps/web/playwright.config.ts` reads that environment value with a fixed local fallback so runner and config cannot silently drift.
@@ -368,7 +393,7 @@ The core domain in `packages/core/src/domain/` covers the entities the plan call
- implemented the validated command dispatcher with envelope + dispatch table + per-command handlers and event logging
- implemented starter templates: `simple-kanban`, `software-project`, `bug-tracker`, `release-planner`
- implemented search, export (JSON / Markdown / CSV), and import (JSON + CSV) in the shared core
-- implemented the React AppShell, theme provider (light/dark/system), and command palette with navigation, item creation, view switching, search hits, and theme toggle commands
+- implemented the React AppShell, versioned semantic theme runtime and Appearance studio, and command palette with navigation, item creation, view switching, search hits, and theme toggle commands
- implemented board, backlog, table, docs (with sanitized Markdown and backlinks), roadmap (drag/resize), calendar, bug triage, my work, search, settings, and the work item drawer
- configured the Tauri desktop shell with narrow Rust commands and a folder-backed storage adapter
- added the PWA manifest, service worker registration, favicon, and auto-save bridge for the web app
diff --git a/Readme.md b/Readme.md
index 609c1c4..bc2e98c 100644
--- a/Readme.md
+++ b/Readme.md
@@ -56,10 +56,24 @@ Grillo is past the skeleton stage. The current app includes:
- Bug triage with readable lanes, severity/priority/source/context fields, intake gates, accept/decline/snooze/assign actions, and a searchable duplicate-link picker.
- Automation rules with command-backed create/update/delete/enable/disable, dry-run previews, item-event triggers, and audited action failures.
- JSON, Markdown, and CSV import/export, plus clean print preview.
-- Light/dark/system themes, a remembered desktop sidebar that toggles between full navigation and an icon rail, context-aware no-project navigation, responsive mobile navigation and project tabs, offline status, and local/self-hosted PWA install support when the browser exposes it.
+- A full Appearance studio with light/dark/system modes, Grillo Adaptive, Graphite, Warm Sand, and High Contrast presets, seed-based custom theme creation, every authored UI color exposed as a semantic role, live preview, contrast checks, safe JSON import/export, per-project personal overrides, and a shared project accent.
+- A remembered desktop sidebar that toggles between full navigation and an icon rail, context-aware no-project navigation, responsive mobile navigation and project tabs, offline status, and local/self-hosted PWA install support when the browser exposes it.
- Planning-surface UX polish including aligned Backlog rows, progressive Table controls, a keyboard-operable Roadmap resize grip, a complete seven-day Calendar beside its agenda, and item-title link names for assistive technology.
- A realistic, non-persistent demo workspace with active and completed work, bug intake, comments, members, dates, milestones, and linked docs.
+## Appearance and themes
+
+Open **Settings -> Appearance** to choose a preset or build your own. Grillo stores light and dark values together, so a custom theme remains coherent when the operating system changes modes.
+
+- Color mode, contrast, motion, selected theme, custom themes, and per-project theme bindings stay local to the current device and browser profile.
+- The optional project accent is different: it is stored in the project bundle and shared with collaborators. Grillo derives its hover, pressed, soft, focus, and readable foreground states automatically.
+- Built-in themes are immutable. Clone one before changing individual semantic roles.
+- Theme imports accept only the versioned Grillo theme structure and recognized hex color values. Imported files cannot inject arbitrary CSS.
+- The editor reports key WCAG text and control-boundary contrast pairs without preventing intentional low-contrast experimentation.
+- System contrast and reduced-motion preferences are respected, with explicit user overrides available.
+
+All authored component colors now route through the semantic contract in `packages/ui/src/theme/theme-contract.ts`. The default palette remains recognizably Grillo, with stronger text, focus, border, and accent contrast than the original token set.
+
## Storage model
The durable project format is a `.pms.json` bundle under `.pm-suite/` when using folder-backed storage. Browser-local projects use local browser storage as a compatibility layer.
diff --git a/apps/desktop/index.html b/apps/desktop/index.html
index 15d4293..a2b8f6e 100644
--- a/apps/desktop/index.html
+++ b/apps/desktop/index.html
@@ -3,6 +3,21 @@
+
+
Grillo Project Hub
diff --git a/apps/web/index.html b/apps/web/index.html
index b3e5348..e849a55 100644
--- a/apps/web/index.html
+++ b/apps/web/index.html
@@ -5,6 +5,20 @@
+
Grillo Project Hub
diff --git a/docs/plans/2026-07-18-visual-system-personalization.md b/docs/plans/2026-07-18-visual-system-personalization.md
new file mode 100644
index 0000000..a8cef46
--- /dev/null
+++ b/docs/plans/2026-07-18-visual-system-personalization.md
@@ -0,0 +1,96 @@
+# Visual System and Personalization Update
+
+Status: implemented on `codex/visual-system-personalization`
+
+## Goal
+
+Raise Grillo's visual polish without replacing its calm, nature-led identity, then give users a safe path from quick presets to complete color control. The same system must work in the browser and Tauri shell, survive older saved preferences, respect system accessibility settings, and remain understandable to future contributors.
+
+## Research signals
+
+The implementation follows the patterns that consistently appeared across mature design systems and accessibility specifications:
+
+- [WCAG 2.2 contrast guidance](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) establishes 4.5:1 for ordinary text, with 3:1 used for large text and essential non-text boundaries.
+- [Media Queries Level 5](https://www.w3.org/TR/mediaqueries-5/) defines preferences such as reduced motion, reduced transparency, and increased contrast.
+- [CSS Color Adjustment](https://www.w3.org/TR/css-color-adjust-1/) defines `color-scheme` and forced-color behavior.
+- [Atlassian design tokens](https://atlassian.design/foundations/tokens/), [Fluent 2 tokens](https://fluent2.microsoft.design/design-tokens), and [Carbon themes](https://carbondesignsystem.com/elements/themes/overview/) converge on primitives feeding semantic aliases, with themes expressed as complete value maps rather than component-specific overrides.
+- The [Design Tokens Community Group format](https://www.designtokens.org/TR/drafts/format/) informed the versioned, data-only import/export boundary. Grillo keeps a narrower application schema for now so imports cannot become arbitrary CSS.
+
+## Product model
+
+Three levels serve different users without exposing complexity too early:
+
+1. Quick selection: system/light/dark, contrast and motion preferences, plus Grillo Adaptive, Graphite, Warm Sand, and High Contrast presets.
+2. Theme creation: name a theme, choose a seed, and derive accessible light/dark accent states from the current palette.
+3. Advanced editing: clone a theme and edit every semantic color role in both modes, with live app preview and a contrast report.
+
+Theme selection, custom themes, and personal per-project overrides are device-local. A project accent is shared in the project bundle; it overlays identity roles without forcing collaborators to use the same theme.
+
+## Technical plan and delivered mapping
+
+### 1. Establish the semantic contract
+
+- Define one typed list for canvas/surfaces, text/icons, controls/focus, feedback/workflow, labels, and visual effects.
+- Move every authored component color, including label chips, shadow tint, sidebar separators, and code/shortcut surfaces, behind those roles.
+- Keep layout, type, spacing, radii, and motion as shared non-theme tokens.
+
+Delivered in `theme-contract.ts`, `tokens.css`, `global.css`, and `WorkItemCard.tsx`.
+
+### 2. Add a resilient runtime
+
+- Version preferences and custom themes separately.
+- Migrate the former `gph.theme` value.
+- Resolve system mode, contrast, and motion; apply complete token maps at the root; synchronize tabs.
+- Bootstrap mode before React to avoid a first-paint flash.
+- Preserve the old provider API used by the header and command system.
+
+Delivered in `theme-storage.ts`, `theme-provider.tsx`, and both app `index.html` files.
+
+### 3. Build the Appearance studio
+
+- Show real miniature previews for built-ins and customs.
+- Support default-device and personal per-project selection.
+- Create from seed, clone, edit both modes, preview, save/discard, inline-confirm delete, reset, and safe import/export.
+- Warn on key text/control contrast pairs while allowing intentional experimentation.
+
+Delivered in `AppearanceSettings.tsx` and its responsive styling.
+
+### 4. Separate personal appearance from project identity
+
+- Keep custom themes and selection out of project data.
+- Add a validated shared six-digit project accent.
+- Derive hover, pressed, soft, focus, active-status, and foreground roles at runtime.
+
+Delivered through `project.updateSettings.patch.accentColor`, `ProjectMeta.accentColor`, and the theme provider overlay.
+
+### 5. Apply the highest-impact polish
+
+- Strengthen default foreground and boundary contrast while retaining the Grillo palette.
+- Restore visible form focus, add motion/transparency/forced-colors behavior, and standardize transition timing.
+- Recompose narrow Settings navigation into a horizontal strip.
+- Keep the Board toolbar in one scrollable row and size mobile lanes to the viewport with snap behavior.
+- Give Overview metrics a consistent hierarchy and work-item sections clearer separation.
+- Use theme-aware label colors everywhere they appear.
+
+Delivered in `tokens.css`, `global.css`, `ViewToolbar.tsx`, Board, Table, Labels settings, Overview, and work-item styling.
+
+## Safety and acceptance criteria
+
+- No component-authored hex/rgb color literals outside theme definitions and color utilities.
+- Every CSS custom-property reference has a declaration.
+- Imported themes contain a complete light and dark semantic map and hex-only values.
+- Built-ins cannot be overwritten or deleted.
+- A broken preference or theme falls back to Grillo Adaptive.
+- Custom theme previews do not persist until Save.
+- Existing light/dark/system preferences migrate.
+- System mode avoids a light flash on startup.
+- Text/control contrast is visible to the user before sharing a theme.
+- Core, UI, web, and desktop type checks/builds pass; theme storage, generation, settings flows, CSS contracts, and project accent commands have regression coverage.
+- Desktop light/dark and 390px mobile Appearance/Board states receive rendered browser QA.
+
+## Follow-on opportunities
+
+- Add typography and density profiles as separate preference axes; do not overload the color theme schema.
+- Add a curated theme gallery only after provenance, compatibility, and trust UX are defined.
+- Consider exporting a parallel full DTCG document if other tools need interchange; keep application import validation narrower than the general standard.
+- Add automated browser-level contrast and forced-colors snapshots once the E2E environment has stable visual baselines.
diff --git a/packages/core/src/commands/dispatcher.test.ts b/packages/core/src/commands/dispatcher.test.ts
index 49d8ab8..e15babb 100644
--- a/packages/core/src/commands/dispatcher.test.ts
+++ b/packages/core/src/commands/dispatcher.test.ts
@@ -984,6 +984,29 @@ describe("command dispatcher", () => {
).toThrow(/Project mismatch/);
});
+ it("stores a validated shared project accent outside personal appearance settings", () => {
+ const bundle = createProjectBundle({ name: "Branded" });
+ const result = dispatchCommand(
+ bundle,
+ envelopeFor({
+ type: "project.updateSettings",
+ projectId: bundle.project.id,
+ patch: { accentColor: "#245ea8" }
+ }, "ui", null)
+ );
+
+ expect(result.bundle.project.accentColor).toBe("#245ea8");
+ expect(result.bundle.projectSettings).not.toHaveProperty("accentColor");
+ expect(() => dispatchCommand(
+ result.bundle,
+ envelopeFor({
+ type: "project.updateSettings",
+ projectId: bundle.project.id,
+ patch: { accentColor: "blue" }
+ }, "ui", null)
+ )).toThrow(/six-digit hex/);
+ });
+
it("stores edits previews disables and deletes automation rules", () => {
let bundle = buildProjectFromTemplate("software-project", "Automation");
const label = bundle.core.labels.find((entry) => entry.name === "frontend")!;
diff --git a/packages/core/src/commands/dispatcher.ts b/packages/core/src/commands/dispatcher.ts
index e87ee3e..d40b45c 100644
--- a/packages/core/src/commands/dispatcher.ts
+++ b/packages/core/src/commands/dispatcher.ts
@@ -368,6 +368,7 @@ function updateProjectSettings(
enabledModuleIds?: string[];
hiddenViewIds?: string[];
pluginTrustMode?: "first-party" | "curated" | "unrestricted";
+ accentColor?: string | null;
};
}
): DispatchResult {
@@ -375,11 +376,18 @@ function updateProjectSettings(
if (payload.patch.pluginTrustMode && !["first-party", "curated", "unrestricted"].includes(payload.patch.pluginTrustMode)) {
throw new Error(`Invalid plugin trust mode: ${payload.patch.pluginTrustMode}`);
}
+ if (payload.patch.accentColor !== undefined && payload.patch.accentColor !== null && !/^#[0-9a-f]{6}$/i.test(payload.patch.accentColor)) {
+ throw new Error("Project accent color must be a six-digit hex color");
+ }
+ const { accentColor, ...settingsPatch } = payload.patch;
const next = bumpRevision({
...bundle,
+ project: accentColor === undefined
+ ? bundle.project
+ : { ...bundle.project, accentColor },
projectSettings: {
...bundle.projectSettings,
- ...payload.patch,
+ ...settingsPatch,
enabledModuleIds: payload.patch.enabledModuleIds ? [...payload.patch.enabledModuleIds] : bundle.projectSettings.enabledModuleIds,
hiddenViewIds: payload.patch.hiddenViewIds ? [...payload.patch.hiddenViewIds] : (bundle.projectSettings.hiddenViewIds ?? [])
}
diff --git a/packages/core/src/commands/envelope.ts b/packages/core/src/commands/envelope.ts
index 48ec7af..c49a727 100644
--- a/packages/core/src/commands/envelope.ts
+++ b/packages/core/src/commands/envelope.ts
@@ -111,6 +111,8 @@ export type ProjectUpdateSettingsPayload = {
enabledModuleIds?: string[];
hiddenViewIds?: string[];
pluginTrustMode?: "first-party" | "curated" | "unrestricted";
+ /** Shared project identity color. Null follows the active personal theme. */
+ accentColor?: string | null;
};
};
diff --git a/packages/ui/src/components/layout/ViewToolbar.tsx b/packages/ui/src/components/layout/ViewToolbar.tsx
index 40c0fc6..cdd0762 100644
--- a/packages/ui/src/components/layout/ViewToolbar.tsx
+++ b/packages/ui/src/components/layout/ViewToolbar.tsx
@@ -1,5 +1,5 @@
import { type ReactNode } from "react";
-export function ViewToolbar({ children }: { children: ReactNode }) {
- return