Component Catalog

Full API reference for all src/ui/ primitives.
Import pattern: @/ui/{name}

---

Table of Contents

1. Button
2. IconButton
3. TextField
4. Heading
5. Text
6. Tag
7. Banner
8. Select
9. Dialog
10. Switch
11. Checkbox
12. Tooltip
13. Other Components
14. Icons

---

Button

Import

Copy
import { Button } from '@/ui/button';

Usage Example

Copy
<Button appearance="white" size="2" state="loading" iconLeft={<IconPlus />} shortcut="⌘S">
  Save
</Button>

Props

---

IconButton

Import

Copy
import { IconButton } from '@/ui/icon-button';

Usage Example

Copy
<IconButton appearance="fade" size="1" aria-label="Close">
  <IconClose />
</IconButton>

Rules

• All variants are identical to Button.
• aria-label is required on every IconButton instance — no exceptions.

---

TextField

Import

Copy
import { TextField } from '@/ui/text-field/text-field';

Usage Example

Copy
<TextField.Root>
  <TextField.Slot><IconSearch /></TextField.Slot>
  <TextField.Input placeholder="Search..." size="2" />
  <TextField.Slot>
    <TextField.Error message="Required" id="field-error" />
  </TextField.Slot>
</TextField.Root>

Structure Rules

• Always wrap in TextField.Root. No exceptions.
• Only TextField.Slot and TextField.Input are valid direct children of TextField.Root.
• Maximum one TextField.Slot before TextField.Input.
• Maximum one TextField.Slot after TextField.Input.
• Slots auto-adjust input padding via ResizeObserver.

TextField.Input Props

---

Heading

Import

Copy
import { Heading } from '@/ui/heading';

Usage Example

Copy
<Heading as="h2" size="5" color="white" weight="semibold">
  Title
</Heading>

Props

Notes

• Sizes 7 and 8 use font-display (ABC Favorit).
• Use the Heading component with the size prop — do not use raw Tailwind text classes.

---

Text

Import

Copy
import { Text } from '@/ui/text';

Usage Example

Copy
<Text as="p" size="2" color="gray">
  Description
</Text>

Props

Notes

• Use the Text component with the size prop — do not use raw Tailwind text classes.

---

Tag

Import

Copy
import { Tag } from '@/ui/tag';

Usage Example

Copy
<Tag appearance="green" variant="solid" size="1">
  Active
</Tag>

Props

---

Banner

Import

Copy
import { Banner } from '@/ui/banner';

Usage Example

Copy
<Banner appearance="yellow" size="2">
  Warning message
</Banner>

Props

Auto Icon Behavior

---

Select

Import

Copy
import * as Select from '@/ui/select';

Usage Example

Copy
<Select.Root value={val} onValueChange={setVal}>
  <Select.Trigger size="2" appearance="gray" />
  <Select.Content>
    <Select.Label>Group</Select.Label>
    <Select.Item value="a">Option A</Select.Item>
    <Select.Separator />
    <Select.Item value="b">Option B</Select.Item>
  </Select.Content>
</Select.Root>

Select.Trigger Props

---

Dialog

Import

Copy
import * as Dialog from '@/ui/dialog';

Usage Example

Copy
<Dialog.Root>
  <Dialog.Trigger asChild>
    <Button>Open</Button>
  </Dialog.Trigger>
  <Dialog.Content size="1">
    <Dialog.Title>Confirm</Dialog.Title>
    <p>Are you sure?</p>
  </Dialog.Content>
</Dialog.Root>

Dialog.Content size Values

Notes

• includeCloseButton defaults to true.
• Dialog auto-manages focus trap and escape key handling.

---

Switch

Import

Copy
import { Switch } from '@/ui/switch';

Usage Example

Copy
<Switch checked={on} onCheckedChange={setOn} disabled={false} />

Props

---

Checkbox

Import

Copy
import { Checkbox } from '@/ui/checkbox';

Usage Example

Copy
<Checkbox checked={val} onCheckedChange={setVal} />

Props

---

Tooltip

Import

Copy
import * as Tooltip from '@/ui/tooltip';

Usage Example

Copy
<Tooltip.Root>
  <Tooltip.Trigger asChild>
    <Button>Hover</Button>
  </Tooltip.Trigger>
  <Tooltip.Content>Tip text</Tooltip.Content>
