als-computing-icons 0.1.59

SVG icon strings for ALS Computing — mirrors @als-computing/icons on npm

ALS Computing Icons

ALS Computing Icons is a collection of SVG icons exported from Figma, automatically optimized and published to both npm and PyPI on every push to main.

• npm: @als-computing/icons
• PyPI: als-computing-icons

Every icon is processed with SVGO and has black fills replaced with currentColor so you can tint them from CSS.

---

Table of Contents

1. How the pipeline works
2. Adding or updating icons
3. One-time setup (do this once when forking / first deploying)
   • npm Automation token
   • PyPI API token
   • Add secrets to GitHub
   • Allow Actions to push back to the repo
4. Using the npm package
5. Using the PyPI package
6. Local development
7. Folder structure
8. Troubleshooting
9. License

---

How the pipeline works

You drop SVGs into assets/
        │
        ▼
  git push to main
        │
        ▼
  GitHub Actions
        │
        ├─ npm run optimize   → optimized-assets/  (SVGO + currentColor)
        ├─ npm run build      → dist/              (JS/TS package)
        ├─ npm run build:python → python/als_computing_icons/__init__.py
        │
        ├─ If anything in dist/ changed:
        │     ├─ Bump patch version in package.json
        │     ├─ git commit + tag + push
        │     ├─ Publish to npm  (@als-computing/icons)
        │     ├─ Create GitHub Release
        │     └─ Publish to PyPI (als-computing-icons)
        │
        └─ Done — both packages now have the new icons

The version number is always kept in sync: whatever patch version npm bumps to, the Python package gets the exact same version.

---

Adding or updating icons

1. Copy your .svg files into the assets/ folder.
2. Commit and push to main.
3. The GitHub Actions workflow runs automatically. No manual steps needed.

Tip: File names become Python/JS variable names. Spaces and special characters are replaced with underscores. For example, linear stage.svg becomes linear_stage.

---

One-time setup

Do these steps once when you first set up this repo (or fork it). After that, every push is fully automatic.

---

1. Create an npm Automation token

You need this so GitHub Actions can publish to npm without triggering a one-time password (OTP) prompt. A regular "Publish" token will fail with EOTP in CI — Automation tokens are specifically designed to skip OTP.

1. Log in at npmjs.com.
2. Click your profile picture (top-right) → Access Tokens.
3. Click Generate New Token → choose Granular Access Token.
   • Token name: anything, e.g. github-actions-publish
   • Expiration: set to your preference (365 days is common)
   • Packages and scopes: select Read and write
   • Select packages: choose @als-computing/icons (or leave as "all packages" before first publish — the package won't exist yet)
   • Organizations: grant access to als-computing
   • Leave everything else as default
4. Click Generate Token and copy it immediately — you won't see it again.

Important: If you see a Classic Token option, choose Automation as the type. The key setting is that the token must bypass OTP/2FA for CI to work.

---

2. Create a PyPI API token

First-time publishing requires an account-scoped token because the project doesn't exist yet on PyPI. After the first successful publish you can optionally narrow it to just the als-computing-icons project.

1. Log in at pypi.org.
2. Click your username (top-right) → Account settings.
3. Scroll to API tokens → click Add API token.
   • Token name: anything, e.g. github-actions
   • Scope: Entire account (for the first publish; change to project-scoped after)
4. Click Create token and copy it immediately — it starts with pypi-.

---

3. Add both tokens to GitHub Secrets

1. Go to your GitHub repository.
2. Click Settings (top menu bar of the repo, not your profile).
3. In the left sidebar: Secrets and variables → Actions.
4. Click New repository secret and add each one:

Secret name	Value
NPM_TOKEN	The npm Automation token you copied in step 1
PYPI_TOKEN	The PyPI API token you copied in step 2

Secret names must match exactly — the workflow references them as ${{ secrets.NPM_TOKEN }} and ${{ secrets.PYPI_TOKEN }}.

---

4. Allow Actions to write to the repo

The workflow bumps the version, commits dist/ and package.json, and pushes a git tag. GitHub blocks this by default.

1. In your repo, go to Settings → Actions → General.
2. Scroll to Workflow permissions.
3. Select Read and write permissions.
4. Check Allow GitHub Actions to create and approve pull requests (optional but harmless).
5. Click Save.

---

Using the npm package

npm install @als-computing/icons

// ESM
import { motor, cluster } from '@als-computing/icons';

// CommonJS
const { motor } = require('@als-computing/icons');

// Render in React
<span dangerouslySetInnerHTML={{ __html: motor }} style={{ color: 'red' }} />

---

Using the PyPI package

pip install als-computing-icons

from als_computing_icons import motor, cluster

# Each variable is the raw SVG string
print(motor)  # <svg xmlns="http://www.w3.org/2000/svg" ...>...</svg>

Rendering in a Jupyter notebook:

from IPython.display import HTML
from als_computing_icons import motor

HTML(f'<span style="color: steelblue; font-size: 48px">{motor}</span>')

Rendering in a Dash / Panel app:

import dash_dangerously_set_inner_html as ddsih
from als_computing_icons import motor

ddsih.DangerouslySetInnerHTML(motor)

---

Local development

# Install JS dependencies
npm install

# Optimize SVGs (assets/ → optimized-assets/)
npm run optimize

# Build the JS/TS package (optimized-assets/ → dist/)
npm run build

# Build the Python package (optimized-assets/ → python/als_computing_icons/__init__.py)
npm run build:python

# Build and package the Python wheel locally
cd python && python3 -m build

---

Folder structure

assets/                   ← DROP YOUR SVGs HERE
optimized-assets/         ← auto-generated by `npm run optimize`
dist/                     ← auto-generated JS/TS package output
python/
  pyproject.toml          ← Python package config (hatchling)
  als_computing_icons/
    __init__.py           ← auto-generated, one variable per icon
    py.typed              ← PEP 561 type marker
scripts/
  optimize-svg.js         ← SVGO pass; replaces black → currentColor
  build.js                ← generates dist/ (JS/TS)
  build_python.js         ← generates python/als_computing_icons/__init__.py
  sync-assets.js          ← optional Figma sync helper
.github/workflows/
  build-and-publish.yml   ← the main CI pipeline
package.json

---

Troubleshooting

Error	Cause	Fix
npm error code EOTP	npm token is a Publish token, not Automation	Re-create the npm token as Automation type (step 1 above)
403 Forbidden on PyPI	Token is project-scoped but project doesn't exist yet	Use an Entire account scoped token for the first publish
HttpError: Resource not accessible by integration	Actions don't have write permission	Enable Read and write permissions in repo Settings → Actions → General
optimized-assets/ missing or empty	SVGs weren't committed to assets/	Add .svg files to assets/ and push
Python variable name clash	Two SVG files sanitise to the same identifier	Rename one of the source files to make names unique

---

License

MIT © ALS Computing