> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/rtr46/meikipop/llms.txt
> Use this file to discover all available pages before exploring further.

# Themes and appearance

> Customize meikipop's popup colors, fonts, and display options to create your perfect reading experience

Meikipop offers extensive customization of the dictionary popup's appearance. Choose from built-in themes or create your own custom color scheme.

## Built-in themes

Meikipop includes four carefully designed color themes plus a custom option.

<Tabs>
  <Tab title="Nazeka (default)">
    **Dark gray theme with cyan and green highlights**

    ```
    Background: #2E2E2E (dark gray)
    Foreground: #F0F0F0 (light gray)
    Word highlight: #88D8FF (cyan)
    Reading highlight: #90EE90 (light green)
    Opacity: 245/255
    ```

    <Info>
      Named after the Nazeka browser extension that inspired meikipop. Provides excellent readability with comfortable colors for extended reading.
    </Info>
  </Tab>

  <Tab title="Celestial Indigo">
    **Deep purple theme with gold and lavender highlights**

    ```
    Background: #281E50 (deep indigo)
    Foreground: #EAEFF5 (off-white)
    Word highlight: #D4C58A (gold)
    Reading highlight: #B5A2D4 (lavender)
    Opacity: 245/255
    ```

    <Tip>
      Elegant and sophisticated. Great for users who prefer warmer, richer colors.
    </Tip>
  </Tab>

  <Tab title="Neutral Slate">
    **Medium gray theme with muted green highlights**

    ```
    Background: #5D5C5B (medium gray)
    Foreground: #EFEBE8 (cream white)
    Word highlight: #A3B8A3 (sage green)
    Reading highlight: #A3B8A3 (sage green)
    Opacity: 245/255
    ```

    <Tip>
      Subtle and professional. Perfect for users who prefer understated colors.
    </Tip>
  </Tab>

  <Tab title="Academic">
    **Light theme with dark text and traditional academic colors**

    ```
    Background: #FDFBF7 (off-white)
    Foreground: #212121 (dark gray)
    Word highlight: #8C2121 (dark red)
    Reading highlight: #005A9C (dark blue)
    Opacity: 245/255
    ```

    <Info>
      High contrast light theme. Ideal for bright environments or users who prefer reading dark text on light backgrounds.
    </Info>
  </Tab>

  <Tab title="Custom">
    **User-defined colors**

    When you manually adjust any color or opacity setting, the theme automatically switches to "Custom".

    <Tip>
      Start with a built-in theme, then tweak individual colors to create your perfect customization.
    </Tip>
  </Tab>
</Tabs>

## Changing themes

<Steps>
  <Step title="Open Settings">
    Right-click the meikipop tray icon and select **Settings**.
  </Step>

  <Step title="Navigate to Popup Appearance tab">
    Click the **Popup Appearance** tab in the Settings dialog.
  </Step>

  <Step title="Select a theme preset">
    In the **Theme** section, choose a preset from the **Preset** dropdown.
  </Step>

  <Step title="Preview (optional)">
    The changes apply in real-time. Trigger a lookup to see the new theme.
  </Step>

  <Step title="Save">
    Click **Save** to make your changes permanent.
  </Step>
</Steps>

<Note>
  Theme changes take effect immediately without restarting meikipop.
</Note>

## Customizing colors

You can customize individual colors to create your own theme.

### Color settings

