Fonts & Icons - Ekanos SDK

Typography

Ekanos pairs Figtree (body) with Bricolage Grotesque (headings). This package only names them in --font-sans / --font-heading, followed by a system fallback stack; no webfont is bundled or fetched.

Load from Google Fonts

Add to your HTML <head>:

<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Figtree:wght@300..700&family=Bricolage+Grotesque:wght@200..800&display=swap"
/>

Load from your CDN

Host the font files yourself and define them in your CSS:

@font-face {
  font-family: 'Figtree';
  src: url('/fonts/Figtree-Regular.woff2') format('woff2');
  font-weight: 400;
}

@font-face {
  font-family: 'Bricolage Grotesque';
  src: url('/fonts/BricolageGrotesque-Regular.woff2') format('woff2');
  font-weight: 400;
}

Use system fonts

If you don’t load Figtree and Bricolage Grotesque, components still render in your platform’s UI font (the fallback stack includes ui-sans-serif, -apple-system, Segoe UI, Roboto, and system-ui).

Icons (Font Awesome)

Icon renders Font Awesome markup (<i class="fa-solid fa-house">). The package ships no icon font, because Ekanos uses Font Awesome Pro under a commercial licence, so you must supply one. name is a Font Awesome class string:

import { Icon } from '@ekanos/ui/icon';

<Icon name="fa-solid fa-house" />;

If you have Font Awesome Pro

Load your own Pro CSS (or kit) and every icon renders exactly as it does in Ekanos.

If you use Font Awesome Free

Install:

npm install @fortawesome/fontawesome-free

Load the stylesheet:

import '@fortawesome/fontawesome-free/css/all.min.css';
import { Icon } from '@ekanos/ui/icon';

<Icon name="fa-solid fa-house" />;

Override the style (Free has no fa-light or fa-duotone):
import { IconStyleOverrideProvider } from '@ekanos/ui/icon'; <IconStyleOverrideProvider value="solid"> <YourApp /> </IconStyleOverrideProvider>;
Free ships fa-solid, fa-regular, and fa-brands. Setting value="solid" rewrites every icon’s style class to fa-solid (brand icons are left alone). This matters because an unrecognised name falls back to fa-light fa-shapes, and Free has no fa-light family. Accepted values: solid, regular, light, duotone, or null.

Which icons are available in Free?

Free is missing many Pro glyphs. The package carries the list of names Font Awesome Free 7.3.1 ships, and in development Icon, resolveIcon, and renderIcon warn once per distinct name that is not in it (see Icon warnings below).

Fallback behavior

The package CSS draws two placeholders so a missing icon is visible rather than blank:

No Font Awesome CSS loaded: each icon renders a placeholder box (□). Set --ekanos-icon-fallback to change it, or --ekanos-icon-fallback: '' to switch it off.
Font Awesome loaded, glyph not in it (a Pro-only glyph under Free): the icon falls back to a question mark, --ekanos-icon-fa-fallback (default '\f059', fa-circle-question).

:root {
  --ekanos-icon-fallback: '\25a1'; /* default: □ */
  --ekanos-icon-fa-fallback: '\f059'; /* default: circle-question */
}

Icon sizing

Icons size by font-size, not width/height. Icon derives font-size from the first h-* / w-* / size-* class:

<Icon name="fa-solid fa-gear" className="h-4 w-4" />  {/* 16px */}
<Icon name="fa-solid fa-gear" className="size-5" />   {/* 20px */}
<Icon name="fa-solid fa-gear" className="h-6 w-8" />  {/* 24px (first token wins) */}
<Icon name="fa-solid fa-gear" />                      {/* 16px default */}

The size is computed in JS (1 unit = 4px), so it is right even on the no-Tailwind path where those utilities have no CSS rule.

Icon resolution

Use resolveIcon() and renderIcon() to work with icons programmatically:

import { resolveIcon, renderIcon } from '@ekanos/ui/icon';

// resolveIcon(name) returns a component that accepts { className, style }
const Star = resolveIcon('fa-solid fa-star');
<Star className="h-5 w-5" />;

// renderIcon(name, className?) returns an element, or null for an empty name
renderIcon('fa-regular fa-bell', 'h-4 w-4');

Both respect IconStyleOverrideProvider.

Icon warnings

In development, Icon, resolveIcon, and renderIcon console.warn once per distinct resolved value that Font Awesome Free does not ship:

[@ekanos/ui] icon "fa-solid fa-not-a-real-icon" resolves to "fa-solid fa-not-a-real-icon", which Font Awesome Free does not ship. Under a Free-only host (like the generated harness) this renders as the circle-question fallback, not the intended glyph. Verify the name against the Free set — run `pnpm --filter @ekanos/ui check:fa-free-names` — or add a Pro→Free shim (see the harness's styles.src.css) if the glyph matters.

The warning never changes what renders, and a Pro host is unaffected. When process.env.NODE_ENV is 'production', it is skipped.

Common icon names

These glyph names are in the package’s Font Awesome Free list:

Glyph	Name	Family
House	`house`	fa-solid
Gear	`gear`	fa-solid
Close	`xmark`	fa-solid
Chevron Down	`chevron-down`	fa-solid
Search	`magnifying-glass`	fa-solid
Check	`check`	fa-solid
Alert	`triangle-exclamation`	fa-solid
Info	`circle-info`	fa-solid
Error	`circle-xmark`	fa-solid
User	`user`	fa-solid
Lock	`lock`	fa-solid
Eye	`eye`	fa-solid

Troubleshooting

Icons render as placeholder box (□)

No Font Awesome CSS loaded. Load @fortawesome/fontawesome-free/css/all.min.css or your Font Awesome Pro kit.

Icons render as circle question mark (?)

Font Awesome is loaded, but the glyph isn’t in it (often a Pro-only glyph under Free). Check the spelling and the development console warning.

Fonts look like system defaults

Figtree and Bricolage Grotesque aren’t loading. Load them from Google Fonts or your CDN.

Some icons appear but others are boxes

You’re likely using Font Awesome Free with icons in a family it lacks (fa-light or fa-duotone). Wrap the tree in <IconStyleOverrideProvider value="solid"> to force a family Free has, or replace missing names with available ones.

​Typography

​Load from Google Fonts

​Load from your CDN

​Use system fonts

​Icons (Font Awesome)

​If you have Font Awesome Pro

​If you use Font Awesome Free

​Which icons are available in Free?

​Fallback behavior

​Icon sizing

​Icon resolution

​Icon warnings

​Common icon names

​Troubleshooting

​Icons render as placeholder box (□)

​Icons render as circle question mark (?)

​Fonts look like system defaults

​Some icons appear but others are boxes