# Utility Classes

These classes enable quick and consistent styling without writing custom CSS.

{% hint style="warning" %}
**Important:** Akinon UI components follow a **non-themable** design philosophy. Always prefer utility classes over custom CSS for visual customizations.
{% endhint %}

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

```bash
pnpm add @akinon/ui-utils
```

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

Import the package at your application's entry point to make utility classes globally available:

```tsx
import '@akinon/ui-utils';
```

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

#### Flexbox Layout

```tsx
<div className="flex items-center justify-between gap-4">
  <span>Left</span>
  <span>Right</span>
</div>
```

#### Spacing (Padding & Margin)

```tsx
<div className="p-4 mb-2">
  <span className="px-6 py-2">Content</span>
</div>
```

#### Sizing

```tsx
<div className="w-full h-screen">
  <div className="w-1/2 min-h-64">Content</div>
</div>
```

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

#### Layout

| Category   | Examples                                                 | Description                         |
| ---------- | -------------------------------------------------------- | ----------------------------------- |
| Display    | `.block`, `.flex`, `.grid`, `.hidden`                    | Element visibility and display type |
| Position   | `.relative`, `.absolute`, `.fixed`, `.sticky`            | Positioning                         |
| Overflow   | `.overflow-hidden`, `.overflow-auto`, `.overflow-scroll` | Overflow behavior                   |
| Z-Index    | `.z-0`, `.z-10`, `.z-50`, `.z-auto`                      | Layer ordering                      |
| Visibility | `.visible`, `.invisible`, `.collapse`                    | Visibility control                  |

#### Flexbox

| Category    | Examples                                                | Description          |
| ----------- | ------------------------------------------------------- | -------------------- |
| Direction   | `.flex-row`, `.flex-col`, `.flex-row-reverse`           | Flex direction       |
| Wrap        | `.flex-wrap`, `.flex-nowrap`                            | Wrap behavior        |
| Justify     | `.justify-start`, `.justify-center`, `.justify-between` | Horizontal alignment |
| Align       | `.items-start`, `.items-center`, `.items-stretch`       | Vertical alignment   |
| Gap         | `.gap-1`, `.gap-2`, `.gap-4`, `.gap-8`                  | Gap between items    |
| Grow/Shrink | `.grow`, `.grow-0`, `.shrink`, `.shrink-0`              | Grow/shrink behavior |

#### Grid

| Category | Examples                                        | Description    |
| -------- | ----------------------------------------------- | -------------- |
| Columns  | `.grid-cols-1`, `.grid-cols-2`, `.grid-cols-12` | Column count   |
| Rows     | `.grid-rows-1`, `.grid-rows-2`, `.grid-rows-6`  | Row count      |
| Span     | `.col-span-1`, `.col-span-full`, `.row-span-2`  | Cell span      |
| Place    | `.place-items-center`, `.place-content-between` | Grid alignment |

#### Sizing

| Category | Examples                                   | Description           |
| -------- | ------------------------------------------ | --------------------- |
| Width    | `.w-4`, `.w-1/2`, `.w-full`, `.w-screen`   | Width                 |
| Height   | `.h-4`, `.h-1/2`, `.h-full`, `.h-screen`   | Height                |
| Min/Max  | `.min-w-0`, `.max-w-full`, `.min-h-screen` | Min/max dimensions    |
| Size     | `.size-4`, `.size-8`, `.size-1/2`          | Both width and height |

{% hint style="warning" %}
Numeric values are calculated in `rem`. `.w-4` = `1rem`, `.w-8` = `2rem`.
{% endhint %}

#### Spacing

| Category | Examples                                      | Description   |
| -------- | --------------------------------------------- | ------------- |
| Padding  | `.p-4`, `.px-6`, `.py-2`, `.pt-4`, `.pb-2`    | Inner spacing |
| Margin   | `.m-4`, `.mx-auto`, `.my-2`, `.mt-4`, `.mb-2` | Outer spacing |

**Direction shortcuts:**

* `p` / `m` - All sides
* `px` / `mx` - Horizontal (left + right)
* `py` / `my` - Vertical (top + bottom)
* `pt`, `pr`, `pb`, `pl` / `mt`, `mr`, `mb`, `ml` - Single side

#### Typography

| Category    | Examples                                                       | Description    |
| ----------- | -------------------------------------------------------------- | -------------- |
| Font Size   | `.text-xs`, `.text-sm`, `.text-base`, `.text-lg`, `.text-xl`   | Font size      |
| Font Weight | `.font-normal`, `.font-medium`, `.font-semibold`, `.font-bold` | Font weight    |
| Text Align  | `.text-left`, `.text-center`, `.text-right`                    | Text alignment |
| Line Height | `.leading-none`, `.leading-tight`, `.leading-normal`           | Line height    |
| Text Color  | `.text-neutral-500`, `.text-gray-700`, `.text-blue-600`        | Text color     |
| Transform   | `.uppercase`, `.lowercase`, `.capitalize`                      | Text transform |
| Overflow    | `.truncate`, `.line-clamp-2`, `.text-ellipsis`                 | Text overflow  |

#### Borders

| Category | Examples                                                  | Description   |
| -------- | --------------------------------------------------------- | ------------- |
| Radius   | `.rounded`, `.rounded-md`, `.rounded-lg`, `.rounded-full` | Border radius |
| Width    | `.border`, `.border-2`, `.border-t`, `.border-b`          | Border width  |
| Color    | `.border-neutral-200`, `.border-gray-300`                 | Border color  |
| Style    | `.border-solid`, `.border-dashed`, `.border-dotted`       | Border style  |

