Gim/internal/theme/themes/README.md

Theme JSON Format (v1)

This document defines the JSON structure for editor themes.

• All color values are 6-digit hex strings (for example #d4d8e1).
• Capture keys must be lowercase and must not include @.
• syntax.exact overrides syntax.group. These can be any values!
• If a capture is missing from both maps, the editor should fall back to the base line style.

Full structure

{
  "name": "default",
  "line": { "fg": "#d4d8e1", "bg": "#111418" },
  "background": { "bg": "#111418" },
  "visual_highlight": { "bg": "#2f334d" },

  "cursors": {
    "normal": { "fg": "#111418", "bg": "#d4d8e1" },
    "insert": { "fg": "#d4d8e1", "bg": "#111418" },
    "command": { "fg": "#111418", "bg": "#d4d8e1" },
    "replace": { "fg": "#d4d8e1", "bg": "#111418" }
  },

  "gutter": {
    "default": { "fg": "#6b7280", "bg": "#0d1014" },
    "current_line": { "fg": "#c0c8d8", "bg": "#0d1014" }
  },

  "status_bar": {
    "default": { "fg": "#8f99aa", "bg": "#0d1014" }
  },

  "command_line": {
    "error": { "fg": "#bf616a", "bg": "#111418" },
    "output_border": { "fg": "#d4d8e1", "bg": "#0d1014" },
    "continue_message": { "fg": "#81a1c1", "bg": "#111418" }
  },

  "syntax": {
    "group": {
      "comment": "#7f8795",
      "function": "#81a1c1",
      "keyword": "#b48ead",
      "number": "#88c0d0",
      "string": "#a3be8c",
      "type": "#ebcb8b",
      "variable": "#d4d8e1"
        ...
    },
    "exact": {
      "comment.documentation": "#8f99aa",
      "function.call": "#81a1c1",
      "keyword.return": "#b48ead",
      "string.escape": "#d08770",
      "variable.parameter": "#c0c8d8",
        ...
    }
  }
}

Field notes

• name: theme name shown by :colorscheme.
• line: base text style used as the default fallback.
• background: background fill style used for empty space.
• visual_highlight: selection background style.
• syntax.group: fallback colors by capture group (keyword, string, comment, etc.).
• syntax.exact: exact capture overrides (keyword.function, string.escape, etc.).

Future ideas

For now, styles only support foreground/background colors.

In a future version we may add optional text attributes such as:

• bold
• italic
• underline