README

Ikonym — geometric avatars generated from an identifier.

Ikonym is an open-source library for generating deterministic SVG avatars and integrating them into digital products. Developers can use the JavaScript package or portable DiceBear JSON definitions. Designers and product leads can compare densities, colors, and visual results before integration. It is also a practical example for anyone tracking generative-avatar tools.

Each identifier selects a vivid, seamless geometric mosaic: shell fans, concentric arcs, curved growth bands, and faceted plates mix tile by tile. Neighboring tiles never repeat the same motif family along an edge, regardless of color or orientation. The same identifier and options always produce the same avatar.

The ikonym package is published on npm, PyPI, crates.io, pub.dev, and NuGet, and as a Go module; numera11y/ikonym is also available on Packagist.

Ikonym is developed by Numera11y and will be featured in its digital-tools catalog. Browse the source code, report issues, or contribute on GitHub.

License and attribution

Ikonym is distributed under the MIT License. You may use, modify, and sell it. Any redistribution, including modified versions, must retain the copyright notice and MIT License text included with the package. See LICENSE for the complete terms.

Integrations

The same JSON style definition works with official DiceBear engines for JavaScript, PHP, Python, Rust, Go, Dart, and C#. See the installation guide and complete examples for the published npm, Packagist, PyPI, crates.io, pub.dev, NuGet, and Go module packages.

The PyPI distribution includes the same five JSON definitions and a small Python API for loading styles. Install the optional DiceBear renderer with pip install "ikonym[dicebear]" to generate SVG avatars.

Usage

import { createAvatar, createAvatarDataUri, getPaletteForSeed } from 'ikonym';

const svg = createAvatar('ikon-satin', { size: 128, density: 7 });

const imageUrl = createAvatarDataUri('ikon-satin');
const palette = getPaletteForSeed('ikon-satin');
// { colors: { navy, blue, cyan, pink, orange, yellow, mint, cream }, pattern }

For PHP, install Ikonym and the DiceBear engine with composer require numera11y/ikonym dicebear/core, then load a style with Numera11y\Ikonym\StyleDefinition::json(7). See the PHP integration example.

Install Ikonym from npm with npm install ikonym, or download the versioned .tgz tarball from this site.

createAvatar(identifier, options?) returns an SVG document. createAvatarDataUri(identifier, options?) returns a data URI for an HTML image element. getPaletteForSeed(identifier, density?) exposes the eight colors and motif selected by the identifier. Options include size (24–1024, default 160), density (3×3, 5×5, 7×7, 9×9, or 12×12 grid; default 7), and optional paletteColors. radius (0–50) is also supported. The old waveCount, pieceCount, and gridSize options remain as deprecated density aliases.

Local demo

npm install
npm run dev

The demo lets you enter an identifier, choose a mosaic density, round the avatar corners, and copy or download the SVG and DiceBear definition.

Python distribution

The Python distribution includes the same five JSON styles; its optional dicebear extra adds SVG rendering. To build a local wheel and source archive:

npm run styles:build
python -m pip install build twine
python -m build --outdir python-dist
python -m twine check python-dist/*

The JSON style loader itself has no runtime dependencies.

Rust crate

The ikonym crate is published on crates.io. Check formatting, tests, and the packaged file list with:

cargo fmt --all -- --check
cargo test --all-targets
cargo package --list

.NET package

Install the Ikonym package from NuGet and render an avatar:

dotnet add package Ikonym

using Ikonym;

var svg = AvatarGenerator.CreateAvatar("account-4821", density: 7, size: 128);

Build the library and site

npm run build:lib
npm run styles:build
npm run styles:validate
npm run composer:validate
npm run contrast:validate
npm run package:download
npm run build

The site is statically generated by Astro at /en/ and /fr/. The root path redirects to English by default and offers direct links to both languages. Astro generates canonical, hreflang, robots.txt, and sitemap metadata for https://ikonym.numera11y.fr; override PUBLIC_SITE_URL if the production domain changes.

styles:validate builds all five densities with DiceBear Core and checks full tile coverage, non-repeating neighboring motif families, deterministic layouts and colors, and wrapper parity.

The public source repository is github.com/numera11y/ikonym; releases are published to npm.

DiceBear

The styles/ikonym-{3,5,7,9,12}.json files are compatible with DiceBear Core. Their presence in this repository does not mean Ikonym is included in the official DiceBear style catalog. A contribution must be proposed, and acceptance is at DiceBear's discretion.

French documentation

See README.fr.md and the French integration guide.

numera11y / ikonym

Package info

Security

Statistics