UI Components

The UI Components layer provides component templates and rendering packages for building interfaces from MDX documents.

Templates (Components)

Templates are JSX components that know how to render to multiple formats and extract data back:

import { Entity, Property, Action } from '@mdxld/jsx/primitives'
 
function Customer({ name, email, tier, actions }) {
  return (
    <Entity name={name} type="Customer">
      <Property name="email">{email}</Property>
      <Property name="tier" default="free">{tier}</Property>
      <Action name="upgrade" returns="Customer">
        Upgrade to a higher tier
      </Action>
    </Entity>
  )
}
 
// Render to any format
Customer.toMarkdown(data)   // → Markdown
Customer.toJSON(data)       // → JSON
Customer.toJSONLD(data)     // → JSON-LD
Customer.toHTML(data)       // → HTML
 
// Extract from any format
Customer.fromMarkdown(md)   // → Object
Customer.fromJSON(json)     // → Object

Composition

Templates compose together like React components:

function StoryBrand({ name, hero, problem, guide }) {
  return (
    <Document name={name}>
      <Hero {...hero} />
      <Problem {...problem} />
      <Guide {...guide} />
    </Document>
  )
}
 
function Hero({ persona, occupation, company }) {
  return (
    <Section name="hero">
      <Property name="persona">{persona}</Property>
      <Property name="occupation">{occupation}</Property>
      <Property name="company">{company}</Property>
    </Section>
  )
}

Composition enables:

Reusability - Use Hero in multiple templates
Nesting - Deep component trees
Overrides - Customize rendering per-component

Encapsulation

Each component encapsulates its own rendering logic:

// Entity knows how to render itself to each format
<Entity name="Customer" plural="Customers">
  <Property name="email" type="string" required />
</Entity>
 
// → Markdown
# Customer (Customers)
| Property | Type | Required |
|----------|------|----------|
| email | string | ✓ |
 
// → JSON
{ "name": "Customer", "plural": "Customers", "properties": [...] }
 
// → JSON-LD
{ "@type": "Class", "name": "Customer", ... }
 
// → HTML
<article><h1>Customer</h1><table>...</table></article>

Components encapsulate:

Schema - The shape of data they accept
Layout - How they render to each format
Extraction - How they parse content back to data

mdxui Package

The presentation layer adds styling on top of semantic output:

@mdxui/shadcn - shadcn/ui styled components
@mdxui/tailwind - Tailwind CSS styling
@mdxui/email - Email-optimized HTML
@mdxui/slack - Slack Block Kit
@mdxui/fumadocs - Documentation sites

npm install mdxui

Component Specifications

Each component is defined with:

Props - Input properties with types
Parts - CSS ::part() slots for styling
CSS Variables - Themeable design tokens
Semantic HTML - Accessibility-first structure

Layout Components

Component	Description
Site	Website wrapper with header, nav, footer
App	Root application with providers
Page	Individual page container
Section	Content section with heading
View	Generic view container
Layout	Flexible layout system

Marketing Components

Component	Description
Hero	Hero section with CTA
LandingPage	Complete landing page
Features	Feature grid
Pricing	Pricing table
CTA	Call-to-action section
Testimonials	Customer testimonials
Team	Team member grid
FAQ	FAQ accordion

Content Components

Component	Description
Blog	Blog listing page
BlogPost	Individual blog post
Article	Long-form article
Docs	Documentation page
API	API documentation

Data Components

Component	Description
Dashboard	Dashboard layout
Directory	Directory listing
Card	Content card
Table	Data table
ListView	List view
DetailView	Detail page
FormView	Form layout

Component	Description
Header	Page header
Footer	Page footer
Nav	Navigation menu
Sidebar	Sidebar navigation
Modal	Modal dialog

Output Formats

Components can render to multiple formats:

html - React/HTML output
markdown - Plain markdown
json - JSON-LD structured data
svg - Vector graphics
png - Raster images

Styling with Parts

Use CSS ::part() selectors for styling:

Site::part(header) {
  background: var(--color-surface);
  border-bottom: 1px solid var(--color-border);
}
 
Site::part(nav-item) {
  color: var(--color-text);
  text-decoration: none;
}
 
Site::part(nav-item):hover {
  color: var(--color-primary);
}

CSS Variables

Each component exposes themeable CSS variables:

:root {
  /* Site */
  --site-max-width: 1280px;
  --site-header-height: 64px;
  --site-padding: 1rem;
 
  /* Hero */
  --hero-padding: 4rem 2rem;
  --hero-title-size: 3rem;
 
  /* Card */
  --card-padding: 1.5rem;
  --card-border-radius: 0.5rem;
}