</Tooltip.Root>

---

Other Components

---

Icons

• Location: @/ui/icons/icon-{name}.tsx
• Count: 100+ icons available.

Commonly Used Icons

Live Examples

Located at: src/app/(internal)/design/components/{name}/page.tsx

---

Design Tokens

Defined in src/styles/globals.css using Tailwind CSS v4 with CSS custom properties.

---

Color System

Built on Radix UI Colors. Each color has 12 steps plus alpha variants.

Gray Scale

Primary neutral scale. Used for text, borders, and backgrounds.

Semantic Colors

Color Step Convention

Background Values

---

Typography

Rule: Use Heading and Text components with the size prop. Do not use raw Tailwind text size classes directly.

---

Sizing Scale

Border Radius Reference

---

Shadows

---

Animations

Scale & Fade

Slide & Fade

Utility Animations

Custom Utility Classes

---

Dark Mode

• Implemented via Tailwind dark: prefix.
• Background flips: #fdfdfd → #000.
• Button with appearance="white" inverts automatically.
• Gray scales adjust automatically via Radix.
• Use dark: only for explicit manual overrides — not as a default styling approach.

---

Component Patterns

---

CVA — Class Variance Authority

All variants use CVA for type-safe styling.

Pattern

Copy
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/cn';

const myVariants = cva('base-classes', {
  variants: {
    appearance: {
      gray: 'bg-gray-a2 border-gray-a3 text-gray-9',
      white: 'bg-black text-white dark:bg-white dark:text-black',
    },
    size: {
      '1': 'h-6 text-xs px-2 rounded-lg',
      '2': 'h-8 text-sm px-3 rounded-xl',
    },
  },
  defaultVariants: { appearance: 'gray', size: '2' },
});

interface MyProps extends React.ComponentProps<'div'>, VariantProps<typeof myVariants> {}

function MyComponent({ appearance, size, className, ...props }: MyProps) {
  return <div className={cn(myVariants({ appearance, size, className }))} {...props} />;
}

Conventions

---

Compound Component Pattern

Two patterns in use. Choose based on coupling level.

Object Namespace

Used for tightly coupled parts (TextField, Avatar, BulkActions).

Copy
export const TextField = { Root, Slot, Input, Error };

<TextField.Root>
  <TextField.Slot>...</TextField.Slot>
  <TextField.Input size="2" />
</TextField.Root>

Named Exports

Used for Radix-based primitives (Select, Dialog, Tooltip, DropdownMenu).

Copy
import * as Select from '@/ui/select';

<Select.Root>
  <Select.Trigger />
  <Select.Content>
    <Select.Item value="x">X</Select.Item>
  </Select.Content>
</Select.Root>

---

Slot Pattern (asChild)

Uses @radix-ui/react-slot to merge props onto a child element instead of rendering a wrapper.

Copy
<Button asChild>
  <Link href="/settings">Settings</Link>
</Button>

<Dialog.Trigger asChild>
  <IconButton appearance="fade"><IconSettings /></IconButton>
</Dialog.Trigger>

---

TextField Slot System

Slots auto-adjust input padding via ResizeObserver.

Copy
<TextField.Root>
  <TextField.Slot><IconSearch /></TextField.Slot>
  <TextField.Input placeholder="Search..." />
  <TextField.Slot><Button size="1" appearance="fade">Clear</Button></TextField.Slot>
</TextField.Root>

Hard Rules

• Maximum one TextField.Slot before TextField.Input.
• Maximum one TextField.Slot after TextField.Input.
• Only TextField.Slot and TextField.Input are valid direct children of TextField.Root.

---

State Management

Use the state prop — not individual boolean props.

Copy
<Button state="loading">Save</Button>
<TextField.Input state="disabled" />
<TextField.Input state="read-only" />

---

Shared Styling

src/ui/shared.ts exports constants for consistent dropdown and floating bar styling.

Copy
import { dropdown, floatingBottomBar } from '@/ui/shared';

<div className={cn(dropdown.content.appearance, dropdown.content.sizing)}>
  <div className={cn(dropdown.item.sizing, dropdown.item.appearance.gray)}>
    Item
  </div>
</div>

---

Server vs Client Components

Pre-classified Components

---

Accessibility