NachUI - nachui-usage — NachUI Skills

Triggers when: “Use when consuming, importing, or integrating NachUI components inside apps/web or any app that depends on @repo/ui.”

NachUI Usage Guide

You are consuming components from the NachUI. Follow these rules precisely.

Available Components

Component	Import Path
`Accordion`	`@repo/ui/components/accordion`
`Avatar`	`@repo/ui/components/avatar`
`Badge`	`@repo/ui/components/badge`
`Banner`	`@repo/ui/components/banner`
`Breadcrumb`	`@repo/ui/components/breadcrumb`
`Button`	`@repo/ui/components/button`
`Callout`	`@repo/ui/components/callout`
`Card`	`@repo/ui/components/card`
`Checkbox`	`@repo/ui/components/checkbox`
`Collapsible`	`@repo/ui/components/collapsible`
`Dialog`	`@repo/ui/components/dialog`
`Drawer`	`@repo/ui/components/drawer`
`DropdownMenu`	`@repo/ui/components/dropdown-menu`
`Input`	`@repo/ui/components/input`
`Kbd`	`@repo/ui/components/kbd`
`Label`	`@repo/ui/components/label`
`Popover`	`@repo/ui/components/popover`
`Progress`	`@repo/ui/components/progress`
`Select`	`@repo/ui/components/select`
`Separator`	`@repo/ui/components/separator`
`Skeleton`	`@repo/ui/components/skeleton`
`Spinner`	`@repo/ui/components/spinner`
`Switch`	`@repo/ui/components/switch`
`Table`	`@repo/ui/components/table`
`Tabs`	`@repo/ui/components/tabs`
`Toast`	`@repo/ui/components/toast`
`Tooltip`	`@repo/ui/components/tooltip`
`Typography`	`@repo/ui/components/typography`

Layout Primitives

Use layout primitives for spatial composition. Do not use raw div with Tailwind flex/grid unless you need something the primitives do not support.

1// Stack = vertical flex column
2<Stack gap="4">
3  <Typography variant="h2">Title</Typography>
4  <Typography variant="p">Body text</Typography>
5</Stack>
6 
7// Flex = horizontal flex row
8<Flex align="center" justify="between" gap="3">
9  <span>Left</span>
10  <Button>Action</Button>
11</Flex>
12 
13// Grid = CSS grid
14<Grid columns="3" gap="6">
15  <Card>...</Card>
16  <Card>...</Card>
17  <Card>...</Card>
18</Grid>
19 
20// Container = max-width wrapper with padding
21<Container size="fluid">
22  {/* page content */}
23</Container>

Container Sizes

Size	Max Width
`sm`	640px
`md`	768px
`lg`	1024px
`xl`	1280px
`fluid`	100% (full width with padding)

Stack / Flex / Grid Gap Values

Accepted gap values: "0" | "1" | "2" | "3" | "4" | "5" | "6" | "8" | "10" | "12" | "16" | "20" | "24" | "32".

Do not pass arbitrary values like gap="2.5" — these will cause TypeScript errors.

Button Usage

1import { Button } from '@repo/ui/components/button';
2 
3// Variants: default | destructive | outline | secondary | ghost | link
4// Sizes: default | sm | lg | icon
5 
6<Button variant="default">Save</Button>
7<Button variant="outline" size="sm">Cancel</Button>
8<Button loading>Processing...</Button>
9<Button leftIcon={<SomeIcon />}>With Icon</Button>
10 
11// Group
12<Button.Group>
13  <Button variant="outline">Left</Button>
14  <Button variant="outline">Right</Button>
15</Button.Group>
16 
17// Attached group
18<Button.Group attached>
19  <Button variant="outline">A</Button>
20  <Button variant="outline">B</Button>
21</Button.Group>

Typography Usage

1import { Typography } from '@repo/ui/components/typography';
2 
3// Variants: h1 | h2 | h3 | h4 | p | lead | large | small | muted | code | blockquote
4<Typography variant="h1">Page Title</Typography>
5<Typography variant="p">Body paragraph text.</Typography>
6<Typography variant="muted">Secondary note.</Typography>

Icons

NachUI uses @hugeicons/core-free-icons and @hugeicons/react. Never use lucide-react or heroicons.

1import { ArrowRight02Icon, Copy01Icon } from '@hugeicons/core-free-icons';
2import { HugeiconsIcon } from '@hugeicons/react';
3 
4<HugeiconsIcon icon={ArrowRight02Icon} size={16} />
5<HugeiconsIcon icon={Copy01Icon} className="h-4 w-4" />

Client vs Server Components

Layout primitives (Container, Stack, Flex, Grid) are Server Component safe — no 'use client' needed.
Interactive components (Button, Dialog, Accordion, Tabs, etc.) are already marked 'use client' internally — you do not need to add the directive when consuming them in a Server Component, Next.js handles the boundary automatically.
Only add 'use client' to your own component files when you use React hooks (useState, useEffect, useRef, etc.).

`cn` Utility

Always use cn to merge class names. Never concatenate strings manually.

1import { cn } from '@/lib/cn';
2 
3<div className={cn('base-class', isActive && 'active-class', className)} />;

nachui-usage