🧩 Developer Handbook

Example usage:

import { Button } from "@/components/ui/button";
import { Icon } from "@/components/ui/Icon";
export default function Example() {
  return (
    <div className="flex gap-4">
      <Button variant="primary">Primary</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="destructive">Destructive</Button>
      <Button variant="muted" disabled>Disabled</Button>
      <Button variant="tertiary">Tertiary Example</Button>
      <Button variant="tertiary"> <Icon name="Star" /></Button>
    </div>
  );
}

Example usage:

import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@/components/ui/accordion'

<Accordion type="single" defaultValue="item-1">
  <AccordionItem value="item-1">
    <AccordionTrigger>Section One</AccordionTrigger>
    <AccordionContent>Content for section one</AccordionContent>
  </AccordionItem>
</Accordion>

<Accordion variant="boxed" iconPosition="left" type="single" defaultValue="boxed-1">
  <AccordionItem value="boxed-1">
    <AccordionTrigger>Title</AccordionTrigger>
    <AccordionContent>Content for boxed item</AccordionContent>
  </AccordionItem>
</Accordion>

Example usage:

import { Button } from "@/components/ui/button";
import { Icon } from "../ui/Icon";
export default function Example() {
  return (
    <div className="flex gap-4">
    <Icon name="Star" size="lg" className="text-muted-foreground" />
      <Icon name="Check" size="lg" className="text-green-600" />
      <Icon name="X" size="lg" className="text-red-600" />
      <Button variant="primary">
        <Star className="w-4 h-4 mr-2" /> Star Button
      </Button>
    </div>
  );
}

Example usage:

import Combobox from "@/components/ui/combobox";

const items = [ { value: "next.js", label: "Next.js" } ];

export default function Example() {
  const [value, setValue] = React.useState("");
  return (
    <Combobox items={items} value={value} onChange={setValue} />
  );
}

Example usage:

import { Avatar, AvatarImage, AvatarFallback } from "@/components/ui/avatar";

export default function Example() {
  return (
    <div className="flex gap-4">
      <Avatar>
  <AvatarImage src="/user-avatar.svg" alt="User avatar" />
        <AvatarFallback>JD</AvatarFallback>
      </Avatar>
    </div>
  );
}

Example usage:

import {
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
  CardContent,
  CardFooter,
  CardAction,
} from "@/components/ui/card";

export default function Example() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Card Title</CardTitle>
        <CardAction>Action</CardAction>
      </CardHeader>
      <CardDescription>Optional description text.</CardDescription>
      <CardContent>This is the main content of the card.</CardContent>
      <CardFooter>Footer content like buttons or metadata.</CardFooter>
    </Card>
  );
}

Example usage:

import { Dialog, DialogTrigger, DialogContent } from "@/components/ui/dialog";
import { Form } from "@/components/ui/form";

<Dialog>
  <DialogTrigger>
    <Button>Open Form Dialog</Button>
  </DialogTrigger>
  <DialogContent>
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)}>
      </form>
    </Form>
  </DialogContent>
</Dialog>

Example usage:

import { CustomPagination } from "@/components/ui/custom-pagination";
import React from "react";

export default function Example() {
  const [page, setPage] = React.useState(1);
  const [pageSize, setPageSize] = React.useState(10);

  return (
    <CustomPagination
      total={100}
      page={page}
      pageSize={pageSize}
      onPageChange={setPage}
      onPageSizeChange={setPageSize}
    />
  );
}

Example usage:

import { Form, FormField, FormItem, FormLabel, FormControl } from "@/components/ui/form";
import { Input } from "@/components/ui/input";

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
    <FormField
      control={form.control}
      name="title"
      render={({ field }) => (
        <FormItem>
          <FormLabel>Title</FormLabel>
          <FormControl>
            <Input placeholder="Enter title..." {...field} />
          </FormControl>
        </FormItem>
      )}
    />
  </form>
</Form>

Example usage:

import { DataTable } from "@/components/ui/table";

const columns = [
  { key: "name", header: "Name" },
  { key: "email", header: "Email" },
  { key: "role", header: "Role" },
  { key: "status", header: "Status", render: (r) => r.status }
];

