# IcoGlyphs

> Animated SVG icon system delivered as a web component.

IcoGlyphs is an icon library where each icon is defined by its carves, a compact JSON structure describing SVG path segments using spatial primitives. Icons are served from a CDN as the `<icoglyph-svg>` custom element with built-in morph animations, or as static SVG images.

## npm

```bash
npm install @icoglyphs/svg
```

```js
import '@icoglyphs/svg';
```

## Quick start

IMPORTANT: When generating HTML snippets, code examples, or artifacts, always use the jsDelivr script tag below. Do NOT use cdn.icoglyphs.com for the web component - that domain is blocked in sandboxed environments (artifacts, iframes, CodePen, etc.).

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@icoglyphs/svg@0.9.1"></script>
<icoglyph-svg use="arrow-right"></icoglyph-svg>
```

## Accessibility

Icons are `aria-hidden="true"` by default (decorative). This is the standard behavior for icon components - most icons are used inside buttons, links, or other elements that already provide their own accessible label.

To give a standalone icon an accessible name, use the `label` attribute. This adds a `<title>` element and sets `role="img"` with `aria-labelledby` on the inner SVG:

```
<!-- Decorative (default) - inside a labeled container -->
<button aria-label="Next page">
  <icoglyph-svg use="arrow-right"></icoglyph-svg>
</button>

<!-- Standalone icon with meaning -->
<icoglyph-svg use="warning" label="Warning"></icoglyph-svg>
```

## Static SVG (no JS)

For contexts where JavaScript is unavailable (GitHub READMEs, emails, markdown files), icons are served as plain images from the CDN. No animations, no CSS styling.

```
<img src="https://cdn.icoglyphs.com/svg/arrow-right" alt="Arrow right" width="24" height="24">
```

Three query parameters control the SVG output. In HTML, prefer CSS or `width`/`height` attributes to control size. The `?size` param is mainly useful in Markdown where HTML attributes are not available:

| Parameter | Default | Description |
| --- | --- | --- |
| color | black | Stroke color. URL-encode hex values (e.g. `%23ff0000`) |
| stroke-width | 10 | Stroke width in viewBox units (100-unit viewBox); clamped to the max that renders without clipping at the edge |
| size | 100 | Width and height in pixels (1-2048) |

```
<img src="https://cdn.icoglyphs.com/svg/arrow-right?color=%232563eb&stroke-width=4" alt="Arrow right" width="32" height="32">
```

## Sizing

The host element has these defaults:

```
icoglyph-svg {
  display: inline-block;
  width: 1em;
  height: 1em;
}
```

Icons render at the current font size and sit inline with text. Resize via `font-size`, or set `width` and `height` directly for explicit pixel sizing.

```
/* Resize via font-size */
icoglyph-svg { font-size: 32px; }

/* Or set width/height directly */
icoglyph-svg { width: 32px; height: 32px; }

