voldmark 0.1.0

A custom SVG icon library with dual light/dark themes

voldmark

A custom SVG icon library with a singular visual language. Not a generic icon set — every icon is authored with intent.

55 icons across 5 categories. Dual light/dark themes. Stroke-only. 24×24 grid. Available for React, Astro, and Python.

---

Design principles

• One grid — 24×24 with 2px safe margin (20×20 usable area)
• One weight — 1.5px stroke (±0.25px optical correction where noted)
• One language — rounded caps and joins, no fills, no effects
• Dual theme — light and dark variants are designed, not inverted

---

Installation

npm (React / Astro)

npm install voldmark

PyPI (Python)

pip install voldmark

---

Usage

React — light (default)

import { ArrowRight, UiSearch, StatusCheck } from 'voldmark/react'

<ArrowRight />
<ArrowRight size={20} />
<ArrowRight size={20} strokeWidth={2} color="#ff0000" />
<ArrowRight title="Go forward" /> // accessible: aria-label + role="img"

React — dark

import { ArrowRight } from 'voldmark/react/dark'

<ArrowRight size={24} />

Astro — light

---
import ArrowRight from 'voldmark/astro/light/ArrowRight'
import UiSearch from 'voldmark/astro/light/UiSearch'
---

<ArrowRight />
<ArrowRight size={20} color="#333" />
<ArrowRight title="Go forward" />

Astro — dark

---
import ArrowRight from 'voldmark/astro/dark/ArrowRight'
---

<ArrowRight size={24} />

Python

from voldmark import light, dark

# Returns a complete SVG string ready to embed in HTML
svg = light.arrow_right()
svg = light.arrow_right(size=20, color="#111", stroke_width=2)
svg = dark.arrow_right(title="Go right")  # accessible: aria-label + role="img"

# All icons have the same signature
svg = light.status_check(size=16)
svg = light.ui_search(class_name="icon", aria_hidden=False)

Python icon function signature:

def arrow_right(
    size: int | str = 24,
    color: str = "currentColor",
    stroke_width: float | None = None,
    class_name: str | None = None,
    title: str | None = None,
    aria_hidden: bool | None = None,
) -> str: ...

Raw SVG strings (JS)

import arrowRight from 'voldmark/svg/light/arrow-right'
import arrowRight from 'voldmark/svg/dark/arrow-right'

Sprite sheet

<!-- In your HTML -->
<script type="module">
  import 'voldmark/sprite/light'
</script>

<svg><use href="#arrow-right" /></svg>

---

Component API

React / Astro props

interface VoldmarkIconProps {
  size?: number | string     // default: 24
  color?: string             // default: 'currentColor'
  strokeWidth?: number       // default: 1.5
  className?: string
  style?: React.CSSProperties  // React only
  title?: string             // accessibility label — renders <title> + aria-label
  'aria-hidden'?: boolean    // default: true when no title
}

---

Icon catalog

Arrows

arrow-right arrow-left arrow-up arrow-down

Chevrons

chevron-right chevron-left chevron-up chevron-down

UI Chrome

ui-close ui-menu ui-search ui-settings ui-plus ui-minus ui-dots-horizontal ui-dots-vertical ui-sparkle ui-wand ui-robot ui-bolt ui-orbit ui-mosaic ui-thread ui-broadcast

Status

status-check status-warning status-error status-info status-lock status-unlock status-target status-trophy status-star status-thumbs-up status-thumbs-down

User

user user-circle user-plus user-minus

File & Folder

file file-text file-plus file-minus file-download file-upload folder folder-open

Data

data-chart-bar data-chart-line data-chart-pie data-flow

Navigation

nav-home nav-back nav-external-link nav-waypoint

---

Development

npm run validate     # check parity + SVG rules
npm run optimize     # SVGO optimization pass
npm run build        # generate React + Astro + Python outputs, bundle dist/
npm run preview      # visual QA at localhost:5173
npm run test         # run all JS tests (Vitest)
pytest python/tests/ # run Python tests

Adding icons

1. Create src/icons/light/<name>.svg
2. Create src/icons/dark/<name>.svg
3. Run npm run validate — must pass before proceeding
4. Run npm run build
5. Run npm test and pytest python/tests/

SVG requirements: viewBox="0 0 24 24", fill="none", currentColor for all strokes, stroke-width="1.5", round caps and joins, no <title>, <style>, <desc>, no hardcoded colors, max 4KB.

Preview app

npm run preview

Opens a side-by-side light/dark grid with a live size slider (12px → 48px). Use this for visual QA before committing new icons.

---

Release

Releases are triggered by pushing a version tag:

git tag v0.1.0
git push origin v0.1.0

The CI/CD pipeline will:

1. Build and test (Node + Python 3.11–3.13)
2. Publish to npm
3. Publish to PyPI
4. Create a GitHub Release

Required secrets: NPM_TOKEN, PYPI_TOKEN.

---

License

MIT — Guilherme Almeida Zeni