# Iconography

This guide covers the `@akinon/icons` package and best practices for using icons in your application.

***

### <mark style="color:red;">Overview</mark>

The Akinon UI Kit provides a comprehensive icon system through the `@akinon/icons` package:

* **React Components** – SVG-based icons as React components for optimal performance
* **Type Safety** – Full TypeScript support with autocomplete for icon names
* **Customizable** – Size, color, and style can be adjusted through props
* **Accessible** – Support for titles and ARIA attributes
* **Tree-shakeable** – Only the icons you use are included in your bundle

***

### <mark style="color:red;">Installation</mark>

Install the icons package:

```bash
pnpm install @akinon/icons
```

***

### <mark style="color:red;">Basic Usage</mark>

Import the `Icon` component and use it with the `icon` prop:

```tsx
import { Icon } from '@akinon/icons';

function MyComponent() {
  return (
    <div>
      <Icon icon="search" />
      <Icon icon="settings" />
      <Icon icon="notification" />
    </div>
  );
}
```

***

### <mark style="color:red;">Icon Component</mark>

The `Icon` component is the primary way to render icons. It accepts various props for customization.

#### Props

| Prop                | Type                    | Default          | Description                                        |
| ------------------- | ----------------------- | ---------------- | -------------------------------------------------- |
| `icon`              | `IconName`              | -                | **Required.** Name of the icon to render.          |
| `size`              | `number \| string`      | `24`             | Size of the icon in pixels or CSS value.           |
| `color`             | `string`                | `'currentColor'` | Color of the icon. Inherits text color by default. |
| `title`             | `string`                | -                | Accessible title for screen readers.               |
| `disableFill`       | `boolean`               | `false`          | Disables the fill color of the icon.               |
| `removeInlineStyle` | `boolean`               | `false`          | Removes all inline styles from the SVG.            |
| `style`             | `CSSProperties`         | -                | Additional inline styles.                          |
| `SvgComponent`      | `JSXElementConstructor` | -                | Custom component to replace `<svg>` element.       |
| `PathComponent`     | `JSXElementConstructor` | -                | Custom component to replace `<path>` elements.     |

The component also accepts all standard SVG element props.

***

### <mark style="color:red;">Examples</mark>

#### Size Variations

```tsx
import { Icon } from '@akinon/icons';

function SizeExamples() {
  return (
    <>
      {/* Numeric size (pixels) */}
      <Icon icon="search" size={16} />
      <Icon icon="search" size={24} />
      <Icon icon="search" size={32} />
      <Icon icon="search" size={48} />

      {/* String size (CSS values) */}
      <Icon icon="search" size="2rem" />
      <Icon icon="search" size="100%" />
    </>
  );
}
```

#### Color Customization

```tsx
import { Icon } from '@akinon/icons';

function ColorExamples() {
  return (
    <>
      {/* Inherits current text color (default) */}
      <span style={{ color: 'blue' }}>
        <Icon icon="info" />
      </span>

      {/* Explicit color */}
      <Icon icon="warning" color="#ff9800" />
      <Icon icon="onay" color="green" />
      <Icon icon="close" color="red" />

      {/* Using theme colors */}
      <Icon icon="notification" color="var(--color-azure-500)" />
    </>
  );
}
```

#### Accessibility

Always provide accessible labels for icons that convey meaning:

```tsx
import { Icon } from '@akinon/icons';
import { Button } from '@akinon/ui-button';

function AccessibleIcons() {
  return (
    <>
      {/* Button with icon and text - text provides context */}
      <Button icon="search">Search</Button>

      {/* Icon-only button with tooltip for accessibility */}
      <Button type="icon" icon="search" tooltip="Search" />

      {/* Status icons should have titles */}
      <Icon icon="warning" title="Warning: Action required" color="orange" />
      <Icon icon="onay" title="Success" color="green" />
    </>
  );
}
```

#### Icon with Button

Use the `Button` component with the `icon` prop for buttons with icons:

```tsx
import { Button } from '@akinon/ui-button';

function IconWithButton() {
  return (
    <>
      {/* Button with icon and text */}
      <Button icon="download">Download Report</Button>

      {/* Icon position can be changed */}
      <Button icon="arrow_down" iconPosition="end">Export</Button>

      {/* Icon-only button */}
      <Button type="icon" icon="settings" tooltip="Settings" />
    </>
  );
}
```

***

