*lush* color scheme creation tool with real time feedback ,gggg, d8" "8I ,dPYb, 88 ,dP IP'`Yb 8888888P" I8 8I 88 I8 8' 88 gg gg ,g, I8 dPgg, ,aa,_88 I8 8I ,8'8, I8dP" "8I dP" "88P I8, ,8I ,8' Yb I8P I8 Yb,_,d88b,,_ ,d8b, ,d8b,,8'_ 8) ,d8 I8, "Y8P" "Y888888P'"Y88P"`Y8P' "YY8P8P88P `Y8 Lush is a color scheme creation aid, written in Lua, for Neovim. Lush lets you define your scheme as a mini-dsl, provides HSL colour manipulation aids, and gives you real time feedback of your changes. Lush colorschemes can be exported easily exported for distribution without Lush, in both lua and vimscript formats, or they can also be imported into other Lua systems to access color data. ================================================================================ CONTENTS *lush-toc* Lush Tutorials |lush-tutorials| HSL & HSLuv Colors |lush-hsl-colors| |lush-hsluv-colors| Define a Color |lush-define-color| Color Operations |lush-color-operations| rotate, ro |lush-color-rotate| saturate, desaturate, sa, de |lush-color-saturate| |lush-color-desaturate| lighten, darken, li, da |lush-color-lighten| |lush-color-darken| mix |lush-color-mix| readable |lush-color-readable| abs_* |lush-color-absolute-operations| hue, saturation, lightness, .h, .s, .l |lush-color-direct| .hex, tostring |lush-color-string-coercion| .rgb |lush-color-rgb| Example |lush-color-example| Lush Spec |lush-spec| Sample lush-spec |lush-spec-sample| Lush-Spec Spec |lush-spec-spec| Direct Definition |lush-spec-direct-definition| Linked Group |lush-spec-linked-group| Inherited Group |lush-spec-inherited-group| Extending lush-specs |lush-extending-specs| extends({parsed_lush_spec, ...}).with(spec) |lush-extends-with| merge({parsed_lush_spec, ...}) |lush-merge| Lush.Ify |lushify| Converting an Existing Theme to Lush |lush-converting-existing-colorscheme| Exporting from Lush |lush-export| Manual Toolchain |lush-manual-toolchain| Pitfalls, Beartraps, Dragons |lush-pitfalls| Bugs or Limitations |lush-bugs| -------------------------------------------------------------------------------- Lush Tutorials *lush-tutorials* An interactive tutorial is provided via the :LushRunTutorial command. -------------------------------------------------------------------------------- HSL & HSLuv Colors *lush-hsl-colors* *lush-hsluv-colors* Lush supports two color spaces: - HSL which is defined by hue, saturation and lightness components and - HSLuv, which functionally similar to HSL but maps better to human perception. That is to say, increasing a hsluv colors lightness by 10% may be more likely to give you a color you would _perceive_ as "10% lighter" rather than what hsl would give you, a color which is mathematically "10% lighter". For more information on HSLuv see: https://www.hsluv.org/ Both colorspaces can be accessed from the `lush` module and may be used interchangeably. For the rest of this document the term hsl can be taken to mean hsl or hsluv. > hsl = lush.hsl hsluv = lush.hsluv hsl(100, 50, 50) hsluv(100, 50, 50) < Define a color *lush-define-color* You can create HSL(UV) colors by providing hue, saturation and lightness values, or providing a hexadecimal string. > color = hsl(0, 100, 50) -- equivilent to rgb(255,0,0) elsewhere hex_color = hsl("#FF0000") -- hex_color == color < Color Operations *lush-color-operations* All color operation functions are pure, they alway return new colors objects and leaving the originals unmodified. > c1 = hsl(0, 100, 50) c2 = c1.rotate(10) -- c2 != c1 < Functions can be chained. > c.rotate(10).saturate(20).lighten(5) < rotate, ro *lush-color-rotate* Rotate values are wrap around 0-360 degrees, `ro` is shorthand for `rotate`. > color.rotate(n) color.rotate(-n) color.ro(n) color.ro(-n) < saturate, desaturate, sa, de *lush-color-saturate* *lush-color-desaturate* Saturation operations are clamped between 0-100. Operations are relative, they increase/decrease a percentage, not by adding a flat value (see |lush-color-absolute-operations|). `sa` is shorthand for `saturate`. `de` is shorthand for `desaturate`. > color.saturate(n) color.desaturate(n) color.sa(n) color.de(n) < lighten, darken, li, da *lush-color-lighten* *lush-color-darken* Lightness operations are clamped between 0-100. Operations are relative, they increase/decrease a percentage, not by adding a flat value (see |lush-color-absolute-operations|). `li` is shorthand for `lighten`. `da` is shorthand for `darken`. > color.lighten(n) color.darken(n) color.li(n) color.da(n) < mix *lush-color-mix* Mix one colour into another. Accepts a target color and strength, where the target is a hsl, hsluv type and strength is between 0-100. A strength of 0 effectively returns the original color, while 100 will return the target color. > color.mix(target, 50) color.mix(target, 0) == color color.mix(target, 100) == target < readable *lush-color-readable* Given a color, return either white or black, which ever provides the better contrast. Most useful when setting a foreground color. > color.readable() < abs_* *lush-color-absolute-operations* Saturation and Lightness operatins work relative to the current values. This is generally preferred when making those kind of adjustments, but all functions, including shorthands, have absolute counterparts, prefixed by `abs_` which will add or subtract an absolute value. Rotate does not have an `abs_` prefixed function, it always operates absolutely. > color = hsl(0, 50, 50) color.saturate(10) -- saturates the color by 10% color.abs_saturate(10) -- adds 10 to 50 < hue, saturation, lightness, .h, .s, .l *lush-color-direct* You may also directly set a HSL value via: > hue(n) saturation(n) lightness(n) < And access members with, > color.h -- hue color.s -- saturation color.l -- lightness < .hex, tostring *lush-color-string-coercion* HSL colors can be coerced into a hex string, either by concatenation with another string, passing to a function which will invoke tostring() or accessing the `.hex` accessor. .rgb() *lush-color-rgb* HSL colors can be converted to RGB values, this should only be done outside of a Lush spec, when you are intending to extract the red, green and blue values for use elsewhere. Example *lush-color-example* > local hsl = require('lush').hsl -- include the module local red = hsl(0, 100, 50) -- define a color local light_red = red.lighten(20) -- modify local orange = red.hue(20) -- set local sum_hues = red.h + light_red.h + orange.h -- access local chained_compliment = red.ro(180) -- chain via aliases .da(30) .sa(10) print(red) -- as string "#FF0000" < -------------------------------------------------------------------------------- Lush Spec *lush-spec* You define your color scheme by writing a lush-spec, which can leverage the HSL module (or any other lua module) and be exported to other parts of Neovim. Lush will expose your lush-spec as a Lua module. The basic definition of a lush-spec is, a Lua table which defines your highlight groups, by name, and their associated color and decoration details. The advantage of using Lush and a lush-spec is that you're able to define groups from previous groups, and make modifications on those groups to easily define relational colours between groups. Sample Lush-Spec *lush-spec-sample* Here's a very simple lush-spec: > -- cool_name/lua/lush_theme/cool_name.lua -- require lush local lush = require('lush') -- lush(), when given a spec, will parse it and return a table -- containing your color information. -- We should return it for use in other files. return lush(function() return { -- Define what vims Normal highlight group should look like Normal { bg = lush.hsl(208, 90, 30), fg = lush.hsl(208, 80, 80) }, -- And make whitespace slightly darker than normal. -- Note you must define Normal before you try to use it. Whitespace { fg = Normal.fg.darken(40) }, -- And make comments look the same, but with italic text Comment { Whitespace, gui="italic" }, -- and clear all highlighting for CursorLine CursorLine { }, } end) < And the corresponding colorscheme loading file for nvim: > " cool_name/colors/cool_name.vim " yes, unfortunately you still have to write some Vim Script set background=dark let g:colors_name="cool_name" " you could detect background == dark || light here and require " different files lua require('lush')(require('lush_theme.cool_name')) < -------------------------------------------------------------------------------- Lush-Spec Spec *lush-spec-spec* Lush supports the following group definitions: Direct Definition *lush-spec-direct-definition* Used to define a stand alone highlight group. Syntax: > GroupName { fg = value, bg = value, gui = value, sp = value, blend = value } < Supports the following keys: fg: sets the `fg` property of a highlight group. value must be a string, or respond to tostring(). bg: sets the `bg` property of a highlight group. value must be a string, or respond to tostring(). sp: sets the `sp` property of a highlight group. value must be a string, or respond to tostring(). blend: sets the `blend` property of a highlight group. value must be an integer between 0 and 100. note: you must have enabled blending in neovim via `pumblend` or `winblend`! gui: a string containing any of the following format modifier values, separated by space or comma. bold: boolean, enables or disables bold. italic: boolean, enables or disables italics. underline: boolean, enables or disables underline. underlineline: boolean, enables or disables double underline. underdouble: boolean, underlineline in nvim 0.8 undercurl: boolean, enables or disables undercurl. underdot: boolean, enables or disables underdot. underdotted: boolean, underdot in nvim 0.8 underdash: boolean, enables or disables underdash. underdashed: boolean, underdash in nvim 0.8 strikethrough: boolean, enables or disables strikethrough. altfont: boolean, enables or disables alternate font in nvim 0.9 reverse: boolean, enables or disables flipping fg and bg values. standout: boolean, enables or disables standout. nocombine: boolean, enables or disables nocombine. lush: a namespace to save arbitrary data to a group. Is not exported to the final highlight but may be accessed in the lush-spec or the parsed-lush-spec. Constraints: `value` may be any Lua type which will concatenate with a string. `value` may be derived from previously defined group properties. All unsupported keys are dropped. Group name is CamelCase by convention, but may be any string beginning with alpha characters. Group names may not be `ALL`, `NONE`, `ALLBUT`, `contained` or `contains`, this is a vim constraint. Linked Group *lush-spec-linked-group* Used to define a highlight link. Syntax: > LinkedGroup { GroupName }, < Supported keys: N/A. Constraints: Linked group must be defined before the link definition. Inherited Group *lush-spec-inherited-group* Used to define a new highlight group, with properties inherited from another group. This is logically similar to a Linked Group, except you wish to define new keys, or redefine old keys. Syntax: > InheritedGroup { Parent, gui = "bold" }, < Supported keys: See Direct Definition. Constraints: Only one parent group may be specified and it must be the first value in the group definition. Inherits constraints of Direct Definition -------------------------------------------------------------------------------- Extending lush-specs *lush-extending-specs* Lush provides two ways to combine multiple lush specs into one: `extends` and `merge`. If you want to combine a list of one or more parsed lush specs, and apply any tweaks, you should use `extends({parsed_spec, ...}).with(spec)`. If you want to combine a list of one or more parsed lush specs, but don't need to adjust them, you can use `merge({parsed_spec, ...}). In both cases, groups later in the list will overwrite any groups before them. Given: > group_1 = { A { fg = "1_a_fg" }, B { fg = "1_b_fg" } } group_2 = { B { fg = "2_b_fg" } } < Extend/merging the groups in order would result in: > {group_1, group_2} = { A { fg = "1_a_fg" }, B { fg = "2_b_fg" } } < extends({parsed_lush_spec, ...}).with(spec) *lush-extends-with* `extends({parsed_lush_spec, ...})` *must* be proceeded by `with(spec)`, which returns a parsed_lush_spec. If you have an existing spec that you wish to modify, you may want to use `extends.with`. Potential use cases: - You like a lush colorscheme you got online, but want to change a few specific parts of it, such as the comment style, or the background color. - You want to add a plugin to an colorscheme by using it's existing groups. - You are writing your own colorscheme and want to make a small tweaks to create a variant, for example a high-contrast or colorblind safe mode. Example - adding plugin support: > local lush = require('lush') local hsl = lush.hsl -- some colorscheme from the internet local harbour = require('lush_theme.harbour') local spec = lush.extends({harbour}).with(function() return { -- make Sneak look like Search Sneak { harbour.Search }, -- you can now use Sneak just like any other group (ref, inherit, etc) SneakScope { bg = Sneak.bg.li(10) }, SneakLabel { Sneak, gui = "italic" }, -- you can use bits from anywhere MixAndMatch { bg = harbour.Normal.fg, fg = SneakLabel.fg, gui = "underline" }, } end) return spec < Example - complex combination: > -- You may have installed this colorscheme via your package manager or similar -- (good lush colorschemes should be portable), or you might be writing a variant -- for your main colorscheme. local some_colorscheme = require('lush_theme.some_colorscheme') -- Maybe you also want to include a community extension that patches -- some missing styles in the original colorscheme. local some_colorscheme_lsp = require('lush_theme.some_colorscheme_lsp') local spec = lush.extends({some_colorscheme, some_colorscheme_lsp}).with(function() -- It is also valid to return an empty spec. This is functionally -- equivalent to calling merge({some_colorscheme}). -- return { } return { -- You can use the same group tools as normal: linking and group -- inheritance, but you must access the groups through their imported -- variables. -- Inherit fg and gui settings, but adjust bg Normal { some_colorscheme.Normal, bg = some_colorscheme.Normal.bg.li(10).sa(20) }, -- Overwrite comment group completely Comment { fg = some_colorscheme.Normal.fg.da(10) }, -- link cursorline to normal CursorLine { some_colorscheme.Normal } } end) return spec < merge({parsed_lush_spec, ...}) *lush-merge* `merge({parsed_lush_spec, ...})` returns a parsed_lush_spec. If you have an group of parsed lush specs that you do not want to tweak, you can simply merge them. Potential use cases: - You have a collection of plugin highlight groups want to let users configure which highlight groups are enabled. - You want to apply a patch/extension to a colorscheme that isn't provided by the main colorscheme repo. - You simply want to define your colorscheme in parts for maintenance reasons. Example: > -- See also extends.with, most concepts are applicable. local some_colorscheme = require('lush_theme.some_colorscheme') -- Maybe LSP highlights are complex and you define them in a different file local some_colorscheme_lsp = require('lush_theme.some_colorscheme_lsp') local specs = { some_colorscheme, some_colorscheme_lsp } -- Only include xyz groups if the user wants them if user_config.enable_xyz then table.insert(specs, require('lush_theme.some_colorscheme.xyz') end -- You might also include variants this way it user_config.italic_comments then -- You can also do this inline, or by using extends.with table.insert(specs, lush(function() return { Comment { some_colorscheme.Comment, gui = "italic" } } end) -- Combine into one local spec = lush.merge(specs) return spec < -------------------------------------------------------------------------------- Lush.ify *lushify* Lush.ify will provide automatic, real-time highlighting of any `hsl(...)` calls, as well as highlighting any groups in your lush-spec with their appropriate colors and decorations. To use lush.ify, open your colorscheme Lua file and run the vim command, > :Lushify < or run it directly via Lua, > :lua require('lush').ify() < Now changes you make to a colorscheme are reflected in real time. See the two starter files for more information and a demonstration. Performance of lush.ify is somewhat dependent on your hardware and probably more specifically, your terminal. Some re-render faster than others. Lush.ify will perform some minor event debouncing, with an increased window on multiple parser failures. The defaults should allow for a smooth experience, but if you desire to change them, you can pass options to lush.ify like so (times are in ms), > :lua require('lush').ify({natural_timeout = 25, error_timeout = 300}) < If you feel performance is poor, please try disabling any linter/lsp/etc first. -------------------------------------------------------------------------------- Converting an Existing Theme to Lush *lush-converting-existing-colorscheme* Lush provides a `:LushImport` command that creates a draft lush spec from the currently loaded colorscheme. It places this in the `z` register, so you can paste it into a new file by typing `"zp`. -------------------------------------------------------------------------------- Exporting From Lush *lush-export* Lush has a comprehensive build system, see BUILD.md until vimdocs are written for this system (sorry). -------------------------------------------------------------------------------- Manual Toolchain *lush-manual-toolchain* If desired, you can manually parse -> compile -> apply your lush-spec. Most usecases are probably better served by the build system, see BUILD.md. > local lush = require('lush') local parsed = lush.parse(function() return { ... } end) local compiled = lush.compile(parsed) lush.apply(compiled) < Parse *lush-manual-toolchain-parse* Accepts a lush spec and returns a parsed lush spec. Accepts no options. > local parsed = lush.parse(function() return { ... } end) < Compile *lush-manual-toolchain-compile* Accepts a parsed lush spec and returns a table of group-attribute pairs which can be passed to `nvim_set_hl`. > local compiled = lush.compile(parsed) < Apply *lush-manual-toolchain-apply* Accepts a table of group-attribute pairs and passes them to nvim_set_hl. Accepts an optional options table: - force_clean: boolean, clear existing highlight before applying given highlights. > lush.apply(compiled, options) < -------------------------------------------------------------------------------- Pitfalls, Beartraps, Dragons *lush-pitfalls* Linters: You will likely get warnings from linters while writing a lush-spec, specifically around "undefined globals". Most of these warnings can be safely ignored, you may wish to disable LSP/Linters temporarily when working on a colorscheme. Dependency Injection: Lush-specs are executed a bare environment, so they don't have access to Lua globals or other modules. However, they are also written as closures, so they do have access to any local level variables in the colorscheme file. This means if you want to access a global module, you simply have to bind it to a local scope variable. > -- all these local variables can be accessed in the spec closure local weather = require('local_weather') local harbour = require('lush_theme.harbour') local math = math lush(function() return { -- set fg color depending on rain or snow Normal { fg = hsl(weather.hex_color_for_current_weather) }, -- set comment color from normal fg, but set to a random -- analogous-ish color Comment { fg = Normal.fg.ro(math.random(-60, 60)) }, -- we can even access other colorscheme data -- automatic colorscheme inheritance and extension is WIP CursorLine { fg = harbour.CursorLine.fg, bg = harbour.CursorLine.bg }, } end) < Easy Motion: Activating the easy motion plugin in a lush.ify'd buffer will cause a lot of syntax errors. This is because easy-motion directly modifies the buffer to display its "jump keys", which we try to parse. It is not recommended you activate easy motion in a lush.ify'd buffer. Live Search-Replace: If you use Neovim's live-updating search-and-replace feature (), you may see Neovim errors being reported. In my experience these can be safely ignored and you may continue as normal. Lightline While Lightline can be styled through Lush, real-time updating has some caveats and performance may be less than optimal due to Vim Script performance. See `examples/lightline-one-file` and `examples/lightline-two-files` for guidance. Generally, if real time performance with Lightline is problematic, I would recommend developing your colorscheme first, then disabling lush.ify with `:e!` in the buffer and applying your changes via . The two examples go into some more detail regarding this method. -------------------------------------------------------------------------------- Bugs or Limitations *lush-bugs* Sometimes line group and HSL highlighting may appear out of sync if you've applied undo/redo chains to a lush.ify'd file. Generally typing more into the buffer will fix these issues as the highlighter re-syncs with the buffer state. You may find some elements don't update in real time (LSP sign column for example). This is a side effect of how colours are applied to those elements, they are only as they are created (afaik). The group name in your lush-spec should update to let you see how it will look when your colorscheme is loaded. Lush.ify'd `hsl()` and group name highlight may sometimes be obscured by CursorLine highlighting. If this is a problem, you can set CursorLine to an empty definition or disable the cursor line with .