Claude Skill

bestax-icons

Use icons in an app built with @allxsmith/bestax-bulma — the Icon/IconText components and the five supported libraries (Font Awesome, Material Design Icons, Ionicons, Google Material Icons, Material Symbols). Use when adding an icon, choosing or configuring the app-wide icon libr

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download allxsmith-bestax-skills_bestax-icons-8fda6de.zip · 8 KB

Install

skills CLI npx skills add https://github.com/allxsmith/bestax/tree/main/skills/bestax-icons
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install allxsmith-bestax@llmmart
Git git clone https://github.com/allxsmith/bestax.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole allxsmith/bestax collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Icons with @allxsmith/bestax-bulma

Icon renders a Bulma icon container (span.icon) around a glyph from any of five icon libraries behind one normalized API. IconText pairs icons with text. The library ships no icon fonts — the chosen library's package (or CDN script) must be installed in the app.

Quick start

import { ConfigProvider, Icon, IconText } from '@allxsmith/bestax-bulma';

// Set the library ONCE at the app root; <Icon> then never needs `library`.
<ConfigProvider iconLibrary="fa">
  <App />
</ConfigProvider>;

// Inside the app:
<Icon name="rocket" ariaLabel="Launch" />;
<IconText iconProps={{ name: 'star', 'aria-hidden': 'true' }}>
  Starred
</IconText>;

The five libraries

Library iconLibrary / library value Name format Example name
Font Awesome (default) 'fa' kebab-case, no fa- prefix rocket
Material Design Icons 'mdi' kebab-case, no mdi- prefix rocket-launch
Ionicons 'ion' kebab-case rocket
Google Material Icons 'material-icons' snake_case (a text ligature) rocket_launch
Material Symbols 'material-symbols' snake_case (a text ligature) rocket_launch

⚠️ The Ionicons value is 'ion', not 'ionicons'. The npm create bestax scaffold's --icon ionicons flag maps to iconLibrary="ion" — passing 'ionicons' to ConfigProvider or library silently renders nothing.

The same glyph has a different name per library (rocket vs rocket-launch vs rocket_launch). When an icon renders blank, the name format for the active library is the first thing to check. A redundant fa-/mdi- prefix in name is tolerated (stripped), but don't rely on it.

Material Symbols' font is several megabytes however few icons the app shows. Keep the default material-symbols/outlined.css import. When the user cares about download size, offer a smaller font as an optimisation (a Google Fonts icon_names subset, a self-hosted subset, or a single-weight package): references/icon-libraries.md has each one and its trade-offs.

Styling

  • size — 'small' | 'medium' | 'large' sizes the Bulma container (is-small ≈ 1rem, is-medium ≈ 2rem, is-large ≈ 3rem box). To scale the glyph, use features (Font Awesome 'fa-lg'/'fa-2x') or a Bulma text-size class ('is-size-3').
  • variant — per-library style: Font Awesome solid (default) / regular / brands / light / duotone / thin; Material Icons filled (default) / outlined / round / sharp; Material Symbols outlined (default) / rounded / sharp; Ionicons outline / sharp. MDI has no variants. Note Material Icons uses round, Material Symbols uses rounded.
  • features — extra library classes, string or array: 'fa-spin', ['fa-lg', 'fa-border'].
  • Color via the helper props: textColor="primary", textColor="danger", etc.

Custom node (SVG, react-icons, FontAwesome React)

Icon also accepts children instead of name — an inline SVG, a react-icons component, a Font Awesome React <FontAwesomeIcon>, … — rendered in place of a class-based glyph. name and children are mutually exclusive (the type rejects passing both, or neither). size, textColor, bgColor, ariaLabel and containerClassName behave identically; library, variant, features and libraryFeatures are ignored since there's no class-based glyph to style.

<Icon ariaLabel="Custom icon">
  <MyReactIconsComponent />
</Icon>

IconText's iconProps / items[].iconProps and Control's iconLeft/iconRight accept the same escape hatch — pass a node directly (instead of an IconProps object) and it is wrapped in an Icon for you: <IconText iconProps={<MySvg />}>Starred</IconText>.

Panel.Icon takes the same children, but its container is panel-icon rather than icon — it always overrides containerClassName, so style and query that class instead.

