# Font & Typography

This guide covers font packages, typography components, token system, and best practices.

***

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

The Akinon UI Kit uses a carefully selected typography system that includes:

* **Jost Variable** – A modern, geometric sans-serif variable font as the primary typeface
* **Typography Components** – React components for semantic text rendering
* **Token-based System** – Consistent styling through design tokens

***

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

#### @akinon/fonts-jost-variable

Jost is the primary font family used across all Akinon applications. We distribute it as a **variable font**, which means:

* Single file contains all weight variations (100-900)
* Smaller bundle size compared to multiple static font files
* Smooth weight transitions for animations
* Better performance and reduced HTTP requests

**Installation**

```bash
pnpm install @akinon/fonts-jost-variable
```

**Usage**

Import the font in your application's entry point:

```tsx
// Default import (includes normal weight axis)
import '@akinon/fonts-jost-variable';

// Or specify the axis explicitly
import '@akinon/fonts-jost-variable/wght.css';

// For italic style
import '@akinon/fonts-jost-variable/wght-italic.css';
```

**Font Specifications**

| Property    | Value                                       |
| ----------- | ------------------------------------------- |
| Font Family | `'Jost Variable'`                           |
| Weights     | 100, 200, 300, 400, 500, 600, 700, 800, 900 |
| Styles      | Normal, Italic                              |
| Subsets     | Latin, Latin Extended, Cyrillic             |
| Format      | WOFF2 (Variable)                            |
| License     | OFL-1.1 (Open Font License)                 |

**CSS Configuration**

Apply the font to your application:

```css
/* Global application */
*,
*::before,
*::after {
  font-family: 'Jost Variable', 'Jost', sans-serif;
}

/* Or target specific elements */
body {
  font-family: 'Jost Variable', 'Jost', sans-serif;
}
```

{% hint style="warning" %}
The Akinon UI Kit theme sets the font family automatically. However, for complete normalization including base font styles, you should use the `@akinon/ui-normalize` package which applies Akinon's standard CSS reset and base typography settings to your application.
{% endhint %}

***

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

The Akinon UI Kit provides semantic typography components built on Ant Design's Typography system.

#### Installation

```bash
pnpm install @akinon/ui-typography
```

#### Available Components

| Component   | HTML Element    | Purpose                  |
| ----------- | --------------- | ------------------------ |
| `Title`     | `<h1>` - `<h5>` | Headings and titles      |
| `Text`      | `<span>`        | Inline text with styling |
| `Paragraph` | `<p>`           | Block-level text content |
| `Link`      | `<a>`           | Hyperlinks with styling  |

***

#### Title Component

Use for headings and page titles. Supports levels 1-5 corresponding to `<h1>` - `<h5>`.

```tsx
import { Title } from '@akinon/ui-typography';

function PageHeader() {
  return (
    <>
      <Title level={1}>Page Title (H1)</Title>
      <Title level={2}>Section Title (H2)</Title>
      <Title level={3}>Subsection Title (H3)</Title>
      <Title level={4}>Card Title (H4)</Title>
      <Title level={5}>Small Title (H5)</Title>
    </>
  );
}
```

**Title Props**

| Prop        | Type                                                | Default | Description               |
| ----------- | --------------------------------------------------- | ------- | ------------------------- |
| `level`     | `1 \| 2 \| 3 \| 4 \| 5`                             | `1`     | Heading level (h1-h5)     |
| `copyable`  | `boolean \| CopyConfig`                             | `false` | Enable copy functionality |
| `delete`    | `boolean`                                           | `false` | Strike-through style      |
| `disabled`  | `boolean`                                           | `false` | Disabled state            |
| `editable`  | `boolean \| EditConfig`                             | `false` | Editable content          |
| `ellipsis`  | `boolean \| EllipsisConfig`                         | `false` | Truncate with ellipsis    |
| `mark`      | `boolean`                                           | `false` | Highlight text            |
| `underline` | `boolean`                                           | `false` | Underline style           |
| `type`      | `'secondary' \| 'success' \| 'warning' \| 'danger'` | -       | Text color type           |

***

#### Text Component

Use for inline text with various styling options.

```tsx
import { Text } from '@akinon/ui-typography';

function TextExamples() {
  return (
    <>
      <Text>Default text</Text>
      <Text type="secondary">Secondary text</Text>
      <Text type="success">Success text</Text>
      <Text type="warning">Warning text</Text>
      <Text type="danger">Danger text</Text>
      <Text strong>Bold text</Text>
      <Text italic>Italic text</Text>
      <Text underline>Underlined text</Text>
      <Text delete>Strikethrough text</Text>
      <Text code>Code text</Text>
      <Text keyboard>Keyboard text</Text>
      <Text mark>Highlighted text</Text>
    </>
  );
}
```

**Text Props**

| Prop        | Type                                                | Default | Description               |
| ----------- | --------------------------------------------------- | ------- | ------------------------- |
| `code`      | `boolean`                                           | `false` | Code style (monospace)    |
| `copyable`  | `boolean \| CopyConfig`                             | `false` | Enable copy functionality |
| `delete`    | `boolean`                                           | `false` | Strike-through style      |
| `disabled`  | `boolean`                                           | `false` | Disabled state            |
| `editable`  | `boolean \| EditConfig`                             | `false` | Editable content          |
| `ellipsis`  | `boolean \| EllipsisConfig`                         | `false` | Truncate with ellipsis    |
| `italic`    | `boolean`                                           | `false` | Italic style              |
| `keyboard`  | `boolean`                                           | `false` | Keyboard key style        |
| `mark`      | `boolean`                                           | `false` | Highlight text            |
| `strong`    | `boolean`                                           | `false` | Bold text                 |
| `underline` | `boolean`                                           | `false` | Underline style           |
| `type`      | `'secondary' \| 'success' \| 'warning' \| 'danger'` | -       | Text color type           |

***

#### Paragraph Component

Use for block-level text content with multi-line support.

```tsx
import { Paragraph } from '@akinon/ui-typography';

function ContentBlock() {
  return (
    <Paragraph>
      This is a paragraph component that supports multiple lines of text.
      It automatically handles line breaks and provides proper spacing
      between paragraphs.
    </Paragraph>
  );
}
```

**Paragraph with Ellipsis**

```tsx
import { Paragraph } from '@akinon/ui-typography';

function TruncatedContent() {
  return (
    <Paragraph
      ellipsis={{
        rows: 3,
        expandable: true,
        symbol: 'Read more'
      }}
    >
      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do
      eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
      ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
      aliquip ex ea commodo consequat.
    </Paragraph>
  );
}
```

***

#### Link Component

Use for hyperlinks with consistent styling.

```tsx
import { Link } from '@akinon/ui-typography';

function NavigationLinks() {
  return (
    <>
      <Link href="/dashboard">Dashboard</Link>
      <Link href="/settings" target="_blank">
        Settings (opens in new tab)
      </Link>
      <Link href="/help" disabled>
        Disabled Link
      </Link>
    </>
  );
}
```

**Link Props**

| Prop       | Type                                                | Default | Description                           |
| ---------- | --------------------------------------------------- | ------- | ------------------------------------- |
| `href`     | `string`                                            | -       | Link URL                              |
| `target`   | `string`                                            | -       | Link target (`_blank`, `_self`, etc.) |
| `disabled` | `boolean`                                           | `false` | Disabled state                        |
| `ellipsis` | `boolean`                                           | `false` | Truncate with ellipsis                |
| `type`     | `'secondary' \| 'success' \| 'warning' \| 'danger'` | -       | Link color type                       |

***

### <mark style="color:red;">Using Typography with Theme Provider</mark>

To ensure typography tokens are applied correctly, wrap your application with `AkinonUiProvider`:

```tsx
import { AkinonUiProvider } from '@akinon/ui-system';
import '@akinon/fonts-jost-variable';

function App() {
  return (
    <AkinonUiProvider>
      <YourApplication />
    </AkinonUiProvider>
  );
}
```

#### Custom Font Family Override

You can override the default font family through the provider:

```tsx
import { AkinonUiProvider } from '@akinon/ui-system';

function App() {
  return (
    <AkinonUiProvider fontFamily="'Custom Font', 'Fallback Font', sans-serif">
      <YourApplication />
    </AkinonUiProvider>
  );
}
```

***

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

#### 1. Use Semantic Components

Always use the appropriate typography component for the content:

```tsx
// ✅ Good - semantic usage
<Title level={1}>Page Title</Title>
<Paragraph>Body content goes here.</Paragraph>
<Text type="secondary">Helper text</Text>

// ❌ Avoid - inline styles or custom CSS
<span style={{ fontSize: '24px', fontWeight: 'bold' }}>Page Title</span>
```

#### 2. Maintain Heading Hierarchy

Follow proper heading order for accessibility:

```tsx
// ✅ Good - proper hierarchy
<Title level={1}>Main Title</Title>
<Title level={2}>Section</Title>
<Title level={3}>Subsection</Title>

// ❌ Avoid - skipping levels
<Title level={1}>Main Title</Title>
<Title level={4}>Subsection</Title>
```

#### 3. Use Type Variants for Context

Leverage type variants to communicate meaning:

```tsx
<Text type="success">Operation completed</Text>
<Text type="warning">Please review before submitting</Text>
<Text type="danger">Error: Invalid input</Text>
<Text type="secondary">Optional field</Text>
```

#### 4. Handle Long Text with Ellipsis

Use ellipsis for potentially long content:

```tsx
<Paragraph ellipsis={{ rows: 2 }}>
  Long content that might overflow...
</Paragraph>

<Text ellipsis>
  Long inline text that might overflow
</Text>
```

#### 5. Use Utility Classes Instead of Custom CSS

The Akinon UI Kit is designed to be **non-themable** to ensure consistency across all applications. Instead of writing custom CSS:

```tsx
// ✅ Good - use utility classes for layout adjustments
<Text className="text-center mt-4">Centered text with margin</Text>

// ❌ Avoid - custom CSS overrides
<Text style={{ textAlign: 'center', marginTop: '16px' }}>...</Text>
```

For available utility classes, see the Utility Classes documentation.

#### 6. Consider Internationalization

The Jost Variable font includes Cyrillic and Latin Extended subsets:

```tsx
// Font automatically loads appropriate subset based on content
<Text>English content</Text>
<Text>Русский текст</Text>
<Text>Türkçe içerik</Text>
```

***

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

#### Font Not Loading

1. Verify the font package is installed:

   ```bash
   pnpm list @akinon/fonts-jost-variable
   ```
2. Check the import statement in your entry file:

   ```tsx
   import '@akinon/fonts-jost-variable';
   ```
3. Inspect browser network tab for WOFF2 file requests

#### Typography Components Not Styled

Ensure `AkinonUiProvider` wraps your application:

```tsx
import { AkinonUiProvider } from '@akinon/ui-system';

function App() {
  return (
    <AkinonUiProvider>
      {/* Typography components will be styled correctly */}
    </AkinonUiProvider>
  );
}
```

***

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

* [Iconography](/akinon-ui/ui-kit/design-system/iconography.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/font-and-typography.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.