Components

Every pixel of UI on the Naalya site comes from one place: app/components/. There is no scattered styling, no one-off <div> soup. Instead the project leans on shadcn/ui — components you own and copy into your repo rather than install from npm — sitting on top of Radix UI primitives and Tailwind CSS v4, with class-variance-authority (cva) doing the variant math.

The single most useful thing to understand up front is that the components folder is sorted into buckets by intent, and almost every mistake people make here comes from putting a file in the wrong one. So before any code, get this mental model straight:

The four buckets

Choosing the right bucket is the most important structural decision you make when adding UI. There are four, and each answers a different question.

ui/ is the base layer — 52 files, mostly generated shadcn primitives (button, card, dialog, form, select, sidebar, and ~45 more). Two project-authored files live here on purpose: optimized-image.tsx (use OptimizedImage instead of a raw img for CMS pictures — you get srcset, LQIP blur, and auto format) and spinner.tsx.

custom-ui/ is where your reusable UI goes. It has two flavours: composites that wrap primitives (phone.input.tsx, success-dialog.tsx, image-preview-dialog.tsx) and pure visual effects (aurora-text.tsx, meteors.tsx, particles.tsx). The composition is literal — image-preview-dialog.tsx just pulls the parts it needs out of ui/:

import { Button } from "../ui/button";
import { Dialog, DialogContent, DialogHeader, DialogTitle } from "../ui/dialog";

ai-elements/ is a vendored copy of the Vercel AI Elements / streamdown chat kit (conversation, message, response, prompt-input, and more) that powers the Naalya-AI chat. Several files carry biome-ignore-all banners marking them as vendored. The shadcn CLI does not manage these — don't try to regenerate them.

The feature buckets assemble everything else: sections/ holds page-level orchestrators (lugazi-admission.tsx), landing-page-components/ holds the smaller presentational cards they pull from, navigation/ holds navbar.tsx and footer.tsx, and providers/ holds the provider tree.

Radix underneath, and the data-slot trick

Every interactive primitive is a thin wrapper around a @radix-ui/react-* package. Radix supplies the behavior — focus management, portals, keyboard handling — and the shadcn wrapper supplies the styling. The new-york style this project uses adds one extra convention you'll see everywhere: every wrapped part is tagged with a data-slot="..." attribute.

Here is the shape of ui/dialog.tsx — notice each piece declares its slot and merges className through cn():

import * as DialogPrimitive from "@radix-ui/react-dialog";
import { cn } from "@/lib/utils";

function Dialog(props: React.ComponentProps<typeof DialogPrimitive.Root>) {
  return <DialogPrimitive.Root data-slot="dialog" {...props} />;
}

function DialogContent({ className, children, ...props }) {
  return (
    <DialogPortal data-slot="dialog-portal">
      <DialogOverlay />
      <DialogPrimitive.Content
        className={cn("fixed top-[50%] left-[50%] z-50 grid /* ... */", className)}
        data-slot="dialog-content"
        {...props}
      />
    </DialogPortal>
  );
}

Why does the slot matter? Because it lets you restyle the inside of a primitive from the outside, without touching the primitive file. Tailwind's arbitrary-variant syntax can target a descendant by its slot. The chat input does exactly this to round a nested input group it doesn't own:

<PromptInput className="**:data-[slot=input-group]:rounded-3xl!" />

cn() — the universal class merger

You'll see cn() in literally every component, so understand it once. It is clsx (which joins class names conditionally) piped through tailwind-merge (which de-duplicates conflicting Tailwind utilities, last-one-wins).

import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

The payoff is that a caller can always override a base style. Because the incoming className is merged last, bg-secondary from a caller correctly beats a base bg-primary instead of producing two fighting classes:

// Caller wins: twMerge drops the base bg-primary in favour of the passed class.
<div className={cn("rounded-md bg-primary p-4", className)} />

Variants with cva

Any component with visual variants — a button with outline vs ghost, a badge with severities — defines them with class-variance-authority. The recipe never changes: a base string, a variants map, defaultVariants, props typed with VariantProps<typeof xVariants>, and both the component and its *Variants function exported.

