---
title: "MDX Integration and M3E Atomic Components"
published: 2026-08-20
description: "A comprehensive guide to composing rich interactive articles in Shirone using MDX, Svelte 5 interactive islands, and Material 3 Expressive design tokens."
image: ""
tags: [MDX, Components, Svelte, Markdown, Demo]
category: "Guides"
draft: false
---

import Button from "@components/atoms/action/Button.svelte";
import Chips from "@components/atoms/action/Chips.svelte";
import Card from "@components/atoms/display/Card.svelte";
import AccentBar from "@components/atoms/display/AccentBar.svelte";
import Badge from "@components/atoms/display/Badge.svelte";
import Divider from "@components/atoms/display/Divider.svelte";
import Skeleton from "@components/atoms/display/Skeleton.svelte";
import LoadingIndicator from "@components/atoms/feedback/LoadingIndicator.svelte";
import ProgressIndicator from "@components/atoms/feedback/ProgressIndicator.svelte";
import TextField from "@components/atoms/input/TextField.svelte";
import Switch from "@components/atoms/selection/Switch.svelte";
import Checkbox from "@components/atoms/selection/Checkbox.svelte";
import SegmentedButton from "@components/atoms/selection/SegmentedButton.svelte";
import Slider from "@components/atoms/selection/Slider.svelte";

export const authorInfo = {
  framework: "Astro 7",
  ui: "Svelte 5",
  tokens: "M3E Design Tokens",
  architecture: "Islands Architecture"
};

export const showcaseItems = [
  { name: "Atomic Component Embedding", desc: "Directly import and render 60+ M3E atoms and molecules in article content" },
  { name: "Svelte 5 Islands", desc: "Selective hydration via client:visible ensures zero unnecessary JavaScript overhead" },
  { name: "JSX Expressions", desc: "Native JavaScript variables, data mappings, and conditional rendering" },
  { name: "Extension Pipeline", desc: "Unified SSOT compilation for Mermaid, KaTeX, Admonitions, and Expressive Code" }
];

export const filterChipOptions = [
  { value: "all", label: "All Components" },
  { value: "display", label: "Display Atoms" },
  { value: "feedback", label: "Feedback" },
  { value: "action", label: "Interactive" }
];

export const segmentedOptions = [
  { value: "linear", label: "Linear" },
  { value: "circular", label: "Circular" },
  { value: "morph", label: "Morphing" }
];

:::tip
**MDX (Markdown + JSX)** bridges the gap between static writing and application interfaces. In Shirone, authors can seamlessly mix dynamic logic, reactive Svelte 5 components, and Material 3 design tokens directly within post content.
:::

## 1. Markdown vs MDX Capability Matrix

| Feature | Standard Markdown (`.md`) | Shirone MDX (`.mdx`) | Execution Mode |
| :--- | :--- | :--- | :--- |
| **Typography & Structure** | Full Support | Full Support | Static SSR |
| **Code Highlighting** | Line Numbers, Frames, Collapsible | Line Numbers, Frames, Collapsible | Static SSR (Expressive Code) |
| **Diagrams & Mathematics** | Mermaid, KaTeX | Mermaid, KaTeX | Client Enhanced |
| **Callout Admonitions** | Note, Tip, Important, Warning, Caution | Note, Tip, Important, Warning, Caution | Static SSR |
| **M3E Display Atoms** | Not Available | Direct Integration (`<Card>`, `<Skeleton>`) | Pure SSR (Zero Client JS) |
| **Svelte 5 Reactive Islands** | Not Available | On-Demand Hydration (`<Button>`, `<Switch>`) | `client:visible` Lazy Hydrated |
| **Feedback & Loading Atoms** | Not Available | Animated Morph (`<LoadingIndicator>`) | `client:visible` Reactive |
| **Dynamic JSX Expressions** | Not Available | Native Evaluation (`{authorInfo.ui}`) | Compile-Time / Client |

---

## 2. Dynamic Expressions and Data Mapping

MDX allows declaring scoped constants using `export const` at the top of the file, which can be evaluated inline or mapped across templates:

- **Core Framework**: {authorInfo.framework}
- **UI Engine**: {authorInfo.ui}
- **Design Tokens**: {authorInfo.tokens}
- **Architecture Pattern**: {authorInfo.architecture}

Arrays and collections can be rendered dynamically into grid layouts:

