Bring the library into any project

1. Point your project at the registry

The packages are self-hosted, not on the public npm registry. Add this line to the .npmrc beside yourpackage.json. It applies to @ba-icons packages only; everything else still comes from npm.

@ba-icons:registry=https://icons.atmosphere.africa/npm/

2. Install the package for your framework

Each adapter brings @ba-icons/core, the interface icons. @ba-icons/illustrations holds every other group (Brands, Custom Software, Business, Hosting…); leave it out if you only need icons. npm, pnpm, yarn and bun all work. pnpm holds back packages released in the last day; installing one sooner still works, and pnpm records the exemption by itself.

npm install @ba-icons/react @ba-icons/illustrations
pnpm add @ba-icons/react @ba-icons/illustrations
yarn add @ba-icons/react @ba-icons/illustrations
bun add @ba-icons/react @ba-icons/illustrations

npm install @ba-icons/vue @ba-icons/illustrations
pnpm add @ba-icons/vue @ba-icons/illustrations
yarn add @ba-icons/vue @ba-icons/illustrations
bun add @ba-icons/vue @ba-icons/illustrations

npm install @ba-icons/astro @ba-icons/illustrations
pnpm add @ba-icons/astro @ba-icons/illustrations
yarn add @ba-icons/astro @ba-icons/illustrations
bun add @ba-icons/astro @ba-icons/illustrations

npm install @ba-icons/vanilla @ba-icons/illustrations
pnpm add @ba-icons/vanilla @ba-icons/illustrations
yarn add @ba-icons/vanilla @ba-icons/illustrations
bun add @ba-icons/vanilla @ba-icons/illustrations

3. Draw an icon

import { Icon } from '@ba-icons/react';

export function SaveButton() {
  return (
    <button className="ba-btn ba-btn-md ba-btn-primary">
      <Icon name="check" size={16} /> Save
    </button>
  );
}

// Alone, with no visible text: give it a label.
<button className="ba-icon-btn" aria-label="Close"><Icon name="x" /></button>

<script setup lang="ts">
import { Icon } from '@ba-icons/vue';
</script>

<template>
  <button class="ba-btn ba-btn-md ba-btn-primary">
    <Icon name="check" :size="16" /> Save
  </button>
</template>

// Or register it once, as <BaIcon>:
import { BaIcons } from '@ba-icons/vue';
app.use(BaIcons);

---
import { Icon } from '@ba-icons/astro';
---

<a class="with-icon" href="/docs/">
  Read the docs <Icon name="arrow-right" size={16} />
</a>

<!-- Rendered on the server: no client JavaScript. -->

import { createIcon, defineIconElement, mountIcons, replaceIcons, toSvg } from '@ba-icons/vanilla';

// An <svg> element, built node by node (works under a strict CSP)
button.prepend(createIcon('check', { size: 16 }));

// A string, for templates and server rendering
const markup = toSvg('lock', { label: 'Locked' });

// <ba-icon name="lock" size="24"></ba-icon>
defineIconElement();

// <i data-ba-icon="lock" data-size="24"></i> → <svg …>
replaceIcons();

// Or both at once, now or when the page loads:
mountIcons();
// …or as an import with nothing else to write:
import '@ba-icons/vanilla/auto';

import { iconNames, isIconName, iconMeta, type IconName } from '@ba-icons/react';

const name: IconName = 'shield-check';   // a typo is a type error
iconNames;                               // every name, sorted
iconMeta['node'].note;                   // how the system says to use it

Illustrations and marks

Every other SVG group of the design system: Brands, Custom Software, Smart Home, Cleaning, Laundry, Office Work, Business, Engineering, Hosting, Payments, Stack, Blockchain, Distribution, Media, People, Animals and Concepts. Each file is@ba-icons/illustrations/<group>/<name>, named as in the design system. One ink, the parent's colour;size is the box it's drawn in (96 by default). Keep them large and out of controls, and use each brand mark only for its own brand.

// One import per file: an app bundles only the artwork it uses.
import { Illustration } from '@ba-icons/react';            // or @ba-icons/vue, @ba-icons/astro
import atmosphere from '@ba-icons/illustrations/brands/ba-brand-atmosphere-solid';
import laundry from '@ba-icons/illustrations/laundry/washing-machine';