### <mark style="color:red;">Available Icons</mark>

The `@akinon/icons` package includes over 100 icons for various use cases including navigation, actions, status indicators, e-commerce, communication, and more.

To browse all available icons with live previews and copy functionality, visit the [**Storybook Icon Gallery**](https://4e1ca350ada947d18edc04e64d784137.lb.akinoncloud.com/?path=/docs/primitive-icon--docs).

You can also retrieve the icon list programmatically:

```tsx
import { getIconList } from '@akinon/icons';

const allIcons = getIconList();
// ['acilissayfalari', 'add_picture', 'add_video', 'ai-star', ...]
```

***

### <mark style="color:red;">TypeScript Support</mark>

The `icon` prop is fully typed with autocomplete support:

```tsx
import { Icon, type IconName } from '@akinon/icons';
import { Button } from '@akinon/ui-button';

// TypeScript will provide autocomplete for icon names
<Icon icon="search" />

// Type for icon names
const myIcon: IconName = 'dashboard';

// Using Button with icon prop (recommended)
<Button icon="download">Download</Button>
<Button type="icon" icon="settings" tooltip="Settings" />

// Using IconName type in custom components
import type { IconName } from '@akinon/icons';

interface CustomProps {
  iconName: IconName;
}
```

***

### <mark style="color:red;">Best Practices</mark>

#### 1. Use Semantic Icons

Choose icons that clearly represent their action or meaning:

```tsx
// ✅ Good - clear meaning
<Icon icon="bin" title="Delete item" />
<Icon icon="edit" title="Edit" />
<Icon icon="download" title="Download" />

// ❌ Avoid - unclear meaning without context
<Icon icon="arti" /> {/* What does this do? */}
```

#### 2. Use Button Component for Interactive Icons

Always use the `Button` component for interactive icons:

```tsx
import { Button } from '@akinon/ui-button';

// ✅ Good - Button with icon and text
<Button icon="download">Download</Button>

// ✅ Good - Icon-only button with tooltip
<Button type="icon" icon="bin" tooltip="Delete item" danger />

// ✅ Good - standalone Icon for status indicators
<Icon icon="onay" title="Success" color="green" />
```

#### 3. Maintain Consistent Sizing

Use consistent icon sizes throughout your application:

```tsx
// ✅ Good - consistent sizes
const ICON_SIZES = {
  small: 16,
  medium: 24,
  large: 32,
};

<Icon icon="search" size={ICON_SIZES.medium} />
<Icon icon="settings" size={ICON_SIZES.medium} />
```

#### 4. Leverage Color Inheritance

Let icons inherit text color when appropriate:

```tsx
// ✅ Good - inherits parent color
<span className="text-azure-500">
  <Icon icon="info" />
  Information message
</span>

// ✅ Good - explicit color for emphasis
<Icon icon="warning" color="var(--color-orange-500)" />
```

#### 5. Use Utility Classes for Layout

Position icons using utility classes, not inline styles:

```tsx
// ✅ Good - utility classes
<div className="flex items-center gap-2">
  <Icon icon="notification" />
  <span>Notifications</span>
</div>

// ❌ Avoid - inline styles
<div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
  <Icon icon="notification" />
  <span>Notifications</span>
</div>
```

***

### <mark style="color:red;">Troubleshooting</mark>

#### Icon Not Rendering

1. Verify the icon name exists:

   ```tsx
   import { getIconList } from '@akinon/icons';
   console.log(getIconList().includes('my-icon')); // Should be true
   ```
2. Check for typos in the icon name (TypeScript will help catch these)
3. Ensure the package is installed:

   ```bash
   pnpm list @akinon/icons
   ```

#### Icon Color Not Changing

The `color` prop might be overridden. Check:

1. Parent element styles
2. CSS specificity issues
3. Use `removeInlineStyle` prop and apply color via CSS class if needed

#### Icon Size Issues

```tsx
// For pixel-perfect sizing, use numbers
<Icon icon="search" size={24} />

// For responsive sizing, use CSS units
<Icon icon="search" size="1.5rem" />
```

***

### <mark style="color:red;">Related Documentation</mark>

* [Typography](/akinon-ui/ui-kit/design-system/font-and-typography.md)
* [Utility Classes](/akinon-ui/ui-kit/design-system/utility-classes.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.akinon.com/akinon-ui/ui-kit/design-system/iconography.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.