<div class="grid grid-cols-1 md:grid-cols-2 gap-4 my-6">
  {showcaseItems.map((item, idx) => (
    <div key={item.name} class="p-4 rounded-xl border border-[var(--outline-variant)] bg-[var(--surface-container-low)]">
      <div class="flex items-center gap-2 mb-1">
        <span class="w-6 h-6 rounded-full bg-[var(--primary)] text-[var(--on-primary)] text-xs flex items-center justify-center font-bold">
          {idx + 1}
        </span>
        <span class="font-bold text-[var(--on-surface)]">{item.name}</span>
      </div>
      <p class="text-sm text-[var(--on-surface-variant)] m-0">{item.desc}</p>
    </div>
  ))}
</div>

---

## 3. M3E Display and Layout Primitives (SSR-Only)

In accordance with Shirone's component architecture (`docs/atomic-structure.md`), stateless display components output clean, accessible semantic HTML with no client-side runtime payload.

### 3.1 Card Containers (`Card.svelte`)

<div class="grid grid-cols-1 md:grid-cols-3 gap-4 my-6">
  <Card variant="filled" class="!p-5">
    <div class="font-bold text-[var(--primary)] mb-2">Filled Card</div>
    <div class="text-sm text-[var(--on-surface-variant)]">Default container background with no elevation shadow. Ideal for grouped content blocks.</div>
  </Card>

  <Card variant="elevated" class="!p-5">
    <div class="font-bold text-[var(--primary)] mb-2">Elevated Card</div>
    <div class="text-sm text-[var(--on-surface-variant)]">Level 1 container elevation with interactive state layering for heightened visual focus.</div>
  </Card>

  <Card variant="outlined" class="!p-5">
    <div class="font-bold text-[var(--primary)] mb-2">Outlined Card</div>
    <div class="text-sm text-[var(--on-surface-variant)]">A crisp 1px outline boundary providing clean separation on neutral surfaces.</div>
  </Card>
</div>

### 3.2 Accent Bars and Badges (`AccentBar` & `Badge`)

<div class="flex items-center gap-4 my-4 p-4 rounded-lg bg-[var(--surface-container-high)]">
  <AccentBar size="large" />
  <div class="flex-1">
    <span class="font-bold text-lg">System Announcement</span>
    <p class="text-xs text-[var(--on-surface-variant)] m-0">Combine AccentBar with Badge to build prominent visual callouts</p>
  </div>
  <Badge>M3E v0.192</Badge>
</div>

### 3.3 Skeleton Placeholders (`Skeleton.svelte`)

For previewing layout skeletons or prototyping async states:

<div class="flex flex-col gap-3 my-6 p-5 rounded-xl border border-[var(--outline-variant)] bg-[var(--surface-container-low)]">
  <div class="flex items-center gap-3">
    <Skeleton variant="circle" width="2.5rem" height="2.5rem" />
    <div class="flex flex-col gap-1.5 flex-1">
      <Skeleton variant="text" width="40%" height="0.875rem" />
      <Skeleton variant="text" width="25%" height="0.75rem" />
    </div>
  </div>
  <Skeleton variant="rect" width="100%" height="3rem" radius="0.5rem" />
</div>

---

## 4. Feedback and Loading Indicators

Shirone features full-fidelity Material 3 Expressive motion and feedback atoms:

### 4.1 Morphing Loading Indicator (`LoadingIndicator.svelte`)

Implemented with `androidx.graphics.shapes` polygon morphing, providing smooth spring-interpolated 7-shape animations:

<div class="grid grid-cols-1 md:grid-cols-3 gap-4 my-6 p-6 rounded-2xl bg-[var(--surface-container)] border border-[var(--outline-variant)] text-center">
  <div class="flex flex-col items-center gap-2">
    <div class="h-16 flex items-center justify-center">
      <LoadingIndicator client:visible />
    </div>
    <span class="text-xs text-[var(--on-surface-variant)]">Indeterminate Shape Morph</span>
  </div>

  <div class="flex flex-col items-center gap-2">
    <div class="h-16 flex items-center justify-center">
      <LoadingIndicator client:visible contained />
    </div>
    <span class="text-xs text-[var(--on-surface-variant)]">Contained Circular Variant</span>
  </div>

  <div class="flex flex-col items-center gap-2">
    <div class="h-16 flex items-center justify-center">
      <LoadingIndicator client:visible progress={0.68} />
    </div>
    <span class="text-xs text-[var(--on-surface-variant)]">Determinate Progress (68%)</span>
  </div>
</div>

### 4.2 Linear and Indeterminate Progress (`ProgressIndicator.svelte`)

