> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.ekanos.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Fonts & Icons

> Set up typography and Font Awesome for your integration.

## 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>`:

```html theme={null}
<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:

```css theme={null}
@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:

```tsx theme={null}
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

1. **Install:**

   ```bash theme={null}
   npm install @fortawesome/fontawesome-free
   ```

2. **Load the stylesheet:**

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

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

3. **Override the style** (Free has no `fa-light` or `fa-duotone`):

   ```tsx theme={null}
   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](#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`).

```css theme={null}
: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:

```tsx theme={null}
<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:

```tsx theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.