# Contributing

Thanks for your interest in contributing to `@dicebear/styles`.

This repository holds the official DiceBear avatar style definitions: the
JSON files in `src/` that `@dicebear/core` (and every other DiceBear
wrapper) loads to render avatars. The schema those files conform to lives
in the [`@dicebear/schema`](https://github.com/dicebear/schema) package.

## Before you start

- Fixing a typo, a color, or a geometry bug in an existing style: open a
  pull request directly (see the guidance below about Figma files first).
- Proposing a brand-new avatar style: open an issue before you do the work
  so we can align on scope, license, and naming.
- Security issues go privately to <contact@dicebear.com>, never into
  a public issue.
- Contributors follow the
  [DiceBear Code of Conduct](https://github.com/dicebear/.github/blob/main/CODE_OF_CONDUCT.md).

## Most definitions come from Figma; don't hand-edit them

Almost every file in `src/` was generated by the
[DiceBear Figma exporter](https://www.dicebear.com/guides/create-an-avatar-style-with-figma/).
Those files are marked at the top with a `createdBy` / generator field and
**should not be edited by hand**. If you open one and change a path, a
color, or a component variant, your change will disappear the next time
someone re-exports the style.

The Figma source files live in the `figma/` folder of this repository.
The correct workflow is:

1. [Duplicate](https://help.figma.com/hc/en-us/articles/360038511533-Duplicate-files)
   the relevant Figma file.
2. Make the change in Figma.
3. Re-export the style with the
   [DiceBear Exporter](https://www.figma.com/community/plugin/1005765655729342787)
   plugin. See
   [Create an avatar style with Figma](https://www.dicebear.com/guides/create-an-avatar-style-with-figma/)
   for the full walkthrough.
4. Replace the corresponding file in `src/` with the export. Commit the
   updated JSON **and** link the duplicated Figma file in your pull
   request description.

A handful of definitions were hand-authored (for example, the programmatic
styles without character art). Those are safe to edit directly; open the
file and check whether it carries the exporter marker first.

## Requirements

- [Node.js](https://nodejs.org/) 20 or newer
- For tests only: [uv](https://docs.astral.sh/uv/) and a container runtime
  ([Docker](https://www.docker.com/) or [Podman](https://podman.io/)), both
  needed by [Bowtie](https://docs.bowtie.report/)

## Local setup

```sh
git clone https://github.com/dicebear/styles.git
cd styles
npm install
```

Install the validator once per machine:

```sh
brew install uv            # macOS; see uv docs for other platforms
uv tool install bowtie-json-schema
```

## Scripts

| Script             | What it does                                                |
| ------------------ | ----------------------------------------------------------- |
| `npm run build`    | Writes minified definition files to `dist/` via `scripts/build.sh` |
| `npm test`         | Validates every file in `src/` against `@dicebear/schema`   |
| `npm run validate` | Same as `npm test`                                          |

`npm test` uses Bowtie under the hood; the first run pulls a validator
container, so expect a slower warm-up.

## Making a change

1. Update the definition in `src/<style>.json` (or replace it from a fresh
   Figma export).
2. Run `npm test`. If the schema rejects the file, Bowtie prints the exact
   keyword and JSON pointer that failed, so you can fix the offending
   value directly.
3. Run `npm run build` and commit the refreshed `dist/` alongside `src/`.
4. If you changed a style's license or credits, update `LICENSE.md`
   accordingly.

### Schema mismatches

If the validator complains about a field you believe is correct, the
problem may be in the schema rather than the definition. In that case,
open an issue on
[`dicebear/schema`](https://github.com/dicebear/schema/issues) referencing
the failing fixture here, and wait for the schema change to land before
you update the definition.

## Licensing

Every avatar style in this repository ships with its own license. The
master list is [`LICENSE.md`](./LICENSE.md); individual styles also carry
the license metadata inside their definition JSON. When you contribute a
new style, include the license terms in both places and make sure you
have the right to redistribute the artwork under them.

By opening a pull request you agree that your contribution is released
under the license you declare for your style (MIT for the tooling and
infrastructure, per-style for the art itself).

## Releasing (maintainers only)

Publishing is automated via the
[publish workflow](.github/workflows/publish.yml). To cut a release, bump the
version across both manifests and tag it:

```sh
scripts/version.sh <version>   # e.g. 10.1.0 or 10.2.0-rc.1
git push && git push --tags
```

`scripts/version.sh` updates `version` in `package.json` **and**
`pyproject.toml`, syncs `package-lock.json`, then creates the commit and the
`v<version>` tag. Both manifests carry the same version, so always release via
this script (not `npm version`, which would bump only `package.json`). Use a
valid [semver](https://semver.org/) value; for prereleases note that PyPI
normalizes to PEP 440, so npm publishes `10.2.0-rc.1` while PyPI publishes
`10.2.0rc1`.

On the tag, the workflow:

1. Validates every file in `src/` and builds the minified dist files.
2. Publishes to npm with provenance (`@dicebear/styles`).
3. Builds the data-only wheel from `src/` and publishes to PyPI via Trusted
   Publishing (`dicebear-styles`).

Packagist picks up the same Git tag automatically (`dicebear/styles`).
