@neynar/ui 0.3.0 → 0.4.0

package/src/components/ui/typography.tsx

@@ -1,1248 +1,572 @@
 import * as React from "react";
-import { Slot } from "@radix-ui/react-slot";
-import { cva, type VariantProps } from "class-variance-authority";
 
 import { cn } from "@/lib/utils";
 
 /**
- * Typography variant configuration using class-variance-authority
+ * Typography Components - Purpose-named, Tailwind-first text components
  *
- * Defines all possible typography variants, sizes, and styling options.
- * Uses Tailwind CSS 4 with custom CSS properties for theming.
- * Provides consistent text styling across the entire application.
+ * This module provides semantic typography components for web applications.
+ * Each component has a clear purpose and sensible Tailwind CSS defaults that
+ * can be fully overridden via the className prop.
  *
- * @variant microcopy - Very small text for fine print, timestamps, and metadata (text-xs)
- * @variant detail - Smaller text for details, captions, and descriptions (text-sm)
- * @variant body - Standard body text for readable content (text-base, leading-snug)
- * @variant blogBody - Body text for blog posts and long form content (text-lg, leading-loose)
- * @variant paragraphLead - Paragraph lead text for blog posts and long form content (text-lg)
- * @variant eyebrow - Eyebrow text for blog posts and long form content (text-xl)
- * @variant subHeadline - Secondary headings for subsections (text-2xl)
- * @variant headline - Primary headings for page/section titles (text-3xl)
- * @variant sectionTitle - Section titles (text-4xl, leading-relaxed)
- * @variant pageTitle - Page titles (text-5xl, leading-relaxed)
- * @variant displayTitle - Display titles (text-6xl, leading-snug)
- * @variant heroTitle - Hero titles (text-7xl, leading-snug)
- * @variant code - Monospace font for inline code, terminal commands, and technical references (text-base, font-mono)
+ * Design Philosophy:
+ * - Purpose-obvious naming (PageTitle, BodyText, Caption)
+ * - Semantic HTML defaults (h1, h2, p, etc.)
+ * - Tailwind-first with zero abstraction
+ * - Full className override control
+ * - Appropriate sizing for web apps (not marketing sites)
  *
- * @see {@link https://cva.style/docs} CVA documentation for variant patterns
- * @see {@link https://ui.shadcn.com/docs/components/typography} Typography component inspiration
- * @since 1.0.0
+ * @see {@link https://tailwindcss.com} Tailwind CSS documentation
+ * @since 2.0.0
  */
-const typographyVariants = cva("", {
-  variants: {
-    variant: {
-      microcopy: "text-xs",
-      detail: "text-sm",
-      body: "text-base leading-snug",
-      blogBody: "text-lg leading-loose",
-      paragraphLead: "text-lg",
-      eyebrow: "text-xl",
-      subHeadline: "text-2xl",
-      headline: "text-3xl",
-      sectionTitle: "text-4xl leading-relaxed",
-      pageTitle: "text-5xl leading-relaxed",
-      displayTitle: "text-6xl leading-snug",
-      heroTitle: "text-7xl leading-snug",
-      code: "text-base font-mono",
-    },
-    /**
-     * Color variants for different semantic meanings and visual hierarchy
-     *
-     * @variant default - Default text color that adapts to light/dark theme (text-foreground)
-     * @variant muted - Subdued text color for secondary information and descriptions (text-muted-foreground)
-     * @variant faint - Very subtle text color for minimal visual prominence (text-neynar-faint-foreground)
-     * @variant accent - Accent color for emphasis, highlights, and interactive elements (text-accent-foreground)
-     * @variant destructive - Red color for error messages, warnings, and destructive actions (text-destructive)
-     * @variant success - Green color for success messages, confirmations, and positive states (text-success)
-     * @variant warning - Orange/yellow color for warnings, cautions, and attention-seeking content (text-warning)
-     */
-    color: {
-      default: "text-foreground",
-      muted: "text-muted-foreground",
-      faint: "text-neynar-faint-foreground",
-      accent: "text-accent-foreground",
-      destructive: "text-destructive",
-      success: "text-success",
-      warning: "text-warning",
-    },
-    /**
-     * Text alignment options for layout control
-     *
-     * @variant left - Left-aligned text (default for LTR languages)
-     * @variant center - Center-aligned text for headings and callouts
-     * @variant right - Right-aligned text for numerical data and RTL content
-     * @variant justify - Justified text for formal documents and articles
-     */
-    align: {
-      left: "text-left",
-      center: "text-center",
-      right: "text-right",
-      justify: "text-justify",
-    },
-    /**
-     * Text transformation options for stylistic effects
-     *
-     * @variant uppercase - ALL CAPS for emphasis and labels
-     * @variant lowercase - all lowercase for stylistic consistency
-     * @variant capitalize - Title Case For Headings And Proper Nouns
-     */
-    transform: {
-      uppercase: "uppercase",
-      lowercase: "lowercase",
-      capitalize: "capitalize",
-    },
-    /**
-     * Font weight variations for visual hierarchy
-     *
-     * @variant normal - Normal font weight (400) for body text
-     * @variant medium - Medium font weight (500) for subtle emphasis
-     * @variant semibold - Semibold font weight (600) for headings and important text
-     * @variant bold - Bold font weight (700) for strong emphasis
-     */
-    weight: {
-      normal: "font-normal",
-      medium: "font-medium",
-      semibold: "font-semibold",
-      bold: "font-bold",
-    },
-  },
-  defaultVariants: {
-    variant: "body",
-    color: "default",
-    align: "left",
-  },
-});
 
