Theme development

This page documents every --mac-* CSS custom property HarborClient exposes for appearance themes. Use it when building a theme in File → Themes → Designer, shipping a theme plugin, or overriding tokens via ThemeContribution.colors / ThemeContribution.metrics.

Token ids come from the SDK ThemeColorToken and ThemeMetricToken types. Each id maps to --mac-<token> on :root.

For installing and managing themes in the app, see Using themes. For packaging theme plugins, see Plugin development and the Plugin SDK — Themes reference.

Designer

Open File → Themes → Designer to design a custom appearance theme with live preview across HarborClient.

Control	Description
Theme title	Human-readable name shown on Installed cards and in View → Theme
Appearance	Base mode: light, dark, or high contrast (sets `color-scheme` and seeds defaults)
Color tokens	Pick colors for layout, text, interactive, status, and HTTP method tokens
Export	Save the current draft as a portable `.json` theme file (`harborclientExport: "theme"`)
Import	Load a theme export into the Designer draft without saving or activating it
Discard	Restore the last loaded or saved snapshot and revert the live preview
Save	Write the theme to disk and make it the active appearance immediately

When you start a new theme, color pickers and the appearance dropdown seed from your currently active theme (built-in, plugin, or custom). Changing Appearance on a new draft reseeds from built-in defaults for that mode.

When you edit an existing custom theme, the Designer loads its saved palette and title.

Renamed save prompt

If you edit a saved theme and change its title, Save asks whether to:

Choice	Result
Update existing	Rename the saved theme in place (same file; also persists color and appearance edits)
Save as new theme	Create a new theme file with the new name; the original theme is left unchanged
Cancel	Dismiss the prompt without saving

CSS custom properties

HarborClient styles the desktop UI with --mac-* custom properties. Theme contributions set token overrides without the --mac- prefix:

typescript

hc.themes.register({
  id: 'solarized',
  title: 'Solarized Dark',
  type: 'dark',
  colors: {
    surface: '#002b36',
    accent: '#268bd2',
  },
  metrics: {
    'layout-radius': '0.5rem',
  },
});

The same keys appear in Theme Designer exports (harborclientExport: "theme") under theme (colors) and optional metrics.

Default values below are the built-in Light, Dark, and High contrast palettes used when a draft is seeded or an appearance mode is selected.

Color tokens

Override these keys in ThemeContribution.colors or a Designer color field. Each maps to --mac-<token>.

`--mac-surface`

Main content background.

Appearance	Default
Light	`#f5f5f7`
Dark	`#1e1e1e`
High contrast	`#000000`

`--mac-header`

Top header strip (sidebar search + request tab bar).

Appearance	Default
Light	`#ececee`
Dark	`#252526`
High contrast	`#000000`

`--mac-page-header`

Page title header background (PageHeader).

Appearance	Default
Light	`#f5f5f7`
Dark	`#1e1e1e`
High contrast	`#000000`

`--mac-page-header-text`

Page title header primary text.

Appearance	Default
Light	`rgba(0, 0, 0, 0.85)`
Dark	`rgba(255, 255, 255, 0.85)`
High contrast	`#ffffff`

`--mac-page-header-muted`

Page title header description and decorative icons.

Appearance	Default
Light	`rgba(0, 0, 0, 0.58)`
Dark	`rgba(255, 255, 255, 0.58)`
High contrast	`#d0d0d0`

`--mac-footer`

Footer status bar background.

Appearance	Default
Light	`#ececee`
Dark	`#252526`
High contrast	`#000000`

`--mac-control`

Panels, inputs, footer bar.

Appearance	Default
Light	`#ffffff`
Dark	`#3a3a3c`
High contrast	`#000000`

`--mac-field`

Input field fill.

Appearance	Default
Light	`#ffffff`
Dark	`#191919`
High contrast	`#141414`

`--mac-separator`

Borders and dividers.

Appearance	Default
Light	`rgba(0, 0, 0, 0.08)`
Dark	`rgba(255, 255, 255, 0.08)`
High contrast	`#ffd60a`

`--mac-terminal`

Footer terminal background.

Appearance	Default
Light	`#000000`
Dark	`#000000`
High contrast	`#000000`

`--mac-sidebar-rail`

Activity rail background.

Appearance	Default
Light	`#ffffff`
Dark	`#313131`
High contrast	`#ffd60a`

`--mac-sidebar-rail-active`

Active/hover activity rail section fill.

Appearance	Default
Light	`#ececee`
Dark	`#252526`
High contrast	`#c9a008`

`--mac-sidebar-rail-text`

Activity rail icons and labels.

Appearance	Default
Light	`rgba(0, 0, 0, 0.85)`
Dark	`#ffffff`
High contrast	`#000000`

`--mac-sidebar-rail-separator`

Activity rail hairline between item groups.

Appearance	Default
Light	`#ededed`
Dark	`#3e3e3e`
High contrast	`#d6b408`

`--mac-sidebar`

Left sidebar background.

Appearance	Default
Light	`#ececee`
Dark	`#252526`
High contrast	`#000000`

`--mac-sidebar-toolbar`

Sidebar/footer toolbar strip background.

Appearance	Default
Light	`#d0d0d1`
Dark	`#1e1e1e`
High contrast	`#141414`

`--mac-sidebar-section`

Sidebar section headers.

Appearance	Default
Light	`rgba(0, 122, 204, 0.18)`
Dark	`#343437`
High contrast	`#000000`

`--mac-sidebar-section-text`

Sidebar section header labels and chevrons.

Appearance	Default
Light	`rgba(0, 0, 0, 0.58)`
Dark	`rgba(255, 255, 255, 0.58)`
High contrast	`#ffffff`

`--mac-breadcrumb-background`

