DOCSEARCHbyAlgolia
Submit Docs

kanso.nvim

repository·main·Indexed 20 days ago

https://github.com/webhooked/kanso.nvim

A dark-focused Neovim colorscheme evolved from Kanagawa, featuring WCAG 2.1 AA compliance. It includes four variants (Zen, Ink, Mist, and Pearl), a Saturated Foreground mode for increased vibrancy, and a Minimal mode to reduce visual noise. The theme provides a two-layer color abstraction system using PaletteColors and ThemeColors, and allows for custom highlight group overrides via the setup configuration.

Tokens
2.2K
Snippets
8
Records
8
Agent score
19%

What's inside kanso.nvim

  1. Use Saturated Foreground mode

    main

    Saturated mode increases the vibrancy of syntax highlighting colors without changing the background or UI colors. This is useful for high-visibility needs.

    • Zen, Ink, and Mist: 20% more vibrant colors.
    • Pearl: 40% more vibrant colors.

    You can set foreground to either a single string or a table to specify different saturation levels for dark and light modes.

    require('kanso').setup({
    foreground = {
        dark = "default",    -- Use default colors in dark mode
        light = "saturated"   -- Use higher saturation in light mode
    },
})

  2. Use Minimal Mode

    main

    Minimal mode reduces the color palette to minimize visual noise and distractions. It uses a specific mapping for elements like variables, functions, and keywords to maintain a clean, focused aesthetic.

    require('kanso').setup({
    minimal = true,
})

  3. Customize colors via Palette and Theme

    main

    Kansō uses two layers of color abstraction:

    1. PaletteColors: Raw RGB Hex strings with arbitrary names (e.g., zen0).
    2. ThemeColors: Semantic names grouped by function (e.g., ui.float.bg).

    You can modify the palette to change all usages of a specific color, or modify the theme to change how specific semantic colors are assigned.

    require('kanso').setup({
    colors = {
        palette = {
            -- change all usages of these colors
            zen0 = "#000000",
            fujiWhite = "#FFFFFF",
        },
        theme = {
            -- change specific usages for a certain theme, or for all of them
            zen = {
                ui = {
                    float = {
                        bg = "none",
                    },
                },
            },
            ink = {
                syn = {
                    parameter = "yellow",
                },
            },
            all = {
                ui = {
                    cursor_line_nr_active_foreground = "#C4746E"
                }
            }
        }
    },
})

  4. Install Kansō.nvim

    main

    Install Kansō.nvim using your preferred Neovim package manager. For optimal performance, it is recommended to set priority = 1000 when using Lazy.nvim.

    -- Using Lazy
{
  "webhooked/kanso.nvim",
  lazy = false,
  priority = 1000,
}

-- Using Packer
use "webhooked/kanso.nvim"

  5. Switch between Kansō themes

    main

    Kansō provides four variants: Zen (Dark), Ink (Dark), Mist (Dark), and Pearl (Light). You can switch between them in three ways:

    1. Via Configuration: Set config.theme to the desired theme name.
    2. Via Background Mode: Use the background option in setup. Any change to vim.o.background will select the theme mapped in config.background.
    3. Directly via Command: Load the specific variant using vim.cmd or the load method.
    -- Using vim.cmd
vim.cmd("colorscheme kanso-zen")
vim.cmd("colorscheme kanso-ink")
vim.cmd("colorscheme kanso-mist")
vim.cmd("colorscheme kanso-pearl")

-- Using the API
require("kanso").load("zen")

  6. Configure Kansō.nvim

    main

    Configure the theme using require('kanso').setup(). Note that setup must be called before loading the colorscheme with vim.cmd('colorscheme kanso').

    Important Requirements:

    • Ensure 'laststatus' and 'cmdheight' are set before calling setup so the theme can adjust to them.
    • If you enable compile = true, you must run the :KansoCompile command every time you modify your configuration.
    require('kanso').setup({
    bold = true,                 -- enable bold fonts
    italics = true,             -- enable italics
    compile = false,             -- enable compiling the colorscheme
    undercurl = true,            -- enable undercurls
    commentStyle = { italic = true },
    functionStyle = {},
    keywordStyle = { italic = true},
    statementStyle = {},
    typeStyle = {},
    transparent = false,         -- do not set background color
    dimInactive = false,         -- dim inactive window `:h hl-NormalNC`
    terminalColors = true,       -- define vim.g.terminal_color_{0,17}
    colors = {                   -- add/modify theme and palette colors
        palette = {},
        theme = { zen = {}, pearl = {}, ink = {}, all = {} },
    },
    overrides = function(colors) -- add/modify highlights
        return {}
    end,
    background = {
        dark = "ink",           -- try "zen", "mist" or "pearl" !
        light = "pearl"         -- try "zen", "mist" or "ink" !
    },
    foreground = "default",      -- "default" or "saturated" (can also be a table like background)
    minimal = false,             -- reduced color palette for a more minimal look,
})

-- setup must be called before loading
vim.cmd("colorscheme kanso")

  7. Override highlight groups

    main

    Use the overrides function in your configuration to add or modify Neovim highlight groups (hlgroups). The function receives the current colors object, allowing you to use theme-aware colors in your overrides.

    require('kanso').setup({
    overrides = function(colors)
        return {
            -- Assign a static color to strings
            String = { fg = colors.palette.carpYellow, italic = config.italics },
            -- theme colors will update dynamically when you change theme!
            SomePluginHl = { fg = colors.theme.syn.type, bold = true },
        }
    end,
})

  8. Retrieve palette and theme colors via API

    main

    If you are building plugins or custom configurations, you can programmatically access the current theme's colors using the kanso.colors module.

    -- Get the colors for the current theme
local colors = require("kanso.colors").setup()
local palette_colors = colors.palette
local theme_colors = colors.theme

-- Get the colors for a specific theme
local zen_colors = require("kanso.colors").setup({ theme = 'zen' })