Choose recognizable glyphs, pair them with clear labels, and use the installed Icon primitive deliberately.
Icons help people recognize actions and scan related information. Use a familiar symbol when it adds meaning; retain text when the symbol could be ambiguous. Keep equivalent actions visually consistent across the interface.
Liquidify exports Icon, IconName, and ICON_NAMES from @liquidify/react. ICON_NAMES enumerates the installed registry; IconName describes its registered names. The primitive is exported even though there is no dedicated Icon page in the current component catalog.
The registry is not Apple's SF Symbols library. A familiar symbol name does not imply that every SF Symbol is available. The shipped Icon API does not expose SF Symbols rendering modes, weight interpolation, or symbol animations.
Figure in preparation
Icons and accessible names
Compare a labelled action, an icon-only action, and a meaningful standalone icon.
Use a visible label when an action needs explanation. In this example, the icon is decorative and the button's text supplies its name.
import { Button, Icon } from "@liquidify/react"
import "@liquidify/react/styles.css"
export function SearchRecords({ onSearch }: { onSearch: () => void }) {
return (
<Button leadingIcon={<Icon name="search" />} onPress={onSearch}>
Search records
</Button>
)
}An Icon without aria-label or aria-labelledby is hidden from assistive technology by default. Supplying either makes a standalone Icon meaningful and gives it the default img role. For an icon-only button, name the button itself with aria-label and keep the glyph decorative. A tooltip can supplement the action but should not be its only accessible name.
Use the supported Icon size values when an explicit size is needed. The installed CSS maps mini, small, regular, large, and xlarge to --lq-space-12, --lq-space-16, --lq-space-20, --lq-space-24, and --lq-space-32 respectively. Without an explicit size, the base glyph is --lq-space-20; surrounding component styles may adjust it.
These dimensions describe the glyph, not its interactive target. Let the containing control provide its supported geometry, focus indication, and hit area. Review optical balance with adjacent text as well as geometric alignment.
For an unregistered symbol, use Icon's glyph prop with SVG inner content. Its viewBox is 0 0 24 24. Do not nest a complete SVG document or combine glyph with a registered name. Use application-owned CSS classes and deliberate fill or stroke values such as currentColor for custom paths.
The runtime has a placeholder fallback for invalid names from untyped callers. Treat that fallback as a defect to resolve, not as a supported symbol. Maintain the same level of detail and stroke weight when mixing registered and custom glyphs.
Check small icons against their actual surface in both themes. Use a supported tint when color adds meaning, and pair status color with text. Confirm that custom artwork remains visible when the surrounding color changes.
Direction, culture, and context can change how an icon is understood. Review those cases explicitly; the primitive does not automatically translate a custom symbol or mirror all directional artwork.
Use the Button catalog for icon slots and action semantics. Pictograms covers larger explanatory artwork, and Accessibility covers naming and task verification.