toxen-design-patterns

name

toxen-design-patterns

description

Toxen UI/UX design system, theming, and consistency conventions. Use when building or modifying any Toxen frontend: React components, panels, buttons, forms, modals, notifications, icons, styling/SCSS, theme colors, or when reviewing UI code for consistency. Ensures new work matches Toxen theming (CSS variables), user-friendliness, and established component patterns. Trigger phrases: "add a button/panel/modal", "style this", "make it themeable", "match Toxen style", "is this consistent", "notify the user", "add an icon", "new settings option".

Toxen Design Patterns & Consistency

Toxen is an Electron 30 + React 18 + TypeScript music player targeting desktop and web through the toxenapi abstraction. This skill captures the design system so new work stays themeable, consistent, and user-friendly.

When to Use

• Building or editing any React component, panel, form, button, modal, or notification.
• Adding or changing styles (SCSS), colors, spacing, or icons.
• Adding a settings option or per-song/playlist override.
• Reviewing frontend code for theming/consistency compliance.

Golden Rules (never violate)

1. Never hardcode colors. Always use theme CSS variables (var(--accent-color), etc.). A user's theme must be able to recolor everything.
2. Never hardcode path separators. Use toxenapi.joinPath(), toxenapi.getBasename(), never / or \.
3. Never assume desktop. Guard filesystem/Electron code with toxenapi.isDesktop() and provide a web fallback or toxenapi.throwDesktopOnly("operation").
4. Never use Font Awesome. Icons come from @tabler/icons-react (see Icons).
5. Never alert()/console-only user feedback. Use Toxen.log/warn/error/notify (see User Feedback).
6. Respect the settings hierarchy: playlist-specific → per-song → global. Don't read global settings when a song/playlist override may apply.

Theming (CSS Variables)

All theming flows through CSS custom properties generated by Theme.parseToCSS() and injected via ThemeContainer. When styling, reference these variables — do not invent hex values.

Core colors: --primary-bg, --secondary-bg, --tertiary-bg, --accent-color, --accent-color-rgb Accent derivations (calculated): --accent-color-dim, --accent-color-hover, --accent-color-active Text: --text-primary, --text-secondary, --text-muted, --text-inverse, --text-primary-rgb Surfaces: --surface-bg, --surface-bg-hover, --surface-bg-active Borders: --border-primary, --border-secondary, --border-focus Status: --success-color, --warning-color, --error-color Motion: --transition-normal

Guidelines:

• Use --accent-color for interactive/brand elements; use its -dim/-hover/-active variants for backgrounds and states, not new opacities.
• Use rgba(var(--accent-color-rgb), <alpha>) when you need transparency.
• Use status colors semantically: success = confirm/save, warning = caution, error = destructive/failure.
• To add a new themeable value, add a ThemeStyleItem to ThemeStyleTemplate in src/app/toxen/Theme.ts (with cssVariable, type, defaultValue, parser) so it appears in the Theme Editor — don't add loose variables.

Styling (SCSS)

• Global utility/base styles live in src/app/tx.scss; app layout in src/app/ToxenApp.scss. Component styles live next to the component (Component.scss, imported by the .tsx).
• Reuse the tx- utility classes rather than re-styling from scratch:
  • .tx-btn (+ variants .tx-btn-action, .tx-btn-warning, .tx-btn-cancel, .tx-btn-next)
  • .tx-form-field for inputs/selects
  • .tx-whitespace-nowrap
• Match the existing visual language: border-radius: 10px, gradient backgrounds from accent variants, backdrop-filter: blur(...), cubic-bezier(0.25, 0.8, 0.25, 1) transitions, subtle translateY/scale on hover, and a focus ring using --accent-color-dim.
• For web-only or desktop-only styling, use the custom ToxenIsWeb() SCSS function (configured in vite.web.config.ts) instead of runtime branching.

UI Components

Priority order when picking a component:

1. Mantine UI (@mantine/core v7) — default for Buttons, Stack, Group, Tabs, Select, TextInput, NumberInput, Modal, etc. Icons go in leftSection (Buttons/Tabs) or the relevant icon/section prop.
2. Toxen custom primitives — e.g. the custom Button (<Button txStyle="action" txDisabled={...} disabledTitle="..." />), Form, FormInput*, Expandable, SelectAsync, Tooltip. Use these when their behavior is needed.
3. React Bootstrap — legacy only; do not add new usages, prefer migrating to Mantine.

Component conventions:

