# UI8Kit Documentation

**UI8Kit** is a modern React UI library with TypeScript-first approach, utility-first styling, and polymorphic components.

## 📚 Documentation

### Quick Start

* [**Overview**](/docs/overview.md) - Library overview
* [**Getting Started**](/docs/getting-started.md) - Installation and setup

### API Reference

* [**Components**](/docs/api-reference/components.md) - Complete component reference
* [**Core UI**](/docs/api-reference/core-ui.md) - Variants system and utilities
* [**Layouts**](/docs/api-reference/layouts.md) - Layout components (Container, Stack, Grid)

### Architecture

* [**Architecture Overview**](/docs/architecture/overview.md) - General architecture
* [**Variant System**](/docs/architecture/variant-system.md) - Variants system (CVA)
* [**Package Structure**](/docs/architecture/package-structure.md) - Package structure
* [**TypeScript Configuration**](/docs/architecture/typescript-configuration.md) - TypeScript setup
* [**Build System**](/docs/architecture/build-system.md) - Build system

### Development

* [**Development Guide**](/docs/development-guide/development-guide.md) - Main guide
* [**Basic Workflow**](/docs/development-guide/basic-workflow.md) - Step-by-step workflow
* [**Best Practices**](/docs/development-guide/best-practices.md) - Best practices
* [**Dark Mode**](/docs/development-guide/dark-mode.md) - Theme implementation

### Troubleshooting

* [**Troubleshooting**](/docs/troubleshooting.md) - Solving common issues

## 🚀 Key Features

* **TypeScript-first**: Full type safety with autocompletion
* **Utility-first**: All styles available as component props
* **Polymorphic components**: Any HTML element via `component` prop
* **Variants system**: Consistent styling through CVA
* **Dark mode**: Built-in theme support
* **Tree shaking**: Automatic unused code removal
* **Accessibility**: ARIA attributes and keyboard navigation

## 📦 Installation

```bash
npm install @ui8kit/core
```

## 🎯 Usage Example

```tsx
import { Button, Block, Container, Stack, Card } from '@ui8kit/core'
import { ThemeProvider } from './providers/theme'

function App() {
  return (
    <ThemeProvider theme={defaultTheme}>
      <Container>
        <Stack gap="lg" align="center">
          <Block py="xl" ta="center">
            <Title size="4xl">Welcome to UI8Kit</Title>
            <Text c="muted">Modern React UI Library</Text>
          </Block>

          <Card p="lg" rounded="xl">
            <Stack gap="md">
              <Text fw="bold">Getting Started</Text>
              <Button variant="primary" size="lg">
                Learn More
              </Button>
            </Stack>
          </Card>
        </Stack>
      </Container>
    </ThemeProvider>
  )
}
```

## 🏗️ Architecture

```
USER LEVEL               COMPOSITE LEVEL           PRIMITIVE LEVEL
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ <Button         │────▶│ components/ui/Button │────▶│ core/ui/Button    │
│   variant="primary"│     │ + buttonVariants   │     │ (no styles)     │
│   size="lg"     │     │ + spacingVariants │     │                 │
│   rounded="md"  │     │ = Beautiful API  │     │                 │
│ />              │     │                  │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
```

## 📊 Performance

* **Bundle size**: \~15KB gzipped (full core)
* **Tree shaking**: Automatic unused code removal
* **Zero runtime**: Styles compiled to CSS
* **Stable references**: No unnecessary re-renders

## 🤝 Community

* **GitHub**: [github.com/ui8kit/core](https://github.com/ui8kit/core)
* **Issues**: For bug reports and feature requests
* **Discussions**: For questions and discussions

## 📄 License

GPL-3.0

***

**Start developing with** [**Getting Started**](/docs/getting-started.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://ui8kit.gitbook.io/docs/readme.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.