⚠️ children excludes undefined. Write a conditional icon as cond ? <MySvg /> : null (or cond && <MySvg />), never cond ? <MySvg /> : undefined — the latter is a type error, because the renderer would fall through to the name path with no name. In the IconText and Control slots a falsy node counts as "no icon": nothing is rendered, and Control falls back to iconLeftName/iconRightName if one is given, otherwise leaving the icon column unreserved.

Accessibility

An Icon is decorative unless it is named: with no ariaLabel it renders aria-hidden="true" and no name. Name it with its camelCase ariaLabel prop, and it renders role="img" with that aria-label. Only a few components declare that prop (Icon, Delete, Slider, Carousel): everything else takes the standard aria-label attribute, e.g. <Navbar.Burger aria-label="menu" />.

  • Meaningful icon (stands alone, conveys information): pass a descriptive ariaLabel="Delete item".
  • Decorative icon (next to visible text that says the same thing, e.g. inside IconText or a labeled Button): leave ariaLabel off, and the icon stays out of the accessible name. An explicit aria-hidden="true", as in the examples here, says the same thing.
  • Icon-only button: use IconButton, whose types require the name: <IconButton icon="trash" aria-label="Delete item" />. Name the action, not the picture, and leave the icon unnamed. Any other icon-only control takes the name the same way, on the control (<Navbar.Burger aria-label="menu" />), not on the icon.

References

  • references/icon-libraries.md — per-library setup (install/import/CDN), the full name-format and variant tables, features values, making the Material Symbols font smaller, and the blank-icon troubleshooting list.
  • examples/icon-usage.tsx — runnable example: ConfigProvider setup, sizes, variants, colors, IconText, and decorative-vs-labeled patterns.
Files (bestax)
  • examples
    • icon-usage.tsx 2.7 KB · in bundle
  • references
    • icon-libraries.md 10 KB
      Loading…
  • SKILL.md 6.6 KB
    ---
    name: bestax-icons
    description: Use icons in an app built with @allxsmith/bestax-bulma — the Icon/IconText components and the five supported libraries (Font Awesome, Material Design Icons, Ionicons, Google Material Icons, Material Symbols). Use when adding an icon, choosing or configuring the app-wide icon library, fixing an icon that renders blank, pairing icons with text, or making icons accessible (decorative vs labeled).
    license: MIT
    ---
    
    # Icons with @allxsmith/bestax-bulma
    
    `Icon` renders a Bulma icon container (`span.icon`) around a glyph from any of five icon
    libraries behind one normalized API. `IconText` pairs icons with text. The library ships **no
    icon fonts** — the chosen library's package (or CDN script) must be installed in the app.
    
    ## Quick start
    
    ```tsx
    import { ConfigProvider, Icon, IconText } from '@allxsmith/bestax-bulma';
    
    // Set the library ONCE at the app root; <Icon> then never needs `library`.
    <ConfigProvider iconLibrary="fa">
      <App />
    </ConfigProvider>;
    
    // Inside the app:
    <Icon name="rocket" ariaLabel="Launch" />;
    <IconText iconProps={{ name: 'star', 'aria-hidden': 'true' }}>
      Starred
    </IconText>;
    ```
    
    ## The five libraries
    
    | Library                | `iconLibrary` / `library` value | Name format                  | Example `name`  |
    | ---------------------- | ------------------------------- | ---------------------------- | --------------- |
    | Font Awesome (default) | `'fa'`                          | kebab-case, no `fa-` prefix  | `rocket`        |
    | Material Design Icons  | `'mdi'`                         | kebab-case, no `mdi-` prefix | `rocket-launch` |
    | Ionicons               | `'ion'`                         | kebab-case                   | `rocket`        |
    | Google Material Icons  | `'material-icons'`              | snake_case (a text ligature) | `rocket_launch` |
    | Material Symbols       | `'material-symbols'`            | snake_case (a text ligature) | `rocket_launch` |
    
    ⚠️ **The Ionicons value is `'ion'`, not `'ionicons'`.** The `npm create bestax` scaffold's
    `--icon ionicons` flag maps to `iconLibrary="ion"` — passing `'ionicons'` to `ConfigProvider`
    or `library` silently renders nothing.
    
    **The same glyph has a different name per library** (`rocket` vs `rocket-launch` vs
    `rocket_launch`). When an icon renders blank, the name format for the active library is the
    first thing to check. A redundant `fa-`/`mdi-` prefix in `name` is tolerated (stripped), but
    don't rely on it.
    
    **Material Symbols' font is several megabytes however few icons the app shows.** Keep the
    default `material-symbols/outlined.css` import. When the user cares about download size,
    offer a smaller font as an optimisation (a Google Fonts `icon_names` subset, a self-hosted
    subset, or a single-weight package): `references/icon-libraries.md` has each one and its
    trade-offs.
    
    ## Styling
    
    - `size` — `'small' | 'medium' | 'large'` sizes the Bulma **container** (`is-small` ≈ 1rem,
      `is-medium` ≈ 2rem, `is-large` ≈ 3rem box). To scale the **glyph**, use `features`
      (Font Awesome `'fa-lg'`/`'fa-2x'`) or a Bulma text-size class (`'is-size-3'`).
    - `variant` — per-library style: Font Awesome `solid` (default) / `regular` / `brands` /
      `light` / `duotone` / `thin`; Material Icons `filled` (default) / `outlined` / `round` /
      `sharp`; Material Symbols `outlined` (default) / `rounded` / `sharp`; Ionicons `outline` /
      `sharp`. MDI has no variants. Note Material **Icons** uses `round`, Material **Symbols**
      uses `rounded`.
    - `features` — extra library classes, string or array: `'fa-spin'`, `['fa-lg', 'fa-border']`.
    - Color via the helper props: `textColor="primary"`, `textColor="danger"`, etc.
    
    ## Custom node (SVG, react-icons, FontAwesome React)
    
    `Icon` also accepts `children` instead of `name` — an inline SVG, a `react-icons` component, a
    Font Awesome React `<FontAwesomeIcon>`, … — rendered in place of a class-based glyph. `name`
    and `children` are mutually exclusive (the type rejects passing both, or neither). `size`,
    `textColor`, `bgColor`, `ariaLabel` and `containerClassName` behave identically; `library`,
    `variant`, `features` and `libraryFeatures` are ignored since there's no class-based glyph to
    style.
    
    ```tsx
    <Icon ariaLabel="Custom icon">
      <MyReactIconsComponent />
    </Icon>
    ```
    
    `IconText`'s `iconProps` / `items[].iconProps` and `Control`'s `iconLeft`/`iconRight` accept
    the same escape hatch — pass a node directly (instead of an `IconProps` object) and it is
    wrapped in an `Icon` for you: `<IconText iconProps={<MySvg />}>Starred</IconText>`.
    
    `Panel.Icon` takes the same `children`, but its container is `panel-icon` rather than `icon` —
    it always overrides `containerClassName`, so style and query that class instead.
    
    ⚠️ **`children` excludes `undefined`.** Write a conditional icon as `cond ? <MySvg /> : null`
    (or `cond && <MySvg />`), never `cond ? <MySvg /> : undefined` — the latter is a type error,
    because the renderer would fall through to the `name` path with no name. In the `IconText` and
    `Control` slots a falsy node counts as "no icon": nothing is rendered, and `Control` falls back
    to `iconLeftName`/`iconRightName` if one is given, otherwise leaving the icon column unreserved.
    
    ## Accessibility
    
    An `Icon` is decorative unless it is named: with no `ariaLabel` it renders `aria-hidden="true"`
    and no name. Name it with its camelCase `ariaLabel` prop, and it renders `role="img"` with that
    `aria-label`. Only a few components declare that prop (`Icon`, `Delete`, `Slider`, `Carousel`):
    everything else takes the standard `aria-label` attribute, e.g.
    `<Navbar.Burger aria-label="menu" />`.
    
    - **Meaningful icon** (stands alone, conveys information): pass a descriptive
      `ariaLabel="Delete item"`.
    - **Decorative icon** (next to visible text that says the same thing, e.g. inside `IconText`
      or a labeled `Button`): leave `ariaLabel` off, and the icon stays out of the accessible
      name. An explicit `aria-hidden="true"`, as in the examples here, says the same thing.
    - **Icon-only button:** use `IconButton`, whose types require the name:
      `<IconButton icon="trash" aria-label="Delete item" />`. Name the action, not the picture, and
      leave the icon unnamed. Any other icon-only control takes the name the same way, on the control
      (`<Navbar.Burger aria-label="menu" />`), not on the icon.
    
    ## References
    
    - `references/icon-libraries.md` — per-library setup (install/import/CDN), the full
      name-format and variant tables, `features` values, making the Material Symbols font
      smaller, and the blank-icon troubleshooting list.
    - `examples/icon-usage.tsx` — runnable example: ConfigProvider setup, sizes, variants,
      colors, IconText, and decorative-vs-labeled patterns.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.