Free DESIGN.md Templates: Google-Compatible Specs for AI Agents

If you've ever tried to feed raw, minified HTML with deep React nesting into an LLM context, you know the pain: you waste 20,000 tokens on useless <div> soup and close-tags. The AI agent receives a mess of structural noise instead of the clean, actionable design information it needs to generate accurate code.

This is the problem Open DesignMD solves. It's an autonomous web app built on Next.js 16 and Tailwind CSS v4 that converts any public URL into a clean design spec (DESIGN.md) for AI agents. By utilizing free open alternatives like Jina Reader and Microlink, it removes paid SaaS paywalls entirely.

Why DESIGN.md Matters for AI Coding Agents

Modern AI coding agents—Cursor, Windsurf, Claude, Copilot—work best when they understand the design system they're building against. A DESIGN.md file provides that context in a structured format: color palettes, spacing scales, typography, component patterns, and accessibility requirements.

Consider a typical scenario. You're building a dashboard component for an existing React application. Without design context, the AI agent might generate a button with padding: 12px when your design system uses 8px spacing increments. It might pick #333 for text color when your brand uses oklch(0.25 0.02 260). These mismatches create friction—you spend time fixing styles instead of focusing on functionality.

A DESIGN.md eliminates this friction. It tells the AI agent exactly what tokens, patterns, and conventions to use. The result? Generated code that matches your design system from the first iteration.

Of course, there are plenty of services that do this. The designmd.supply service demonstrated this concept works. But it's a paid SaaS product. For developers running local AI workflows, iterating on design systems, or building in privacy-sensitive environments, a self-hosted alternative isn't just convenient—it's necessary.

But is it even possible to do without paid APIs altogether?

The Tech Stack: Why Next.js 16 and Tailwind v4?

100% free and open-source Open DesignMD isn't just a wrapper around an API. It's a full-stack application that demonstrates modern web development patterns while solving a real problem. The choice of Next.js 16 and Tailwind CSS v4 isn't arbitrary—each brings specific advantages that make the tool more capable and maintainable.

Next.js 16 Route Handlers

The core of the application lives in a single API route. Here's the actual implementation:

// app/api/design-md/route.ts
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';
import { NextRequest, NextResponse } from 'next/server';

const PROMPT = `Analyze this webpage and generate a comprehensive DESIGN.md file...
[truncated for brevity]`;

export async function POST(req: NextRequest) {
  const { url } = await req.json();
  
  // Fetch and clean the HTML using Jina Reader
  const response = await fetch(`https://r.jina.ai/${url}`);
  const html = await response.text();
  
  const { text } = await generateText({
    model: openai.chat('gpt-4o-mini', {
      compatibility: 'compatible',
    }),
    prompt: PROMPT + html,
  });
  
  return NextResponse.json({ designMd: text });
}

The compatibility: 'compatible' flag is critical. It forces the Vercel AI SDK to use the standard /v1/chat/completions endpoint instead of OpenAI's newer /v1/responses API. This matters when you're routing through custom gateways, Ollama, or OpenRouter—all of which expect the chat completions format.

Tailwind CSS v4: CSS-Only Configuration

Tailwind v4 introduces a paradigm shift: configuration moves from JavaScript to CSS. Open DesignMD leverages this with the @theme inline directive:

@import "tailwindcss";

@theme inline {
  --color-primary: oklch(0.65 0.25 260);
  --color-secondary: oklch(0.75 0.18 180);
  --font-sans: "Inter", system-ui, sans-serif;
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  --spacing-xl: 2rem;
}

This approach eliminates the tailwind.config.js file entirely. Your design tokens live in CSS, making them directly consumable by browsers and build tools without JavaScript processing overhead. Turbopack handles the rest, delivering sub-second hot reloads during development.

Multi-Provider LLM Support

One of Open DesignMD's strongest features is its flexibility with AI providers. The Vercel AI SDK abstracts the underlying API, so you can swap between providers with a single environment variable change.

Configuration Block

Here's the .env.example showing supported providers:

# Choose your AI provider (uncomment one)

# Option 1: OpenAI (requires API key)
OPENAI_API_KEY=sk-your-key-here

# Option 2: Ollama (local, free, no key needed)
OPENAI_API_BASE=http://localhost:11434/v1
OPENAI_API_KEY=ollama

# Option 3: OpenRouter (multi-model gateway)
OPENAI_API_BASE=https://openrouter.ai/api/v1
OPENAI_API_KEY=sk-or-your-key

# Option 4: Google Gemini
GOOGLE_GENERATIVE_AI_API_KEY=your-gemini-key

# Option 5: Anthropic
ANTHROPIC_API_KEY=sk-ant-your-key

The beauty here is simplicity. Switching from OpenAI to Ollama doesn't require code changes—just update two environment variables. For developers running 100+ builds daily, this eliminates API costs entirely.

The .chat() Fix: Why It Matters

Here's a gotcha that trips up many developers using the Vercel AI SDK with custom gateways. When you use openai('gpt-4o-mini'), the SDK attempts to call OpenAI's /v1/responses endpoint by default. Most OpenAI-compatible gateways (Ollama, vLLM, LocalAI) don't support this newer endpoint.

The fix is explicit model invocation with the chat() method:

// ❌ This might call /v1/responses
const model = openai('gpt-4o-mini');
const { text } = await generateText({ model, prompt });

