Usage

Akinon UI Kit is a comprehensive React component library designed to ensure visual consistency across all Akinon applications and extensions.

Installation

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:

pnpm add @akinon/ui-react

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

pnpm add @akinon/button

Install peer dependencies (React 18 or React 19):

pnpm add react@19 react-dom@19

Optional Packages

Install additional packages as needed:

# 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

Basic Setup

1. Import Fonts

Install with:

pnpm add @akinon/fonts-jost-variable

Import Akinon's typography system in your entry file:

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:

import '@akinon/ui-utils';

3. Wrap Your App with Provider

The UI Kit requires AkinonUIProvider for proper component functionality:

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

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

Basic Usage

Importing Components

Import components from the main package:

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

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

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

Using Hooks

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..."
    />
  );
};

Responsive Design

Using Grid System

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>
);

TypeScript Support

All components are fully typed:

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" />

Best Practices

1. Use Semantic Imports

// 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

// 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

// 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:

// 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>

Migration from Other Libraries

From Ant Design

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

// 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

// 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"

Troubleshooting

Styles Not Applying

Ensure fonts and utilities are imported:

// 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:

<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.

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

Bundle Size Too Large

Use specific imports for advanced components:

// 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

Next Steps

• 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

Support

For interactive examples and live demos, visit the Storybook documentation where you can explore all components with live code examples.