Design

Design your MDXLD applications from the ground up - user interfaces, data models, and system architecture.

UI/UX Design

Component-Driven Design

Design reusable components for your $type definitions:

// Design system based on $type
const components = {
  'BlogPost': BlogPostLayout,
  'Article': ArticleLayout,
  'LandingPage': LandingPageLayout,
  'Documentation': DocsLayout
}

// Automatic rendering
function render(doc: MDXDocument) {
  const Component = components[doc.$type]
  return <Component {...doc.data} />
}

Design Tokens

Define design tokens in mdxui:

import { styles } from 'mdxui'

const theme = {
  colors: {
    primary: '#3b82f6',
    secondary: '#8b5cf6',
    background: '#ffffff',
    foreground: '#0f172a'
  },
  typography: {
    fontFamily: {
      sans: 'Inter, system-ui, sans-serif',
      serif: 'Georgia, serif',
      mono: 'Consolas, monospace'
    },
    fontSize: {
      xs: '0.75rem',
      sm: '0.875rem',
      base: '1rem',
      lg: '1.125rem',
      xl: '1.25rem'
    }
  },
  spacing: {
    0: '0',
    1: '0.25rem',
    2: '0.5rem',
    4: '1rem',
    8: '2rem'
  }
}

Responsive Design

Design for all screen sizes:

import { useBreakpoint } from 'mdxui'

function BlogPost({ title, content }) {
  const breakpoint = useBreakpoint()
  
  return (
    <article className={breakpoint === 'mobile' ? 'mobile-layout' : 'desktop-layout'}>
      <h1>{title}</h1>
      <div>{content}</div>
    </article>
  )
}

Accessibility

Design accessible components:

Semantic HTML: Use proper heading hierarchy
ARIA labels: Add labels for screen readers
Keyboard navigation: Support tab navigation
Color contrast: Ensure WCAG AA compliance
Focus indicators: Visible focus states

<button
  aria-label="Share blog post"
  onClick={handleShare}
  className="focus:ring-2 focus:ring-primary"
>
  Share
</button>

Data Model Design

Schema.org Vocabulary

Design data models using Schema.org types:

---
$context: https://schema.org
$type: BlogPost
$id: /blog/my-post

# Schema.org properties
name: My Blog Post
author:
  $type: Person
  name: Jane Doe
  email: [email protected]
datePublished: 2024-01-15
keywords:
  - TypeScript
  - MDX
  - Web Development
---

Custom Types

Extend with custom types from schema.org.ai:

---
$context:
  - https://schema.org
  - https://schema.org.ai
$type: LandingPage

hero:
  $type: Hero
  headline: Build Amazing Products
  subheadline: Ship faster with MDXLD
  cta:
    text: Get Started
    href: /docs

features:
  - $type: Feature
    title: Fast
    description: Lightning fast builds
    icon: zap
  - $type: Feature
    title: Simple
    description: Zero configuration
    icon: check
---

Type Hierarchies

Design type hierarchies with discriminated unions:

// Base content type
interface Content {
  $type: string
  $id: string
  $context: string
  title: string
}

// Specific content types
interface BlogPost extends Content {
  $type: 'BlogPost'
  author: string
  datePublished: string
}

interface Article extends Content {
  $type: 'Article'
  headline: string
  articleBody: string
}

interface Documentation extends Content {
  $type: 'TechArticle'
  version: string
}

// Union type
type ContentType = BlogPost | Article | Documentation

Relationships

Design relationships between entities:

---
$type: BlogPost
$id: /blog/my-post
title: My Blog Post
author:
  $id: /authors/jane-doe
  $type: Person
  name: Jane Doe
category:
  $id: /categories/technology
  $type: Category
  name: Technology
relatedPosts:
  - $id: /blog/related-post-1
  - $id: /blog/related-post-2
---

Database Design

Document Structure

Design document structure:

interface MDXDocument {
  // Identity
  $id: string              // Unique identifier
  $type: string            // Type discriminator
  $context: string         // Semantic context
  
  // Metadata
  path: string             // File path
  created: Date            // Creation date
  modified: Date           // Last modified date
  
  // Content
  data: Record<string, any> // Frontmatter
  content: string          // MDX content
  
  // Relations
  refs: string[]           // Referenced documents
  backlinks: string[]      // Documents referencing this
}

Indexing Strategy

Design indexes for common queries:

// Primary index: $id
index: { $id: 1 }

// Type index: for filtering by $type
index: { $type: 1, created: -1 }

// Search index: full-text search
index: { 
  'data.title': 'text',
  'content': 'text'
}

// Relationship index: for graph queries
index: { refs: 1 }
index: { backlinks: 1 }

// Composite index: common query patterns
index: { 
  $type: 1,
  'data.datePublished': -1,
  'data.author': 1
}

Query Patterns

Design for common query patterns:

// List by type
await list({ type: 'BlogPost' })

// Search
await search('TypeScript', { type: 'BlogPost' })

// Get by ID
await get('/blog/my-post')

// Related documents
await related('/blog/my-post', 'relatedPosts')

