Naming Convention

Core Insight: The name ${Noun}${Component} directly encodes the props inheritance.

The Pattern

${Noun}${Component} = ${Component} + ${Noun}-specific props + ${Noun}-specific defaults

Every component name in mdxui follows this pattern:

Pattern	Usage	Examples
`${Component}`	Generic/shared	`Nav`, `Hero`, `Sidebar`, `Card`
`${SiteType}${Component}`	Site-specialized	`DocsNav`, `BlogPost`, `MarketplaceListing`
`${AppType}${Component}`	App-specialized	`DashboardPanel`, `AdminTable`, `CRMPipeline`
`${ThingType}${Display}`	Thing renderers	`PersonCard`, `ProductRow`, `EventTile`

Props Inheritance

The naming convention directly maps to TypeScript inheritance:

// Base component with base props
interface NavProps {
  items: NavItem[]
  logo?: Logo
  position?: 'top' | 'side'
}

// Specialized = Base + context defaults + extended props
interface DocsNavProps extends NavProps {
  // Inherits: items, logo, position
  // Adds Docs-specific:
  tree: DocTree           // hierarchical doc structure
  activeDoc?: string      // current doc path
  collapsible?: boolean   // collapse sections
  // Defaults: position = 'side'
}

interface BlogNavProps extends NavProps {
  // Inherits: items, logo, position
  // Adds Blog-specific:
  categories?: Category[]
  recentPosts?: Post[]
  // Defaults: position = 'top'
}

The formula:

${Noun}${Component}Props = ${Component}Props
                         + ${Noun}-specific props
                         + ${Noun}-specific defaults

Applied at Every Level

Level	Generic	Specialized Examples
Site	`Site`	`DocsSite`, `BlogSite`, `MarketplaceSite`
Page	`Page`	`DocsPage`, `BlogPost`, `ListingPage`
Section	`Section`	`Hero`, `Features`, `Pricing`, `Problem`
Panel	`Panel`	`DetailPanel`, `PreviewPanel`, `ChatPanel`
Display	`Collection`	`Cards`, `Rows`, `Kanban`, `Timeline`
Thing	`Thing`	`Person`, `Product`, `Event`, `Agent`
Renderer	`ThingCard`	`PersonCard`, `ProductCard`, `AgentCard`

Composition

Components compose following the same pattern:

// MarketplaceSite contains marketplace-specialized components
interface MarketplaceSiteProps extends SiteProps {
  // Inherits Site structure
  // Contains:
  nav: MarketplaceNavProps      // Nav + marketplace defaults
  search: MarketplaceSearchProps // Search + marketplace filters
  listings: ListingProps[]       // Things rendered as ProductCard, etc.
}

// Each nested component follows the same pattern
MarketplaceSite = Site<MarketplaceSiteProps>
MarketplaceNav = Nav<MarketplaceNavProps>
MarketplaceSearch = Search<MarketplaceSearchProps>

Site Type Specializations

Marketing Site

// Generic sections, marketing-optimized defaults
Hero        // headline, subheadline, CTA, image/video
Problem     // pain points, agitation
Solution    // how you solve it
Features    // feature grid/bento
Benefits    // outcomes, value props
Steps       // numbered process (1, 2, 3)
HowItWorks  // explanation, demo, video
Testimonials // social proof
Pricing     // tiers, comparison
FAQ         // accordion Q&A
CTA         // final conversion
Newsletter  // email signup
LogoCloud   // customer logos

Documentation Site

// Docs-specialized components
DocsSite     = Site + docs structure + search
DocsNav      = Nav + tree hierarchy + collapsible
DocsPage     = Page + TOC + prev/next + edit link
DocsSearch   = Search + doc indexing + keyboard shortcut
DocsTOC      = TOC + heading extraction + scroll spy
DocsContent  = Content + code blocks + callouts
CodeBlock    = syntax highlighting + copy + line numbers
Callout      = info/warning/error/tip boxes

Blog Site

// Blog-specialized components
BlogSite     = Site + posts + authors + categories
BlogNav      = Nav + categories + recent posts
BlogPage     = Page + post list + filters
BlogPost     = Page + author + date + tags + related
BlogFeed     = Collection<Post> + infinite scroll
AuthorPage   = Page + author bio + posts
CategoryPage = Page + category posts

Marketplace Site

// Marketplace-specialized components
MarketplaceSite    = Site + listings + sellers + cart
MarketplaceNav     = Nav + categories + cart icon
MarketplaceSearch  = Search + filters + facets
MarketplaceListing = Page + product + seller + reviews
ProductCard        = Card + price + rating + add to cart
SellerPage         = Page + seller profile + listings
CartPage           = Page + items + checkout

App Type Specializations

Dashboard App

DashboardApp     = App + metrics + charts
DashboardNav     = Nav + dashboard sections
DashboardView    = View + metric cards + charts
DashboardPanel   = Panel + KPIs + sparklines
MetricCard       = Card + value + trend + sparkline
ChartPanel       = Panel + chart + controls

Admin App

AdminApp         = App + collections + CRUD
AdminNav         = Nav + collection list
AdminView        = View + table + filters + bulk actions
AdminTable       = Rows + sorting + selection + pagination
AdminForm        = Form + field types + validation
AdminDetail      = Panel + record view + edit

Developer Dashboard

DeveloperApp     = App + API keys + webhooks + usage
DeveloperNav     = Nav + API sections
APIKeysView      = View + key list + create + revoke
WebhooksView     = View + webhook list + logs
UsageView        = View + usage charts + limits
LogsView         = View + request logs + filters

Thing Renderer Specializations

Every schema.org.ai Thing can render at any display mode:

// Person renderers
PersonCard       = Card + avatar + name + role
PersonRow        = Row + avatar + name + email + actions
PersonTile       = Tile + large avatar + bio
PersonMarker     = Marker + avatar tooltip
PersonListItem   = ListItem + avatar + name + subtitle

// Product renderers
ProductCard      = Card + image + name + price + rating
ProductRow       = Row + image + name + category + price + stock
ProductTile      = Tile + large image + overlay price
ProductGalleryItem = GalleryItem + image + lightbox

// Event renderers
EventCard        = Card + date + title + location
EventRow         = Row + date + title + location + RSVP
EventCalendarItem = CalendarItem + positioned by date
EventTimelineItem = TimelineItem + chronological

Inheritance Lookup

When rendering a Thing, mdxui looks up renderers by specificity:

// Rendering a Car as a card
1. CarCard          // Most specific - if exists
2. VehicleCard      // Parent type
3. ProductCard      // Grandparent
4. ThingCard        // Ultimate fallback

// The first match wins
function getRenderer(type: string, display: string): Component {
  const hierarchy = getTypeHierarchy(type) // ['Car', 'Vehicle', 'Product', 'Thing']
  for (const t of hierarchy) {
    const renderer = registry[`${t}${display}`]
    if (renderer) return renderer
  }
  return ThingRenderers[display] // Fallback
}

Summary

The naming convention ${Noun}${Component} is not just a convention - it's the type system:

Names encode inheritance - DocsNav extends Nav
Props follow the pattern - DocsNavProps extends NavProps
Defaults are contextual - Each specialization has sensible defaults
Composition is recursive - Specialized sites contain specialized components
Lookup is hierarchical - Most specific renderer wins

This creates a predictable, extensible system where:

Adding a new Site type = defining its specialized components
Adding a new Thing type = defining its renderers
Adding a new display mode = adding renderers for each Thing type

Naming Convention

On this page