# Usage

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

#### For New Projects

If you created your project using `create-akinon-app`, the UI Kit is already configured and ready to use. Skip to Basic Usage.

#### For Existing Projects

Install the UI Kit package:

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

If your application doesn't support tree shaking, you may install components separately:

```bash
pnpm add @akinon/button
```

Install peer dependencies (React 18 or React 19):

```bash
pnpm add react@19 react-dom@19
```

#### Optional Packages

Install additional packages as needed:

```bash
# For advanced forms
pnpm add @akinon/akiform

# For filtering capabilities
pnpm add @akinon/akifilter

# For advanced tables
pnpm add @akinon/akitable

# For icons
pnpm add @akinon/icons

# For custom hooks
pnpm add @akinon/ui-hooks

# For utility classes
pnpm add @akinon/ui-utils
```

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

#### 1. Import Fonts

Install with:

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

Import Akinon's typography system in your entry file:

```typescript
import '@akinon/fonts-jost-variable';
```

This loads the Jost Variable font used throughout Akinon's design system.

#### 2. Import Utility Classes

For utility-first styling approach:

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

#### 3. Wrap Your App with Provider

The UI Kit requires `AkinonUIProvider` for proper component functionality:

```tsx
// src/providers.tsx
import { AkinonUIProvider } from '@akinon/ui-react';

export const Providers = ({ children }) => (
  <AkinonUIProvider>
    {children}
  </AkinonUIProvider>
);
```

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

#### Importing Components

Import components from the main package:

```tsx
import { Button, Input, Card, Space } from '@akinon/ui-react';

export const MyComponent = () => {
  return (
    <Card title="User Profile">
      <Space direction="vertical">
        <Input placeholder="Enter name" />
        <Button type="primary">Save</Button>
      </Space>
    </Card>
  );
};
```

#### Importing Icons

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

export const UserMenu = () => {
  return (
    <div>
      <Icon icon="refresh" /> Refresh
    </div>
  );
};
```

#### Using Hooks

```tsx
import { Input } from '@akinon/input';
import { useDebounce, useLocalStorage } from '@akinon/ui-hooks';
import { useState } from 'react';

export const SearchComponent = () => {
  const [search, setSearch] = useState('');
  const debouncedSearch = useDebounce(search, 500);
  const [savedSearch, setSavedSearch] = useLocalStorage();
  
  useState(() => {
    setSavedSearch(debouncedSearch);
  }, [debouncedSearch]);

  return (
    <Input
      value={search}
      onChange={(e) => setSearch(e.target.value)}
      placeholder="Search..."
    />
  );
};
```

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

#### Using Grid System

```tsx
import { Row, Col } from '@akinon/ui-react';

export const ResponsiveLayout = () => (
  <Row gutter={[16, 16]}>
    <Col xs={24} sm={12} md={8} lg={6}>
      <div>Column 1</div>
    </Col>
    <Col xs={24} sm={12} md={8} lg={6}>
      <div>Column 2</div>
    </Col>
    <Col xs={24} sm={12} md={8} lg={6}>
      <div>Column 3</div>
    </Col>
    <Col xs={24} sm={12} md={8} lg={6}>
      <div>Column 4</div>
    </Col>
  </Row>
);
```

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

All components are fully typed:

```tsx
import { Button, type ButtonProps } from '@akinon/ui-react';

interface CustomButtonProps extends ButtonProps {
  customProp?: string;
}

export const CustomButton = ({ customProp, ...props }: CustomButtonProps) => {
  return <Button {...props}>{customProp}</Button>;
};

// Type-safe usage
<CustomButton type="primary" customProp="value" />
```

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

#### 1. Use Semantic Imports

```tsx
// Good - specific imports
import { Button, Input } from '@akinon/ui-react';

// Avoid - namespace imports (larger bundle)
import * as AkinonUI from '@akinon/ui-react';
```

#### 2. Use Composition

```tsx
// Good - composition pattern
import { Card, Space, Button } from '@akinon/ui-react';

export const UserCard = ({ user }) => (
  <Card>
    <Space direction="vertical">
      <div>{user.name}</div>
      <Button>View Profile</Button>
    </Space>
  </Card>
);
```

#### 3. Optimize Bundle Size

```tsx
// Good - tree-shaking friendly
import { Button } from '@akinon/ui-react';

// If you need only icons
import { Icon } from '@akinon/icons';

// For specific advanced components
import { AkiTable } from '@akinon/akitable';
```

#### 4. Follow Design System Guidelines

The UI Kit is pre-styled to maintain Akinon's design consistency. Use components as provided without extensive style customization:

```tsx
// Good - using components as designed
<Button type="primary">Submit</Button>
<Alert type="success" message="Saved!" />

// Avoid - style prop fires type error - DO_NOT_USE_OR_YOU_WILL_BE_FIRED_INTERNAL_STYLE
<Button
  type="primary"
  style={{
    backgroundColor: '#custom',
    borderRadius: '20px',
    fontSize: '10px'
  }}
>
  Submit
</Button>
```

### <mark style="color:red;">Migration from Other Libraries</mark>

#### From Ant Design

Akinon UI is based on Ant Design, so migration is straightforward:

```tsx
// Before (Ant Design)
import { Button } from 'antd';

// After (Akinon UI)
import { Button } from '@akinon/ui-react';

// Mostly same API, Akinon styling
<Button type="primary">Click Me</Button>
```

#### From Material-UI

```tsx
// Material-UI
import { Button } from '@mui/material';

// Akinon UI equivalent
import { Button } from '@akinon/ui-react';

// Prop mapping examples:
// variant="contained" → type="primary"
// variant="outlined" → type="default"
// variant="text" → type="link"
```

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

#### Styles Not Applying

Ensure fonts and utilities are imported:

```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';

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

#### Provider Missing Error

Wrap your app with `AkinonUIProvider`:

```tsx
<AkinonUIProvider>
  <App />
</AkinonUIProvider>
```

#### Cannot Read Style Token

Error message would be similar with:

```
TypeError: Cannot read properties of undefined (reading 'colorBgContainerDisabled')
```

Use latest theme version with latest component versions. Ensure all components are compatible with core `@akinon/theme` package.

```json
// package.json
"dependencies": {
  "@akinon/button": "^1.3.0",
  "@akinon/theme": "^1.1.0"
}
```

#### Bundle Size Too Large

Use specific imports for advanced components:

```tsx
// Instead of
import { AkiTable } from '@akinon/ui-react';

// Use
import { AkiTable } from '@akinon/akitable';
```

#### Components Look Different Than Expected

The UI Kit is pre-styled with Akinon's design system. If components don't look right:

1. Ensure `AkinonUIProvider` is wrapping your app
2. Check that fonts are imported: `import '@akinon/fonts-jost-variable'`
3. Verify no global CSS is overriding component styles
4. Don't apply custom styles that conflict with the design system

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

* **Design System**: Learn about design tokens and typography
* **Explore Components**: Check the Primitives for complete component documentation
* **Advanced Features**: Dive into AkiForm, AkiFilter, and AkiTable
* **Custom Hooks**: Discover useful hooks for common patterns
* **Utilities**: Explore utility packages for dates, localization, and validation

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

For interactive examples and live demos, visit the [Storybook documentation](https://4e1ca350ada947d18edc04e64d784137.lb.akinoncloud.com/) where you can explore all components with live code examples.


---

# 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/usage.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.