<Illustration asset={atmosphere} size={240} label="Atmosphere" />
<Illustration asset={laundry} size={160} />

// Vanilla: createIllustration(asset), or <ba-illustration name="laundry/washing-machine">
// The catalogue, with no artwork: groups, files, titles, what each shows
import { groups, illustrationIds } from '@ba-icons/illustrations';
// Every illustration at once (about 3 MB): servers and catalogues only
import { illustrations } from '@ba-icons/illustrations/all';

Props

Colour comes from the parent: set color on the element around the icon (ink orink-muted). Every icon renders as<svg class="ba-icon" data-icon="name" …>, so it can be styled and found the same way everywhere.

Plain HTML, no build step

For a static page, an email template's preview or a CMS: one script from this site, versioned so it never changes under you.

<!-- One script, no build step: defines <ba-icon> and replaces placeholders -->
<script src="https://icons.atmosphere.africa/cdn/ba-icons-0.3.0.js" defer></script>

<ba-icon name="lock"></ba-icon>
<ba-icon name="arrow-right" size="16"></ba-icon>
<ba-icon name="x" label="Close"></ba-icon>

<!-- Illustrations and marks: <group>/<name>, fetched from https://icons.atmosphere.africa/svg/ -->
<ba-illustration name="brands/ba-brand-atmosphere-solid" size="240"></ba-illustration>

<!-- Or a placeholder that becomes the <svg> itself -->
<i data-ba-icon="search" data-size="16" class="search-icon"></i>

<script>
  // window.BaIcons: createIcon, replaceIcons, toSvg, iconNames…
  document.body.append(BaIcons.createIcon('check'));
</script>

Files, sprite and data

Every file is the design system's own, byte for byte, in its groups and under its names. As an <img> they draw in black; inline them, or use a component, to take the parent's colour.

https://icons.atmosphere.africa/svg/<group>/<file>.svg    any SVG, e.g. /svg/brands/ba-brand-atmosphere-solid.svg
https://icons.atmosphere.africa/svg/interface-icons/ba-lock.svg
https://icons.atmosphere.africa/downloads/logos/ba-lockup-horizontal.png
https://icons.atmosphere.africa/sprite.svg                   every interface icon as a <symbol>
https://icons.atmosphere.africa/catalogue.json               every group and file, in the design system's order

# In the packages
@ba-icons/core/svg/ba-lock.svg
@ba-icons/core/sprite.svg
@ba-icons/illustrations/svg/<group>/<file>.svg
@ba-icons/illustrations/catalogue.json

<!-- Once per page (or Astro: <Sprite /> from @ba-icons/astro) -->
<!-- https://icons.atmosphere.africa/sprite.svg, or @ba-icons/core/sprite.svg from the package -->

<svg class="ba-icon" width="20" height="20" aria-hidden="true">
  <use href="/sprite.svg#ba-lock" />
</svg>

Rules from the design system

• 16, 20 or 24. 20 is the default; 16 beside small text, 24 for navigation and empty states. Every icon is drawn to read at 16px.
• Colour from the parent. ink or ink-muted. Green, Yellow and Red only inside a status component, always with the state in words.
• A label only when it stands alone. An icon beside its text is decoration and stays hidden from screen readers.
• node means a system. Never server for that; server is hosting and infrastructure.
• Anchor glyphs (symbol, node, lock, unlock) carry the inverted power geometry. No other glyph gets it, and the power symbol points down.
• Never change the stroke width, scale a group inside a glyph, fill an outline, add gradients, glows or shadows, or mix in icons from another set.
• Illustrations stay out of controls. Interface icons inside buttons and fields; illustrations and marks large and alone. Never mix the two at the same size.
• Other companies' marks (in Hosting, Payments, Stack and Media) are references, not ours: for anything published, use the official file.

Need a glyph that isn't here? It's drawn in the Black Atmosphere Design System to BA Icons / Standard 01 (24 × 24 grid, 2px padding, one 2px stroke, round caps and joins, outline only), then released here. Never draw one in a project.