<div class="flex flex-col gap-4 my-6 p-6 rounded-2xl bg-[var(--surface-container)] border border-[var(--outline-variant)]">
  <div class="flex flex-col gap-2">
    <div class="flex justify-between text-xs text-[var(--on-surface-variant)]">
      <span>Pipeline Compilation</span>
      <span>80%</span>
    </div>
    <ProgressIndicator client:visible progress={0.8} />
  </div>

  <div class="flex flex-col gap-2 mt-2">
    <div class="text-xs text-[var(--on-surface-variant)]">Continuous Dual-Line Animation</div>
    <ProgressIndicator client:visible />
  </div>
</div>

---

## 5. Interactive Svelte 5 Islands

Components declared with `client:visible` are lazy-hydrated via `IntersectionObserver` when entering the viewport:

### 5.1 Button Matrix (`Button.svelte`)

<div class="flex flex-wrap items-center gap-3 my-6 p-4 rounded-xl border border-[var(--outline-variant)]">
  <Button client:visible variant="filled">Filled Button</Button>
  <Button client:visible variant="elevated">Elevated</Button>
  <Button client:visible variant="tonal">Tonal Button</Button>
  <Button client:visible variant="outlined">Outlined</Button>
  <Button client:visible variant="text">Text Button</Button>
</div>

### 5.2 Filter Chips and Segmented Buttons (`Chips` & `SegmentedButton`)

<div class="flex flex-col gap-4 my-6 p-6 rounded-2xl bg-[var(--surface-container)] border border-[var(--outline-variant)]">
  <div>
    <div class="text-xs font-bold text-[var(--on-surface-variant)] mb-2">M3E Filter Chips</div>
    <Chips client:visible items={filterChipOptions} value="all" />
  </div>

  <Divider />

  <div>
    <div class="text-xs font-bold text-[var(--on-surface-variant)] mb-2">Segmented Control</div>
    <SegmentedButton client:visible options={segmentedOptions} value="linear" />
  </div>
</div>

### 5.3 Switches, Checkboxes, and Sliders (`Switch`, `Checkbox`, `Slider`)

<div class="flex flex-col gap-4 my-6 p-6 rounded-2xl bg-[var(--surface-container)] border border-[var(--outline-variant)]">
  <div class="flex items-center justify-between">
    <span class="font-bold text-sm">Switch with Status Icons</span>
    <Switch client:visible checked={true} icons label="Push notifications" />
  </div>

  <Divider />

  <div class="flex items-center justify-between">
    <span class="font-bold text-sm">Selection Checkboxes</span>
    <div class="flex items-center gap-4">
      <Checkbox client:visible checked={true} label="Selected" />
      <Checkbox client:visible checked={false} label="Unselected" />
      <Checkbox client:visible checked={null} triState label="Indeterminate" />
    </div>
  </div>

  <Divider />

  <div class="flex flex-col gap-2">
    <span class="font-bold text-sm">Hue Spectrum Slider</span>
    <Slider client:visible value={60} label="Hue adjustment" />
  </div>
</div>

### 5.4 Input Controls (`TextField.svelte`)

<div class="grid grid-cols-1 md:grid-cols-2 gap-4 my-6">
  <TextField client:visible variant="filled" label="Filled Text Field" placeholder="Enter text..." />
  <TextField client:visible variant="outlined" label="Outlined Text Field" placeholder="Enter text..." />
</div>

---

## 6. Markdown Extension Compatibility

Shirone's SSOT unified plugin pipeline preserves full compatibility with all Markdown extensions:

### 6.1 GitHub Repository Cards

::github{repo="saicaca/fuwari"}

### 6.2 Mermaid Architecture Diagrams

```mermaid
flowchart TD
    MDX[MDX Source Entry] --> Compiler["@astrojs/mdx Compiler"]
    Compiler --> Plugins["Remark / Rehype SSOT Pipeline"]
    Plugins --> Islands["Svelte 5 Interactive Islands"]
    Islands --> Swup["Swup Client Navigation Shell"]
    Swup --> Screen["M3E Expressive Article View"]
```

### 6.3 Mathematical Expressions (LaTeX / KaTeX)

Inline equation: Mass-energy equivalence $E = mc^2$ and Gaussian integral $\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$.

Block equation:

$$
\mathcal{L}_{M3E} = \sum_{i=1}^{N} \left( \text{Token}_i \cdot \text{ContrastRatio} \right) + \lambda \|\text{MotionElegance}\|
$$

---

## 7. Summary

The native integration of MDX empowers technical writers to build rich, interactive documentation while preserving Shirone's ultra-fast static performance. All components adhere to the Material 3 Expressive token design system, ensuring consistency, accessibility, and visual harmony.