================================================================
BuMoSm PDF Viewer — Theme File Guide
================================================================

Theme files are JSON files placed in this folder.
The application loads all .json files here at startup and
reloads them automatically when a file is changed, so you can
edit a theme and see the result without restarting.

The bundled dark.json and light.json are samples.
They are restored to their original content when the app is updated.
To make changes, copy them under a different name and also change
the "name" inside.


----------------------------------------------------------------
ABOUT THE TWO "name" KEYS (READ THIS FIRST)
----------------------------------------------------------------

A theme file contains a key called "name" in two places.
They serve completely different purposes — do not confuse them.

  {
    "name": "BuMoSm PDF Viewer Theme",   <- [1] around line 3
    "themes": [
      {
        "name": "Light",                  <- [2] THIS appears in
        ...                                     the Settings panel
      }
    ]
  }

[1] The top-level "name"

  Meaning : The name of the theme file as a whole.
  Display : NOT shown anywhere in the application.
  Editing : You do not need to edit this.
            All theme files for this application use
            "BuMoSm PDF Viewer Theme".
            When creating a new file, copy it as-is.
  Note    : This value is discarded after parsing, so it is
            fine for every file to use the same value.
            Changing it has no visible effect.

[2] The "name" inside "themes"

  Meaning : The name of an individual theme.
  Display : Shown in the theme list in the Settings panel.
  Editing : Edit this one to change the displayed name.
  Note    : Keep this unique across ALL theme files.
            If two themes share the same name, the one loaded
            later overwrites the earlier one and it disappears
            from the Settings panel.
            File load order is not fixed, so which one survives
            is not predictable.


----------------------------------------------------------------
FILE STRUCTURE
----------------------------------------------------------------

A theme file has two required top-level keys:

  "name"    — The name of the theme file as a whole.
               Leave this as "BuMoSm PDF Viewer Theme".

  "themes"  — An array of theme objects.
               Each object becomes one entry in the theme list
               in the Settings panel.

Keys of each theme object:

  "name"       — The name shown in the Settings panel. (required)
                 Must be unique across all theme files.

  "mode"       — Either "light" or "dark". (required)
                 Controls which system appearance the theme
                 is applied to when "Follow the system" is
                 selected.

  "colors"     — Object holding the colors. (required)
                 See the reference below for the keys you can
                 use.

  "is_default" — Optional.
                 Moves the theme earlier in the Settings list.


----------------------------------------------------------------
COLOR VALUES
----------------------------------------------------------------

Values in "colors" accept these formats:

  Hex color     — "#rrggbb" or "#rrggbbaa"
                  Examples: "#ffffff", "#1a1a1aff"

  Tailwind name — A Tailwind CSS color name with a shade number.
                  Examples: "neutral-950", "blue-400", "white",
                  "black"
                  Shades: 50, 100-900 (in steps of 100), 950.

  Transparent   — "#00000000" (useful for removing backgrounds
                  such as scrollbars)

The last two hex digits set the alpha (opacity).
Omitting them means fully opaque.

Keys you leave out fall back to the built-in default for that
mode (light or dark). You do not need to specify every key.

A misspelled key is silently ignored. If a color you set has
no effect, compare the key name against the reference below.


================================================================
COLOR KEY REFERENCE (69 entries)
================================================================

Every color key that has an effect in this application.


----------------------------------------------------------------
* BASICS (8 entries)
----------------------------------------------------------------

  background
    Background of the page area — the largest surface in the
    window.

  foreground
    Base text color. Used for the toolbar button labels, the
    page numbers and the title bar text.

  border
    Base border color. Used for the line under the toolbar and
    search bar, and thumbnail outlines.
    Also used for the outline around each page when the page
    is hard to tell apart from the background (for example the
    light theme in normal view, the dark theme with inverted
    colors, or a PDF with a black page). The page edge color is
    measured from the rendered page. If the outline would blend
    into the background or the page, it is adjusted automatically
    until it stands out. No outline is drawn when the page
    already stands out.

  window.border
    Color of the window frame, passed to the operating system
    (Windows 11 only). If omitted, it is the same color as
    border.

  selection.background
    Highlight color for selected text on a page.

  overlay
    The veil drawn over the window while the settings panel is
    open. Keep it semi-transparent.

  ring
    Outline drawn around a focused element when navigating with
    the Tab key.

  caret
    The blinking text cursor in input fields. Used in the page
    number, zoom, search and password fields.