Request editor breadcrumb bar track.

Appearance	Default
Light	`#ececee`
Dark	`#252526`
High contrast	`#ffd60a`

`--mac-breadcrumb-segment`

Breadcrumb chevron segment fill (collection/folder crumbs).

Appearance	Default
Light	`#f5f5f7`
Dark	`#323234`
High contrast	`#141414`

`--mac-breadcrumb-current`

Trailing request-name breadcrumb segment fill.

Appearance	Default
Light	`#ffffff`
Dark	`#3a3a3c`
High contrast	`#1f1f1f`

`--mac-text`

Primary text.

Appearance	Default
Light	`rgba(0, 0, 0, 0.85)`
Dark	`rgba(255, 255, 255, 0.85)`
High contrast	`#ffffff`

`--mac-text-secondary`

Secondary labels.

Appearance	Default
Light	`rgba(0, 0, 0, 0.65)`
Dark	`rgba(255, 255, 255, 0.65)`
High contrast	`#ffffff`

`--mac-muted`

De-emphasized text.

Appearance	Default
Light	`rgba(0, 0, 0, 0.58)`
Dark	`rgba(255, 255, 255, 0.58)`
High contrast	`#d0d0d0`

`--mac-footer-text`

Footer primary text (active segment buttons, selection-style icons).

Appearance	Default
Light	`rgba(0, 0, 0, 0.85)`
Dark	`rgba(255, 255, 255, 0.85)`
High contrast	`#ffd60a`

`--mac-footer-muted`

Footer de-emphasized text (inactive segment buttons).

Appearance	Default
Light	`rgba(0, 0, 0, 0.58)`
Dark	`rgba(255, 255, 255, 0.58)`
High contrast	`#ffd60a`

`--mac-accent`

Links, focus rings, primary actions.

Appearance	Default
Light	`#007acc`
Dark	`#4098dc`
High contrast	`#ffd60a`

`--mac-selection`

Selected row / highlight fill.

Appearance	Default
Light	`rgba(0, 122, 204, 0.18)`
Dark	`rgba(64, 152, 220, 0.22)`
High contrast	`#ffd60a`

`--mac-doc-markdown`

Collection sidebar markdown document icon.

Appearance	Default
Light	`#007acc`
Dark	`#4098dc`
High contrast	`#ffd60a`

`--mac-footer-icon-active`

Active footer icon toggle color.

Appearance	Default
Light	`rgba(0, 0, 0, 0.85)`
Dark	`rgba(255, 255, 255, 0.85)`
High contrast	`#ffd60a`

`--mac-toolbar-action-active`

Pressed sidebar toolbar action icon color.

Appearance	Default
Light	`rgba(0, 0, 0, 0.85)`
Dark	`rgba(255, 255, 255, 0.85)`
High contrast	`#ffd60a`

`--mac-tab-underline`

Active request tab underline.

Appearance	Default
Light	`#007acc`
Dark	`#ffffff`
High contrast	`#ffd60a`

`--mac-resize-separator`

Resizable panel separator track and edge border.

Appearance	Default
Light	`#ffffff`
Dark	`#3a3a3c`
High contrast	`#000000`

`--mac-resize-handle`

Resizable panel grip (and high-contrast chrome accents).

Appearance	Default
Light	`rgba(0, 0, 0, 0.29)`
Dark	`rgba(255, 255, 255, 0.29)`
High contrast	`#ffd60a`

`--mac-variable-token`

{{variable}} syntax highlight in editors.

Appearance	Default
Light	`#007acc`
Dark	`#4098dc`
High contrast	`#5fe3f0`

`--mac-tab-bar`

Request editor tab bar strip background.

Appearance	Default
Light	`#ececee`
Dark	`#252526`
High contrast	`#000000`

`--mac-tab-active`

Active request/editor tab fill.

Appearance	Default
Light	`#f5f5f7`
Dark	`#1e1e1e`
High contrast	`#000000`

`--mac-tab-inactive`

Inactive request/editor tab fill.

Appearance	Default
Light	`rgba(255, 255, 255, 0.2)`
Dark	`rgba(58, 58, 60, 0.2)`
High contrast	`rgba(0, 0, 0, 0.2)`

`--mac-tab-hover`

Inactive request/editor tab hover and focus-visible fill.

Appearance	Default
Light	`rgba(0, 122, 204, 0.108)`
Dark	`rgba(64, 152, 220, 0.132)`
High contrast	`rgba(255, 214, 10, 0.6)`

`--mac-tab-text`

Active (and hover/focus) request/editor tab label color.

Appearance	Default
Light	`rgba(0, 0, 0, 0.85)`
Dark	`rgba(255, 255, 255, 0.85)`
High contrast	`#ffffff`

`--mac-tab-text-inactive`

Inactive request/editor tab label color.

Appearance	Default
Light	`rgba(0, 0, 0, 0.58)`
Dark	`rgba(255, 255, 255, 0.58)`
High contrast	`#d0d0d0`

`--mac-tab-unsaved`

Request/markdown tab title when the tab has unsaved changes.

Appearance	Default
Light	`#b45309`
Dark	`#ffb340`
High contrast	`#5fe3f0`

`--mac-danger`

Status colors.

Appearance	Default
Light	`#ff3b30`
Dark	`#ff453a`
High contrast	`#ff8a80`

`--mac-danger-light`

Status colors.

Appearance	Default
Light	`#d70015`
Dark	`#ff6961`
High contrast	`#ffb4af`

`--mac-warning`

Status colors.

Appearance	Default
Light	`#ff9500`
Dark	`#ff9f0a`
High contrast	`#ffb340`

`--mac-success`

Status colors.

Appearance	Default
Light	`#34c759`
Dark	`#30d158`
High contrast	`#5ce06a`