EthanHealy01
b86e963c9d
## What this does Consolidates the frontend's colour/theme system into a small, well-defined token layer and reworks the theme picker. The goal was a minimal, scalable set of semantic tokens that the editor **and** the Processor/portal (and Storybook) all share, plus a theme model that's easy to reason about. ## Token architecture (`core/theme/`) A four-file layer, imported once via `index.css`: | File | Role | |---|---| | `primitives.css` | The raw palette — the **only** place literal colours live (neutral ramps `--p-gray-*`/`--p-zinc-*` + status hues). | | `colors.css` | ~21 semantic `--c-*` tokens (surfaces, text, borders, primary, status) mapped from primitives per theme. **Reference these.** | | `compat.css` | Legacy names (`--bg-*`, `--text-*`, `--color-*`) aliased onto `--c-*` via `:root:root` so ~200 existing files keep working. | | `dimensions.css` | All non-colour tokens (spacing, radius, z-index, type, motion) — single source, resolving prior collisions. | A blocking linter (`scripts/lint/theme-lint.mjs`, run in `frontend:lint`) enforces "literals only in `primitives.css`" within `core/theme/`, and has a non-blocking WCAG contrast report. See `core/theme/README.md`. ## Theme model - **Mode** (`light` / `dark` / `system`) and **accent** are independent. Each mode has its own accent (`lightPrimary` / `darkPrimary`). - The editor is always `data-app-theme="custom"`; `ThemeProvider` injects the accent as `--user-primary` and sets `data-accent`. - **Two accent states:** - A **colour** (preset or custom hex) → tints every surface that hue (whole-app theming). - The **`default`** sentinel → neutral surfaces (white/grey light, zinc black/grey dark) with blue buttons, no tint. (`data-accent="default"` opts surfaces out of the tint.) - Accent contrast guardrails (`utils/customPrimary.ts`): lightness clamps so an accent can't collapse into the base, a contrast-picked on-primary foreground, and an accent-as-foreground variant so accent text is never dark-on-dark. ## Theme picker (Settings → General) - 3×5 grid: a distinct **Default** icon chip (not a colour) + 14 curated accents, in a dropdown per mode. - **Custom** colour via the shared `ColorInput`, with a live gamut clamp (`clampValue`) that refuses white/grey/black — the picker handle sticks at the boundary and preserves the working hue at achromatic extremes. - "Restore theme to default" resets both modes. ## Other - Dark mode is a true neutral zinc (no navy "midnight" tint); the Mantine dark ramp and Tailwind dark channels were neutralised to match. - Pre-paint inline script in `index.html` applies theme + accent before first paint (no FOUC); portal and editor now share the same `preferences.theme` source of truth. - High-visibility surfaces migrated to tokens (FAB, landing upload buttons, portal hero banners); scattered per-component colour swaps were intentionally **left for a follow-up** to keep this PR focused. ## Testing - `task frontend:check:all` (typecheck all variants + eslint + prettier + colour-lint) green. - Verified light/dark, default vs tinted accents, and the custom clamp via computed styles in the dev preview. > Note: the `prerender-og` build step failing in the e2e/deploy jobs is unrelated to this diff — it's in `vite.config.ts` (untouched here) and builds cleanly locally.
Frontend
All frontend commands are run from the repository root using Task:
task frontend:dev— start Vite dev server (localhost:5173)task frontend:build— production buildtask frontend:test— run teststask frontend:test:watch— run tests in watch modetask frontend:lint— run ESLint + cycle detectiontask frontend:typecheck— run TypeScript type checkingtask frontend:check— run typecheck + lint + testtask frontend:install— install npm dependencies
For desktop app development, see the Tauri section below.
Layout
frontend/ is a workspace containing one or more apps. Today it holds the
PDF editor under frontend/editor/; new apps (the developer portal, etc.)
will sit alongside it as siblings. Shared tooling — package.json, node_modules,
.storybook/, ESLint, Prettier — lives at frontend/ so every app installs
once and lints with the same config.
Environment Variables
The editor's environment variables live in committed .env files at
frontend/editor/:
.env— used by all builds (core, proprietary, and as the base for desktop/SaaS).env.desktop— additional vars loaded in desktop (Tauri) mode.env.saas— additional vars loaded in SaaS mode
These files contain non-secret defaults and are checked into Git, so most dev work needs no further setup.
To override values locally (API keys, machine-specific settings), create an uncommitted sibling editor/.env.local / editor/.env.desktop.local / editor/.env.saas.local. Vite automatically layers these on top of the committed files.
Docker Setup
For Docker deployments and configuration, see the Docker README.
Tauri
All desktop tasks are available via Task. From the root of the repo:
Dev
task desktop:dev
This ensures the JLink runtime and backend JAR exist (skipping if already built), then starts Tauri in dev mode.
Build
task desktop:build
This does a full clean rebuild of the backend JAR and JLink runtime, then builds the Tauri app for production.
Platform-specific dev builds are also available:
task desktop:build:dev # No bundling
task desktop:build:dev:mac # macOS .app bundle
task desktop:build:dev:windows # Windows NSIS installer
task desktop:build:dev:linux # Linux AppImage
JLink Tasks
You can also run JLink steps individually:
task desktop:jlink # Build JAR + create JLink runtime
task desktop:jlink:jar # Build backend JAR only
task desktop:jlink:runtime # Create JLink custom JRE only
task desktop:jlink:clean # Remove JLink artifacts
Clean
task desktop:clean
Removes all desktop build artifacts including JLink runtime, bundled JARs, Cargo build, and dist/build directories.