ayu-colors: the palette that feeds the ayu editor themes

A palette package, not an editor theme you install

The ayu-colors repository does not install into your editor. It publishes to npm under the name `ayu`, and what it sells is a color palette. The README describes it as a bright color theme that comes in three versions, dark, mirage and light, for all-day comfortable work, and it states the purpose plainly: colors for building your own themes and tools.

That split is the entire design of the project. If you are a person who wants a nicer looking editor, this package does nothing for you and you should install one of the theme ports instead. The README lists those separately under Ports, pointing at Sublime Text, VS Code and further options linked from ayutheme.com. Those live in their own repositories under the ayu-theme organization.

If you are instead writing a tool, a template, a chart theme, a terminal color scheme or a syntax highlighter of your own, and you would rather not hardcode a list of hex strings you copied out of a screenshot, this package is the address to use. It hands you the scheme as structured data with a typed surface, and it stays out of the way of the rest of your build.

Three named entries over one nested color tree

The public surface is small enough to read in one sitting. The entry point exports three named objects: `dark`, `light` and `mirage`. Each is a nested tree whose keys describe a role in an interface rather than a hue, so you reach for `syntax.keyword` or `editor.bg` or `common.accent.tint` instead of something called orange or blue. Role-based naming is what lets the three variants share one shape.

The accessors are equally thin. A color node exposes a `hex()` method that returns a string in the form `#ff8f40`, and an `rgb()` method that returns an array of three numbers such as `[170, 217, 76]`. There is no formatting layer, no theming engine and no runtime style injection. You call a getter and you get a value you can put into a config file, an inline style, a terminal escape sequence or a canvas fill.

Because the tree is role-based rather than name-based, the interesting decision for a consumer is which roles matter to you. A Markdown preview only cares about `editor.bg` and `common.accent.tint`. A terminal emulator wants a deeper set, and the README does not enumerate a terminal role set, so a consumer who needs one is working from the same tree the editor ports use.

Installing ayu and reading your first hex value

The install is a single npm package, and the README gives it as a bash block:

npm install ayu

The package name in the npm registry is `ayu`, not `ayu-colors`. The repository is named ayu-colors and the package.json name field is `ayu`, which is a small naming mismatch worth checking against your own dependency list. The engines field requires Node `>=22.18.0`, so on an older runtime the install will warn or fail depending on your package manager.

After install, the usage example in the README is a TypeScript block that shows both the role paths and the two conversion helpers:

import { dark, light, mirage } from 'ayu'

// Access colors
dark.syntax.keyword.hex()         // '#ff8f40'
light.editor.bg.hex()             // '#fcfcfc'
mirage.common.accent.tint.hex()   // '#ffcc66'

// RGB values
dark.syntax.string.rgb()     // [170, 217, 76]

A first real use is therefore one import and one call. Import only the variant you need, `import { dark } from 'ayu'`, then log `dark.syntax.keyword.hex()` in a scratch script and compare the output with the `#ff8f40` shown above. If the string matches, your import path and your build are both correct.

The build generates the tree before TypeScript compiles it

The palette is not hand written as a giant literal in the published output. The package.json scripts show a pipeline in which theme generation comes first, type generation second, and the TypeScript compiler last:

    "build": "npm run generate && tsx scripts/generate-types.ts && tsc && cp src/scheme.d.ts dist/",

The `generate` script runs `tsx scripts/generate-themes.ts`, and the build step then runs `tsx scripts/generate-types.ts` before invoking `tsc`. The repository layout supports this reading: there is a `themes/` directory, a `designer/` directory, a `scripts/` directory and a `src/` directory, alongside `colors.svg` and `palette.svg` at the top level. The SVG files and the designer directory point to a visual source of truth that is turned into code, which is a different workflow from maintaining a color list by hand in a `.ts` file.

A `test` script exists as well, and it builds the package before running `tsx --test scripts/test.ts`, so the checks run against generated output rather than against source files. If you fork this project and change how colors are produced, that ordering matters: a test run without a preceding build would exercise stale files.

The published package carries dist and icons, nothing more

The `files` array in package.json lists exactly two entries:

  "files": [
    "dist",
    "icons"
  ]

That is the entire npm tarball. The designer application, the scripts, the source SVG artwork and the theme generation sources are not published, so a consumer cannot rebuild the palette from the installed package or pull the raw design files out of it. If you need to regenerate the palette yourself, you work from the repository.