• Existing code is largely class components; when editing a class component, stay class-based for consistency. New standalone components should be functional.
• Panels register themselves on the global Toxen static (e.g. Toxen.songPanel = this) and expose an update() method; global refreshes go through Toxen.updateSongPanels().
• For functional components that must react to shared state, use the controller pattern: create a Controller subclass, instantiate with useMemo, and subscribe with useController(controller) from src/app/lib/useController.ts. The component re-renders when the controller calls notify().

Icons

• Import named icons from @tabler/icons-react: import { IconPlayerPlay } from "@tabler/icons-react";
• Use size="1em" so the icon inherits the surrounding font-size and currentColor (this keeps icons themeable and correctly scaled). Use an explicit numeric size only when a fixed size is required.
• Place icons in Mantine leftSection/icon props, not as bare siblings, when the host component provides a slot.

User Feedback (Notifications)

Use the global Toxen helpers — never alert() or console-only messaging. Signatures live in src/app/ToxenApp.tsx.

Toxen.log("Saved.", 3000);              // info toast, auto-dismiss after 3s
Toxen.warn("Heads up…", 4000);          // warning toast
Toxen.error("Something failed: " + e);  // error toast (also logs to console)
const id = Toxen.notify({               // full control; returns an id
  title: "Uploading",
  content: <>Custom <b>JSX</b> allowed</>,
  type: "normal",        // "normal" | "warning" | "error"
  expiresIn: 0,          // 0/undefined = persist until updated/closed
  disableClose: true,
});

Guidelines:

• expiresIn in ms; use 0/omit for long-running operations, then update/replace the notification when done.
• Keep messages short, action-oriented, and human. Include the failing item name in errors (Failed to upload ${file.name}).
• Reuse preset errors via Toxen.sendError("CURRENTLY_EDITING_SONG") where they exist rather than retyping strings.

Modals

Use Mantine modals via the useModals() hook (@mantine/modals):

• modals.openModal({ title, children }) for custom content; capture the returned id to close it (modals.closeModal(id)).
• modals.openConfirmModal({ title, children, labels, onConfirm }) for confirm/cancel flows.
• Always confirm destructive actions (delete, clear, overwrite) with openConfirmModal.

Platform Abstraction (desktop vs web)

if (toxenapi.isDesktop()) {
  const files = await toxenapi.fs.promises.readdir(dir); // desktop-only
} else {
  // web fallback
}
// or, for strictly desktop features:
if (!toxenapi.isDesktop()) return toxenapi.throwDesktopOnly("exportSongPackage");

• Access fs/path/Electron/remote only through toxenapi. On the web controller these members don't exist, so unguarded access is a type + runtime error.
• Gate UI affordances too: if a feature is desktop-only, disable/hide the control on web and explain via a notification when invoked.

Settings & Overrides

• Read/write globals with Settings.get(key) / Settings.set(key, value); apply with side effects via Settings.apply(partial, save?).
• Respect precedence: a Song's per-song value (e.g. visualizerColor) overrides global; song.playlistSettings[playlistId] overrides per-song when playing from that playlist.
• New settings go in the ISettings interface and are surfaced in the Settings panel with a matching Mantine control and a <sup> help description, consistent with neighbors.

Consistency Checklist (run before finishing UI work)

• No hardcoded colors — only theme CSS variables (or Mantine theme).
• Icons are Tabler (@tabler/icons-react, size="1em"), no Font Awesome.
• Buttons/inputs use Mantine or tx- classes and match the existing radius/gradient/hover language.
• User feedback uses Toxen.log/warn/error/notify; destructive actions use a confirm modal.
• Desktop-only code is guarded with toxenapi.isDesktop() / throwDesktopOnly, with a sensible web fallback or disabled control.
• Paths use toxenapi helpers, never string concatenation.
• Settings reads honor playlist → song → global precedence; new settings appear in the Settings panel with help text.
• Class vs functional component choice matches surrounding code; shared state uses the controller/useController pattern.
• New themeable values added to ThemeStyleTemplate so the Theme Editor exposes them.

Key References

• Theme system & CSS variables: src/app/toxen/Theme.ts, src/app/components/ThemeContainer/ThemeContainer.tsx
• Utility styles: src/app/tx.scss
• Global helpers (notify/log/error, panel refs): src/app/ToxenApp.tsx
• Custom button: src/app/components/Button/Button.tsx
• Controller hook: src/app/lib/useController.ts
• Platform controllers: src/ToxenControllers/ToxenController.tsx, src/ToxenControllers/DesktopController.tsx