wiremd

Text-first UI design tool - Create wireframes and mockups using Markdown syntax

wiremd is a markdown-based UI wireframing tool that lets you create wireframes and mockups using familiar markdown syntax with intuitive extensions. Write your UI designs as text, render them as beautiful wireframes.

Why wiremd?

• Designer-friendly syntax - No complex DSL to learn, just extended Markdown
• Version control ready - Store your wireframes as plain text in Git
• Fast iteration - Update designs as quickly as you can type
• Collaboration - Review wireframe changes in pull requests
• Developer handoff - Export to HTML or framework components
• No vendor lock-in - Open source MIT license, runs anywhere

Quick Example

Contact Form

Create a contact.md file:

## Contact Form

Name
[_____________________________]{required}

Email
[_____________________________]{type:email required}

Message
[_____________________________]{rows:5}

[Submit]* [Cancel]

Generate a wireframe:

wiremd contact.md --style sketch

This renders into a styled HTML wireframe with a form, inputs, and buttons.

Grid Layout

Create a features.md file:

## Product Features {.grid-3}

### :rocket: Fast
Lightning quick performance

### :shield: Secure
Bank-level security

### :gear: Flexible
Fully customizable

Generate a wireframe:

wiremd features.md --style sketch

This creates a responsive 3-column grid layout with icons and descriptions.

Features

• ✅ Markdown-first - Valid markdown that degrades gracefully
• ✅ Full markdown support - Headings, text formatting, lists, links, images, blockquotes, code blocks, tables
• ✅ Grid layouts - Responsive multi-column grids (2, 3, 4+ columns) with simple .grid-N syntax
• ✅ Visual syntax - Looks like what it renders
• ✅ Fast to write - Intuitive shortcuts for common patterns
• ✅ Extensible - Add classes and attributes as needed
• ✅ Multiple outputs - HTML, JSON, React (JSX/TSX), Tailwind CSS, Figma (via plugin)
• ✅ 7 visual styles - sketch (Balsamiq-inspired), clean, wireframe, tailwind, material, brutal, none
• ✅ Full CLI tool - Watch mode, live-reload dev server, style switching
• ✅ Rich examples - Showcase files demonstrating all styles
• ✅ Framework renderers - React, Tailwind CSS classes (Vue, Svelte coming soon)
• ✅ VS Code extension - Live preview with real-time updates and style switching

Project Structure

This is an open-source MIT-licensed project containing:

• src/ - Core parser and renderer library
• tests/ - Comprehensive test suite (48 tests)
• docs/ - Documentation site (Live at akonan.github.io/wiremd)
• examples/ - Example wireframes
• figma-plugin/ - Figma plugin for importing wiremd designs
• obsidian-plugin/ - Obsidian plugin for live wireframe previews
• vscode-extension/ - VS Code extension with live preview and style switching

Installation

npm

npm install -g wiremd

yarn

yarn global add wiremd

pnpm

pnpm add -g wiremd

Homebrew (macOS)

brew install akonan/wiremd/wiremd

From Source

git clone https://github.com/akonan/wiremd.git
cd wiremd
npm install
npm run build
npm link

CLI Usage

# Generate HTML with default sketch style
wiremd wireframe.md

# Output to specific file
wiremd wireframe.md -o output.html

# Use alternative styles
wiremd wireframe.md --style clean      # Modern minimal
wiremd wireframe.md --style wireframe  # Traditional grayscale
wiremd wireframe.md --style tailwind   # Utility-first with purple accents
wiremd wireframe.md --style material   # Google Material Design
wiremd wireframe.md --style brutal     # Neo-brutalism style
wiremd wireframe.md --style none       # Unstyled semantic HTML

# Watch mode with live-reload dev server
wiremd wireframe.md --watch --serve 3000

# Generate different output formats
wiremd wireframe.md --format json      # JSON AST output
wiremd wireframe.md --format react     # React/JSX component
wiremd wireframe.md --format tailwind  # HTML with Tailwind CSS classes

Exporting to Figma

wiremd designs can be imported into Figma as fully editable, native Figma designs using the wiremd Figma Plugin.

Quick Start

1. Generate JSON from your wiremd file:

   wiremd your-mockup.md --format json -o mockup.json

2. Install the Figma Plugin:

   • Open Figma → Plugins → Browse plugins
   • Search for "wiremd Importer"
   • Click Install

3. Import to Figma:

   • Open the wiremd Importer plugin
   • Paste your JSON
   • Choose a visual theme (Sketch, Clean, Wireframe, or Minimal)
   • Click "Import to Figma"

Your wiremd design will appear as a new Figma page with:

• Native Figma frames and text nodes
• Auto-layout for responsive designs
• Fully editable components
• Professional styling based on your chosen theme

Visual Themes

• Sketch - Balsamiq-style hand-drawn look (perfect for brainstorming)
• Clean - Modern, polished design (great for presentations)
• Wireframe - Traditional grayscale (ideal for specifications)
• Minimal - Bare-bones styling (customize yourself)

What Gets Imported

✅ All layout components (containers, grids, navigation) ✅ Form elements (buttons, inputs, selects, checkboxes, radios) ✅ Content (headings, paragraphs, lists, tables, code blocks) ✅ Proper spacing, padding, and auto-layout constraints ✅ Theme-specific styling (colors, fonts, shadows)

See figma-plugin/README.md for complete documentation.

Using in Obsidian

wiremd has a native Obsidian plugin that brings live wireframe previews directly into your notes.

Features