----------------------------------------------------------------
* TITLE BAR AND STATUS BAR (4 entries)
----------------------------------------------------------------

  title_bar.background
    Background of the title bar. In this application it is also
    used for the toolbar and the search bar, so changing it has
    a wide effect.

  title_bar.border
    Line under the title bar.

  status_bar.background
    Background of the status bar at the bottom of the window.

  status_bar.border
    Line above the status bar.


----------------------------------------------------------------
* SIDEBAR (7 entries)
----------------------------------------------------------------

The left panel holding the outline, thumbnails and search
results.

  sidebar.background
    Background of the sidebar.

  sidebar.foreground
    Text color in the sidebar, such as outline entries.

  sidebar.border
    Border between the sidebar and the page area.

  sidebar.accent.background
    Background of emphasized areas within the sidebar.

  sidebar.accent.foreground
    Its text color.

  sidebar.primary.background
    Background of the most prominent areas within the sidebar.

  sidebar.primary.foreground
    Its text color.


----------------------------------------------------------------
* TABS (6 entries)
----------------------------------------------------------------

Used by the tab bar at the top and by the sidebar tabs.

  tab_bar.background
    Background of the strip the tabs sit on.
    Also used for the sidebar tab strip.

  tab_bar.segmented.background
    Background of segmented (joined) tabs.

  tab.background
    Background of an inactive tab.
    light.json sets this to "#00000000" (transparent) so the
    strip color shows through.

  tab.foreground
    Text color of an inactive tab.

  tab.active.background
    Background of the selected tab.

  tab.active.foreground
    Text color of the selected tab.


----------------------------------------------------------------
* BUTTONS (12 entries)
----------------------------------------------------------------

Used by the toolbar buttons and the settings panel buttons.

  button.background
    Background of a normal button.

  button.foreground
    Text color of a normal button.

  button.hover.background
    Background while the pointer is over it.
    Frequently visible on toolbar buttons.

  button.active.background
    Background while the button is pressed.
    Frequently visible on toolbar buttons.

  button.primary.background
    Background of an emphasized button, such as Apply in
    the settings panel.

  button.primary.foreground
    Its text color.

  button.primary.hover.background
    Background while the pointer is over it.

  button.primary.active.background
    Background while pressed.

  button.secondary.background
    Background of a quieter button, such as Cancel in the
    settings panel.

  button.secondary.foreground
    Its text color.

  button.secondary.hover.background
    Background while the pointer is over it.

  button.secondary.active.background
    Background while pressed.


----------------------------------------------------------------
* ACCENT AND SUPPORTING COLORS (10 entries)
----------------------------------------------------------------

  accent.background
    Background of the highlighted item, such as the selected
    entry in a settings dropdown.

  accent.foreground
    Its text color.

  primary.background
    The accent color. In this application it outlines the
    current page in the thumbnail panel.

  primary.foreground
    Text color placed on the accent color.

  primary.hover.background
    Accent color while the pointer is over it.

  primary.active.background
    Accent color while pressed.

  secondary.background
    Background of quieter elements.

  secondary.foreground
    Its text color.

  secondary.hover.background
    Background while the pointer is over it.

  secondary.active.background
    Background while pressed.


----------------------------------------------------------------
* MUTED AND ERROR COLORS (4 entries)
----------------------------------------------------------------

  muted.background
    Background of de-emphasized areas.

  muted.foreground
    Muted text color. Used for the "Drop a PDF file here"
    message, the status bar text, and outline entries with no
    destination.

  danger.background
    Error color. Used for the message shown when a password is
    incorrect.

  danger.foreground
    Text color placed on the error color.


----------------------------------------------------------------
* INPUT FIELDS (1 entry)
----------------------------------------------------------------

  input.border
    Border around input fields. Used by the page number, zoom,
    search and password fields, and by the numeric fields in
    the settings panel.


----------------------------------------------------------------
* POPUPS (2 entries)
----------------------------------------------------------------

  popover.background
    Background of popups. Used for the page number bubble shown
    while dragging the scrollbar, the recent files list, the
    right-click menu, and the skipped-pages menu.

  popover.foreground
    Text color in popups.