<ParamField path="color_background" type="hex color" default="#2E2E2E">
  **Background color**

  The popup window's background color.

  **Tips:**

  * Dark backgrounds (#1E1E1E - #4E4E4E) reduce eye strain in low light
  * Light backgrounds (#E0E0E0 - #FFFFFF) work better in bright environments
  * Avoid pure black (#000000) or pure white (#FFFFFF) for better comfort
</ParamField>

<ParamField path="color_foreground" type="hex color" default="#F0F0F0">
  **Foreground color**

  The default text color for definitions, part of speech, and body text.

  **Tips:**

  * Ensure high contrast with background (4.5:1 minimum for readability)
  * Light gray on dark background is easier on eyes than pure white
  * Dark gray on light background is more comfortable than pure black
</ParamField>

<ParamField path="color_highlight_word" type="hex color" default="#88D8FF">
  **Word highlight color**

  Color used for the main word form (kanji/kana) and kanji characters.

  **Tips:**

  * Choose a bright, saturated color for emphasis
  * Should stand out from foreground color
  * Common choices: cyan, gold, red, bright blue
</ParamField>

<ParamField path="color_highlight_reading" type="hex color" default="#90EE90">
  **Reading highlight color**

  Color used for furigana/reading text in square brackets.

  **Tips:**

  * Should be distinct from word highlight color
  * Slightly less saturated than word color works well
  * Common choices: light green, lavender, orange, pink
</ParamField>

### Picking custom colors

<Steps>
  <Step title="Open color settings">
    Navigate to **Settings** → **Popup Appearance** → **Colors** section.
  </Step>

  <Step title="Click a color button">
    Each color setting has a button showing the current color. Click it to open the color picker.
  </Step>

  <Step title="Choose your color">
    Use the color picker to select a new color:

    * Pick from the color wheel
    * Enter a hex code (e.g., `#FF5733`)
    * Use RGB sliders for precise control
  </Step>

  <Step title="Confirm selection">
    Click **OK** in the color picker. The button updates to show your new color.
  </Step>

  <Step title="Test and iterate">
    Trigger a lookup to see your color in action. Adjust as needed.
  </Step>

  <Step title="Save changes">
    Click **Save** in the Settings dialog to apply your custom theme.
  </Step>
</Steps>

<Tip>
  When you customize any color, the theme automatically switches to "Custom" to preserve your changes.
</Tip>

## Adjusting opacity

Control the transparency of the popup background.

<ParamField path="background_opacity" type="integer" default="245">
  **Background opacity**

  Controls how transparent the popup background is.

  **Range:** 50-255

  * `255`: Fully opaque (no transparency)
  * `245`: Slightly transparent (default)
  * `200`: Noticeably transparent
  * `150`: Highly transparent
  * `50`: Very transparent (minimal visibility)

  <Info>
    Slight transparency (230-250) makes the popup feel lighter and less obtrusive while maintaining excellent readability.
  </Info>
</ParamField>

### How to adjust

<Tabs>
  <Tab title="Via Settings dialog">
    1. Open **Settings** → **Popup Appearance**
    2. In the **Theme** section, adjust the **Background Opacity** slider
    3. The label shows the current value (50-255)
    4. Changes preview in real-time
    5. Click **Save** to apply
  </Tab>

  <Tab title="Via config.ini">
    Edit the configuration file:

    ```ini theme={null}
    [Theme]
    background_opacity = 245
    ```

    Restart meikipop for changes to take effect.
  </Tab>
</Tabs>

<Warning>
  Very low opacity values (below 150) can make text difficult to read, especially over complex backgrounds like games or videos.
</Warning>

## Typography settings

Customize fonts and sizes for optimal readability.

### Font family

<ParamField path="font_family" type="string" default="">
  **Font family**

  The font used for all popup text. Empty string uses the system default.

  **Recommended Japanese fonts:**

  **Windows:**

  * `Yu Gothic` - Modern, clean (default on Windows 10/11)
  * `Meiryo` - Excellent screen readability
  * `MS Gothic` - Traditional monospaced
  * `MS PGothic` - Proportional variant

  **macOS:**

  * `Hiragino Sans` - System default, excellent quality
  * `Hiragino Kaku Gothic Pro` - Classic choice
  * `Hiragino Mincho Pro` - Serif style

  **Linux:**

  * `Noto Sans CJK JP` - Google's high-quality font
  * `Noto Serif CJK JP` - Serif variant
  * `IPAGothic` - Free, widely compatible
  * `TakaoGothic` - IPA-based alternative

  <Tip>
    Leave this setting empty to use your system's default Japanese font, which is usually a good choice.
  </Tip>
</ParamField>

### Font sizes

<ParamField path="font_size_header" type="integer" default="18">
  **Header font size**

  Size in pixels for the main word and reading.

  **Range:** 8-72

  **Guidelines:**

  * `14-16`: Compact (more entries visible)
  * `18-20`: Comfortable (default range)
  * `22-26`: Large (easier to read)
  * `28+`: Very large (accessibility)
</ParamField>

<ParamField path="font_size_definitions" type="integer" default="14">
  **Definition font size**

  Size in pixels for definitions and body text.

  **Range:** 8-72

  **Guidelines:**

  * `12-13`: Compact
  * `14-15`: Standard (default)
  * `16-18`: Comfortable
  * `20+`: Large

  <Tip>
    Keep definition size 2-4 pixels smaller than header size for good visual hierarchy.
  </Tip>
</ParamField>

### Changing typography

<Steps>
  <Step title="Open Settings">
    Navigate to **Settings** → **Popup Appearance**.
  </Step>

  <Step title="Find Typography section">
    Scroll to the **Typography** group.
  </Step>

  <Step title="Select font (optional)">
    Choose a font from the **Font Family** dropdown. Fonts are filtered to show Japanese-compatible options.
  </Step>

  <Step title="Adjust sizes">
    Use the spinboxes to set:

    * **Font Size (Header)**: Main word size
    * **Font Size (Definitions)**: Body text size
  </Step>

  <Step title="Test readability">
    Trigger a lookup to see how your changes look in practice.
  </Step>

  <Step title="Save">
    Click **Save** to apply your typography settings.
  </Step>
</Steps>

<Tip>
  For visually impaired users: Try `font_size_header = 24`, `font_size_definitions = 18`, and a clear sans-serif font like `Noto Sans CJK`.
</Tip>

## Popup positioning

Control how the popup is positioned relative to your cursor.

<ParamField path="popup_position_mode" type="string" default="flip_vertically">
  **Position mode**

  Determines how meikipop positions the popup to avoid screen edges.

  <Tabs>
    <Tab title="Flip Vertically">
      **Default and recommended**

      * Appears below cursor by default
      * Flips above cursor if no space below
      * Pushes horizontally to stay on screen

      **Best for:** General use, games, manga
    </Tab>

    <Tab title="Flip Horizontally">
      * Appears to the right of cursor by default
      * Flips to the left if no space on right
      * Pushes vertically to stay on screen

      **Best for:** Vertical text layouts, narrow windows
    </Tab>

    <Tab title="Flip Both">
      * Flips both horizontally and vertically as needed
      * Maximum flexibility
      * Most aggressive at avoiding edges

      **Best for:** Small screens, corner reading
    </Tab>

    <Tab title="Visual Novel Mode">
      * Intelligent positioning based on screen thirds
      * Smooth interpolation between positions
      * Optimized for text in lower/upper portions
      * Centers horizontally when in middle third

      **Best for:** Visual novels, dialogue-heavy games

      <Info>
        Visual Novel Mode uses a sophisticated algorithm:

        * Lower third of screen: popup appears above
        * Upper third: popup appears below
        * Horizontal position smoothly interpolates from right-aligned (left edge) to center-aligned (middle) to left-aligned (right edge)
      </Info>
    </Tab>
  </Tabs>
</ParamField>

### Changing position mode

In **Settings** → **General** → **Popup Behavior**:

1. Locate the **Position Mode** dropdown
2. Select your preferred mode
3. Click **Save**
4. Test by moving cursor to different screen positions

<Tip>
  Try Visual Novel Mode if you're reading text that appears at the bottom or top of the screen. It's designed to minimize obstruction.
</Tip>

## Content display options

Control what information appears in the popup.

### Compact vs expanded mode

<ParamField path="compact_mode" type="boolean" default="true">
  **Compact mode**

  <Tabs>
    <Tab title="Enabled (default)">
      Multiple definitions on one line, separated by semicolons.

      ```
      食べる [たべる] to eat; to live on; to make a living
      ```

      **Pros:**

      * More entries fit on screen
      * Faster to scan
      * Less popup movement

      **Best for:** Quick lookups, compact displays
    </Tab>

    <Tab title="Disabled">
      Each definition on its own line with numbers.

      ```
      食べる [たべる]
      (1) to eat
      (2) to live on
      (3) to make a living
      ```

      **Pros:**

      * Easier to distinguish multiple meanings
      * More space for detailed information
      * Better for learning

      **Best for:** Study, detailed analysis
    </Tab>
  </Tabs>
</ParamField>

### Information visibility toggles

All of these are configured in **Settings** → **Popup Content**.

<Accordion title="show_all_glosses">
  **Show all glosses** (default: `false`)

  When enabled, shows every gloss for each definition instead of just the first.

  **Example:**

  * Disabled: `to eat`
  * Enabled: `to eat, to consume, to devour, to gobble up`

  <Note>
    Makes popups longer but more comprehensive.
  </Note>
</Accordion>

<Accordion title="show_deconjugation">
  **Show deconjugation** (default: `false`)

  Displays the deconjugation process for inflected forms.

  **Example:**

  ```
  食べられる [たべられる] (食べる ← potential form)
  ```

  <Tip>
    Helpful for learners to understand verb conjugations.
  </Tip>
</Accordion>

<Accordion title="show_pos">
  **Show part of speech** (default: `false`)

  Adds part-of-speech tags to definitions.

  **Example:**

  ```
  (1) (v1, vt) to eat
  (2) (exp) to make a living
  ```

  Tags like `v1` (ichidan verb), `vt` (transitive), `exp` (expression).
</Accordion>

<Accordion title="show_tags">
  **Show tags** (default: `false`)

  Displays dictionary metadata tags in the header.

  **Example:**

  ```
  食べる [たべる] [common, jlpt-n5, v1, vt]
  ```

  Includes frequency, JLPT level, and word type information.
</Accordion>

<Accordion title="show_kanji">
  **Show kanji entries** (default: `true`)

  Includes kanji information in lookup results.

  **When disabled:**

  * Only vocabulary entries shown
  * Faster lookups
  * Shorter popups

  **When enabled:**

  * Shows kanji meanings, readings, examples
  * More comprehensive
  * Helpful for learning kanji
</Accordion>

<Accordion title="show_examples">
  **Show examples** (default: `false`, kanji only)

  Displays example words containing the kanji.

  **Example:**

  ```
  食 [ショク, ジキ]
  食, eat, food
  食事 [しょくじ] meal; 食べ物 [たべもの] food
  ```

  <Note>
    Only applies to kanji entries. Requires `show_kanji = true`.
  </Note>
</Accordion>

<Accordion title="show_components">
  **Show components** (default: `false`, kanji only)

  Shows the radical components that make up the kanji.

  **Example:**

  ```
  食 [ショク]
  食, eat
  人 person, 良 good
  ```

  Helpful for remembering kanji through mnemonics.

  <Note>
    Only applies to kanji entries. Requires `show_kanji = true`.
  </Note>
</Accordion>

## Creating a custom theme

Let's walk through creating a custom purple theme from scratch.

<Steps>
  <Step title="Start with a base theme">
    Open **Settings** → **Popup Appearance**.

    Choose **Celestial Indigo** as a starting point since it's already purple-ish.
  </Step>

  <Step title="Customize the background">
    Click the **Background** color button.

    Choose a deeper purple: `#1A0F2E` (very dark purple).
  </Step>

  <Step title="Adjust the foreground">
    Keep foreground light for contrast: `#E8DFF5` (light lavender).
  </Step>

  <Step title="Pick accent colors">
    * Word highlight: `#C77DFF` (bright purple)
    * Reading highlight: `#FFD60A` (golden yellow for contrast)
  </Step>

  <Step title="Fine-tune opacity">
    Set background opacity to `240` for slight transparency.
  </Step>

  <Step title="Test readability">
    Trigger several lookups to test the theme with different words.

    Adjust if colors are too similar or contrast is insufficient.
  </Step>

  <Step title="Save your theme">
    Click **Save**. Your custom theme is now active!
  </Step>
</Steps>

<Info>
  The theme selector will show "Custom" when you have manually adjusted colors.
</Info>

## Theme showcase

Here are some community-inspired themes you can recreate:

### Solarized Dark

```ini theme={null}
[Theme]
theme_name = Custom
color_background = #002B36
color_foreground = #93A1A1
color_highlight_word = #268BD2
color_highlight_reading = #2AA198
background_opacity = 245
```

### Gruvbox

```ini theme={null}
[Theme]
theme_name = Custom
color_background = #282828
color_foreground = #EBDBB2
color_highlight_word = #FABD2F
color_highlight_reading = #B8BB26
background_opacity = 245
```

### Nord

```ini theme={null}
[Theme]
theme_name = Custom
color_background = #2E3440
color_foreground = #ECEFF4
color_highlight_word = #88C0D0
color_highlight_reading = #A3BE8C
background_opacity = 245
```

### Tokyo Night

```ini theme={null}
[Theme]
theme_name = Custom
color_background = #1A1B26
color_foreground = #C0CAF5
color_highlight_word = #7AA2F7
color_highlight_reading = #9ECE6A
background_opacity = 245
```

<Tip>
  Copy these configurations into your `config.ini` file and restart meikipop to try them out!
</Tip>

## Accessibility considerations

<AccordionGroup>
  <Accordion title="For low vision users">
    **Recommended settings:**

    * `font_size_header = 24`
    * `font_size_definitions = 18`
    * `background_opacity = 255` (fully opaque)
    * High contrast theme (Academic or custom)
    * `compact_mode = false` (more spacing)

    **Color contrast:**

    * Aim for 7:1 contrast ratio (WCAG AAA standard)
    * Test with a contrast checker tool
  </Accordion>

  <Accordion title="For dyslexia">
    **Recommended settings:**

    * Clear sans-serif font (`Noto Sans CJK`)
    * Larger font sizes (20+)
    * Slightly lower opacity (220-235) to reduce harsh contrast
    * Warm background colors (beige, cream)
    * `compact_mode = false`
  </Accordion>

  <Accordion title="For color blindness">
    **Protanopia/Deuteranopia (red-green):**

    * Avoid red/green color combinations
    * Use blue/yellow or blue/orange instead
    * Example: word = `#4A9EFF`, reading = `#FFB347`

    **Tritanopia (blue-yellow):**

    * Avoid blue/yellow combinations
    * Use red/green or pink/teal instead
    * Example: word = `#FF6B9D`, reading = `#26A69A`
  </Accordion>
</AccordionGroup>

## Performance impact

<Info>
  Appearance settings have minimal performance impact. Font rendering and color calculations are highly optimized by Qt.
</Info>

Factors that **do** affect performance:

* Very large font sizes (40+) slightly increase render time
* Extremely long popups from `show_all_glosses` + many definitions
* Multiple kanji entries with `show_examples` and `show_components`

Factors that **don't** affect performance:

* Color choice
* Opacity level
* Theme selection
* Font family (assuming the font is installed)

## Troubleshooting

<AccordionGroup>
  <Accordion title="Popup text is unreadable">
    **Possible causes:**

    * Insufficient contrast between colors
    * Opacity too low
    * Font size too small

    **Solutions:**

    1. Switch to a built-in theme (Nazeka or Academic)
    2. Increase `background_opacity` to 245+
    3. Increase font sizes
    4. Use a contrast checker to verify color choices
  </Accordion>

  <Accordion title="Japanese characters don't display correctly">
    **Symptoms:** Boxes, question marks, or missing characters

    **Cause:** Missing Japanese font

    **Solutions:**

    * Windows: Install `Yu Gothic` or `Meiryo`
    * macOS: Should work by default
    * Linux: Install `fonts-noto-cjk` package
    * Or explicitly set `font_family` to an installed Japanese font
  </Accordion>

  <Accordion title="Theme changes don't apply">
    **If using Settings dialog:**

    * Ensure you clicked **Save**
    * Try triggering a new lookup
    * Check if config.ini was updated

    **If editing config.ini manually:**

    * Restart meikipop after editing
    * Verify syntax (no typos in color codes)
    * Check file permissions
  </Accordion>

  <Accordion title="Colors look different than expected">
    **Possible causes:**

    * Monitor color profile
    * Display calibration
    * Night mode/flux affecting colors
    * Graphics driver settings

    These are system-level factors. Adjust your color choices to compensate or configure your display settings.
  </Accordion>
</AccordionGroup>