// Recent posts by author
await list({
  type: 'BlogPost',
  filter: { 'data.author': 'Jane Doe' },
  sort: { 'data.datePublished': -1 },
  limit: 10
})

Denormalization

Design denormalized data for performance:

---
$type: BlogPost
$id: /blog/my-post
title: My Blog Post

# Denormalized author data
author:
  $id: /authors/jane-doe
  name: Jane Doe
  avatar: /images/jane.jpg
  bio: Software engineer

# Denormalized category data
category:
  $id: /categories/technology
  name: Technology
  slug: technology
  
# Denormalized stats
stats:
  views: 1234
  shares: 56
  comments: 12
---

Architecture Design

Component Architecture

Design component hierarchy:

App
├── Layout
│   ├── Header
│   ├── Navigation
│   └── Footer
├── Pages
│   ├── BlogPost
│   │   ├── PostHeader
│   │   ├── PostContent
│   │   └── PostFooter
│   ├── Article
│   └── LandingPage
│       ├── Hero
│       ├── Features
│       └── CTA
└── Shared
    ├── Button
    ├── Card
    └── Typography

Data Flow

Design data flow architecture:

// Server: Fetch data
export async function getStaticProps({ params }) {
  const doc = await get(params.id)
  return { props: { doc } }
}

// Component: Render data
export default function BlogPost({ doc }) {
  return <BlogPost {...doc.data} />
}

// Client: Interactive updates
function ShareButton({ postId }) {
  const [shared, setShared] = useState(false)
  
  async function handleShare() {
    await track('share', { postId })
    setShared(true)
  }
  
  return <Button onClick={handleShare}>Share</Button>
}

State Management

Design state management:

// Global state
const AppContext = createContext({
  theme: 'light',
  user: null,
  docs: []
})

// Document state
const DocumentContext = createContext({
  doc: null,
  loading: false,
  error: null
})

// Local state
function BlogPost() {
  const [expanded, setExpanded] = useState(false)
  const { theme } = useContext(AppContext)
  const { doc } = useContext(DocumentContext)
  
  return <article data-theme={theme}>...</article>
}

API Design

Design API endpoints:

// REST API
GET    /api/posts          // List posts
GET    /api/posts/:id      // Get post
POST   /api/posts          // Create post
PUT    /api/posts/:id      // Update post
DELETE /api/posts/:id      // Delete post
GET    /api/search?q=...   // Search posts

// GraphQL API
query {
  post(id: "/blog/my-post") {
    $type
    title
    author {
      name
      avatar
    }
    content
  }
}

Deployment Architecture

Design deployment strategy:

┌─────────────────────────────────────┐
│         Cloudflare Edge             │
│  ┌──────────────────────────────┐   │
│  │   Static Assets (MDX)        │   │
│  │   - Cached at edge           │   │
│  │   - Auto HTTPS               │   │
│  │   - DDoS protection          │   │
│  └──────────────────────────────┘   │
└─────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────┐
│         Worker (Dynamic)            │
│  ┌──────────────────────────────┐   │
│  │   MDXLD Processing           │   │
│  │   - Parse MDX                │   │
│  │   - Validate types           │   │
│  │   - Render components        │   │
│  └──────────────────────────────┘   │
└─────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────┐
│         .do Platform API            │
│  ┌──────────────────────────────┐   │
│  │   MDX Database               │   │
│  │   - List/Search/Get          │   │
│  │   - Publish/Pull             │   │
│  │   - AI Generation            │   │
│  └──────────────────────────────┘   │
└─────────────────────────────────────┘

Design Tools

Visual Design

Figma: UI/UX design and prototyping
Sketch: Design mockups
Adobe XD: User experience design

Type Design

# Generate TypeScript types from MDX
mdxld extract-types blog-post.mdx > types.ts

# Validate types
mdxld validate blog-post.mdx --types types.ts

Schema Design

# Generate schema from examples
mdxld infer-schema blog-posts/*.mdx > schema.json

# Validate documents against schema
mdxld validate --schema schema.json

Design Patterns

Template Pattern

---
$type: Template
$id: /templates/blog-post
name: Blog Post Template

properties:
  title:
    type: string
    required: true
  author:
    type: string
    required: true
  content:
    type: string
    required: true
---

# {title}

By {author}

{content}

Factory Pattern

function createDocument(type: string, data: any): MDXDocument {
  const factories = {
    'BlogPost': createBlogPost,
    'Article': createArticle,
    'LandingPage': createLandingPage
  }
  
  return factories[type](data)
}

Observer Pattern

// Subscribe to document changes
const unsubscribe = observe('/blog/my-post', (doc) => {
  console.log('Document updated:', doc)
})

// Cleanup
unsubscribe()

Best Practices

Design for types: Start with $type definitions
Use Schema.org: Leverage existing vocabularies
Think components: Design reusable UI components
Plan queries: Design indexes for common queries
Consider scale: Design for growth
Document decisions: Keep design documentation
Iterate quickly: Use tools for rapid prototyping
Test early: Validate designs with users

Design

On this page