\n\n# themer \n\n`themer` takes a set of colors and generates [editor themes](#editorsides), [terminal themes](#terminals), [themes for other apps](#other-apps), and [desktop wallpapers](#wallpapers).\n\n\n\n## Table of contents\n\n- [Getting started](#getting-started)\n- [CLI documentation](#cli-documentation)\n - [Installation](#installation)\n - [Usage](#usage)\n - [Example workflow: dotfiles integration](#example-workflow-dotfiles-integration)\n - [Example workflow: npx](#example-workflow-npx)\n - [Example workflow: using base16 schemes with Themer](#example-workflow-using-base16-schemes-with-themer)\n- [API documentation](#api-documentation)\n - [Installation](#installation-1)\n - [Interface](#interface)\n - [Create custom `ColorSet`s](#create-custom-colorsets)\n - [Color mappings](#color-mappings)\n - [Create custom `Template`s](#create-custom-templates)\n- [Themer color sets](#themer-color-sets)\n - [Web-only color sets](#web-only-color-sets)\n - [Original color sets](#original-color-sets)\n - [Ports from third-party themes](#ports-from-third-party-themes)\n- [Themer templates](#themer-templates)\n - [Terminals](#terminals)\n - [Editors/IDEs](#editorsides)\n - [Other apps](#other-apps)\n - [Wallpapers](#wallpapers)\n- [Prior art](#prior-art)\n- [Contributing](#contributing)\n\n## Getting started\n\nThere are a few different ways to level up your development setup with `themer`:\n\n1. **Web-based graphical user interface.** `themer` has an official progressive web app located at [themer.dev](https://themer.dev).\n2. **Command-line interface.** `themer` can be used to generate themes on the CLI, see the [CLI docs](#cli-documentation) below.\n3. **Application programming interface.** `themer` exposes a JavaScript API (complete with TypeScript type definitions) for programmatic use; see the [API docs](#api-documentation) below.\n\nFeature comparison:\n\n| | Web UI | CLI/API |\n| ----------------------------- | -------------- | -------- |\n| Instant preview | ✅ | ❌ |\n| Supported color format | Any CSS format | Hex only |\n| Wallpaper output format | PNG + SVG | SVG only |\n| Raytraced 3D wallpaper | ✅ | ❌ |\n| Seamless dotfiles integration | ❌ | ✅ |\n\n## CLI documentation\n\nAs of V5, `themer` is distributed as a single TypeScript/JavaScript package containing all built-in color sets and templates for ease of use—but still supports the use of [custom color sets](#create-custom-colorsets) or [templates](#create-custom-templates).\n\n### Installation\n\nInstall `themer` from npm with your JavaScript package manager of choice.\n\n```sh\nnpm install themer\n```\n\n`themer` can also be installed globally. Or if you prefer not to install it at all, [it can be used with `npx`](#example-workflow-npx).\n\n### Usage\n\n```sh\nthemer [options]\n```\n\nPass `themer` one or more color sets, as many templates as you wish, as many wallpaper resolutions as you wish, and an output directory.\n\n| Option | Description | Default value | Available options |\n| ----------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `-c, --color-set ` | the color set(s) to render | `default` | [color set name](#themer-color-sets), or path to JS file containing a [custom color set](#create-custom-colorsets), or a file path to a [base16 yaml file](#example-workflow-using-base16-schemes-with-themer) |\n| `-t, --template ` | the theme template(s) to render | `*` (all built-in templates) | [template name](#themer-templates), or path to JS file containing a [custom template](#create-custom-templates) |\n| `-s, --size ` | resolution to render in pixels, in the format [width]x[height] | `2880x1800` | any |\n| `-o, --output ` | the output directory | `themer-output` | any |\n\n`--color-set`, `--template`, and `--size` may be specified multiple times.\n\nYour generated theme files, as well as a README on how to install them, will be written to the output directory.\n\n### Example workflow: dotfiles integration\n\nSay you wanted to generate a vim theme and desktop background using `themer`'s default color set. First, install `themer`:\n\n```sh\ncd my-dotfiles\nnpm install themer\n```\n\nThen edit your `package.json`:\n\n```json\n{\n \"scripts\": {\n \"build\": \"themer -c default -t vim -t vim-lightline -t hyper -t wallpaper-block-wave -o gen\"\n }\n}\n```\n\nThen run your new script:\n\n```sh\nnpm run build\n```\n\nNow check the `gen/` folder for your generated files. Here's the result:\n\n\n\n### Example workflow: npx\n\nThis command will generate a Vim theme and the Block Wave wallpaper, using `themer`'s default color set, and put them in a folder called `output`:\n\n```sh\nnpx themer -c default -t vim -t wallpaper-block-wave -o output\n```\n\n### Example workflow: using base16 schemes with Themer\n\nIn place of a themer color set, you can also provide `themer` with any base16 scheme YAML file.\n\n```\nthemer --color-set path/to/base16-scheme.yml ...\n```\n\nRefer to the [base16 repository](https://github.com/chriskempson/base16#scheme-repositories) for a list of base16 schemes.\n\n## API documentation\n\n`themer` ships with a JavaScript API (with TypeScript type definitions) for use in programmatically generating themes.\n\n### Installation\n\n```sh\nnpm install themer\n```\n\n### Interface\n\n`themer`'s default export is an [async generator function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function*) that takes three arguments:\n\n1. An array of [`ColorSet` objects](#create-custom-colorsets), or string identifiers of [`themer`'s built-in color sets](#themer-color-sets)\n2. An array of [`Template` objects](#create-custom-templates), or string identifiers of [`themer`'s built-in templates](#themer-templates)\n3. A `RenderOptions` object used to specify the resolution of the outputted wallpaper images\n4. (Optional) an `OutputFileTransform` async generator function that transforms the files generated by the provided templates. This function runs between each template's `render` and `renderInstructions` functions.\n\nThe objects yielded by the generator are `OutputFile`s or the type yielded by `OutputFileTransform`.\n\n```ts\nimport themer from \"themer\";\nimport myColors from \"./my-colors\";\nimport myTemplate from \"./my-template\";\n\n// Example usage: generate Vim themes, 1440x900 wallpapers, and custom files\n// from themer's \"Night Sky\" color set and a custom color set.\nconst files = themer(\n [\"night-sky\", myColors],\n [\"vim\", \"wallpaper-block-wave\", myTemplate],\n { wallpaperSizes: [{ width: 1440, height: 900 }] }\n);\n\nfor await (const file of files) {\n // ...\n}\n```\n\n### Create custom `ColorSet`s\n\n```ts\nimport type { ColorSet } from \"themer\";\n\nconst myColorSet: ColorSet = {\n // Color sets should provide a human-readable name.\n name: \"My Color Set\",\n\n // Color sets can define a dark variant, a light variant, or both.\n // Each variant provides two or eight shades and eight accent colors in hex format.\n variants: {\n // In a dark variant, shade0 should be the darkest and shade7 should be\n // the lightest.\n dark: {\n shade0: \"#333333\",\n // Note: you can define shades 1 through 6 yourself, or you can omit\n // them; if omitted, they will be calculated automatically by\n // interpolating between shade0 and shade7.\n shade7: \"#eeeeee\",\n accent0: \"#ff4050\",\n accent1: \"#f28144\",\n accent2: \"#ffd24a\",\n accent3: \"#a4cc35\",\n accent4: \"#26c99e\",\n accent5: \"#66bfff\",\n accent6: \"#cc78fa\",\n accent7: \"#f553bf\",\n },\n\n // In a light variant, shade7 should be the darkest and shade0 should be\n // the lightest.\n light: {\n shade0: \"#eeeeee\",\n shade7: \"#333333\",\n accent0: \"#f03e4d\",\n accent1: \"#f37735\",\n accent2: \"#eeba21\",\n accent3: \"#97bd2d\",\n accent4: \"#1fc598\",\n accent5: \"#53a6e1\",\n accent6: \"#bf65f0\",\n accent7: \"#ee4eb8\",\n },\n },\n};\n\nexport default myColorSet;\n```\n\n_Pro Tip: you can use [`themer`'s Web UI](https://themer.dev) to more easily select your colors, then click the \"Download\" button to generate a `colors.js` file in the correct format. With the Web UI, you can also input any valid CSS color format (keyword, HSL, RGB, etc.) and it will automatically convert the color to hex for you._\n\n#### Color mappings\n\nTo help you choose colors for your own color set, this is approximately how most `themer` templates will utilize your colors:\n\n| Color Key | Typical Usage | Conventional Color\\* |\n| --------- | ------------------------- | -------------------- |\n| `accent0` | error, VCS deletion | Red |\n| `accent1` | syntax | Orange |\n| `accent2` | warning, VCS modification | Yellow |\n| `accent3` | success, VCS addition | Green |\n| `accent4` | syntax | Cyan |\n| `accent5` | syntax | Blue |\n| `accent6` | syntax, caret/cursor | |\n| `accent7` | syntax, special | Magenta |\n| `shade0` | background color | |\n| `shade1` | UI | |\n| `shade2` | UI, text selection | |\n| `shade3` | UI, code comments | |\n| `shade4` | UI | |\n| `shade5` | UI | |\n| `shade6` | foreground text | |\n| `shade7` | foreground text | |\n\n_\\*Conventional color is suggested for consistency with ANSI color names in terminal themes, but is not a hard requirement._\n\nSee [`themer`'s Web UI](https://themer.dev) for a more visual representation of the color mappings.\n\n### Create custom `Template`s\n\n```ts\nimport type { Template } from \"themer\";\n\nconst template: Template = {\n // Templates should provide a human-readable name.\n name: \"My Template\",\n\n // The render async generator function takes a color set and the render\n // options, and yields one or more output files. The color set is fully\n // expanded (e.g., if the color set did not include shades 1 through 6\n // when originally authored, those intermediary shades will have already\n // been calculated and included).\n render: async function* (colorSet, options) {\n // The yielded output file has two properties: a string path (relative)\n // and a Buffer of the file's content.\n yield {\n path: \"my-file.txt\",\n content: Buffer.from(\"Hello, world!\", \"utf8\"),\n };\n },\n\n // The renderInstructions function takes an array of paths generated from\n // the render function and should return a Markdown string, which will be\n // included in the generated README.md file.\n renderInstructions: (paths) =>\n `Copy the files (${paths.join(\" and \")}) to your home directory.`,\n};\n\nexport default template;\n```\n\n## Themer color sets\n\n### Web-only color sets\n\n(Only available on [themer.dev](https://themer.dev).)\n\n| Name | Dark Preview | Light Preview |\n| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [Concert](https://themer.dev/concert) |  |  |\n| [Victor Mono](https://themer.dev/victor-mono) |  |  |\n| [Future Pro](https://themer.dev/future-pro) |  |  |\n\n### Original color sets\n\n| Name | Dark Preview | Light Preview |\n| ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [`default`](https://github.com/mjswensen/themer/tree/main/cli/src/color-set/default.ts) |  |  |\n| [`finger-paint`](https://github.com/mjswensen/themer/tree/main/cli/src/color-set/finger-paint.ts) |  |  |\n| [`green-as-a-whistle`](https://github.com/mjswensen/themer/tree/main/cli/src/color-set/green-as-a-whistle.ts) |  |  |\n| [`monkey`](https://github.com/mjswensen/themer/tree/main/cli/src/color-set/monkey.ts) |  |  |\n| [`night-sky`](https://github.com/mjswensen/themer/tree/main/cli/src/color-set/night-sky.ts) |  | (dark only) |\n| [`polar-ice`](https://github.com/mjswensen/themer/tree/main/cli/src/color-set/polar-ice.ts) |  |  |\n| [`right-in-the-teals`](https://github.com/mjswensen/themer/tree/main/cli/src/color-set/right-in-the-teals.ts) |  |  |\n| [`shoulder-pads`](https://github.com/mjswensen/themer/tree/main/cli/src/color-set/shoulder-pads.ts) |  |  |\n\n### Ports from third-party themes\n\n| Name | Dark Preview | Light Preview |\n| ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [`dracula`](https://github.com/mjswensen/themer/tree/main/cli/src/color-set/dracula.ts) |  | (dark only) |\n| [`github-universe`](https://github.com/mjswensen/themer/tree/main/cli/src/color-set/github-universe.ts) |  | (dark only) |\n| [`lucid`](https://github.com/mjswensen/themer/tree/main/cli/src/color-set/lucid.ts) |  |  |\n| [`mojave`](https://github.com/mjswensen/themer/tree/main/cli/src/color-set/mojave.ts) |  |  |\n| [`nova`](https://github.com/mjswensen/themer/tree/main/cli/src/color-set/nova.ts) |  | (dark only) |\n| [`one`](https://github.com/mjswensen/themer/tree/main/cli/src/color-set/one.ts) |  |  |\n| [`rivet`](https://github.com/mjswensen/themer/tree/main/cli/src/color-set/rivet.ts) |  |  |\n| [`seti`](https://github.com/mjswensen/themer/tree/main/cli/src/color-set/seti.ts) |  | (dark only) |\n| [`solarized`](https://github.com/mjswensen/themer/tree/main/cli/src/color-set/solarized.ts) |  |  |\n\n## Themer templates\n\n### Terminals\n\n- [`alacritty`](https://github.com/mjswensen/themer/tree/main/cli/src/template/alacritty.ts)\n- [`cmd`](https://github.com/mjswensen/themer/tree/main/cli/src/template/cmd.ts)\n- [`conemu`](https://github.com/mjswensen/themer/tree/main/cli/src/template/conemu.ts)\n- [`hyper`](https://github.com/mjswensen/themer/tree/main/cli/src/template/hyper.ts)\n- [`iterm`](https://github.com/mjswensen/themer/tree/main/cli/src/template/iterm.ts)\n- [`kitty`](https://github.com/mjswensen/themer/tree/main/cli/src/template/kitty.ts)\n- [`konsole`](https://github.com/mjswensen/themer/tree/main/cli/src/template/konsole.ts)\n- [`terminal`](https://github.com/mjswensen/themer/tree/main/cli/src/template/terminal.ts)\n- [`terminator`](https://github.com/mjswensen/themer/tree/main/cli/src/template/terminator.ts)\n- [`warp`](https://github.com/mjswensen/themer/tree/main/cli/src/template/warp.ts)\n- [`windows-terminal`](https://github.com/mjswensen/themer/tree/main/cli/src/template/windows-terminal.ts)\n\n### Editors/IDEs\n\n- [`bbedit`](https://github.com/mjswensen/themer/tree/main/cli/src/template/bbedit.ts)\n- [`emacs`](https://github.com/mjswensen/themer/tree/main/cli/src/template/emacs.ts)\n- [`sublime-text`](https://github.com/mjswensen/themer/tree/main/cli/src/template/sublime-text.ts)\n- [`vim-lightline`](https://github.com/mjswensen/themer/tree/main/cli/src/template/vim-lightline.ts)\n- [`vim`](https://github.com/mjswensen/themer/tree/main/cli/src/template/vim.ts)\n- [`visual-studio`](https://github.com/mjswensen/themer/tree/main/cli/src/template/visual-studio.ts)\n- [`vs-code`](https://github.com/mjswensen/themer/tree/main/cli/src/template/vs-code.ts)\n- [`xcode`](https://github.com/mjswensen/themer/tree/main/cli/src/template/xcode.ts)\n- [`zed`](https://github.com/mjswensen/themer/tree/main/cli/src/template/zed.ts)\n\n### Other apps\n\n- [`alfred`](https://github.com/mjswensen/themer/tree/main/cli/src/template/alfred.ts)\n- [`brave`](https://github.com/mjswensen/themer/tree/main/cli/src/template/brave.ts)\n- [`chrome`](https://github.com/mjswensen/themer/tree/main/cli/src/template/chrome.ts)\n- [`css`](https://github.com/mjswensen/themer/tree/main/cli/src/template/css.ts)\n- [`firefox-addon`](https://github.com/mjswensen/themer/tree/main/cli/src/template/firefox-addon.ts)\n- [`firefox-color`](https://github.com/mjswensen/themer/tree/main/cli/src/template/firefox-color.ts)\n- [`kde-plasma-colors`](https://github.com/mjswensen/themer/tree/main/cli/src/template/kde-plasma-colors.ts)\n- [`keypirinha`](https://github.com/mjswensen/themer/tree/main/cli/src/template/keypirinha.ts)\n- [`prism`](https://github.com/mjswensen/themer/tree/main/cli/src/template/prism.ts)\n- [`sketch-palettes`](https://github.com/mjswensen/themer/tree/main/cli/src/template/sketch-palettes.ts)\n- [`slack`](https://github.com/mjswensen/themer/tree/main/cli/src/template/slack.ts)\n- [`wox`](https://github.com/mjswensen/themer/tree/main/cli/src/template/wox.ts)\n- [`xresources`](https://github.com/mjswensen/themer/tree/main/cli/src/template/xresources.ts)\n\n### Wallpapers\n\nSee [`themer`'s Web UI](https://themer.dev) for wallpaper previews.\n\n- 3D (web-only)\n - [`wallpaper-exhibit`](https://github.com/mjswensen/themer/tree/main/web/src/lib/template/wallpaper-exhibit.ts)\n - [`wallpaper-logos`](https://github.com/mjswensen/themer/tree/main/web/src/lib/template/wallpaper-logos.ts)\n- 2D (web & CLI)\n - [`wallpaper-block-wave`](https://github.com/mjswensen/themer/tree/main/cli/src/template/wallpaper-block-wave.ts)\n - [`wallpaper-burst`](https://github.com/mjswensen/themer/tree/main/cli/src/template/wallpaper-burst.ts)\n - [`wallpaper-circuits`](https://github.com/mjswensen/themer/tree/main/cli/src/template/wallpaper-circuits.ts)\n - [`wallpaper-diamonds`](https://github.com/mjswensen/themer/tree/main/cli/src/template/wallpaper-diamonds.ts)\n - [`wallpaper-dot-grid`](https://github.com/mjswensen/themer/tree/main/cli/src/template/wallpaper-dot-grid.ts)\n - [`wallpaper-octagon`](https://github.com/mjswensen/themer/tree/main/cli/src/template/wallpaper-octagon.ts)\n - [`wallpaper-shirts`](https://github.com/mjswensen/themer/tree/main/cli/src/template/wallpaper-shirts.ts)\n - [`wallpaper-triangles`](https://github.com/mjswensen/themer/tree/main/cli/src/template/wallpaper-triangles.ts)\n - [`wallpaper-trianglify`](https://github.com/mjswensen/themer/tree/main/cli/src/template/wallpaper-trianglify.ts)\n\n## Prior art\n\n`themer` is inspired by [chriskempson/base16](http://chriskempson.com/projects/base16/) and similar projects.\n\nConceptually, `themer` is very similar to [base16](http://chriskempson.com/projects/base16/), but:\n\n1. It is lighter, and simpler to use.\n2. It is more easily extensible with your own color sets and templates.\n3. It integrates better with your dotfiles, especially if you keep them under version control.\n\n## Contributing\n\nFor instructions on how to contribute to `themer`, see [CONTRIBUTING.md](https://github.com/mjswensen/themer/blob/main/.github/CONTRIBUTING.md) and [`themer`'s code of conduct](https://github.com/mjswensen/themer/blob/main/CODE_OF_CONDUCT.md).\n","readmeFilename":"README.md","users":{"tjfwalker":true,"willpracht":true,"flumpus-dev":true}}
![\"Themer](\"https://cdn.jsdelivr.net/gh/mjswensen/themer@8af6e97f2d51b7002894ba86bb7b3fccf965efb9/assets/icon.png\"){kind=icon}
\n \n