// ✅ This forces /v1/chat/completions
const model = openai.chat('gpt-4o-mini', {
  compatibility: 'compatible',
});
const { text } = await generateText({ model, prompt });

Without this pattern, your self-hosted setup will throw cryptic 404 errors. Open DesignMD includes this fix by default, saving you hours of debugging.

Data Flow: From URL to DESIGN.md

The processing pipeline is straightforward but effective:

Target URL → Jina Reader → Clean Markdown → LLM Analysis → DESIGN.md Output
     ↓              ↓              ↓              ↓              ↓
  User Input    HTML Parsing   Token Reduction  AI Processing  Structured Spec

Jina Reader handles the heavy lifting of HTML-to-Markdown conversion. Unlike raw HTML scraping, it strips navigation, scripts, and layout noise, preserving only content and structure. This reduces token consumption by 60-80% compared to feeding raw HTML directly to the LLM.

Self-Hosted Setup: One-Click Local Portability

Getting Open DesignMD running locally takes five minutes. The application uses a completely self-contained Windows setup with local Node.js runtimes, avoiding global configuration issues.

Quick Start

# Clone the repository
git clone https://github.com/Yp-pro/open-designmd.git
cd open-designmd

# Install dependencies
npm install

# Copy environment template
cp .env.example .env.local

# Start development server
npm run dev

That's it. No global npm packages, no Docker containers, no cloud dependencies. The SQLite database (via Turso) initializes automatically on first run.

Windows-Specific Considerations

Windows developers often face friction with native Node modules. The better-sqlite3 package, which Open DesignMD uses for local storage, requires compilation against the Visual C++ runtime. On fresh Windows installations, this usually means installing the Build Tools for Visual Studio.

The setup script handles this gracefully. If it detects missing build tools, it prompts for administrator elevation and downloads the necessary components. For teams deploying on Windows Server or CI environments, the script supports unattended installation via the --silent flag.

Docker Alternative

For developers who prefer containerization, Open DesignMD includes a Dockerfile and docker-compose.yml. The containerized version bundles Node.js 20, SQLite, and all dependencies. Run docker compose up and access the application at localhost:3000. This approach works identically across Windows, macOS, and Linux—useful when your team mixes operating systems.

Trade-offs: Why Not Just Use designmd.supply?

The original service is excellent. It's well-maintained, has a clean UI, and handles edge cases gracefully. So why self-host?

Cost at Scale: Running 100 design extractions daily on the paid service costs \(5-10/day. With Ollama and Jina's free tier, Open DesignMD costs \)0. For indie developers and small teams, this difference compounds quickly. Over a year, you're looking at $1,800-3,600 in savings—enough to fund other parts of your development stack.

Privacy: If you're building internal tools, client projects, or working with proprietary designs, sending URLs to a third-party service isn't ideal. Self-hosting keeps everything on your machine. No data leaves your network. No third-party logs. No risk of design information leaking through API requests.

Customization: Need to extract specific design tokens? Want to add custom LLM prompts for your design system? Fork Open DesignMD and modify the prompt template. The codebase is 200 lines total. Compare that to reverse-engineering a SaaS API—you'll spend less time forking than you would understanding their undocumented endpoints.

Offline Development: Working on a plane, in a secure facility, or without internet? Open DesignMD with Ollama works completely offline. No API keys required. No network dependencies. This is invaluable for developers in restrictive environments or those working with classified/proprietary designs.

Learning Opportunity: The codebase demonstrates Next.js 16 App Router patterns, Vercel AI SDK integration, Tailwind v4 configuration, and SQLite/Turso usage. Reading the source teaches you modern web development techniques you can apply to your own projects.

What You Get: The Output Format

The generated DESIGN.md follows a consistent structure that AI agents can parse reliably:

# Design Specification

## Color Palette
- Primary: `oklch(0.65 0.25 260)` (vibrant blue)
- Secondary: `oklch(0.75 0.18 180)` (teal accent)
- Background: `#ffffff`
- Text: `#1a1a1a`

## Typography
- Headings: Inter, 700 weight
- Body: Inter, 400 weight
- Code: JetBrains Mono, monospace

## Spacing Scale
- xs: 0.25rem (4px)
- sm: 0.5rem (8px)
- md: 1rem (16px)
- lg: 1.5rem (24px)
- xl: 2rem (32px)

## Component Patterns
[Extracted from page structure]

AI agents consume this format naturally. Cursor uses it to generate component code that matches the existing design system. Claude references it when explaining design decisions. Copilot leverages it for context-aware completions.

Beyond Basic Tokens

The output goes beyond simple color and spacing values. Open DesignMD extracts component-level patterns: button styles, card layouts, form element conventions, and navigation structures. When the LLM analyzes a page, it identifies recurring patterns—a primary button with rounded corners and a specific hover state—and documents them as reusable specifications.

This pattern extraction is what makes DESIGN.md more useful than a simple screenshot or color palette tool. It captures the intent behind design decisions, not just the raw values.

The choice is yours

The open-source community thrives on contribution.

1. Star the original repository: context-dot-dev/designmd-supply — the project that proved this concept works.

2. Star the free fork: Yp-pro/open-designmd — the self-hosted, free alternative.

Building with AI agents means giving them the right context. DESIGN.md is that context. And now it's free.