ui/button.tsx is the canonical example. Note two project customizations baked in: the outline variant is branded (border-primary ... text-primary hover:bg-primary/4, not stock shadcn gray), and the project added icon-sm / icon-lg sizes.

import { Slot } from "@radix-ui/react-slot";
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";

const buttonVariants = cva("inline-flex items-center justify-center /* base */", {
  variants: {
    variant: {
      default: "bg-primary text-primary-foreground hover:bg-primary/90",
      outline: "border border-primary bg-background text-primary hover:bg-primary/4",
      ghost: "hover:bg-accent hover:text-accent-foreground",
      /* destructive, secondary, link ... */
    },
    size: { default: "h-9 px-4 py-2", sm: "h-8 px-3", "icon-sm": "size-8" /* ... */ },
  },
  defaultVariants: { variant: "default", size: "default" },
});

function Button({ className, variant, size, asChild = false, ...props }:
  React.ComponentProps<"button"> & VariantProps<typeof buttonVariants> & { asChild?: boolean }) {
  const Comp = asChild ? Slot : "button";
  return <Comp className={cn(buttonVariants({ variant, size, className }))} data-slot="button" {...props} />;
}

export { Button, buttonVariants };

The same pattern shows up in ui/badge.tsx, in ui/navigation-menu.tsx (navigationMenuTriggerStyle), and even outside ui/ — ai-elements/message.tsx keys a cva variant off group classes to style user vs assistant bubbles. Once you've read one, you've read them all.

asChild and the Radix Slot

That asChild prop on Button is worth a closer look, because it's how the project gets a button-styled link without duplicating styles. When asChild is true, the component renders Radix's Slot, which merges its props (including the cva className) onto its single child instead of rendering its own element.

import { Link } from "react-router";
import { Button } from "@/components/ui/button";

// The button's cva classes flow onto the <Link>, which renders the real <a>.
<Button asChild size="lg">
  <Link to={pageLink}>Explore campus</Link>
</Button>;

Adding a component

When you need a primitive the project doesn't have yet, you don't write it — you let the CLI generate it. Run it from the frontend package root (the folder containing components.json). The CLI reads that config, drops the file into app/components/ui/, and installs any new dependency (a Radix package, sometimes lucide-react).

# Add one primitive
pnpm dlx shadcn@latest add tooltip

# Add several at once
pnpm dlx shadcn@latest add dialog popover command

# List/search what's available (run with no name)
pnpm dlx shadcn@latest add

Once it lands, import it through the @/components/ui alias (@/* resolves to app/*):

import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";

One subtlety: this is Tailwind v4, so there is no tailwind.config.js. If a new primitive needs keyframes — the accordion's accordion-up / accordion-down, for instance — they go into app/app.css, not a JS config. Styling & Theming covers where theme tokens and keyframes live.

The primitive authoring checklist

If you do author or restyle a primitive, follow the house style so it stays consistent with the generated ones:

1. Accept className and append it last via cn().
2. Spread {...props} through to the underlying element.
3. Type the signature as React.ComponentProps<'tag'> or React.ComponentProps<typeof RadixPrimitive.Part>.
4. Tag each wrapper part with data-slot="name".
5. If it has variants, use cva and export both the component and its *Variants function.

What lives on the other pages

Two big topics deliberately don't live here, to keep this page about the component system rather than every feature built on it.

Forms. The react-hook-form + Zod + shadcn Form pattern is the most repeated pattern in the codebase, and it has its own home. See Forms for the gold-standard admission-form.tsx, binding non-native inputs, and the Zod v4 idioms.

Icons and toasts. The project uses @tabler/icons-react in feature code and lucide-react inside primitives — match whatever the surrounding file imports, and don't introduce iconsax-react (installed but unused). The sonner Toaster is mounted once in app.provider.tsx; call toast.* from anywhere, and never mount a second one. Both fit better alongside the styling discussion.

Where to go next