• Live Preview: Automatically render wiremd code blocks as interactive previews in Obsidian
• 7 Visual Styles: Switch between sketch, clean, wireframe, tailwind, material, brutal, or none
• Quick Style Switching: Click the style badge to instantly change preview styles
• Export Functionality: Export wiremd previews as standalone HTML files
• Mobile Optimized: Touch-friendly interface with responsive design
• Command Palette Integration: Access all features via Obsidian commands

Installation

1. Clone the plugin into your Obsidian vault's plugins folder:

   cd /path/to/your/vault/.obsidian/plugins/
   git clone https://github.com/akonan/wiremd-obsidian.git wiremd-preview
   cd wiremd-preview
   npm install
   npm run build

2. Enable the plugin in Obsidian:

   • Open Settings → Community Plugins
   • Turn off "Safe mode" if needed
   • Click "Reload" to refresh the plugins list
   • Find "Wiremd Preview" and toggle it on

3. Create wiremd blocks in your notes:

   ```wiremd
   ## Login Form
   
   Username
   [____________________________]
   
   Password
   [****************************]
   
   [Sign In]{.primary} [Cancel]
   ```

The plugin will automatically render a live preview with your chosen style!

Available Commands

• Set style - Change the rendering style (7 commands for each style)
• Toggle auto-preview - Enable/disable automatic rendering
• Refresh previews - Manually refresh all wiremd previews
• Export as HTML - Export current wiremd block as standalone HTML
• Export all styles - Export in all 7 styles at once
• Copy to clipboard - Copy rendered HTML to clipboard

See the wiremd-obsidian repository for complete documentation.

Programmatic API

import { parse, renderToHTML, renderToJSON, renderToReact, renderToTailwind } from 'wiremd';

// Parse markdown to AST
const ast = parse(`
  ## Contact Form

  ![Logo](logo.png)

  Name
  [_____________________________]
  [Submit]{.primary}
`);

// Render to HTML with visual style
const html = renderToHTML(ast, { style: 'sketch' });

// Render to JSON
const json = renderToJSON(ast, { pretty: true });

// Render to React component (TypeScript)
const reactComponent = renderToReact(ast, {
  typescript: true,
  componentName: 'ContactForm'
});

// Render to HTML with Tailwind CSS classes
const tailwindHTML = renderToTailwind(ast, { pretty: true });

Documentation

Not sure where to start? → Documentation Guide

📖 Learning & Reference

| Document | Description | Best For | |----------|-------------|----------| | Syntax Showcase | Comprehensive interactive guide with live examples | Learning by example, copying patterns | | Quick Reference | One-page syntax cheat sheet | Quick lookups, experienced users | | Syntax Guide | User-friendly tutorial with best practices | Structured learning | | FAQ | Common questions and troubleshooting | Solving problems, known issues |

📖 📚 View Full Documentation → - Complete documentation site with interactive examples

🚀 Getting Started

| Document | Description | |----------|-------------| | 🌐 Live Documentation Site | Full docs with interactive examples | | 🚀 Getting Started | Installation and first steps | | 📝 Syntax Reference | Complete syntax guide | | 🎮 Interactive Playground | Try wiremd in your browser | | ⚙️ API Documentation | Programmatic API reference | | 🔌 Framework Integrations | Next.js, React, Vite, Express | | 🔧 Troubleshooting | Common issues and solutions | | 🎨 Live Showcases | Examples in all 7 styles | | 📂 Example Files | Local wiremd files to explore |

🔧 Technical Documentation

| Document | Description | |----------|-------------| | Syntax Specification | Formal specification with parser rules | | API Documentation (Local) | Local API reference | | Project Plan | Development roadmap | | CLAUDE.md | Project overview for AI assistants |

🤝 Contributing

| Document | Description | |----------|-------------| | CONTRIBUTING.md | Contribution guidelines | | TESTING.md | Testing strategy and guidelines | | CODE_OF_CONDUCT.md | Community guidelines | | SECURITY.md | Security policy |

Development Status

✅ Completed (Phase 1-2)

• [x] Research existing solutions
• [x] Create test corpus with 20 UI patterns
• [x] Lock v0.1 syntax specification
• [x] Complete TypeScript implementation
• [x] Parser with full syntax support
• [x] AST transformer with 40+ node types
• [x] HTML renderer with 7 visual styles
• [x] JSON output
• [x] 48+ passing tests
• [x] Full-featured CLI tool with watch mode and live-reload
• [x] Rich example showcase demonstrating all styles
• [x] React component renderer (JSX/TSX output)
• [x] Tailwind CSS class renderer

🚧 In Progress (Phase 3)

• [x] Documentation site ✅ Live Now!
• npm package publishing

📋 Coming Soon (Phase 4+)

• Framework-specific renderers (Vue, Svelte)
• Interactive web playground with live editor

See Project Plan for full roadmap.

Contributing

Contributions are welcome! Phase 1-2 are complete with a working parser, renderer, and CLI. Feel free to:

• Report bugs or request features via GitHub Issues
• Submit pull requests for improvements
• Add new visual styles or examples
• Improve documentation

Please check the Project Plan for upcoming features.

Quick Start for Contributors

# Clone the repository
git clone https://github.com/akonan/wiremd.git
cd wiremd

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Run type check
npm run typecheck

License

MIT License - See LICENSE for details.

Community & Support

• Issues & Bugs - GitHub Issues
• Discussions - GitHub Discussions
• Security - See SECURITY.md
• Changelog - CHANGELOG.md

Credits

Created by akonan

Inspired by:

• Balsamiq - Pioneering rapid wireframing
• Mermaid - Markdown-inspired diagramming
• PlantUML Salt - Text-based GUI mockups
• Markdown-UI - Markdown to UI components

Status: Phase 1-2 Complete (Core + CLI) | Version: 0.1.0 | Node: ≥18.0.0

Made with ❤️ for designers and developers who love plain text