-type TypographyVariant =
-  | "microcopy"
-  | "detail"
-  | "body"
-  | "blogBody"
-  | "paragraphLead"
-  | "eyebrow"
-  | "subHeadline"
-  | "headline"
-  | "sectionTitle"
-  | "pageTitle"
-  | "displayTitle"
-  | "heroTitle"
-  | "code";
-
-type TypographyColor =
-  | "default"
-  | "muted"
-  | "faint"
-  | "accent"
-  | "destructive"
-  | "success"
-  | "warning";
-
-// eslint-disable-next-line unused-imports/no-unused-vars
-type TypographyDocsProps = {
-  /** Typography variant that determines text size, weight, and line height @default "body" */
-  variant?: TypographyVariant;
-  /** Color variant for semantic meaning and visual hierarchy @default "default" */
-  color?: TypographyColor;
-  /** Text alignment within the container @default "left" */
-  align?: "left" | "center" | "right" | "justify";
-  /** Text transformation for stylistic effects */
-  transform?: "uppercase" | "lowercase" | "capitalize";
-  /** Font weight override for visual emphasis */
-  weight?: "normal" | "medium" | "semibold" | "bold";
-  /** The HTML element or component to render as @default "p" */
-  as?: React.ElementType;
-  /** For label elements, the associated input ID for accessibility */
-  htmlFor?: string;
-  /** Whether to render as a Slot component for composition patterns. When true, the component merges its props onto its immediate child instead of rendering its own DOM element @default false */
-  asChild?: boolean;
-  /** Whether the text should be rendered in italic style @default false */
-  italic?: boolean;
-  /** Whether the text should have underline decoration @default false */
-  underline?: boolean;
-  /** Whether the text should have strikethrough decoration @default false */
-  strikethrough?: boolean;
-  /** Whether text should be truncated with ellipsis on overflow @default false */
-  truncate?: boolean;
-  /** Hide visually but keep accessible to screen readers @default false */
-  srOnly?: boolean;
+/**
+ * Base typography component props
+ *
+ * All typography components accept these props:
+ * - `as` - The HTML element to render (each component has a sensible default)
+ * - `className` - Additional Tailwind classes to merge with defaults
+ * - `children` - Content to render
+ * - All standard HTML attributes for the underlying element
+ */
+type TypographyBaseProps<T extends React.ElementType> = {
+  /** The HTML element or component to render as */
+  as?: T;
   /** Additional CSS classes for custom styling */
   className?: string;
   /** Content to render within the typography element */
   children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLElement>;
+};
+
+type TypographyProps<T extends React.ElementType> = TypographyBaseProps<T> &
+  Omit<React.ComponentPropsWithoutRef<T>, keyof TypographyBaseProps<T>>;
 
 /**
- * Base props for all Typography components
+ * Props for PageTitle (Documentation only - NOT used in component implementation)
  */
-type TypographyBaseProps = {
-  /** Typography variant that determines text size, weight, and line height */
-  variant?: TypographyVariant;
-  /** Color variant for semantic meaning and visual hierarchy */
-  color?: TypographyColor;
-  /** Text alignment within the container */
-  align?: VariantProps<typeof typographyVariants>["align"];
-  /** Text transformation for stylistic effects */
-  transform?: VariantProps<typeof typographyVariants>["transform"];
-  /** Font weight override for visual emphasis */
-  weight?: VariantProps<typeof typographyVariants>["weight"];
-  /** The HTML element or component to render as @default "p" */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type PageTitleDocsProps = {
+  /** The HTML element to render @default "h1" */
   as?: React.ElementType;
-  /** For label elements, the associated input ID for accessibility */
-  htmlFor?: string;
-  /** Whether to render as a Slot component for composition patterns @default false */
-  asChild?: boolean;
-  /** Whether the text should be rendered in italic style @default false */
-  italic?: boolean;
-  /** Whether the text should have underline decoration @default false */
-  underline?: boolean;
-  /** Whether the text should have strikethrough decoration @default false */
-  strikethrough?: boolean;
-  /** Whether text should be truncated with ellipsis on overflow @default false */
-  truncate?: boolean;
-  /** Hide visually but keep accessible to screen readers @default false */
-  srOnly?: boolean;
-  /** Additional CSS classes for custom styling */
+  /** Additional Tailwind CSS classes to customize styling */
   className?: string;
-  /** Content to render within the typography element */
+  /** Content to render within the page title */
   children?: React.ReactNode;
-};
+} & React.HTMLAttributes<HTMLHeadingElement>;
 
 /**
- * Complete props for the Typography component
+ * Props for SectionTitle (Documentation only - NOT used in component implementation)
  */
-type TypographyProps = TypographyBaseProps &
-  Omit<React.HTMLAttributes<HTMLElement>, keyof TypographyBaseProps>;
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SectionTitleDocsProps = {
+  /** The HTML element to render @default "h2" */
+  as?: React.ElementType;
+  /** Additional Tailwind CSS classes to customize styling */
+  className?: string;
+  /** Content to render within the section title */
+  children?: React.ReactNode;
+} & React.HTMLAttributes<HTMLHeadingElement>;
 
 /**
- * Typography - Comprehensive text styling component for consistent design system implementation
- *
- * A flexible typography component that provides semantic text variants, color options, and accessibility features.
- * Built with class-variance-authority (CVA) for type-safe variant management and supports both semantic HTML
- * elements and composition patterns via Radix UI Slot. Designed to handle all text styling needs across
- * the application with consistent visual hierarchy and accessibility compliance.
- *
- * @example
- * ```tsx
- * // Basic heading with semantic HTML
- * <Typography variant="heading" as="h1">
- *   Welcome to Neynar
- * </Typography>
- *
- * // Body text with color variant
- * <Typography variant="body" color="muted">
- *   This is secondary body text with reduced visual prominence.
- * </Typography>
- *
- * // Code snippet with proper semantics
- * <Typography variant="code" as="code">
- *   const message = "Hello, world!";
- * </Typography>
- * ```
- *
- * @example
- * ```tsx
- * // Advanced styling with multiple variants
- * <Typography
- *   variant="subheading"
- *   color="accent"
- *   align="center"
- *   weight="semibold"
- *   italic
- *   underline
- *   className="mb-4"
- * >
- *   Styled Subheading with Multiple Variants
- * </Typography>
- *
- * // Truncated text for constrained layouts
- * <Typography variant="body" truncate className="max-w-xs">
- *   This is a very long text that will be truncated with ellipsis when it exceeds the container width
- * </Typography>
- * ```
- *
- * @example
- * ```tsx
- * // Accessibility features
- * <Typography variant="details" srOnly>
- *   Additional context for screen readers only
- * </Typography>
- *
- * // Form label with proper association
- * <Typography variant="field" as="label" htmlFor="email-input">
- *   Email Address
- * </Typography>
- *
- * // Composition with asChild for complex structures
- * <Typography variant="body" asChild>
- *   <a href="/about" className="hover:underline">
- *     Learn more about our platform
- *   </a>
- * </Typography>
- * ```
- *
- * @accessibility
- * - **Semantic HTML**: Uses appropriate HTML elements via `as` prop for proper document structure
- * - **Screen Reader Support**: `srOnly` prop provides content accessible only to assistive technologies
- * - **Color Contrast**: All color variants meet WCAG 2.1 AA contrast requirements (4.5:1 minimum)
- * - **Label Association**: `htmlFor` prop properly associates labels with form controls
- * - **Focus Management**: Interactive elements receive proper focus indicators
- * - **Text Scaling**: All font sizes scale appropriately with user's browser text size preferences
- * - **High Contrast Mode**: Respects system high contrast mode preferences
- *
- * @performance
- * - Uses CVA for efficient class generation and tree-shaking
- * - Minimal runtime overhead with compile-time optimizations
- * - Cached class combinations for repeated variant usage
- *
- * @see {@link H1} Semantic H1 heading component
- * @see {@link H2} Semantic H2 heading component
- * @see {@link P} Semantic paragraph component
- * @see {@link Code} Semantic code element component
- * @see {@link https://cva.style/docs} Class Variance Authority documentation
- * @see {@link https://ui.shadcn.com/docs/components/typography} shadcn/ui Typography reference
- * @since 1.0.0
+ * Props for SubsectionTitle (Documentation only - NOT used in component implementation)
  */
-function Typography({
-  className,
-  variant,
-  color,
-  align,
-  transform,
-  weight,
-  as: Element = "p",
-  asChild = false,
-  italic = false,
-  underline = false,
-  strikethrough = false,
-  truncate = false,
-  srOnly = false,
-  ...props
-}: TypographyProps) {
-  const Comp = asChild ? Slot : Element;
-
-  return (
-    <Comp
-      data-slot="typography"
-      className={cn(
-        typographyVariants({ variant, color, align, transform, weight }),
-        {
-          italic,
-          underline,
-          "line-through": strikethrough,
-          "truncate overflow-hidden text-ellipsis whitespace-nowrap": truncate,
-          "sr-only": srOnly,
-        },
-        className,
-      )}
-      {...props}
-    />
-  );
-}
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SubsectionTitleDocsProps = {
+  /** The HTML element to render @default "h3" */
+  as?: React.ElementType;
+  /** Additional Tailwind CSS classes to customize styling */
+  className?: string;
+  /** Content to render within the subsection title */
+  children?: React.ReactNode;
+} & React.HTMLAttributes<HTMLHeadingElement>;
 
 /**
- * Individual semantic typography components with pre-configured defaults
- *
- * These components provide semantic HTML elements with pre-configured typography variants,
- * ensuring consistent styling while maintaining proper document structure and accessibility.
- * Each component uses the appropriate HTML element and typography variant for its semantic meaning.
+ * Props for BodyText (Documentation only - NOT used in component implementation)
  */
-
 // eslint-disable-next-line unused-imports/no-unused-vars
-type H1DocsProps = {
-  /** Color variant for semantic meaning and visual hierarchy @default "default" */
-  color?: TypographyColor;
-  /** Text alignment within the container @default "left" */
-  align?: "left" | "center" | "right" | "justify";
-  /** Text transformation for stylistic effects */
-  transform?: "uppercase" | "lowercase" | "capitalize";
-  /** Font weight override for visual emphasis */
-  weight?: "normal" | "medium" | "semibold" | "bold";
-  /** For label elements, the associated input ID for accessibility */
-  htmlFor?: string;
-  /** Whether to render as a Slot component for composition patterns @default false */
-  asChild?: boolean;
-  /** Whether the text should be rendered in italic style @default false */
-  italic?: boolean;
-  /** Whether the text should have underline decoration @default false */
-  underline?: boolean;
-  /** Whether the text should have strikethrough decoration @default false */
-  strikethrough?: boolean;
-  /** Whether text should be truncated with ellipsis on overflow @default false */
-  truncate?: boolean;
-  /** Hide visually but keep accessible to screen readers @default false */
-  srOnly?: boolean;
-  /** Additional CSS classes for custom styling */
+type BodyTextDocsProps = {
+  /** The HTML element to render @default "p" */
+  as?: React.ElementType;
+  /** Additional Tailwind CSS classes to customize styling */
   className?: string;
-  /** Content to render within the typography element */
+  /** Content to render within the body text */
   children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLHeadingElement>;
-
-/** Props for H1 heading component */
-type H1Props = Omit<TypographyProps, "as">;
+} & React.HTMLAttributes<HTMLParagraphElement>;
 
 /**
- * H1 - Primary page heading component
- *
- * The main heading for a page or major section. Uses the "displayTitle" variant with h1 semantic element.
- * Should be used once per page for proper document outline and SEO.
- *
- * @example
- * ```tsx
- * // Page title
- * <H1>Welcome to Neynar Platform</H1>
- *
- * // With color variant
- * <H1 color="muted">Draft: Article Title</H1>
- *
- * // With custom styling
- * <H1 align="center" className="mb-8">
- *   Centered Page Heading
- * </H1>
- * ```
- *
- * @accessibility
- * - Creates proper document outline structure
- * - Should be the first heading on the page
- * - Provides main page topic for screen readers
- * - Helps with keyboard navigation landmarks
- *
- * @see {@link H2} Secondary heading component
- * @see {@link Typography} Base typography component
+ * Props for BodyTextLarge (Documentation only - NOT used in component implementation)
  */
-function H1({ variant = "displayTitle", weight = "bold", ...props }: H1Props) {
-  return <Typography variant={variant} weight={weight} as="h1" {...props} />;
-}
-
 // eslint-disable-next-line unused-imports/no-unused-vars
-type H2DocsProps = {
-  /** Color variant for semantic meaning and visual hierarchy @default "default" */
-  color?: TypographyColor;
-  /** Text alignment within the container @default "left" */
-  align?: "left" | "center" | "right" | "justify";
-  /** Text transformation for stylistic effects */
-  transform?: "uppercase" | "lowercase" | "capitalize";
-  /** Font weight override for visual emphasis */
-  weight?: "normal" | "medium" | "semibold" | "bold";
-  /** For label elements, the associated input ID for accessibility */
-  htmlFor?: string;
-  /** Whether to render as a Slot component for composition patterns @default false */
-  asChild?: boolean;
-  /** Whether the text should be rendered in italic style @default false */
-  italic?: boolean;
-  /** Whether the text should have underline decoration @default false */
-  underline?: boolean;
-  /** Whether the text should have strikethrough decoration @default false */
-  strikethrough?: boolean;
-  /** Whether text should be truncated with ellipsis on overflow @default false */
-  truncate?: boolean;
-  /** Hide visually but keep accessible to screen readers @default false */
-  srOnly?: boolean;
-  /** Additional CSS classes for custom styling */
+type BodyTextLargeDocsProps = {
+  /** The HTML element to render @default "p" */
+  as?: React.ElementType;
+  /** Additional Tailwind CSS classes to customize styling */
   className?: string;
-  /** Content to render within the typography element */
+  /** Content to render within the large body text */
   children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLHeadingElement>;
-
-/** Props for H2 heading component */
-type H2Props = Omit<TypographyProps, "as">;
+} & React.HTMLAttributes<HTMLParagraphElement>;
 
 /**
- * H2 - Secondary section heading component
- *
- * Section headings that divide page content into logical groups. Uses the "sectionTitle" variant
- * with h2 semantic element. Essential for creating proper document hierarchy.
- *
- * @example
- * ```tsx
- * // Section heading
- * <H2>Getting Started</H2>
- *
- * // With accent color
- * <H2 color="accent">Featured Content</H2>
- *
- * // With additional styling
- * <H2 weight="bold" className="border-b pb-2">
- *   Section with Border
- * </H2>
- * ```
- *
- * @accessibility
- * - Maintains document outline hierarchy
- * - Should follow H1 and precede H3 elements
- * - Provides section navigation for screen readers
- * - Essential for skip navigation functionality
- *
- * @see {@link H1} Primary heading component
- * @see {@link H3} Tertiary heading component
+ * Props for BodyTextSmall (Documentation only - NOT used in component implementation)
  */
-function H2({ variant = "sectionTitle", weight = "bold", ...props }: H2Props) {
-  return <Typography variant={variant} weight={weight} as="h2" {...props} />;
-}
-
 // eslint-disable-next-line unused-imports/no-unused-vars
-type H3DocsProps = {
-  /** Color variant for semantic meaning and visual hierarchy @default "default" */
-  color?: TypographyColor;
-  /** Text alignment within the container @default "left" */
-  align?: "left" | "center" | "right" | "justify";
-  /** Text transformation for stylistic effects */
-  transform?: "uppercase" | "lowercase" | "capitalize";
-  /** Font weight override for visual emphasis */
-  weight?: "normal" | "medium" | "semibold" | "bold";
-  /** For label elements, the associated input ID for accessibility */
-  htmlFor?: string;
-  /** Whether to render as a Slot component for composition patterns @default false */
-  asChild?: boolean;
-  /** Whether the text should be rendered in italic style @default false */
-  italic?: boolean;
-  /** Whether the text should have underline decoration @default false */
-  underline?: boolean;
-  /** Whether the text should have strikethrough decoration @default false */
-  strikethrough?: boolean;
-  /** Whether text should be truncated with ellipsis on overflow @default false */
-  truncate?: boolean;
-  /** Hide visually but keep accessible to screen readers @default false */
-  srOnly?: boolean;
-  /** Additional CSS classes for custom styling */
+type BodyTextSmallDocsProps = {
+  /** The HTML element to render @default "p" */
+  as?: React.ElementType;
+  /** Additional Tailwind CSS classes to customize styling */
   className?: string;
-  /** Content to render within the typography element */
+  /** Content to render within the small body text */
   children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLHeadingElement>;
-
-/** Props for H3 heading component */
-type H3Props = Omit<TypographyProps, "as">;
+} & React.HTMLAttributes<HTMLParagraphElement>;
 
 /**
- * H3 - Tertiary subsection heading component
- *
- * Subsection headings for further content division. Uses the "headline" variant
- * with h3 semantic element for consistent visual hierarchy.
- *
- * @example
- * ```tsx
- * // Subsection heading
- * <H3>Installation Guide</H3>
- *
- * // In a card or content block
- * <H3 color="muted" className="mb-3">
- *   Optional Configuration
- * </H3>
- * ```
- *
- * @accessibility
- * - Should follow H2 elements in document flow
- * - Helps create detailed content structure
- * - Improves navigation with assistive technologies
- * - Supports table of contents generation
+ * Props for Caption (Documentation only - NOT used in component implementation)
  */
-function H3({ variant = "headline", weight = "bold", ...props }: H3Props) {
-  return <Typography variant={variant} weight={weight} as="h3" {...props} />;
-}
-
 // eslint-disable-next-line unused-imports/no-unused-vars
-type H4DocsProps = {
-  /** Color variant for semantic meaning and visual hierarchy @default "default" */
-  color?: TypographyColor;
-  /** Text alignment within the container @default "left" */
-  align?: "left" | "center" | "right" | "justify";
-  /** Text transformation for stylistic effects */
-  transform?: "uppercase" | "lowercase" | "capitalize";
-  /** Font weight override for visual emphasis */
-  weight?: "normal" | "medium" | "semibold" | "bold";
-  /** For label elements, the associated input ID for accessibility */
-  htmlFor?: string;
-  /** Whether to render as a Slot component for composition patterns @default false */
-  asChild?: boolean;
-  /** Whether the text should be rendered in italic style @default false */
-  italic?: boolean;
-  /** Whether the text should have underline decoration @default false */
-  underline?: boolean;
-  /** Whether the text should have strikethrough decoration @default false */
-  strikethrough?: boolean;
-  /** Whether text should be truncated with ellipsis on overflow @default false */
-  truncate?: boolean;
-  /** Hide visually but keep accessible to screen readers @default false */
-  srOnly?: boolean;
-  /** Additional CSS classes for custom styling */
+type CaptionDocsProps = {
+  /** The HTML element to render @default "span" */
+  as?: React.ElementType;
+  /** Additional Tailwind CSS classes to customize styling */
   className?: string;
-  /** Content to render within the typography element */
+  /** Content to render within the caption */
   children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLHeadingElement>;
-
-/** Props for H4 heading component */
-type H4Props = Omit<TypographyProps, "as">;
+} & React.HTMLAttributes<HTMLSpanElement>;
 
 /**
- * H4 - Minor heading component for detailed sections
- *
- * Minor headings for detailed content organization. Uses "subHeadline" variant
- * with h4 semantic element for subtle but distinct hierarchy.
- *
- * @example
- * ```tsx
- * // Minor section heading
- * <H4>Configuration Options</H4>
- *
- * // In detailed documentation
- * <H4 color="muted">Advanced Settings</H4>
- * ```
- *
- * @accessibility
- * - Maintains proper heading hierarchy flow
- * - Provides fine-grained content organization
- * - Supports screen reader document navigation
+ * Props for Overline (Documentation only - NOT used in component implementation)
  */
-function H4({ variant = "subHeadline", weight = "bold", ...props }: H4Props) {
-  return <Typography variant={variant} weight={weight} as="h4" {...props} />;
-}
-
 // eslint-disable-next-line unused-imports/no-unused-vars
-type H5DocsProps = {
-  /** Color variant for semantic meaning and visual hierarchy @default "default" */
-  color?: TypographyColor;
-  /** Text alignment within the container @default "left" */
-  align?: "left" | "center" | "right" | "justify";
-  /** Text transformation for stylistic effects */
-  transform?: "uppercase" | "lowercase" | "capitalize";
-  /** Font weight override for visual emphasis */
-  weight?: "normal" | "medium" | "semibold" | "bold";
-  /** For label elements, the associated input ID for accessibility */
-  htmlFor?: string;
-  /** Whether to render as a Slot component for composition patterns @default false */
-  asChild?: boolean;
-  /** Whether the text should be rendered in italic style @default false */
-  italic?: boolean;
-  /** Whether the text should have underline decoration @default false */
-  underline?: boolean;
-  /** Whether the text should have strikethrough decoration @default false */
-  strikethrough?: boolean;
-  /** Whether text should be truncated with ellipsis on overflow @default false */
-  truncate?: boolean;
-  /** Hide visually but keep accessible to screen readers @default false */
-  srOnly?: boolean;
-  /** Additional CSS classes for custom styling */
+type OverlineDocsProps = {
+  /** The HTML element to render @default "span" */
+  as?: React.ElementType;
+  /** Additional Tailwind CSS classes to customize styling */
   className?: string;
-  /** Content to render within the typography element */
+  /** Content to render within the overline */
   children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLHeadingElement>;
-
-/** Props for H5 heading component */
-type H5Props = Omit<TypographyProps, "as">;
+} & React.HTMLAttributes<HTMLSpanElement>;
 
 /**
- * H5 - Small heading component for micro-sections
- *
- * Small headings for very specific content divisions. Uses "eyebrow" variant
- * with h5 semantic element.
- *
- * @example
- * ```tsx
- * // Small section heading
- * <H5>Error Codes</H5>
- *
- * // In lists or detailed breakdowns
- * <H5 weight="semibold">Step 1: Setup</H5>
- * ```
+ * Props for Code (Documentation only - NOT used in component implementation)
  */
-function H5({ variant = "eyebrow", weight = "bold", ...props }: H5Props) {
-  return <Typography variant={variant} weight={weight} as="h5" {...props} />;
-}
-
 // eslint-disable-next-line unused-imports/no-unused-vars
-type H6DocsProps = {
-  /** Color variant for semantic meaning and visual hierarchy @default "default" */
-  color?: TypographyColor;
-  /** Text alignment within the container @default "left" */
-  align?: "left" | "center" | "right" | "justify";
-  /** Text transformation for stylistic effects */
-  transform?: "uppercase" | "lowercase" | "capitalize";
-  /** Font weight override for visual emphasis */
-  weight?: "normal" | "medium" | "semibold" | "bold";
-  /** For label elements, the associated input ID for accessibility */
-  htmlFor?: string;
-  /** Whether to render as a Slot component for composition patterns @default false */
-  asChild?: boolean;
-  /** Whether the text should be rendered in italic style @default false */
-  italic?: boolean;
-  /** Whether the text should have underline decoration @default false */
-  underline?: boolean;
-  /** Whether the text should have strikethrough decoration @default false */
-  strikethrough?: boolean;
-  /** Whether text should be truncated with ellipsis on overflow @default false */
-  truncate?: boolean;
-  /** Hide visually but keep accessible to screen readers @default false */
-  srOnly?: boolean;
-  /** Additional CSS classes for custom styling */
+type CodeDocsProps = {
+  /** The HTML element to render @default "code" */
+  as?: React.ElementType;
+  /** Additional Tailwind CSS classes to customize styling */
   className?: string;
-  /** Content to render within the typography element */
+  /** Content to render within the code element */
   children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLHeadingElement>;
-
-/** Props for H6 heading component */
-type H6Props = Omit<TypographyProps, "as">;
+} & React.HTMLAttributes<HTMLElement>;
 
 /**
- * H6 - Smallest heading component for minimal emphasis
- *
- * The smallest semantic heading level. Uses "details" variant with h6 element
- * for minimal but semantic emphasis.
- *
- * @example
- * ```tsx
- * // Smallest heading
- * <H6>Notes and Disclaimers</H6>
- *
- * // In deeply nested content
- * <H6 color="muted">Technical Details</H6>
- * ```
+ * Props for Blockquote (Documentation only - NOT used in component implementation)
  */
-function H6({ variant = "body", weight = "bold", ...props }: H6Props) {
-  return <Typography variant={variant} weight={weight} as="h6" {...props} />;
-}
-
 // eslint-disable-next-line unused-imports/no-unused-vars
-type PDocsProps = {
-  /** Color variant for semantic meaning and visual hierarchy @default "default" */
-  color?: TypographyColor;
-  /** Text alignment within the container @default "left" */
-  align?: "left" | "center" | "right" | "justify";
-  /** Text transformation for stylistic effects */
-  transform?: "uppercase" | "lowercase" | "capitalize";
-  /** Font weight override for visual emphasis */
-  weight?: "normal" | "medium" | "semibold" | "bold";
-  /** For label elements, the associated input ID for accessibility */
-  htmlFor?: string;
-  /** Whether to render as a Slot component for composition patterns @default false */
-  asChild?: boolean;
-  /** Whether the text should be rendered in italic style @default false */
-  italic?: boolean;
-  /** Whether the text should have underline decoration @default false */
-  underline?: boolean;
-  /** Whether the text should have strikethrough decoration @default false */
-  strikethrough?: boolean;
-  /** Whether text should be truncated with ellipsis on overflow @default false */
-  truncate?: boolean;
-  /** Hide visually but keep accessible to screen readers @default false */
-  srOnly?: boolean;
-  /** Additional CSS classes for custom styling */
+type BlockquoteDocsProps = {
+  /** The HTML element to render @default "blockquote" */
+  as?: React.ElementType;
+  /** Additional Tailwind CSS classes to customize styling */
   className?: string;
-  /** Content to render within the typography element */
+  /** Content to render within the blockquote */
   children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLParagraphElement>;
-
-/** Props for P paragraph component */
-type PProps = Omit<TypographyProps, "as">;
+} & React.HTMLAttributes<HTMLQuoteElement>;
 
 /**
- * P - Paragraph component for body text content
+ * PageTitle - Primary page heading component
  *
- * Standard paragraph element for readable body text. Uses "body" variant with p semantic element.
- * Optimized for readability with appropriate line height and font size.
+ * The main heading for a page, typically used once per page. Uses text-3xl (30px)
+ * which is appropriate for web application page titles. Defaults to h1 element.
+ *
+ * @param as - HTML element to render @default "h1"
+ * @param className - Additional Tailwind classes (e.g., "text-4xl text-accent")
+ * @param children - Content to render
+ * @param ...props - All standard HTMLHeadingElement attributes
  *
  * @example
  * ```tsx
- * // Standard paragraph
- * <P>This is standard body text that provides information to the user.</P>
+ * // Default usage
+ * <PageTitle>User Dashboard</PageTitle>
  *
- * // With color variants
- * <P color="muted">Secondary information with reduced visual prominence.</P>
+ * // With custom styling
+ * <PageTitle className="text-4xl text-accent">
+ *   Custom Styled Title
+ * </PageTitle>
  *
- * // With custom spacing
- * <P className="mb-6">Paragraph with custom bottom margin for layout control.</P>
+ * // As different element
+ * <PageTitle as="h2">Section Title as H2</PageTitle>
  *
- * // Truncated paragraph
- * <P truncate className="max-w-md">
- *   Long paragraph content that will be truncated with ellipsis
- * </P>
+ * // Responsive sizing
+ * <PageTitle className="text-2xl md:text-3xl lg:text-4xl">
+ *   Responsive Title
+ * </PageTitle>
  * ```
  *
  * @accessibility
- * - Provides proper semantic structure for body content
- * - Maintains readable line height for accessibility
- * - Supports screen reader text flow and navigation
- *
- * @see {@link Typography} Base typography component
+ * - Should be used once per page for proper document outline
+ * - Provides main page topic for screen readers
+ * - Helps with keyboard navigation landmarks
  */
-function P(props: PProps) {
-  return <Typography as="p" {...props} />;
+export function PageTitle<T extends React.ElementType = "h1">({
+  className,
+  as,
+  ...props
+}: TypographyProps<T>) {
+  const Component = as || "h1";
+  return (
+    <Component
+      className={cn("text-3xl font-bold leading-tight tracking-wide", className)}
+      {...props}
+    />
+  );
 }
 
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SpanDocsProps = {
-  /** Typography variant that determines text size, weight, and line height @default "body" */
-  variant?: TypographyVariant;
-  /** Color variant for semantic meaning and visual hierarchy @default "default" */
-  color?: TypographyColor;
-  /** Text alignment within the container @default "left" */
-  align?: "left" | "center" | "right" | "justify";
-  /** Text transformation for stylistic effects */
-  transform?: "uppercase" | "lowercase" | "capitalize";
-  /** Font weight override for visual emphasis */
-  weight?: "normal" | "medium" | "semibold" | "bold";
-  /** For label elements, the associated input ID for accessibility */
-  htmlFor?: string;
-  /** Whether to render as a Slot component for composition patterns @default false */
-  asChild?: boolean;
-  /** Whether the text should be rendered in italic style @default false */
-  italic?: boolean;
-  /** Whether the text should have underline decoration @default false */
-  underline?: boolean;
-  /** Whether the text should have strikethrough decoration @default false */
-  strikethrough?: boolean;
-  /** Whether text should be truncated with ellipsis on overflow @default false */
-  truncate?: boolean;
-  /** Hide visually but keep accessible to screen readers @default false */
-  srOnly?: boolean;
-  /** Additional CSS classes for custom styling */
-  className?: string;
-  /** Content to render within the typography element */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLSpanElement>;
-
-/** Props for Span inline component */
-type SpanProps = Omit<TypographyProps, "as">;
-
 /**
- * Span - Inline text component for text fragments and styling
+ * SectionTitle - Secondary section heading component
+ *
+ * Section headings that divide page content into logical groups. Uses text-2xl (24px)
+ * for clear hierarchy below PageTitle. Defaults to h2 element.
  *
- * Generic inline element for styling text fragments within other content.
- * Supports all typography variants while maintaining inline display behavior.
+ * @param as - HTML element to render @default "h2"
+ * @param className - Additional Tailwind classes
+ * @param children - Content to render
+ * @param ...props - All standard HTMLHeadingElement attributes
  *
  * @example
  * ```tsx
- * // Inline text styling
- * <p>
- *   Regular text with <Span color="accent" weight="semibold">highlighted</Span> content
- * </p>
+ * // Default usage
+ * <SectionTitle>Recent Activity</SectionTitle>
  *
- * // Small inline details
- * <Span variant="details" color="muted">
- *   Updated 5 minutes ago
- * </Span>
+ * // With custom color
+ * <SectionTitle className="text-accent">
+ *   Featured Section
+ * </SectionTitle>
  *
- * // Inline code reference
- * <Span variant="code" className="bg-muted px-1 rounded">
- *   onClick
- * </Span>
+ * // As h3 element
+ * <SectionTitle as="h3">Subsection Title</SectionTitle>
  * ```
  *
  * @accessibility
- * - Maintains inline text flow for screen readers
- * - Preserves semantic meaning within larger text blocks
- * - Does not interrupt document structure or navigation
+ * - Maintains document outline hierarchy
+ * - Should follow PageTitle (h1) in document flow
+ * - Provides section navigation for screen readers
  */
-function Span(props: SpanProps) {
-  return <Typography as="span" {...props} />;
+export function SectionTitle<T extends React.ElementType = "h2">({
+  className,
+  as,
+  ...props
+}: TypographyProps<T>) {
+  const Component = as || "h2";
+  return (
+    <Component
+      className={cn("text-2xl font-semibold leading-tight tracking-wide", className)}
+      {...props}
+    />
+  );
 }
 
-// eslint-disable-next-line unused-imports/no-unused-vars
-type CodeDocsProps = {
-  /** Color variant for semantic meaning and visual hierarchy @default "default" */
-  color?: TypographyColor;
-  /** Text alignment within the container @default "left" */
-  align?: "left" | "center" | "right" | "justify";
-  /** Text transformation for stylistic effects */
-  transform?: "uppercase" | "lowercase" | "capitalize";
-  /** Font weight override for visual emphasis */
-  weight?: "normal" | "medium" | "semibold" | "bold";
-  /** For label elements, the associated input ID for accessibility */
-  htmlFor?: string;
-  /** Whether to render as a Slot component for composition patterns @default false */
-  asChild?: boolean;
-  /** Whether the text should be rendered in italic style @default false */
-  italic?: boolean;
-  /** Whether the text should have underline decoration @default false */
-  underline?: boolean;
-  /** Whether the text should have strikethrough decoration @default false */
-  strikethrough?: boolean;
-  /** Whether text should be truncated with ellipsis on overflow @default false */
-  truncate?: boolean;
-  /** Hide visually but keep accessible to screen readers @default false */
-  srOnly?: boolean;
-  /** Additional CSS classes for custom styling */
-  className?: string;
-  /** Content to render within the typography element */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLElement>;
-
-/** Props for Code component */
-type CodeProps = Omit<TypographyProps, "as" | "variant">;
-
 /**
- * Code - Inline code component for technical content
+ * SubsectionTitle - Tertiary subsection heading component
+ *
+ * Subsection headings for further content division. Uses text-xl (20px) for
+ * subtle distinction from SectionTitle. Defaults to h3 element.
  *
- * Semantic code element for inline code snippets, variable names, and technical references.
- * Uses monospace font and "code" variant for clear distinction from regular text.
+ * @param as - HTML element to render @default "h3"
+ * @param className - Additional Tailwind classes
+ * @param children - Content to render
+ * @param ...props - All standard HTMLHeadingElement attributes
  *
  * @example
  * ```tsx
- * // Inline code snippet
- * <Code>const message = "Hello, world!";</Code>
- *
- * // Terminal command
- * <Code color="muted">npm install @neynar/react</Code>
+ * // Default usage
+ * <SubsectionTitle>Configuration Options</SubsectionTitle>
  *
- * // Variable reference
- * <p>Set the <Code>API_KEY</Code> environment variable.</p>
- *
- * // With background styling
- * <Code className="bg-muted px-2 py-1 rounded">
- *   function handleClick()
- * </Code>
+ * // With custom styling
+ * <SubsectionTitle className="text-muted-foreground">
+ *   Optional Settings
+ * </SubsectionTitle>
  * ```
  *
  * @accessibility
- * - Uses semantic code element for proper meaning
- * - Monospace font aids in code readability
- * - Screen readers understand this as technical content
- * - Maintains proper inline behavior within text
- *
- * @see {@link Typography} Base typography component for multi-line code blocks
+ * - Should follow SectionTitle (h2) in document flow
+ * - Helps create detailed content structure
+ * - Supports screen reader document navigation
  */
-function Code(props: CodeProps) {
-  return <Typography variant="code" as="code" {...props} />;
+export function SubsectionTitle<T extends React.ElementType = "h3">({
+  className,
+  as,
+  ...props
+}: TypographyProps<T>) {
+  const Component = as || "h3";
+  return (
+    <Component
+      className={cn("text-xl font-semibold leading-snug tracking-wide", className)}
+      {...props}
+    />
+  );
 }
 
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SmallDocsProps = {
-  /** Color variant for semantic meaning and visual hierarchy @default "default" */
-  color?: TypographyColor;
-  /** Text alignment within the container @default "left" */
-  align?: "left" | "center" | "right" | "justify";
-  /** Text transformation for stylistic effects */
-  transform?: "uppercase" | "lowercase" | "capitalize";
-  /** Font weight override for visual emphasis */
-  weight?: "normal" | "medium" | "semibold" | "bold";
-  /** For label elements, the associated input ID for accessibility */
-  htmlFor?: string;
-  /** Whether to render as a Slot component for composition patterns @default false */
-  asChild?: boolean;
-  /** Whether the text should be rendered in italic style @default false */
-  italic?: boolean;
-  /** Whether the text should have underline decoration @default false */
-  underline?: boolean;
-  /** Whether the text should have strikethrough decoration @default false */
-  strikethrough?: boolean;
-  /** Whether text should be truncated with ellipsis on overflow @default false */
-  truncate?: boolean;
-  /** Hide visually but keep accessible to screen readers @default false */
-  srOnly?: boolean;
-  /** Additional CSS classes for custom styling */
-  className?: string;
-  /** Content to render within the typography element */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLElement>;
-
-/** Props for Small component */
-type SmallProps = Omit<TypographyProps, "as">;
-
 /**
- * Small - Fine print component for supplementary information
+ * BodyText - Primary paragraph text component
+ *
+ * Standard paragraph element for readable body text. Uses text-base (16px) with
+ * relaxed line height for optimal readability. Defaults to p element.
  *
- * Semantic small element for fine print, disclaimers, timestamps, and supplementary information.
- * Uses "microcopy" variant for reduced visual prominence while maintaining readability.
+ * @param as - HTML element to render @default "p"
+ * @param className - Additional Tailwind classes
+ * @param children - Content to render
+ * @param ...props - All standard HTMLParagraphElement attributes
  *
  * @example
  * ```tsx
- * // Legal disclaimer
- * <Small>Terms and conditions apply. See details for more information.</Small>
- *
- * // Timestamp or metadata
- * <Small color="muted">Last updated 2 minutes ago</Small>
- *
- * // Copyright notice
- * <Small className="text-center">
- *   © 2024 Neynar. All rights reserved.
- * </Small>
+ * // Default usage
+ * <BodyText>
+ *   This is standard body text that provides information to the user.
+ * </BodyText>
  *
- * // Form help text
- * <Small color="muted">Password must be at least 8 characters long.</Small>
+ * // With custom styling
+ * <BodyText className="text-muted-foreground">
+ *   Secondary information with reduced visual prominence.
+ * </BodyText>
+ *
+ * // As different element
+ * <BodyText as="div">
+ *   Body text in a div container.
+ * </BodyText>
  * ```
  *
  * @accessibility
- * - Uses semantic small element for proper meaning
- * - Indicates fine print or less important information
- * - Maintains sufficient contrast for readability
- * - Works well with form help text and descriptions
+ * - Provides proper semantic structure for body content
+ * - Maintains readable line height for accessibility
+ * - Supports screen reader text flow and navigation
  */
-function Small({ variant = "detail", ...props }: SmallProps) {
-  return <Typography variant={variant} as="small" {...props} />;
+export function BodyText<T extends React.ElementType = "p">({
+  className,
+  as,
+  ...props
+}: TypographyProps<T>) {
+  const Component = as || "p";
+  return (
+    <Component
+      className={cn("text-base leading-relaxed tracking-wide", className)}
+      {...props}
+    />
+  );
 }
 
-// eslint-disable-next-line unused-imports/no-unused-vars
-type StrongDocsProps = {
-  /** Color variant for semantic meaning and visual hierarchy @default "default" */
-  color?: TypographyColor;
-  /** Text alignment within the container @default "left" */
-  align?: "left" | "center" | "right" | "justify";
-  /** Text transformation for stylistic effects */
-  transform?: "uppercase" | "lowercase" | "capitalize";
-  /** Font weight override for visual emphasis */
-  weight?: "normal" | "medium" | "semibold" | "bold";
-  /** For label elements, the associated input ID for accessibility */
-  htmlFor?: string;
-  /** Whether to render as a Slot component for composition patterns @default false */
-  asChild?: boolean;
-  /** Whether the text should be rendered in italic style @default false */
-  italic?: boolean;
-  /** Whether the text should have underline decoration @default false */
-  underline?: boolean;
-  /** Whether the text should have strikethrough decoration @default false */
-  strikethrough?: boolean;
-  /** Whether text should be truncated with ellipsis on overflow @default false */
-  truncate?: boolean;
-  /** Hide visually but keep accessible to screen readers @default false */
-  srOnly?: boolean;
-  /** Additional CSS classes for custom styling */
-  className?: string;
-  /** Content to render within the typography element */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLElement>;
-
-/** Props for Strong component */
-type StrongProps = Omit<TypographyProps, "as">;
-
 /**
- * Strong - Emphasized text component for important content
+ * BodyTextLarge - Emphasized body text component
+ *
+ * Larger body text for lead paragraphs and emphasized content. Uses text-lg (18px)
+ * with relaxed line height. Defaults to p element.
  *
- * Semantic strong element for text that needs strong emphasis or importance.
- * Uses "bodyEmphasized" variant with strong semantic meaning.
+ * @param as - HTML element to render @default "p"
+ * @param className - Additional Tailwind classes
+ * @param children - Content to render
+ * @param ...props - All standard HTMLParagraphElement attributes
  *
  * @example
  * ```tsx
- * // Important information
- * <Strong>Important: This action cannot be undone.</Strong>
+ * // Lead paragraph
+ * <BodyTextLarge>
+ *   This is a lead paragraph that introduces the main content.
+ * </BodyTextLarge>
+ *
+ * // Emphasized content
+ * <BodyTextLarge className="font-medium text-accent">
+ *   Important announcement text.
+ * </BodyTextLarge>
+ * ```
+ */
+export function BodyTextLarge<T extends React.ElementType = "p">({
+  className,
+  as,
+  ...props
+}: TypographyProps<T>) {
+  const Component = as || "p";
+  return (
+    <Component
+      className={cn("text-lg leading-relaxed tracking-wide", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * BodyTextSmall - De-emphasized body text component
  *
- * // Critical warning
- * <Strong color="destructive">Error: Invalid credentials provided.</Strong>
+ * Smaller body text for less prominent content. Uses text-sm (14px) with
+ * normal line height. Defaults to p element.
  *
- * // In body text
- * <p>
- *   Make sure to <Strong>save your changes</Strong> before leaving the page.
- * </p>
+ * @param as - HTML element to render @default "p"
+ * @param className - Additional Tailwind classes
+ * @param children - Content to render
+ * @param ...props - All standard HTMLParagraphElement attributes
  *
- * // Success message
- * <Strong color="success">Account created successfully!</Strong>
+ * @example
+ * ```tsx
+ * // Small body text
+ * <BodyTextSmall>
+ *   This is smaller, less prominent body text.
+ * </BodyTextSmall>
+ *
+ * // Helper text
+ * <BodyTextSmall className="text-muted-foreground">
+ *   Additional context or helper information.
+ * </BodyTextSmall>
  * ```
- *
- * @accessibility
- * - Uses semantic strong element for emphasis
- * - Screen readers understand this as important content
- * - Provides semantic meaning beyond visual styling
- * - Maintains proper emphasis hierarchy in content
  */
-function Strong(props: StrongProps) {
-  return <Typography weight="bold" as="strong" {...props} />;
+export function BodyTextSmall<T extends React.ElementType = "p">({
+  className,
+  as,
+  ...props
+}: TypographyProps<T>) {
+  const Component = as || "p";
+  return (
+    <Component
+      className={cn("text-sm leading-normal tracking-wide", className)}
+      {...props}
+    />
+  );
 }
 
-// eslint-disable-next-line unused-imports/no-unused-vars
-type LeadDocsProps = {
-  /** Color variant for semantic meaning and visual hierarchy @default "muted" */
-  color?: TypographyColor;
-  /** Text alignment within the container @default "left" */
-  align?: "left" | "center" | "right" | "justify";
-  /** Text transformation for stylistic effects */
-  transform?: "uppercase" | "lowercase" | "capitalize";
-  /** Font weight override for visual emphasis */
-  weight?: "normal" | "medium" | "semibold" | "bold";
-  /** For label elements, the associated input ID for accessibility */
-  htmlFor?: string;
-  /** Whether to render as a Slot component for composition patterns @default false */
-  asChild?: boolean;
-  /** Whether the text should be rendered in italic style @default false */
-  italic?: boolean;
-  /** Whether the text should have underline decoration @default false */
-  underline?: boolean;
-  /** Whether the text should have strikethrough decoration @default false */
-  strikethrough?: boolean;
-  /** Whether text should be truncated with ellipsis on overflow @default false */
-  truncate?: boolean;
-  /** Hide visually but keep accessible to screen readers @default false */
-  srOnly?: boolean;
-  /** Additional CSS classes for custom styling */
-  className?: string;
-  /** Content to render within the typography element */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLParagraphElement>;
-
-/** Props for Lead component */
-type LeadProps = Omit<TypographyProps, "as">;
-
 /**
- * Lead - Introductory paragraph component for article openings
+ * Caption - Small supplementary text component
+ *
+ * Small text for metadata, timestamps, and supplementary information. Uses text-sm (14px)
+ * with muted color. Defaults to span element for inline usage.
  *
- * Lead paragraph for article introductions, page descriptions, and summary content.
- * Uses "subheading" variant with muted color for visual hierarchy.
+ * @param as - HTML element to render @default "span"
+ * @param className - Additional Tailwind classes
+ * @param children - Content to render
+ * @param ...props - All standard HTMLSpanElement attributes
  *
  * @example
  * ```tsx
- * // Article introduction
- * <Lead>
- *   This comprehensive guide covers everything you need to know about
- *   building modern web applications with React and TypeScript.
- * </Lead>
+ * // Timestamp
+ * <Caption>Last updated 2 minutes ago</Caption>
  *
- * // Page description
- * <Lead className="mb-8">
- *   Discover powerful APIs and tools to build the next generation
- *   of social applications on Farcaster.
- * </Lead>
+ * // Image caption
+ * <Caption>Figure 1: System architecture diagram</Caption>
  *
- * // With custom color
- * <Lead color="default">
- *   This lead paragraph uses the default text color for more prominence.
- * </Lead>
+ * // Metadata
+ * <Caption className="block mt-2">
+ *   Created by John Doe on Jan 15, 2025
+ * </Caption>
  * ```
  *
  * @accessibility
- * - Provides clear content hierarchy for screen readers
- * - Larger text size improves readability for introductory content
- * - Maintains proper document flow and structure
+ * - Maintains inline text flow for screen readers
+ * - Sufficient contrast with muted color
+ * - Works well for supplementary information
  */
-function Lead({
-  variant = "paragraphLead",
-  color = "muted",
+export function Caption<T extends React.ElementType = "span">({
+  className,
+  as,
   ...props
-}: LeadProps) {
-  return <Typography variant={variant} as="p" color={color} {...props} />;
+}: TypographyProps<T>) {
+  const Component = as || "span";
+  return (
+    <Component
+      className={cn("text-sm text-muted-foreground leading-normal tracking-wide", className)}
+      {...props}
+    />
+  );
 }
 
-// eslint-disable-next-line unused-imports/no-unused-vars
-type ADocsProps = {
-  /** Typography variant that determines text size, weight, and line height @default "body" */
-  variant?: TypographyVariant;
-  /** Color variant for semantic meaning and visual hierarchy @default "default" */
-  color?: TypographyColor;
-  /** Text alignment within the container @default "left" */
-  align?: "left" | "center" | "right" | "justify";
-  /** Text transformation for stylistic effects */
-  transform?: "uppercase" | "lowercase" | "capitalize";
-  /** Font weight override for visual emphasis */
-  weight?: "normal" | "medium" | "semibold" | "bold";
-  /** For label elements, the associated input ID for accessibility */
-  htmlFor?: string;
-  /** Whether to render as a Slot component for composition patterns @default false */
-  asChild?: boolean;
-  /** Whether the text should be rendered in italic style @default false */
-  italic?: boolean;
-  /** Whether the text should have underline decoration @default false */
-  underline?: boolean;
-  /** Whether the text should have strikethrough decoration @default false */
-  strikethrough?: boolean;
-  /** Whether text should be truncated with ellipsis on overflow @default false */
-  truncate?: boolean;
-  /** Hide visually but keep accessible to screen readers @default false */
-  srOnly?: boolean;
-  /** Link destination URL */
-  href?: string;
-  /** Additional CSS classes for custom styling */
-  className?: string;
-  /** Content to render within the typography element */
-  children?: React.ReactNode;
-} & React.AnchorHTMLAttributes<HTMLAnchorElement>;
-
-/** Props for A anchor component */
-type AProps = Omit<TypographyProps, "as"> & {
-  /** Link destination URL */
-  href?: string;
-} & React.AnchorHTMLAttributes<HTMLAnchorElement>;
 
 /**
- * A - Anchor component for interactive text links
+ * Overline - Small uppercase label component
+ *
+ * Small uppercase text for category tags and eyebrow labels. Uses text-xs (12px)
+ * with uppercase transformation and wide tracking. Defaults to span element.
  *
- * Semantic anchor element for links with built-in hover states and accessibility features.
- * Uses "body" variant with underline and smooth color transitions.
+ * @param as - HTML element to render @default "span"
+ * @param className - Additional Tailwind classes
+ * @param children - Content to render
+ * @param ...props - All standard HTMLSpanElement attributes
  *
  * @example
  * ```tsx
- * // External link
- * <A href="https://neynar.com" target="_blank" rel="noopener noreferrer">
- *   Visit Neynar Website
- * </A>
+ * // Category label
+ * <Overline>Featured</Overline>
+ *
+ * // Section eyebrow
+ * <Overline className="text-accent-foreground">
+ *   New Feature
+ * </Overline>
+ *
+ * // Tag
+ * <Overline className="bg-accent px-2 py-1 rounded">
+ *   Beta
+ * </Overline>
+ * ```
+ */
+export function Overline<T extends React.ElementType = "span">({
+  className,
+  as,
+  ...props
+}: TypographyProps<T>) {
+  const Component = as || "span";
+  return (
+    <Component
+      className={cn("text-xs font-medium uppercase tracking-wider", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Code - Inline code component
+ *
+ * Monospace text for inline code snippets and technical references. Uses text-sm
+ * with monospace font and subtle background. Defaults to code element.
+ *
+ * @param as - HTML element to render @default "code"
+ * @param className - Additional Tailwind classes
+ * @param children - Content to render
+ * @param ...props - All standard HTMLElement attributes
  *
- * // Internal navigation
- * <A href="/dashboard" color="accent">
- *   Go to Dashboard
- * </A>
+ * @example
+ * ```tsx
+ * // Inline code
+ * <Code>const message = "Hello, world!";</Code>
  *
- * // Composition with Next.js Link
- * <A asChild>
- *   <Link href="/about">
- *     Learn More About Us
- *   </Link>
- * </A>
+ * // Variable reference
+ * <p>Set the <Code>API_KEY</Code> environment variable.</p>
  *
- * // In paragraph text
- * <P>
- *   For more information, <A href="/docs">check our documentation</A> or
- *   contact support.
- * </P>
+ * // Terminal command
+ * <Code className="bg-accent">npm install @neynar/ui</Code>
  * ```
  *
  * @accessibility
- * - Uses semantic anchor element for proper link behavior
- * - Includes hover and focus states for interaction feedback
- * - Supports keyboard navigation (Enter key activation)
- * - Maintains color contrast requirements for links
- * - Works with screen reader link navigation modes
- * - Supports external link indicators when needed
- *
- * @see {@link Typography} Base typography component with asChild
+ * - Uses semantic code element for proper meaning
+ * - Monospace font aids in code readability
+ * - Screen readers understand this as technical content
  */
-function A({ href, asChild = false, className, ...props }: AProps) {
+export function Code<T extends React.ElementType = "code">({
+  className,
+  as,
+  ...props
+}: TypographyProps<T>) {
+  const Component = as || "code";
   return (
-    <Typography
-      as={asChild ? undefined : "a"}
-      asChild={asChild}
-      className={cn(
-        "underline underline-offset-2 hover:text-primary transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary",
-        className,
-      )}
-      {...(href ? { href } : {})}
+    <Component
+      className={cn("font-mono text-sm bg-muted px-1 rounded", className)}
       {...props}
     />
   );
 }
 
-// eslint-disable-next-line unused-imports/no-unused-vars
-type BlockquoteDocsProps = {
-  /** Color variant for semantic meaning and visual hierarchy @default "default" */
-  color?: TypographyColor;
-  /** Text alignment within the container @default "left" */
-  align?: "left" | "center" | "right" | "justify";
-  /** Text transformation for stylistic effects */
-  transform?: "uppercase" | "lowercase" | "capitalize";
-  /** Font weight override for visual emphasis */
-  weight?: "normal" | "medium" | "semibold" | "bold";
-  /** For label elements, the associated input ID for accessibility */
-  htmlFor?: string;
-  /** Whether to render as a Slot component for composition patterns @default false */
-  asChild?: boolean;
-  /** Whether the text should be rendered in italic style @default false */
-  italic?: boolean;
-  /** Whether the text should have underline decoration @default false */
-  underline?: boolean;
-  /** Whether the text should have strikethrough decoration @default false */
-  strikethrough?: boolean;
-  /** Whether text should be truncated with ellipsis on overflow @default false */
-  truncate?: boolean;
-  /** Hide visually but keep accessible to screen readers @default false */
-  srOnly?: boolean;
-  /** Additional CSS classes for custom styling */
-  className?: string;
-  /** Content to render within the typography element */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLQuoteElement>;
-
-/** Props for Blockquote component */
-type BlockquoteProps = Omit<TypographyProps, "as">;
-
 /**
- * Blockquote - Quoted text component for citations and excerpts
+ * Blockquote - Quoted text component
+ *
+ * Semantic blockquote element for extended quotations and excerpts. Features
+ * italic styling and left border for visual distinction. Defaults to blockquote element.
  *
- * Semantic blockquote element for extended quotations, testimonials, and excerpts.
- * Features italic styling and left border for visual distinction.
+ * @param as - HTML element to render @default "blockquote"
+ * @param className - Additional Tailwind classes
+ * @param children - Content to render
+ * @param ...props - All standard HTMLQuoteElement attributes
  *
  * @example
  * ```tsx
@@ -1253,17 +577,15 @@ type BlockquoteProps = Omit<TypographyProps, "as">;
  *
  * // With attribution
  * <div>
- *   <Blockquote className="mb-2">
- *     "Building great products requires deep understanding of user needs
- *     and technical excellence in equal measure."
+ *   <Blockquote>
+ *     "Building great products requires deep understanding of user needs."
  *   </Blockquote>
- *   <Small>— Product Engineering Team</Small>
+ *   <Caption className="mt-2">— Product Team</Caption>
  * </div>
  *
- * // Customer testimonial
- * <Blockquote color="muted" className="bg-muted/50 p-4 rounded-lg">
- *   "Neynar's APIs have transformed how we build social features.
- *   The developer experience is exceptional."
+ * // Custom styling
+ * <Blockquote className="bg-muted/50 p-4 rounded-lg">
+ *   Customer testimonial or feedback.
  * </Blockquote>
  * ```
  *
@@ -1271,59 +593,17 @@ type BlockquoteProps = Omit<TypographyProps, "as">;
  * - Uses semantic blockquote element for proper quotation meaning
  * - Screen readers understand this as quoted content
  * - Maintains proper text flow and readability
- * - Supports citation attribution when paired with cite element
- *
- * @see {@link Small} For attribution text
- * @see {@link Typography} Base typography component
  */
-function Blockquote({ className, ...props }: BlockquoteProps) {
+export function Blockquote<T extends React.ElementType = "blockquote">({
+  className,
+  as,
+  ...props
+}: TypographyProps<T>) {
+  const Component = as || "blockquote";
   return (
-    <Typography
-      as="blockquote"
-      italic
-      className={cn("border-l-4 border-border pl-4 my-2", className)}
+    <Component
+      className={cn("border-l-4 border-border pl-4 italic tracking-wide", className)}
       {...props}
     />
   );
 }
-
-export {
-  Typography,
-  H1,
-  H2,
-  H3,
-  H4,
-  H5,
-  H6,
-  P,
-  Span,
-  Code,
-  Small,
-  Strong,
-  Lead,
-  A,
-  Blockquote,
-};
-
-export type {
-  TypographyProps,
-  H1Props,
-  H2Props,
-  H3Props,
-  H4Props,
-  H5Props,
-  H6Props,
-  PProps,
-  SpanProps,
-  CodeProps,
-  SmallProps,
-  StrongProps,
-  LeadProps,
-  AProps,
-  BlockquoteProps,
-};
-
-/**
- * Type export for CVA variant props
- */
-export type { VariantProps as TypographyVariantProps } from "class-variance-authority";