Documentation

Technical reference — tech stack, design system, and UI components.

Tech Stack

Last updated: 2026-02-21

Framework

Next.js 16 — App Router, server components, static/dynamic rendering
React 19 — Latest React with concurrent features

UI

shadcn/ui — Radix Maia theme (style: "radix-maia" in components.json)
Tailwind CSS v4 — Utility-first styling via @tailwindcss/postcss
Radix UI — Accessible primitives (Select, Tooltip, Slot, etc.)
Lucide React — Icon library
class-variance-authority (cva) — Variant styling for components
tailwind-merge — Merge Tailwind classes without conflicts

Data

Neon — Serverless Postgres (@neondatabase/serverless)
Drizzle ORM — Type-safe queries and migrations
pgvector — Vector embeddings for RAG (Ask page)

AI

Vercel AI SDK — ai and @ai-sdk/react for streaming chat
OpenAI — Embeddings and chat completions (via API key or Vercel AI Gateway)

Key Libraries

Category	Package	Purpose
Markdown	`@mdx-js/mdx`, `react-markdown`, `remark-gfm`, `rehype-highlight`, `rehype-slug`	MDX and Markdown rendering
Search	`fuse.js`	Client-side fuzzy search
Command palette	`cmdk`	Command menu (⌘K)
Carousel	`embla-carousel-react`	Image/content carousels
Forms & validation	`zod`	Schema validation
Analytics	`@vercel/analytics`, `@vercel/speed-insights`	Vercel analytics and Core Web Vitals
Payments	`stripe`	Checkout and webhooks
Theming	`next-themes`	Dark/light mode
Toasts	`sonner`	Toast notifications

Design System — shadcn UI Consistency

Source of truth: components.json with style: "radix-maia"
Last updated: 2026-02-16

Native Maia theme (enforced)

Use native shadcn Maia theme components only. Do not add custom style overrides that deviate from the theme.

All UI components (Select, Button, Dialog, etc.) must come from the shadcn registry.
No className overrides for radius, background, or border on shadcn primitives. If something looks wrong, fix the component file or theme, not the usage.

Add or update components with:

Code

npx shadcn@latest add <component> --overwrite

Do not change style or baseColor in components.json unless intentionally switching themes.

Design tokens

Radius: Defined in app/globals.css via @theme inline and :root.
Muted (light mode): --muted: oklch(0.92 0 0) — tuned for perceptible ghost-button hover contrast against --background (WCAG 2.1 non-text contrast).
--radius: 1rem (large). Derived: --radius-sm through --radius-4xl.
Use the same radius token for related elements (e.g. trigger and dropdown).

Dropdowns and popovers

Corner radius: Dropdowns/popovers that attach to triggers must use the same corner radius as the trigger.
- Example: Select trigger uses rounded-4xl (pill) → SelectContent uses rounded-4xl.
Positioning: For attached dropdowns that should overlap the trigger (shadcn Maia style), use:
Code
```
sideOffset={-4}
```
instead of a positive gap (e.g. sideOffset={8}).

Component-specific notes

Component	Trigger radius	Content radius	Item radius	sideOffset
Select	rounded-4xl	rounded-4xl	first:rounded-t-4xl last:rounded-b-4xl first:last:rounded-4xl	-4

UI Components

Source: components/ui — shadcn registry (radix-maia theme)
Last updated: 2026-02-21

shadcn components

All components are from the shadcn registry unless noted. Add or update with: