Custom Themes

With custom themes, you can adjust Tinkerwell's appearance to your preference. Create and adjust your desired color palette to have a personalized experience.

Where to Place Your Themes

#

Your custom themes should be placed in the ~/.config/tinkerwell/themes directory on macOS and Linux.

For Windows users, you should place them in your home directory following the same path structure: %USERPROFILE%\.config\tinkerwell\themes.

When adding your themes, keep these in mind:

• Theme filenames must follow kebab-case (e.g., my-new-theme.json).
• Ensure that you don't name your theme after any of the pre-existing themes.

Structuring Your Theme

#

Themes are based on the Monaco Editor Theme structure. To ensure they integrate into Tinkerwell seamlessly, your theme JSON files need an additional custom entry, containing the following:

"custom": {
    "primary.background": "#6e6a86",
    ... [other theme details]
    "theme.isLight": true
}

Deep Dive: How Do Custom Theme Colors Work?

#

Custom theme colors predominantly influence the button components, especially in their hover and active states. They also enhance other elements in Tinkerwells UI. The custom colors mirror the predefined theme colors and can be hand-selected to align better with the overall theme, optimizing Tinkerwell's visual appeal.

Detailed Explanation of Color Choices

The custom colors are best chosen with buttons as main usage in mind.

Primary Button Colors

• primary.background: Often the editor.selectionBackground without any opacity is already matching well.
• primary.hoverBackground: A bit lighter than the background, but the same saturation and hue – but a bit more saturation can be good if it’s a darker theme.
• primary.activeBackground: A bit darker than the background, but the same saturation and hue.
• primary.textColor: Whatever is a good contrast to the three colors above, often editor.background is good.

Secondary Button Colors

• secondary.background: The secondary buttons are built around a border-focused style, nevertheless, they need a background (because transparent buttons are not very flexible). The editor.background color is often a good choice for that.
• secondary.border: The editor.selectionBackground without opacity works here as well. Depending on the general colour scheme there may be adjustments necessary, since the secondary border color is shown only on a very fine line. So maybe a bit more brightness and/or saturation is better.
• secondary.hoverBorder: A bit lighter than the background.
• secondary.activeBorder: A bit darker than the background.
• secondary.textColor: Whatever is a good contrast to the background, often editor.foreground is good.

Default Button Colors

The default buttons are similar to the secondary buttons, but with a thinner border and a less prominent text color (via opacity).

• default.background: The default buttons are built around a border-focused style, but less prominent than the secondary buttons. The editor.background color is often a good choice for the background.
• default.border: The editor.selectionBackground without opacity works here as well. Depending on the general colour scheme there may be adjustments necessary, since the default border color is shown only on a very fine line. So maybe a bit more brightness and/or saturation is better.
• default.hoverBorder: A bit lighter than the background.
• default.activeBorder: A bit darker than the background.
• default.textColor: Whatever is a good contrast to the background, often editor.foreground is good.

Deriving the Custom Colors for a Theme

Here's an approach to work on your custom theme colors:

1. Define the Primary Colors
   • primary.background: Typically, editor.selectionBackground without opacity works well.
   • primary.hoverBackground: A shade lighter than primary.background.
   • primary.activeBackground: A shade darker than primary.background.
   • primary.textColor: The color of editor.background is often suitable or adjust accordingly to the background color.
2. Work on the Secondary Colors: These can be based on the primary colors for a harmonious look.
   • secondary.border: The color of editor.selectionBackground works well.
   • secondary.hoverBorder: Adopt primary.hoverBackground.
   • secondary.activeBorder: Adopt primary.activeBackground.
   • secondary.background: Most of the times, editor.background or a slightly lighter shade is suitable for a more subtle look.
   • secondary.textColor: Adopt editor.foreground or adjust accordingly to the background color.
3. Determine the Default Colors: These should be derived in a manner similar to the secondary colors.
   • default.border: The color of editor.selectionBackground works well.
   • default.hoverBorder: Adopt primary.hoverBackground.
   • default.activeBorder: Adopt primary.activeBackground.
   • default.background: Most of the times, editor.background is suitable for a more subtle look.
   • default.textColor: Adopt editor.foreground or adjust accordingly to the background color.

While this method might not align perfectly with all color palettes, it's a great starting point for most.

Automatic Defaults

If no custom colours are defined, the defaults are taken from the editor theme like the following. The respective text colors are determined accordingly to a matching contrast to the background colors.

primary.background: editorCursor.foreground
primary.hoverBackground: editorCursor.foreground
primary.activeBackground: editorCursor.foreground
 
secondary.background: editor.background
secondary.border: editor.selectionBackground
secondary.hoverBorder: editor.foreground
secondary.activeBorder: editor.foreground
 
default.background: editor.background
default.border: editor.selectionBackground
default.hoverBorder: editor.foreground
default.activeBorder: editor.selectionBackground