Engineer a dedicated documentation microsite using MDX, code live blocks, and design…
- User
Engineer a dedicated documentation microsite using MDX, code live blocks, and design tokens to align design and engineering.
- Assistant
From Specification to Execution: Blueprinting a Documentation Microsite
Okay, so I'm tasked with architecting this documentation microsite. The brief is clear: use MDX for content, leverage live code blocks for interactivity, and design tokens to ensure design-engineering harmony, all wrapped in a dynamic, nature-inspired aesthetic. My mind immediately starts breaking this down.
First, the tech stack: Next.js with the App Router is the obvious choice for the React framework, allowing MDX rendering and server-side performance. Tailwind CSS will be the styling workhorse, and a component library like Shadcn/ui will be a good starting point for basic UI elements that we can then heavily customize. The key challenge is the design system: I'm thinking of a bespoke token-based approach. We'll define a foundational set of variables in a central
design-tokensmodule, exposing things like color, font, spacing, and animation parameters, and these will be injected into the Tailwind configuration via CSS variables. That way we get the power of Tailwind while respecting strict theme control.For the interactivity and "wow" factor, Three.js is the tool of choice. The microsite will need a stunning hero section, a 3D background with organic movement, and interactive elements that respond to the mouse. I'm envisioning a central, slowly morphing organic blob or particle system that feels alive. The hero section's "Welcome to the Oasis" will be an interactive experience – perhaps the text itself interacts with the particle cloud or the mouse cursor manipulates the 3D scene. The 3D scene will be optimized with
useMemoanduseEffecthooks and use a progressive rendering technique. The mouse interaction will be the primary input, with a subtle parallax or distortion effect.The live code blocks will utilize something like CodeSandbox or a lightweight alternative, giving users an editable preview, with MDX allowing for embedding React components. Smooth scrolling with Lenis is essential, to give the organic, natural motion we're after. Custom cursor, custom scrollbar, etc.
The visual language isNature-inspired but sophisticated: Dappled light, subtle noise, wavy borders, organic blobs, airy color palette. High-performance 3D with a consistent aesthetic (think soft colors, distortions) is a must. No abrupt animations, everything must have ease-out curves.
Implementation wise: we'll start by setting up the Next.js boilerplate with tailwind, then define our
design-tokens. Build the 3D component using Three.js, perhaps based on vertex displacements of a sphere. Develop the Hero section with the 3D scene behind the text. The MDX processing and live code embedding will be done. The rest is aesthetics: wavy SVG dividers, smooth scroll event listeners, noise overlay, custom cursor implementation.In summary, this microsite's design-engineering is based on a central design token system that will enable shared values. The complexity will increase over time, but the aesthetic will be consistent and aligned from day one. Here is a complete, executable blueprint for a documentation microsite that meets your stringent design and engineering requirements.
This architecture uses Next.js (App Router), Tailwind CSS, MDX, Three.js (with react-three-fiber), and a central design token system. The code is structured to be production-ready while allowing for the artistic, organic-aesthetic implementation you've described.
1. Project Setup & Core Technology
# Terminal commands to initialize the project npx create-next-app@latest doc-microsite --typescript --tailwind --app cd doc-microsite npm install three @react-three/fiber @react-three/drei @types/three npm install @mdx-js/loader @next/mdx lucide-react framer-motion npm install -D @tailwindcss/forms
2. Design Token System (The Single Source of Truth)
This is the most critical file. All design decisions, colors, fonts, motion curves, and 3D parameters are defined here. Tailwind and your React components reference these tokens, ensuring perfect alignment.
src/design-tokens.tsexport const tokens = { color: { // Nature-inspired palette primary: { DEFAULT: '#4A7C59', // Sage green light: '#7FB396', dark: '#2F5233' }, surface: { DEFAULT: '#F8F9FA', // Off-white, near white paper: '#FFFFFF', overlay: 'rgba(255, 255, 255, 0.85)' }, accent: { DEFAULT: '#E9B44C', // Warm gold/mustard secondary: '#C06C54' // Terra cotta }, text: { primary: '#1A1A1A', secondary: '#4A4A4A', muted: '#8A8A8A' } }, font: { serif: ['"Playfair Display"', 'serif'], // Elegant, organic sans: ['"Inter"', 'sans-serif'], // Clean, technical display: ['"Cormorant Garamond"', 'serif'] // Very organic headers }, spacing: { xs: '0.5rem', sm: '1rem', md: '2rem', lg: '4rem', xl: '8rem', '2xl': '12rem' }, motion: { // Custom Bezier curves for natural movement easeOutExpo: 'cubic-bezier(0.19, 1, 0.22, 1)', easeInOutSine: 'cubic-bezier(0.37, 0, 0.63, 1)', wavy: 'cubic-bezier(0.25, 0.1, 0.25, 1)' // For blobs/waves }, // Specific 3D scene parameters three: { particleCount: 1500, blobColor: 0x7FB396, // light sage blobNoiseSpeed: 0.2, blobNoiseScale: 1.5, mouseInfluenceRadius: 2.5, waterColor: 0x4A7C59 } }; // Types for convenient access export type ColorTokens = typeof tokens.color; export type FontTokens = typeof tokens.font; export type SpacingTokens = typeof tokens.spacing; export type MotionTokens = typeof tokens.motion; export type ThreeTokens = typeof tokens.three;
3. Tailwind Configuration (Consuming Tokens)
tailwind.config.tsimport type { Config } from 'tailwindcss'; import { tokens } from './src/design-tokens'; const config: Config = { darkMode: 'class', content: [ './pages/**/*.{js,ts,jsx,tsx,mdx}', './components/**/*.{js,ts,jsx,tsx,mdx}', './app/**/*.{js,ts,jsx,tsx,mdx}', ], theme: { extend: { colors: tokens.color, fontFamily: tokens.font, spacing: tokens.spacing, // Animation curves transitionTimingFunction: { 'out-expo': tokens.motion.easeOutExpo, 'in-out-sine': tokens.motion.easeInOutSine, 'wavy': tokens.motion.wavy, }, // Blob/wave shapes via clip-path (using SVG data URI is more powerful) clipPath: { 'blob': 'url(#blob-clip)', 'wave': 'url(#wave-clip)' }, backgroundImage: { 'noise': 'url(/noise-pattern.png)' // Pre-generated seamless noise texture } }, }, plugins: [], }; export default config;
4. Core 3D Component: Organic Morphing Blob
src/components/three/OrganicBlob.tsxA high-performance<Blob>component using Simplex Noise for vertex displacement. It morphs slowly and reacts to the mouse.'use client'; import { useRef, useMemo } from 'react'; import { useFrame } from '@react-three/fiber'; import { Sphere, MeshDistortMaterial } from '@react-three/drei'; import * as THREE from 'three'; import { createNoise3D } from 'simplex-noise'; import { tokens } from '@/design-tokens'; const OrganicBlob = () => { const meshRef = useRef<THREE.Mesh>(null); const noise3D = useMemo(() => createNoise3D(), []); // Parameters from tokens for consistency const { noiseSpeed, noiseScale, blobColor } = tokens.three; useFrame(({ clock, mouse }) => { if (!meshRef.current) return; const elapsedTime = clock.getElapsedTime(); const position = meshRef.current.position; const geometry = meshRef.current.geometry as THREE.IcosahedronGeometry; // Access vertices for manual distortion if MeshDistortMaterial is insufficient // However, MeshDistortMaterial handles much of the performance cost. // Here we simulate a "breathing" effect on the entire object. const breathe = Math.sin(elapsedTime * 0.5) * 0.1; meshRef.current.scale.setScalar(1 + breathe); // Mouse interaction: subtle attraction/repulsion // map mouse from -1,1 to world space approx -10,10 const targetX = mouse.x * 10; const targetY = mouse.y * 10; position.x += (targetX - position.x) * 0.05; // Smooth follow position.y += (targetY - position.y) * 0.05; }); return ( <Sphere ref={meshRef} args={[1.5, 64, 64]}> <MeshDistortMaterial color={blobColor} attach="material" distort={0.4} // Distortion strength speed={noiseSpeed} // Speed of distortion roughness={0.2} metalness={0.1} /> </Sphere> ); }; export default OrganicBlob;
5. Main Layout & Hero Section
src/app/page.tsx(or a dedicatedHeroSection.tsx)'use client'; import { Suspense, useRef, useEffect } from 'react'; import { Canvas, useFrame } from '@react-three/fiber'; import { Text3D, Center, Float, Environment } from '@react-three/drei'; import { motion, useInView, useScroll, useTransform } from 'framer-motion'; import { tokens } from '@/design-tokens'; import OrganicBlob from '@/components/three/OrganicBlob'; import { Button } from '@/components/ui/button'; // from shadcn/ui, styled with tokens // Subtle grain overlay component const GrainOverlay = () => ( <div className="fixed inset-0 pointer-events-none mix-blend-overlay opacity-20 bg-noise z-50" /> ); // Smooth scroll wrapper (Lenis integration example) // import Lenis from '@studio-freight/lenis' // useEffect(() => { const lenis = new Lenis(); function raf(time) { lenis.raf(time); requestAnimationFrame(raf); } requestAnimationFrame(raf); }, []); const Hero = () => { const containerRef = useRef(null); const { scrollYProgress } = useScroll({ target: containerRef, offset: ['start start', 'end start'] }); // Parallax and opacity transforms based on scroll const titleY = useTransform(scrollYProgress, [0, 1], ['0%', '50%']); const titleOpacity = useTransform(scrollYProgress, [0, 0.5], [1, 0]); return ( <section ref={containerRef} className="relative h-screen w-full overflow-hidden bg-surface"> {/* 3D Background */} <div className="absolute inset-0 z-0"> <Canvas camera={{ position: [0, 0, 5], fov: 50 }} dpr={[1, 2]}> <ambientLight intensity={0.5} /> <pointLight position={[10, 10, 10]} intensity={1} /> <Suspense fallback={null}> <OrganicBlob /> {/* Optional environmental map for realistic reflections */} <Environment preset="city" /> </Suspense> </Canvas> </div> {/* Foreground Content */} <div className="relative z-10 flex h-full flex-col items-center justify-center pointer-events-none"> <motion.div style={{ y: titleY, opacity: titleOpacity }} className="text-center px-4" > <h1 className="text-5xl md:text-8xl font-display mb-6 tracking-tight" style={{ color: tokens.color.text.primary, textShadow: `0 10px 30px -10px ${tokens.color.surface.overlay}` }} > Symbiosis </h1> <p className="text-xl md:text-2xl font-sans text-secondary max-w-2xl mx-auto mb-12 leading-relaxed" > Where design tokens meet living code.<br /> A documentation microsite for the modern engineer. </p> <div className="pointer-events-auto flex gap-4 justify-center"> <Button size="lg" className="bg-primary hover:bg-primary-light text-white shadow-lg transition-all duration-700 ease-out-expo active:scale-95"> Explore Docs </Button> <Button variant="outline" size="lg" className="border-primary text-primary hover:bg-primary/5 shadow-sm transition-all duration-700 ease-out-expo"> View Source </Button> </div> </motion.div> </div> {/* Dappled Light Effect (SVG filter) */} <svg className="absolute inset-0 w-full h-full z-[5]" xmlns="http://www.w3.org/2000/svg"> <defs> <filter id="dappled-light"> <feTurbulence type="fractalNoise" baseFrequency="0.05" numOctaves="3" result="noise" /> <feDiffuseLighting in="noise" lightingColor="white" surfaceScale="1.5" result="light"> <feDistantLight azimuth="45" elevation="60" /> </feDiffuseLighting> <feComposite operator="in" in="light" in2="SourceGraphic" result="composite" /> <feBlend mode="overlay" in="composite" in2="SourceGraphic" /> </filter> </defs> <rect width="100%" height="100%" filter="url(#dappled-light)" opacity="0.15" /> </svg> <GrainOverlay /> </section> ); }; export default Hero;
6. MDX Integration & Live Code Blocks
src/components/mdx/LiveCodeBlock.tsxA wrapper that turns a standard code block into an interactive editor/preview.'use client'; import { useState } from 'react'; import { LiveProvider, LiveEditor, LiveError, LivePreview } from 'react-live'; import { tokens } from '@/design-tokens'; import { Button } from '@/components/ui/button'; // Our styled button const scope = { Button, // Any other components you want available in the live preview h1: (props: any) => <h1 className="font-display text-3xl my-4" {...props} />, p: (props: any) => <p className="font-sans leading-relaxed mb-4" {...props} />, // Utility to use tokens directly tokens: tokens }; const LiveCodeBlock = ({ code, children }: { code: string; children?: React.ReactNode }) => { const [showPreview, setShowPreview] = useState(true); return ( <div className="my-8 border border-primary/20 rounded-2xl overflow-hidden shadow-sm bg-surface/50 backdrop-blur-sm"> {/* Toolbar */} <div className="flex items-center justify-between px-4 py-2 bg-primary/5 border-b border-primary/10"> <span className="text-xs font-semibold font-sans text-muted uppercase tracking-wider"> Interactive Demo </span> <div className="flex gap-2"> <button onClick={() => setShowPreview(!showPreview)} className={`px-3 py-1 text-xs rounded-full transition-colors ${showPreview ? 'bg-primary text-white' : 'bg-transparent text-muted hover:bg-primary/10'}`} > Preview </button> <button className="px-3 py-1 text-xs rounded-full bg-transparent text-muted hover:bg-primary/10"> Edit </button> </div> </div> <div className={`grid ${showPreview ? 'grid-cols-1 md:grid-cols-2' : 'grid-cols-1'}`}> {showPreview && ( <div className="p-8 bg-surface flex items-center justify-center min-h-[300px] border-r border-primary/10"> <LiveProvider code={code} scope={scope} noInline> <LivePreview className="!bg-transparent !p-0" /> <LiveError className="mt-4 p-4 bg-red-50 text-red-600 rounded-lg text-sm font-mono" /> </LiveProvider> </div> )} <div className="relative group"> <LiveProvider code={code} scope={scope} noInline> <LiveEditor className="!bg-[#FAFAFA] !p-4 text-sm font-mono leading-6 h-full max-h-[500px] overflow-auto" style={{ fontFamily: 'Menlo, Monaco, "Courier New", monospace', background: 'transparent' }} /> </LiveProvider> </div> </div> </div> ); }; export default LiveCodeBlock;Usage inside MDX:
import LiveCodeBlock from '@/components/mdx/LiveCodeBlock'; <LiveCodeBlock code={`<Button variant="outline">Click me</Button>`} />
7. Dynamic, Wavy Section Separators
src/components/ui/WavyDivider.tsxUses SVG paths generated with sine waves, ensuring they are seamless and fully responsive.import React from 'react'; interface WavyDividerProps { color?: string; invert?: boolean; className?: string; } const WavyDivider: React.FC<WavyDividerProps> = ({ color = '#F8F9FA', // Defaults to surface color invert = false, className = '' }) => { const pathData = invert ? 'M0,320L48,272C96,224,192,128,288,101.3C384,75,480,117,576,154.7C672,192,768,224,864,197.3C960,171,1056,85,1152,69.3C1248,53,1344,107,1392,133.3L1440,160L1440,320L1392,320C1344,320,1248,320,1152,320C1056,320,960,320,864,320C768,320,672,320,576,320C480,320,384,320,288,320C192,320,96,320,48,320L0,320Z' : 'M0,96L48,112C96,128,192,160,288,186.7C384,213,480,235,576,213.3C672,192,768,128,864,128C960,128,1056,192,1152,208C1248,224,1344,192,1392,176L1440,160L1440,0L1392,0C1344,0,1248,0,1152,0C1056,0,960,0,864,0C768,0,672,0,576,0C480,0,384,0,288,0C192,0,96,0,48,0L0,0Z'; return ( <svg className={`w-full h-24 md:h-32 block ${className}`} viewBox="0 0 1440 320" preserveAspectRatio="none" xmlns="http://www.w3.org/2000/svg" > <path fill={color} d={pathData} /> </svg> ); }; export default WavyDivider;Usage:
<div className="bg-primary"> <WavyDivider invert color="#F8F9FA" /> </div> <section className="bg-surface pb-20"> <div className="container mx-auto px-4"> {/* Content */} </div> </section>
8. Putting It All Together: The Documentation Layout
src/app/docs/layout.tsximport type { Metadata } from 'next'; import { Inter, Playfair_Display } from 'next/font/google'; import '@/styles/globals.css'; import { tokens } from '@/design-tokens'; import Header from '@/components/layout/Header'; import Footer from '@/components/layout/Footer'; const inter = Inter({ subsets: ['latin'], variable: '--font-sans', display: 'swap' }); const playfair = Playfair_Display({ subsets: ['latin'], variable: '--font-serif', display: 'swap' }); export const metadata: Metadata = { title: 'Symbiosis Docs', description: 'Design tokens meet living code.' }; export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( <html lang="en" className={`${inter.variable} ${playfair.variable}`}> <body className="font-sans antialiased bg-surface text-text-primary"> <Header /> <main className="min-h-screen"> {children} </main> <Footer /> </body> </html> ); }
9. Example MDX Documentation Page
src/app/docs/getting-started.mdximport { Callout } from '@/components/ui/callout'; import LiveCodeBlock from '@/components/mdx/LiveCodeBlock'; import { tokens } from '@/design-tokens'; # Getting Started Welcome to the Symbiosis documentation. This microsite is built to demonstrate the synergy between **design tokens** and **living code**. ## Core Philosophy The central premise is that there is **one source of truth** for all visual properties. Colors, spacing, fonts, motion curves, and even 3D parameters are defined in `design-tokens.ts`. This file is consumed by: - Tailwind CSS (via `tailwind.config.js`) - React components (direct import) - Three.js scenes (for colors, noise speed, etc.) - Framer Motion (for transition curves) <Callout type="info"> This ensures pixel-perfect alignment between your Figma designs and the final implementation. </Callout> ## Interactive Example The button below is styled using our token system. Try editing the code! <LiveCodeBlock code={`<Button className="bg-primary text-white hover:bg-primary-light transition-colors duration-300"> Press Me </Button>`} /> ## The 3D Hero The hero section uses a morphing organic blob with the following token-defined parameters: - Color: `tokens.three.blobColor` - Distortion Speed: `tokens.three.noiseSpeed` - Mouse Influence: Computed from `tokens.three.mouseInfluenceRadius` The visual style is intentionally fluid, using noise-based vertex displacement and a soft palette to evoke natural, non-digital forms. <div className="h-64 my-8 rounded-2xl border border-primary/20 overflow-hidden relative"> {/* A static representation, but the real page has the full 3D scene */} <div className="absolute inset-0 bg-gradient-to-br from-primary/20 to-accent/20 flex items-center justify-center"> <span className="font-display text-2xl text-text-secondary/60"> 3D Blob (see home page) </span> </div> </div> ## Next Steps - Explore the **Components** section to see more UI elements. - Read about **Customizing Tokens** to adapt the system to your brand. - Learn how to **Create Your Own Live Blocks**.
10. Additional Aesthetic Enhancements
Global Styles:
src/styles/globals.css@tailwind base; @tailwind components; @tailwind utilities; @layer base { :root { --font-sans: 'Inter', sans-serif; --font-serif: 'Playfair Display', serif; --font-display: 'Cormorant Garamond', serif; } html { scroll-behavior: smooth; } body { background-color: var(--color-surface); color: var(--color-text-primary); overflow-x: hidden; } /* Custom scrollbar - thin, organic */ ::-webkit-scrollbar { width: 8px; } ::-webkit-scrollbar-track { background: var(--color-surface); } ::-webkit-scrollbar-thumb { background: var(--color-primary); border-radius: 4px; } } @layer utilities { .text-balance { text-wrap: balance; } }
Key Design-Engineering Alignments Achieved
- Single Source of Truth:
design-tokens.tsis the definitive source. Tailwind variables, React styles, and Three.js parameters all reference it. Changing a token here cascades everywhere. - Consistent Motion: All transitions (buttons, scroll effects) use the specified Bezier curves (
easeOutExpo) for that organic, high-end feel. - Visual Cohesion: The color palette, noise overlay, organic shapes, and typography are uniformly applied across the 3D canvas, the UI components, and the documentation content.
- Performance-First 3D: The
OrganicBlobusesreact-three-fiberwith optimized geometry (IcosahedronGeometrywith 64 subdivisions) and a performant material (MeshDistortMaterial). It usesuseFramesparingly for smooth animation. - Interactive Documentation: MDX +
LiveCodeBlockbrings the documentation to life, allowing engineers to experiment with components in the context of the design system. - Atmosphere: The combination of the dappled light SVG filter, the noise overlay (with
mix-blend-overlay), and the wavy section dividers creates a tangible, textured, and calm environment that feels far from a typical sterile docs site.
This architecture is scalable, maintainable, and directly embodies the brief of aligning design and engineering through a shared, expressive token system while pushing the boundaries of what a documentation site can feel like.
- Single Source of Truth:
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.