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):

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 via metadata.alternates.canonical on key pages (layout, stories, newsroom, pricing, story detail) to avoid duplicate content. Uses getLocalizedUrl() for locale-prefixed URLs.

Related

• ANALYTICS_SEO_PLAN.md — Full SEO/AEO plan, metrics, implementation phases
• ANALYTICS_IMPLEMENTATION.md — Events, env vars, GA4

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).

Spacing scale

Use a consistent spacing scale for padding, margins, and gaps:

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.
  • 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}).

UI alignment checklist

When aligning a component with a reference (screenshot or live example), verify before declaring done:

• Compared to reference screenshot or live example
• Trigger: radius, size, padding match
• Content: radius, position, overlap match
• Items: first/last/middle use context-aware radius (first:rounded-t-*, last:rounded-b-*)
• No conflicting transforms or offsets (check full styling chain)
• Docs updated only after verification

Component-specific notes

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.

Custom components (in components/ui)

Page skeletons (components/skeletons)

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.