03

Iconography

Font Awesome Sharp — solid Builder Component

BrainStorm uses Font Awesome Sharp Solid exclusively across the platform UI. Sharp is the squared, angular variant of FA Solid — it matches DM Sans's geometric character and reads clearly at small sizes in dense enterprise interfaces. The Free solid style is visually close and used in these demos; production requires FA Pro.

Why Sharp Solid

Brand alignment

Sharp's squared corners mirror DM Sans's geometric letterforms. Regular Solid icons have rounded terminations that read as softer — Sharp maintains consistent visual tension across type and icon.

Legibility at 12–16px

Rounded terminals blur at small sizes on non-retina screens. Sharp's flat endpoints fill the optical target more completely, improving recognition in table cells, chips, and nav items at 12–16px.

Practical consistency

A single icon style (Sharp Solid) eliminates per-engineer decisions about outline vs filled vs duotone. Solid icons are unambiguous about state; Sharp keeps the set visually unified.

Industry reference: Linear, Vercel, Raycast, and 1Password all use angular/sharp icon systems paired with geometric sans-serif type. The visual consistency between letterform and icon edge is well-documented in Nielsen Norman Group research on enterprise UI icon recognition.

Anti-patterns — never do

❌ Missing fa-sharp
<i class="fa-solid fa-bolt"> — silently renders the rounded Free Solid variant, not Sharp. Every icon must include both bsn-icon and fa-sharp fa-solid:
<i class="bsn-icon fa-sharp fa-solid fa-bolt fa-sm" style="color:var(--color-alpine);" aria-hidden="true"></i>
❌ Using fill instead of color
FA icons are font glyphs — they render via currentColor. fill has no effect. Always set style="color:var(--token);" or inherit from a parent element.
❌ Hardcoded hex colors on icons
style="color:#23403b" — never. Use CSS tokens: style="color:var(--color-alpine);". This keeps icons theme-able and auditable.
❌ Arbitrary inline font-size
style="font-size:13px" — use only the seven documented FA sizing classes. If a new size is genuinely needed, add it as a scale stop — don't scatter ad-hoc overrides through pages.

Icon sizes — mapped to spacing scale

Use FA sizing classes or explicit font-size. Always pair icon size with context — a 12px icon in a 13px body sentence, a 16px icon in a 44px button, a 24px icon in an empty state.

fa-xs 12px Chips · badges
fa-sm 14px Inline text
(default) 16px Buttons · inputs
fa-lg 20px Nav items
fa-xl 24px Feature icons
fa-2xl 32px Cards · headers
fa-3x 48px Empty states

Icon color — semantic usage

--color-alpine Default UI
--color-arches Warning
--color-wasatch Interactive
--color-uinta Success
--color-canyonlands Error
--color-salt On dark
--text-disabled Muted / inactive builder: "muted"
Rule: Always use color (not fill) for FA icons — they inherit via CSS currentColor. Never hard-code a hex value inline; always reference a CSS token or inherit from a parent with a semantic class.

3a — Navigation icons

fa-starPrioritized Learning
fa-heartFavorites
fa-clock-rotate-leftHistory
fa-chart-lineCustom Reports
fa-brainAI / Intelligence
fa-buildingAccount Admin
fa-usersUser Admin
fa-layer-groupContent Mgmt
fa-boltAutomations
fa-puzzle-pieceExtensions
fa-gearSettings
fa-circle-questionHelp
fa-robotAI Agent

3b — Action icons

fa-plusCreate / Add
fa-magnifying-glassSearch
fa-filterFilter
fa-slidersAdjust
fa-pen-to-squareEdit
fa-trashDelete
fa-cloneDuplicate
fa-downloadExport
fa-uploadImport
fa-arrow-up-right-from-squareExternal link
fa-ellipsis-verticalMore options
fa-xmarkClose / dismiss
fa-checkConfirm
fa-chevron-downExpand
fa-chevron-rightNavigate
fa-arrow-leftBack
fa-arrows-up-downSort
fa-listList view
fa-table-cells-largeGrid view
fa-share-nodesShare

3c — Status & feedback icons

fa-circle-checkSuccess
fa-circle-xmarkError
fa-triangle-exclamationWarning
fa-circle-infoInfo
fa-spinner fa-spinLoading
fa-circleStatus dot
fa-circle-half-strokePartial/inactive
fa-lockLocked/secure

3d — Content type icons

fa-diagram-projectFlows
fa-playVideo
fa-file-pdfPDF
fa-rectangle-listSurvey
fa-clipboard-checkAssessment
fa-envelopeEmail / Comm
fa-calendar-daysEvent
fa-linkExt. trigger

3e — Agentic UX icons BrainStorm AI

fa-wand-magicAI generate
fa-robotAgent (BrainStorm AI)
fa-messageChat
fa-boltQuick action
fa-clock-rotate-leftHistory
fa-quote-rightCitation
fa-brainIntelligence
fa-screwdriver-wrenchTool use

Placement rules

Leading positionIcon always left of label in buttons, nav items, chips, and list rows.
Text inputsLeading icon 12px from left edge (md/16px). Add padding-left:36px to prevent text overlap.
Status & feedbackStatus icons always lead their label. Trailing icons reserved for external-link only (fa-arrow-up-right-from-square).
No consecutive iconsNever two icons adjacent without a text label between them. Icon-only buttons need a title and aria-label.

Icon Component

The shared icon primitive. Every other component emits icons through bsnIcon so the Font Awesome Sharp Solid class chain stays consistent.

Mount point: <div class="bsn-icon-mount" data-bsn-icon='{…}'></div> — rendered via buildIcon(). Auto-generated from ssot/components/icon/.