CSS Theming Recommendations v2

[gravelfreeman]

Poznote should use one universal CSS theme API based on --pz-* tokens.

Target architecture

Use the same universal tokens in every mode. Only their values change:

:root {
    --pz-bg: #ffffff;
    --pz-surface: #f8f9fa;
    --pz-text: #212529;
    --pz-border: #dee2e6;
}

html[data-theme="dark"] {
    --pz-bg: #181818;
    --pz-surface: #242424;
    --pz-text: #f5f5f5;
    --pz-border: #414141;
}

Components should always consume the universal tokens:

.editor-toolbar {
    background: var(--pz-surface);
    border-color: var(--pz-border);
    color: var(--pz-text);
}

The stable public API should contain:

• --pz-color-*: canonical palette primitives and derived colours;
• --pz-*: universal structural and semantic roles.

Theme authors should not need to define --dm-* variables.

Use the global palette as the source of truth

Semantic roles should reference --pz-color-* instead of duplicating hardcoded colours:

/* Good */
--pz-danger: var(--pz-color-red);
--pz-danger-hover: var(--pz-color-brown);
--pz-danger-soft: var(--pz-color-red-soft);

/* Bad */
--pz-danger: #dc3545;
--pz-danger-hover: #c82333;

This applies to accent, link, danger, success, warning, selection, and disabled states. Derived values should use existing tokens or color-mix().

Remove duplicate dark layers

Application CSS should replace usages such as:

var(--dm-danger)
var(--dm-surface)
var(--dm-text)

with their universal equivalents:

var(--pz-danger)
var(--pz-surface)
var(--pz-text)

Rules that only differ by colour should become shared rules. Keep a dark-mode selector only when behavior is genuinely mode-specific.

Third-party libraries should be adapted at their integration boundary:

.editor-library {
    --library-background: var(--pz-surface);
    --library-foreground: var(--pz-text);
    --library-border: var(--pz-border);
}

Libraries without CSS variables should receive focused overrides that use the universal Poznote tokens.

Theme author contract

A custom stylesheet should override only values that differ from the upstream defaults:

:root {
    --pz-accent: var(--pz-color-blue);
    --pz-danger: var(--pz-color-red);
    --pz-bg: #eff1f5;
    --pz-surface: #e6e9ef;
}

html[data-theme="dark"] {
    --pz-bg: #1e1e2e;
    --pz-surface: #181825;
}

Theme authors shouldn’t need to copy the entire token list or redefine internal aliases unless they want deeper customization. Any values they leave unchanged should simply inherit from upstream.

Remaining hardcoded colors

I’ve noticed that many files are still using hardcoded colors after your last pass:

• kanban.css
• dashboard.css
• tasks-page.css
• tasks.css
• notes-manager.css
• trash.css
• workspaces.css
• shared/dark-mode.css
• shared/buttons-modal.css
• dark-mode/editor.css
• dark-mode/modals.css
• dark-mode/kanban.css

[timothepoznanski]

Thanks, done. It will ship with the next release.

• One vocabulary. The app now reads --pz-* only. Same token names in every theme, only the values change: light on :root, dark in html[data-theme='dark']. CI rejects any --dm-* outside tokens.css.
• Your current theme keeps working. --dm-* is still honoured as a legacy input, and --pz-* wins when both are set. No rush to migrate. When you do, the renames are mostly direct (--dm-text → --pz-text, --dm-surface → --pz-surface), with a few to know: --dm-content-bg → --pz-bg, --dm-bg → --pz-chrome-bg, --dm-text-bright → --pz-text-strong, --dm-accent → --pz-accent-text, --dm-danger → --pz-danger-text. The full list is in src/public/css/README.md.
• Override only what differs. Anything a theme leaves out keeps the upstream value.
• Fill vs text. --pz-accent stays a fill (a button ground under a label) and --pz-accent-text is the accent as text, icon or outline. In a light theme they are the same colour. A theme like yours, with dark labels on its fills, can set both to the same value.
• Hardcoded colours: 363 → 218, starting with the files you listed (kanban, tasks, trash, notes manager, workspaces, shared page, dark modals). What is left is deliberate: syntax highlighting, swatches, a video letterbox.
• Duplicate dark rules: removed where a browser check showed nothing moves. Many carry specificity that other rules depend on, so the rest will go gradually.
• Not done: deriving --pz-danger and friends from --pz-color-*. The palette is tuned for text, so in dark it is too pale to sit under a white label. A theme can still do it on its side.

Everything was compared in a browser against the previous build, in light, dark and black: nothing moves except the hardcoded colours that now follow the theme, and a few intentional dark-mode fixes (coloured icons keep their colour, alerts and accent text are more readable).

I'm sure there are still some problems and UI bugs in there, but we will keep improving it. 😉