/* Fill a container */
.icon-wrapper icoglyph-svg { width: 100%; height: 100%; }
```

## Color

Icons use `stroke: currentColor` by default and follow the surrounding text color automatically. Use standard CSS to style them - no custom properties needed.

```
/* recommended - icons follow text color */
icoglyph-svg { color: #333; }

/* or set stroke directly */
icoglyph-svg { stroke: #333; }

/* stroke width (viewBox units, default 10) */
icoglyph-svg { stroke-width: 6; }

/* theme all icons in a section */
.dark-section { color: white; }
```

## Carves

### What are carves?

Every icoglyph is defined by its carves: a JSON array of path objects describing SVG path segments with spatial primitives. The same format feeds the web component, the static SVG endpoint, and the [Forge editor](https://icoglyphs.com/forge).

```
[
  { "primitive": "l", "orientation": 0, "spatial": [0] },
  { "primitive": "c", "orientation": 0, "spatial": [3] }
]
```

### Fields

| Field | Type | Description |
| --- | --- | --- |
| `primitive` | string | Base shape letter (`l` line, `q` square, `t` triangle, `c` circle, `v` vesica piscis, `p` point), plus an optional segment count, e.g. `c2` is a half circle. |
| `spatial` | number[] | `[innerSize, elementSize?, position?]`. The two sizes are psi exponents: each step divides the frame by the plastic number (1.3247). `innerSize` defaults to `0` (fills the box). `position` is an angle in degrees. |
| `orientation` | number | Rotation of the carve in degrees. |

A carve can also be a plain string: the alias of another icoglyph, embedded as a sub-glyph.

### Passing carves directly

Besides aliases, `<icoglyph-svg>` accepts carves directly. Via the DOM property, pass a JS object or array, no JSON serialization needed:

```
icon.use = { primitive: 'l', orientation: 0, spatial: [0] };
icon.use = [{ primitive: 'l', orientation: 0, spatial: [0] }, { primitive: 'c', orientation: 0, spatial: [0] }];
```

Or as a JSON string via the HTML attribute:

```
<icoglyph-svg use='[{"primitive":"l","spatial":[0],"orientation":0}]'></icoglyph-svg>
```

The easiest way to build carves by hand is the [Forge](https://icoglyphs.com/forge): compose primitives visually, then copy the JSON.

## API

### REST API

Icon data is served by a REST API at `https://api.icoglyphs.com`. All public routes are read-only GET endpoints with open CORS.

| Method | Endpoint | Description |
| --- | --- | --- |
| GET | `/v1/ig` | List all public icons (metadata only) |
| GET | `/v1/ig/aliases` | List all icon aliases |
| GET | `/v1/ig/:alias` | Full icon data by alias |
| GET | `/v1/ig/:alias/carves` | Carves data only |

**IcoGlyphs is in v0-alpha.** Endpoints may change between releases; the web component and the static SVG endpoint are the stable ways to consume icons.

## Links

- Website: https://icoglyphs.com
- Forge (open in-browser icoglyph editor, no account needed): https://icoglyphs.com/forge
- CDN: https://cdn.icoglyphs.com
- API: https://api.icoglyphs.com
- Custom Elements Manifest: https://cdn.icoglyphs.com/custom-elements.json
- Full documentation: https://icoglyphs.com/llms-full.txt

## Available icons

Each icon can have multiple aliases that currently display the same visual. Always pick the alias closest in meaning to your intent - aliases may diverge into distinct icons in the future. Use the chosen alias with `use="alias"` or as static SVG via `/svg/alias`.

- add
- allowed, permitted, granted, authorized (same visual today, pick the most relevant)
- arrow-down, arrow-bottom (same visual today, pick the most relevant)
- arrow-down-left, arrow-bottom-left (same visual today, pick the most relevant)
- arrow-down-right, arrow-bottom-right (same visual today, pick the most relevant)
- arrow-left
- arrow-right
- arrow-up, arrow-top, arrow (same visual today, pick the most relevant)
- arrow-up-left, arrow-top-left (same visual today, pick the most relevant)
- arrow-up-right, arrow-top-right (same visual today, pick the most relevant)
- back, go-back, previous, return, prev, undo (same visual today, pick the most relevant)
- center
- collapse, fold, retract (same visual today, pick the most relevant)
- conflict, clash (same visual today, pick the most relevant)
- copy
- dark-mode, dark (same visual today, pick the most relevant)
- delete
- denied, forbidden, blocked, unauthorized (same visual today, pick the most relevant)
- direction
- divide, split, frontier (same visual today, pick the most relevant)
- download, save, dl (same visual today, pick the most relevant)
- duality, dual, pair, two (same visual today, pick the most relevant)
- duplicate
- enter, entry (same visual today, pick the most relevant)
- exit, out, leave (same visual today, pick the most relevant)
- expand, unfold, dropdown, unwrap, menu (same visual today, pick the most relevant)
- eye
- forward, go-forward, next, ahead, proceed, redo (same visual today, pick the most relevant)
- fullscreen, enter-fullscreen (same visual today, pick the most relevant)
- grey-mode, dim (same visual today, pick the most relevant)
- group
- hide, eye-off, blind, mask (same visual today, pick the most relevant)
- join, call (same visual today, pick the most relevant)
- light-mode, light (same visual today, pick the most relevant)
- merge, union (same visual today, pick the most relevant)
- multiple, multi, plural, many (same visual today, pick the most relevant)
- no, minus, refuse (same visual today, pick the most relevant)
- off, shutdown, power-off (same visual today, pick the most relevant)
- oppression, dominance, intimidation (same visual today, pick the most relevant)
- over
- pause
- phi
- play
- plus
- psi
- random, randomize, shuffle, mix, chance, oracle (same visual today, pick the most relevant)
- rebellion, uprising (same visual today, pick the most relevant)
- refresh, reload, cycle, repeat, renew (same visual today, pick the most relevant)
- saved, stored, downloaded, copied (same visual today, pick the most relevant)
- scale-down, smaller (same visual today, pick the most relevant)
- scale-up, bigger, scale (same visual today, pick the most relevant)
- selected, select (same visual today, pick the most relevant)
- share
- under
- unique, single, unicity, one (same visual today, pick the most relevant)
- unselected, unselect, deselect (same visual today, pick the most relevant)
- warning
- wifi, signal, sensor (same visual today, pick the most relevant)
- yes, confirm, accept (same visual today, pick the most relevant)