VOODO: Voxel's Official Design Ontology

This library acts as both a design system and a component library for Voxel51's front-end applications.

This library adheres to semantic versioning best-practices.

Installation

npm i @voxel51/voodo

Usage

Using components

This library exports a number of React components which are consistent with VOODO's look and feel.

import { Button } from "@voxel51/voodo";

export const Component = () => {
    return (
        <Button onClick={() => alert("Button clicked!")}>
            Click me!
        </Button>
    )
};

Note that you'll need to import this library's theme somewhere in your application for the components to be styled correctly. See CSS Themes.

Using icons

Every icon is exported as its own component so that bundlers only include the icons you actually import (there is intentionally no icon-name enum or runtime icon map — that would defeat tree-shaking):

import { CheckIcon, Size } from "@voxel51/voodo";

export const Component = () => <CheckIcon size={Size.Md} />;

To add a new icon, drop the SVG in src/img (PascalCase filename) and run npm run generate-icons.

Theming

CSS Themes

This library is based on Tailwind and exports a set of CSS variables which capture the relevant colors, spacing, typography, etc.

To consume the CSS variables, simply include the following line somewhere in your application.

import "@voxel51/voodo/theme.css";

CSS variables are the preferred way to consume theme values: they react to light/dark with no JavaScript involved. Typed references are exported as cssVar, so you can bind to them from sx, emotion, or plain CSS-in-JS without hardcoding variable names:

import { cssVar } from "@voxel51/voodo";

<div style={{ color: cssVar.color.text.primary }} />;

Literal color values

Some consumers cannot use a var(--…): canvas and WebGL, charting libraries that parse colors themselves, and image export. For those, useColorPalette resolves the palette for the active mode:

import { useColorPalette } from "@voxel51/voodo";

const palette = useColorPalette();
ctx.strokeStyle = palette.pool[i % palette.pool.length];
ctx.fillStyle = palette.teal;

pool is the ordered palette slots — a palette is N colors, however many the tokens define, and the hue-named aliases are not part of it.

Tokens outside of React

@voxel51/voodo/tokens exports the token values as plain data, with no React and no CSS, so it is safe to import from workers, Node tooling, and other non-UI contexts where importing the package root is not an option:

import { colors, palettePool, primitives } from "@voxel51/voodo/tokens";

const pool = palettePool.dark;

FiftyOne's Python package reads this same entry to generate its default color pool, via a script that runs node against the installed dependency.

Contributing

This library is based on HeadlessUI and Tailwind. Components should be minimal, intentional, and adhere strictly to the Voxel51's internal design guidelines.

General rules of thumb:

• Prefer explicit behavior over implicit
• Provide configurability where appropriate
  • Ensure top-level properties adhere to design guidelines
  • Allow for property overrides
• Prefer small, composable components

Publishing

Pushing a v* tag publishes to NPM via the release workflow. The tag must match package.json or the workflow fails.

main always holds the next unreleased version. When releasing without a release branch, a stable release is a tag on the current main head:

git tag v0.3.0 && git push origin v0.3.0

If work must keep landing on main that should not ship in the release, cut a release branch from main instead and tag its head once ready:

git checkout -b release/v0.3.0 main
# land fixes, then:
git tag v0.3.0 && git push origin v0.3.0

Either way, the moment main's version is claimed — by the tag or by the release branch cut — open a PR bumping main to the next version:

npm version minor --no-git-tag-version

Patch releases use a release branch created from the relevant tag, never main. Bump package.json to the patch version on the branch, land the fixes there, and tag the branch head:

git checkout -b release/v0.3.1 v0.3.0
npm version patch --no-git-tag-version
# commit the bump and the fixes, then:
git tag v0.3.1 && git push origin v0.3.1

Delete release branches once the release is tagged — the tag is the durable pointer, and patch releases recreate a branch from it as above.

Prerelease, on any branch:

git tag v0.2.0-dev-my-feature.0 && git push origin v0.2.0-dev-my-feature.0

Prerelease versions (vX.Y.Z-<id>.N) are stamped from the tag — they never appear in package.json — and publish under NPM dist-tag <id> (npm i @voxel51/voodo@dev-my-feature), so latest only moves on stable releases. Use rc as the id for release candidates from main and dev-<branch> for feature-branch builds.

This library is currently in a pre-release state, with versions matching 0.x.y. Standard semantic versioning will be enforced starting with version 1.0.0.

License

Copyright 2024-2026 Voxel51, Inc. Licensed under the Apache License, Version 2.0.

A portion of the icon artwork is derived from Google Material Icons (Apache License 2.0), extracted via @mui/icons-material (MIT License). See NOTICE for attribution details.