The exports map adds two subpath entry points beyond the root:

  "exports": {
    ".": {
      "types": "./dist/colors.d.ts",
      "default": "./dist/colors.js"
    },
    "./color": {
      "types": "./dist/color.d.ts",
      "default": "./dist/color.js"
    },
    "./icons": {
      "types": "./dist/icons.d.ts",
      "default": "./dist/icons.js"
    }
  },

The `main` and `types` fields point at `./dist/colors.js` and `./dist/colors.d.ts`. Note that these files only exist after a build, and the package is declared as an ES module with `"type": "module"`. If your project is CommonJS, a bundler, or an older toolchain, that combination is the first thing to verify before writing code against it.

Version numbers do not line up between the registry and the releases

The package.json version is `9.1.0`. The GitHub releases listed for the repository stop much earlier: v6.0.0 on 2018-08-06 with the note Update colours to ayu sublime v4 color scheme, v5.0.0 on 2017-09-21 matching the colors of [email protected], and v3.0.0 on 2016-11-30 with no note at all.

So the tag history and the registry version tell different stories. The release notes are how the scheme was aligned to specific versions of the Sublime Text theme, which is a sensible design, but it means the changelog on GitHub does not describe the version you install from npm. If you need to know which ayu color revision a given `ayu` version corresponds to, that mapping is not written down in the release notes available here.

The repository is not archived, and the last push was on 2026-10-16, four days before the current date. That is recent work, though the README does not explain what the recent pushes changed, so do not assume a new feature shape. The dependency list has clearly moved on since 2018: TypeScript 6, React 19, Next 16, zustand, culori 4, and `apca-w3` for perceptual contrast, plus `shiki` for syntax highlighting. Those are development dependencies for the designer, not runtime requirements for consumers, whose only runtime dependency is culori.

What the palette does not do for you

Several things people expect from a theme package are simply absent. There is no CSS file, no stylesheet to link, no editor extension and no way to apply the scheme to a running application. The palette hands you values; applying them is your job, and that decision is where most of the real work sits.

The tree is also ayu specific rather than general purpose. It models the roles the ayu editor themes need, so if your tool expects tokens like `info`, `warn` or `error` in the shape another system uses, you will be mapping onto `common.accent` and friends rather than reading them off directly. A mapping layer written by you is a normal part of adopting this package, not a defect in it.

Another limit is the color helper itself. `hex()` and `rgb()` cover the two common cases, and the `color` subpath export suggests more is available in the color module, but the README does not document what other conversions or utilities that module offers. If your design system needs perceptual mixing, alpha variants or contrast checks at runtime, treat that as unconfirmed and check the module directly rather than assuming it is there. The `apca-w3` development dependency suggests contrast thinking happens in the designer side of the project.

Licence terms and the shape of the upgrade cost

The package is published under the MIT licence, and the repository carries a `license` file at the top level along with the SPDX identifier in package.json. MIT is permissive and short, and it places no requirement on how you redistribute or use the color values, which matters here because a palette is typically embedded into output you ship to end users rather than kept as a runtime dependency.

The upgrade cost depends on how you consume it. If you import the palette at runtime and read values from the installed package, a major version bump can change the tree shape under you, so the risky pattern is code that walks the tree generically rather than code that names roles explicitly. Code that names roles explicitly, such as `dark.syntax.keyword.hex()`, breaks loudly and immediately when a role is renamed, which is the better failure.

The other cost is the build. Because the published package contains only `dist` and `icons`, adopting the palette inside a product that also wants to re-theme it later means either depending on the npm package at build time or vendoring the values. Both are workable, and the choice comes down to whether you want a dependency bump to be able to change your colors without a code change.

Editorial conclusion

Adopt ayu-colors when you are building a tool that needs the ayu palette in code, especially in TypeScript projects already on Node 22.18 or newer. Skip it if you want a finished editor theme, since the ports for Sublime Text and VS Code are separate installs. Before you commit, check that the named roles in the color tree, such as syntax.keyword and editor.bg, match the roles your own tool expects, because the tree describes the ayu scheme rather than a general purpose token set.

Frequently asked questions

Official sources

1. ayu-theme/ayu-colors on GitHub
2. License: MIT
3. Project website
4. README
5. Releases