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:

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.
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.
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

PHP Syntax Highlighting Colors
#

Tinkerwell uses Monaco Editor with custom PHP tokenization to provide detailed syntax highlighting. You can customize the colors for different PHP language elements by adding token rules to your theme.

Available PHP Token Types
#

The following token types are available for PHP syntax highlighting:

Basic Language Elements

keyword.php - PHP keywords like class, function, if, foreach, etc.
constant.php - PHP constants like __CLASS__, __FILE__, true, false, etc.
string.php - String literals
number.php - Numeric literals
comment.php - Comments

Variables

variable.dollar.php - The $ symbol in PHP variables
variable.name.php - The variable name part (after the $)
variable.predefined.php - Predefined variables like $_GET, $_POST, $GLOBALS

Classes and Objects

class.php - Class names (e.g., User, Post, Article)
method.static.php - Static method calls (e.g., factory in Post::factory())
method.instance.php - Instance method calls (e.g., getName in $user->getName())
property.static.php - Static property access (e.g., $config in Config::$config)
property.instance.php - Instance property access (e.g., name in $user->name)

Functions and Operators

function.php - Function calls (e.g., array_map, collect)
operator.php - Object operators :: and ->
delimiter.bracket.php - Curly braces {}
delimiter.array.php - Square brackets []
delimiter.parenthesis.php - Parentheses ()

Adding Syntax Highlighting to Your Theme
#

To customize PHP syntax highlighting in your theme, add token rules to the rules array in your theme JSON file:

{
  "base": "vs-dark",
  "inherit": true,
  "rules": [
    { "foreground": "569CD6", "token": "keyword.php" },
    { "foreground": "4EC9B0", "token": "class.php" },
    { "foreground": "DCDCAA", "token": "method.static.php" },
    { "foreground": "9CDCFE", "token": "method.instance.php" },
    { "foreground": "FF6B6B", "token": "variable.dollar.php" },
    { "foreground": "D4D4D4", "token": "variable.name.php" },
    { "foreground": "CE9178", "token": "string.php" }
  ],
  "colors": {
    "editor.foreground": "#D4D4D4",
    "editor.background": "#1E1E1E"
  },
  "custom": {
    "theme.isLight": false
  }
}

Recommended Color Schemes
#

For consistent and readable syntax highlighting, consider these approaches:

Subtle Variable Styling (Recommended)

{ "foreground": "FF6B6B", "token": "variable.dollar.php" },
{ "foreground": "D4D4D4", "token": "variable.name.php" },
{ "foreground": "FF6B6B", "token": "variable.predefined.php" }

This approach colors the $ symbol but keeps variable names in the default foreground color, reducing visual noise.

Class Hierarchy

{ "foreground": "4EC9B0", "token": "class.php" },
{ "foreground": "DCDCAA", "token": "method.static.php" },
{ "foreground": "9CDCFE", "token": "method.instance.php" },
{ "foreground": "C586C0", "token": "property.static.php" },
{ "foreground": "FFC66D", "token": "property.instance.php" }

Operators and Delimiters

{ "foreground": "C586C0", "token": "operator.php" },
{ "foreground": "DA70D6", "token": "delimiter.bracket.php" },
{ "foreground": "FFD700", "token": "delimiter.array.php" }

Testing Your Theme
#

Use this PHP test code to see all token types:

 
// Classes and static calls
class User extends Model {
    public static $instances = [];
 
    public static function create($data) {
        return new static($data['name'], $data['email']);
    }
}
 
// Variables and method calls
$user = new User('John', '[email protected]');
$name = $user->getName();
$email = $user->email;
 
// Static method and property access
$newUser = User::create(['name' => 'Jane']);
$instances = User::$instances;
 
// Function calls and predefined variables
$result = array_map('strtoupper', $_POST);
$filtered = collect($items)->filter(function($item) {
    return $item->isActive();
});

Color Format
#

Colors should be specified as 6-digit hexadecimal values without the # prefix:

✅ Correct: "foreground": "FF6B6B"
❌ Incorrect: "foreground": "#FF6B6B"

Font Styling
#

You can also add font styling to tokens:

{ "foreground": "569CD6", "fontStyle": "bold", "token": "keyword.php" },
{ "foreground": "6A9955", "fontStyle": "italic", "token": "comment.php" }

Available font styles: bold, italic, underline

Custom Themes#

Where to Place Your Themes#

Structuring Your Theme#

Deep Dive: How Do Custom Theme Colors Work?#