----------------------------------------------------------------
* DRAG AND DROP (2 entries)
----------------------------------------------------------------

  drag.border
    Frame drawn around the window while a PDF file is being
    dragged onto it.

  drop_target.background
    Background marking a place that can accept a dragged item.


----------------------------------------------------------------
* LISTS (6 entries)
----------------------------------------------------------------

Used by the outline, thumbnail, search result and recent files
lists.

  list.background
    Background of a list.

  list.hover.background
    Background of a row while the pointer is over it.
    Frequently visible in the outline and search results.

  list.active.background
    Background of the row matching your current position.
    Used to mark where you are in the outline.

  list.active.border
    Border around that row.

  list.even.background
    Background of even rows, for striped lists.

  list.head.background
    Background of a list header row.


----------------------------------------------------------------
* SCROLLBAR (3 entries)
----------------------------------------------------------------

  scrollbar.background
    Color of the scrollbar track.
    light.json sets this to "#fafafa00" (transparent).

  scrollbar.thumb.background
    Color of the scrollbar handle.

  scrollbar.thumb.hover.background
    Color of the handle while the pointer is over it.


----------------------------------------------------------------
* SWITCHES (2 entries)
----------------------------------------------------------------

Used by the on/off toggles in the settings panel.

  switch.background
    Color of the switch track.

  switch.thumb.background
    Color of the switch knob.


----------------------------------------------------------------
* SELECTED BUTTONS (1 entry)
----------------------------------------------------------------

  link
    Icon color of a button that is switched on in the toolbar and
    the search bar (outline, thumbnails, bookmarks, search options).
    light.json sets this to "#fe4e4e" (red); dark.json sets it to "#5ac1fe" (blue).
    If omitted: blue in dark, red in light.


----------------------------------------------------------------
* OTHER (1 entry)
----------------------------------------------------------------

  skeleton.background
    The placeholder fill shown while content is loading.


================================================================
COLORS A THEME CANNOT CHANGE
================================================================

Three colors are unaffected by the theme. They are drawn on top
of the page, so they are chosen against the white of the paper
rather than the surroundings. They stay the same in a dark theme.

  - The placeholder fill where a page bitmap has not arrived
    yet (light gray)
  - The highlight on a search match (yellow)
  - The highlight on the currently selected match (orange)


================================================================
MINIMAL EXAMPLE
================================================================

{
  "name": "BuMoSm PDF Viewer Theme",
  "themes": [
    {
      "name": "My Dark",
      "mode": "dark",
      "colors": {
        "background": "#1e1e1e",
        "foreground": "#d4d4d4",
        "border": "#3e3e3e",
        "title_bar.background": "#3c3c3c",
        "status_bar.background": "#007acc",
        "sidebar.background": "#252526",
        "sidebar.foreground": "#cccccc",
        "tab_bar.background": "#2d2d2d",
        "tab.active.background": "#1e1e1e",
        "tab.active.foreground": "#ffffff",
        "tab.foreground": "#969696",
        "muted.foreground": "#8a8a8a",
        "selection.background": "#264f78",
        "primary.background": "#0e639c",
        "primary.foreground": "#ffffff",
        "list.hover.background": "#2a2d2e",
        "list.active.background": "#37373d",
        "popover.background": "#252526",
        "popover.foreground": "#cccccc",
        "input.border": "#3e3e3e",
        "scrollbar.thumb.background": "#4e4e4e",
        "drag.border": "#0e639c"
      }
    }
  ]
}

The Settings panel will show "My Dark".
"BuMoSm PDF Viewer Theme" is not shown anywhere.


================================================================
MULTIPLE THEMES IN ONE FILE
================================================================

The "themes" array can hold more than one object — for example,
a matching light and dark pair in a single file.

{
  "name": "BuMoSm PDF Viewer Theme",
  "themes": [
    { "name": "Solarized Light", "mode": "light", "colors": { ... } },
    { "name": "Solarized Dark",  "mode": "dark",  "colors": { ... } }
  ]
}

This produces two separate entries in the Settings panel.


================================================================
NOTES
================================================================

- A file with a JSON syntax error is silently skipped.
  The theme will not appear in the Settings panel.

- A misspelled key is silently ignored. If a color you set has
  no effect, compare the key name against the reference above.

- Using the same name as a built-in theme (Light, Dark) in
  "themes" "name" replaces that built-in theme. Use a different
  name to add yours as a separate entry.

================================================================