<DataTable columns={columns} data={usersArray} pageSize={5} />;

Example usage:

import { Label } from "@/components/ui/label";

<Label>Default Label</Label>
<Label className="text-blue-600">Focus Label</Label>
<Label className="text-red-600">Danger Label</Label>
<Label className="text-muted-foreground">Title (optional)</Label>

<p className="text-xs text-gray-500">Helper text</p>
<p className="text-xs text-red-500">Error helper text</p>

Example usage:

import { Input } from "@/components/ui/input";
              import Icon from "@/components/ui/Icon";

<Input placeholder="Suggestion..." />

<Input aria-invalid="true" placeholder="Invalid input" />

<Input placeholder="Suggestion..." disabled />

<div className="relative">
  <Input placeholder="Input" className="pr-8" />
  <Icon name="X" size="sm" className="absolute right-2 top-1/2 -translate-y-1/2 text-muted-foreground cursor-pointer hover:text-foreground transition-colors" />
</div>

Example usage:

import { Textarea } from "@/components/ui/textarea";

<Textarea placeholder="Suggestion..." showCount maxLength={100} />

<Textarea aria-invalid={true} value="Input" showCount readOnly />

<Textarea placeholder="Disabled..." disabled showCount maxLength={100} />

Example usage:

import { Checkbox } from "@/components/ui/checkbox";

<Checkbox />

<Checkbox defaultChecked />

<Checkbox disabled />

Example usage:

import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";

<RadioGroup>
  <label className="flex items-center gap-3">
    <RadioGroupItem value="1" />
    <span>Option</span>
  </label>
</RadioGroup>

Example usage (Manual composition):

import {
  CommonTabsRoot as TabsRoot,
  CommonTabsList as TabsList,
  CommonTabsTrigger as TabsTrigger,
  CommonTabsContent as TabsContent,
} from "@/components/ui/common-tabs";

export default function ManualTabsDemo() {
  return (
    <TabsRoot defaultValue="account" className="w-full">
      <TabsList>
        <TabsTrigger value="account">Account</TabsTrigger>
        <TabsTrigger value="password">Password</TabsTrigger>
      </TabsList>

      <TabsContent value="account">
        Make changes to your account here.
      </TabsContent>
      <TabsContent value="password">
        Change your password here.
      </TabsContent>
    </TabsRoot>
  );
}

Example usage (Array-driven):

import { CommonSimpleTabs } from "@/components/ui/common-tabs";

export default function SimpleTabsDemo() {
  return (
    <CommonSimpleTabs
      defaultValue="account"
      items={[
        { value: "account", label: "Account", content: "Make changes to your account here." },
        { value: "password", label: "Password", content: "Change your password here." },
      ]}
    />
  );
}

Example usage:

import * as React from "react";
import { Button } from "@/components/ui/button";
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownOptionItem,
  DropdownOptionCheckboxItem,
} from "@/components/ui/dropdown-menu";
import { Icon } from "../ui/Icon";
export default function Example() {
  const [selectedId, setSelectedId] = React.useState("opt-2");
  const [checked, setChecked] = React.useState<Record<string, boolean>>({ "chk-1": true });

  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="secondary" className="w-56 justify-between">
          Open dropdown
        </Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent className="w-64">
        <DropdownMenuLabel>Options</DropdownMenuLabel>
        <DropdownMenuSeparator />
        <DropdownOptionItem
          selected={selectedId === "opt-1"}
          onSelect={(e) => { e.preventDefault(); setSelectedId("opt-1"); }}
        >
          Option
        </DropdownOptionItem>
        <DropdownOptionItem
          iconLeft={<Icon name="Star" size="sm" />}
          selected={selectedId === "opt-2"}
          onSelect={(e) => { e.preventDefault(); setSelectedId("opt-2"); }}
        >
          Option
        </DropdownOptionItem>
        <DropdownOptionCheckboxItem
          checked={!!checked["chk-1"]}
          onCheckedChange={(next) => setChecked(p => ({ ...p, "chk-1": !!next }))}
        >
          Option
        </DropdownOptionCheckboxItem>
        <DropdownOptionItem subtext="Subtext">Option</DropdownOptionItem>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}