Icons

Summary

Neura ships with 53 glyphs, sourced primarily from Lucide (ISC licensed), rendered via mask-image + currentColor. Icons inherit the parent's text color, so coloring and theming work the same as text. Two sizes: default 16px and large 32px via .neura-icon-large.

When to use

Pattern	Use it for
Inline with text	Buttons, menu items, message banners. The icon picks up the surrounding text color.
Icon-only button	Toolbar actions. Pair with `aria-label` on the button so screen readers know the action.
Decorative	Visual hint that doesn't add information. Hide from assistive tech: it's a span with no text.

Available icons

All 53 glyphs at large size. Each icon picks up currentColor from its parent: change the page text color and they all theme together.

HTML

An inline icon picks up currentColor:

<span class="neura-icon neura-icon-settings"></span>

Text inside the span is visually hidden but stays readable by screen readers; use it as a fallback label when the icon carries meaning:

<span class="neura-icon neura-icon-mail">Email</span>

Inside a button, the icon takes the button's text color:

<button class="neura-button">
  <span class="neura-icon neura-icon-plus"></span>
  Add item
</button>

Icon-only (always include aria-label):

<button class="neura-button neura-button-subtle" aria-label="Edit">
  <span class="neura-icon neura-icon-pencil"></span>
</button>

Larger size:

<span class="neura-icon neura-icon-large neura-icon-bell"></span>

CSS classes

Class	Effect
`.neura-icon`	Base icon (16×16). Required.
`.neura-icon-large`	32×32 size variant.
`.neura-icon-{name}`	The specific glyph. See the grid above for the full list.
`.neura-icon-small`	Explicit 16×16, identical to the base size. Exists so markup (and the `aui-icon-small` alias) can state the size explicitly.

JavaScript

None: icons are CSS-only. Color comes from currentColor, so styling is just a matter of setting color on the parent.

Adding a new icon

Icons are listed in src/icons/icons.config.mjs with their Lucide source name. The build script (scripts/build-icons.mjs, run automatically by npm run dev and npm run build) reads this config, generates the SVG mask URLs, and writes src/css/_icons.generated.scss.

// src/icons/icons.config.mjs
export default [
  { name: 'apps',      source: 'lucide', from: 'grid-3x3' },
  { name: 'settings',  source: 'lucide', from: 'settings' },
  // add your new icon here:
  { name: 'heart',     source: 'lucide', from: 'heart' },
];

Then npm run icons:build regenerates the CSS, and you can use .neura-icon-heart.

Entries can also override Lucide's stroke weight (strokeWidth: 3.1; the close glyph does this to match AUI's bolder X) or embed a hand-drawn glyph with source: 'inline' and an svg string (see settings-solid).

Consuming apps don't need the build script at all - each glyph class only sets the --neura-icon-mask custom property, so a one-off icon is plain CSS:

.icon-heart { --neura-icon-mask: url("data:image/svg+xml,…"); }

<span class="neura-icon icon-heart"></span>

AUI compatibility

AUI's icon font (.aui-iconfont-*) is replaced by Neura's mask-image set. The shim aliases the most common .aui-icon-* names onto Neura icons - see src/shim/_aui-classes.scss for the mapping. Branded glyphs from AUI's font that don't exist in Neura render as a transparent box; consult the audit list before relying on a specific old name.