pgvector — Vector embeddings for RAG (Ask page). Retrieval expands the question, searches a candidate pool, then reranks the matches. Citation links use locale-prefixed page URLs.
AI
Vercel AI SDK — ai and @ai-sdk/react for streaming chat
OpenAI — Embeddings and chat completions (via API key or Vercel AI Gateway)
Feature Flags
Feature flags — A named flag is on when NEXT_PUBLIC_FEATURE_<NAME> is true
Request headers — Optional headers can vary a server-rendered section (for example a hero variant)
Internationalization
Key Libraries
SEO & Discovery
Last updated: 2026-02-24
Summary of how the site is made discoverable to search engines and AI answer engines.
Sitemap
Theme
Source of truth:components.json with style: "radix-maia" Last updated: 2026-02-27
Native Maia theme (enforced)
Use native shadcn Maia theme components only. Do not add custom style overrides that deviate from the theme.
UI Components
Source:components/ui — shadcn registry (radix-maia theme) Last updated: 2026-03-19
shadcn components
All components are from the shadcn registry unless noted. Add or update with:
Code
npx shadcn@latest add <component> --overwrite
components.json
Tailwind CSS v4 — Utility-first styling via @tailwindcss/postcss
Contents: Base pages (home, stories, about, newsroom, pricing, ask, docs, legal), story projects, and newsroom posts — all locales (en, hi, ar, es)
Source:getLocalizedUrl() from lib/site.ts; NEXT_PUBLIC_SITE_URL for base URL
Robots
File:app/robots.ts
URL:/robots.txt
Rules:User-Agent: * — allow /, disallow /api/
Sitemap: Points to {baseUrl}/sitemap.xml
AI Crawlers
We allow the following AI crawlers to access public content (AEO / answer engine optimization):
Crawler
Purpose
GPTBot
OpenAI (ChatGPT)
PerplexityBot
Perplexity
Google-Extended
Google AI Overviews
anthropic-ai
Claude
CCBot
Common Crawl
Each has explicit allow: "/" and disallow: ["/api/"] in app/robots.ts. This supports appearing as a cited source for queries like "who is Gagan Malik" or "how to contact Gagan Malik."
Canonicals
Canonical URLs are set on key pages (home, stories, newsroom, pricing, and story detail) so each page has one address. Those addresses include the language prefix.
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.
Corner curve:--corner-shape: squircle (superellipse(2)). Applied in @layer base wherever corner-shape is supported. Radius tokens are unchanged. A full radius (the border radius is at least half the shorter layout side) is a circle or capsule and uses corner-shape: round, because a squircle on a full radius replaces the semicircle and Chromium paints that corner square. A partial radius stays squircle, including cards, dialogs, sheets, and the lab phone frame. rounded-full and any fixed side of at most 4rem with rounded-4xl are round before paint. One client pass then measures layout size (offsetWidth / offsetHeight) and sets the same rule on every element, including content-sized chips and arbitrary radii. Browsers without the property keep the quarter-circle.
Use the same radius token for related elements (e.g. trigger and dropdown).
Spacing scale
Use a consistent spacing scale for padding, margins, and gaps:
Pixels
Tailwind
Usage
4
p-1, gap-1
Tight gaps, icon padding
8
p-2, gap-2
Small gaps between related elements
16
p-4, gap-4
Default padding, card gaps
24
p-6, gap-6
Section spacing
32
,
Avoid arbitrary values unless aligning to a specific design spec.
Accessibility
WCAG AA — Text contrast and non-text contrast (ghost buttons, borders).
Focus states — All interactive elements have visible focus rings (focus-visible:ring-2, focus-visible:ring-ring).
Semantic markup — Use aria-label, aria-describedby, role where appropriate. Prefer native elements (<button>, <a>) over divs.
Reduced motion — Respect prefers-reduced-motion for animations. Transitions should clarify state, not distract.
Motion (Framer Motion)
Library: Framer Motion is available for declarative enter/exit, layout, and gesture-based animations.
Import path: Use @/lib/motion (re-exports motion, AnimatePresence, and types) so future reduced-motion or config changes stay centralized.
Reduced motion: When adding animated components, use the useReducedMotionTransition() hook from @/lib/motion for the transition prop so animations are disabled when the user prefers reduced motion. See lib/hooks.ts for usePrefersReducedMotion().
Guideline: Use motion to clarify state and hierarchy; avoid decorative or distracting animation.
Touch targets
Minimum 44×44pt for interactive elements (buttons, links, form controls).
Use min-h-11 (44px) or size-11 for touch-friendly buttons on mobile.
Ensure adequate spacing between tap targets to prevent mis-taps.
Dropdowns and popovers
Corner radius: Dropdowns/popovers that attach to triggers must use the same corner radius as the trigger.
first:rounded-l-lg last:rounded-r-lg (8px, on first/last cell per row)
—
Switch: Use for boolean toggles (e.g. Ask voice settings: Voice mode, Wake word). Wrap in min-h-[44px] min-w-[44px] flex items-center justify-center when a larger touch target is needed. From shadcn registry; has built-in focus-visible ring.
Table row cells: First and last cells (th or td) in each row use rounded-l-lg / rounded-r-lg (8px) in default and hover states. Requires border-separate border-spacing-0 on the table for rounded corners to render correctly.
Route-level loading UIs use shared skeleton components. They mirror mobile vs desktop layouts: tighter horizontal padding (px-4 → sm:px-6 / sm:px-8), primary CTA pairs stacked vertically with full-width controls on small viewports (flex-col → sm:flex-row), newsroom bento heroes with image on top and text block below on mobile (matching WritingsBentoCard), and section headers with title + “View archive” stacked on narrow screens. Inline skeletons in app/**/loading.tsx (e.g. pricing, archive, legal index) follow the same padding pattern.
p-8
gap-8
Large section breaks
Command
command.tsx
Command palette (⌘K)
Dialog
dialog.tsx
Modal dialogs
Dropdown Menu
dropdown-menu.tsx
Context menus, dropdown actions
Hover Card
hover-card.tsx
Hover-triggered popover
Input
input.tsx
Text input field
Input Group
input-group.tsx
Input with addons (prefix/suffix)
Pagination
pagination.tsx
Page navigation
Popover
popover.tsx
Floating popover content
Select
select.tsx
Dropdown select
Separator
separator.tsx
Visual divider
Sheet
sheet.tsx
Slide-out panel
Sidebar
sidebar.tsx
Collapsible sidebar layout
Skeleton
skeleton.tsx
Loading placeholder
Sonner
sonner.tsx
Toast notifications
Switch
switch.tsx
Toggle (Voice mode, Wake word in Ask voice settings sheet)