#### Backgrounds

| Category | Examples                                            | Description         |
| -------- | --------------------------------------------------- | ------------------- |
| Color    | `.bg-neutral-50`, `.bg-gray-100`, `.bg-transparent` | Background color    |
| Position | `.bg-center`, `.bg-top`, `.bg-cover`, `.bg-contain` | Background position |

#### Effects

| Category | Examples                                                 | Description    |
| -------- | -------------------------------------------------------- | -------------- |
| Shadow   | `.shadow-sm`, `.shadow-md`, `.shadow-lg`, `.shadow-none` | Shadow effects |
| Opacity  | `.opacity-0`, `.opacity-50`, `.opacity-100`              | Opacity        |

#### Interactivity

| Category       | Examples                                                    | Description     |
| -------------- | ----------------------------------------------------------- | --------------- |
| Cursor         | `.cursor-pointer`, `.cursor-default`, `.cursor-not-allowed` | Cursor type     |
| Pointer Events | `.pointer-events-auto`, `.pointer-events-none`              | Click behavior  |
| User Select    | `.select-none`, `.select-text`, `.select-all`               | Text selection  |
| Scroll         | `.scroll-smooth`, `.overflow-auto`                          | Scroll behavior |

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

Utility classes support Akinon theme colors:

| Color Group | Examples                                                      |
| ----------- | ------------------------------------------------------------- |
| Neutral     | `.text-neutral-500`, `.bg-neutral-100`, `.border-neutral-200` |
| Gray        | `.text-gray-700`, `.bg-gray-50`, `.border-gray-300`           |
| Blue        | `.text-blue-600`, `.bg-blue-100`, `.border-blue-500`          |
| Green       | `.text-green-600`, `.bg-green-100`, `.border-green-500`       |
| Red         | `.text-red-600`, `.bg-red-100`, `.border-red-500`             |
| Orange      | `.text-orange-600`, `.bg-orange-100`, `.border-orange-500`    |
| Purple      | `.text-purple-600`, `.bg-purple-100`, `.border-purple-500`    |
| Akinon      | `.text-akinon-500`, `.bg-akinon-100`, `.border-akinon-500`    |

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

#### Card Layout

```tsx
import { Card } from '@akinon/ui-card';
import { Akilocale } from '@akinon/akilocale';

const locale = Akilocale.createInstance({
  translations: { en: {}, tr: {} },
  fallbackLng: 'en'
});

const formatPrice = (value: number) =>
  new Intl.NumberFormat(locale.lng, { style: 'currency', currency: 'USD' }).format(value);

export const ProductCard = () => (
  <Card className="p-4 flex flex-col gap-3">
    <div className="w-full h-48 bg-neutral-100 rounded-lg" />
    <h3 className="text-lg font-semibold truncate">Product Name</h3>
    <p className="text-sm text-neutral-500 line-clamp-2">
      Product description goes here...
    </p>
    <div className="flex items-center justify-between mt-auto">
      <span className="text-xl font-bold text-akinon-500">{formatPrice(199)}</span>
      <span className="text-sm text-neutral-400 line-through">{formatPrice(249)}</span>
    </div>
  </Card>
);
```

#### Form Layout

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

export const LoginForm = () => (
  <div className="flex flex-col gap-4 p-6 max-w-md mx-auto">
    <h2 className="text-2xl font-bold text-center mb-2">Sign In</h2>
    <Input placeholder="Email" className="w-full" />
    <Input placeholder="Password" type="password" className="w-full" />
    <Button className="w-full mt-2">Sign In</Button>
    <p className="text-sm text-center text-neutral-500">
      Don't have an account? <a className="text-blue-600 cursor-pointer">Sign up</a>
    </p>
  </div>
);
```

#### Header Layout

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

export const Header = () => (
  <header className="flex items-center justify-between px-6 py-4 border-b border-neutral-200">
    <div className="flex items-center gap-4">
      <Icon name="menu" className="cursor-pointer" />
      <span className="text-xl font-bold">Logo</span>
    </div>
    <nav className="hidden md:flex items-center gap-6">
      <a className="text-neutral-600 cursor-pointer">Products</a>
      <a className="text-neutral-600 cursor-pointer">About</a>
      <a className="text-neutral-600 cursor-pointer">Contact</a>
    </nav>
    <div className="flex items-center gap-2">
      <Button type="icon" icon="search" tooltip="Search" />
      <Button type="icon" icon="cart" tooltip="Cart" />
    </div>
  </header>
);
```

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

#### ✅ Correct Usage

```tsx
// Layout adjustments with utility classes
<div className="flex items-center gap-4 p-4">
  <Icon name="check" />
  <span>Confirmed</span>
</div>
```

#### ❌ Incorrect Usage

```tsx
// Prefer utility classes over custom CSS
<div style={{ display: 'flex', alignItems: 'center', gap: '16px', padding: '16px' }}>
  <Icon name="check" />
  <span>Confirmed</span>
</div>
```

#### Guidelines

1. **Prioritize utility classes** - Use existing utility classes instead of writing custom CSS
2. **Use component props** - If components have their own props (e.g., `size`, `type`), prefer them over utility classes
3. **Think semantically** - If you're using too many classes, consider wrapping into a component
4. **Stay consistent** - Use the same class combinations for the same patterns


---

# 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/utility-classes.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.