Katsuragi UI Wireframe Generator

Generate text-based UI wireframes using .kui file syntax. Katsuragi converts simple declarative files into SVG/PNG images, serving as a communication medium for UI discussions.

GitHub: https://github.com/enlinks-llc/katsuragi

Install

# Install this skill
npx skills add enlinks-llc/katsuragi

# Install katsuragi CLI
npm install -g katsuragi
# or use directly with npx
npx ktr input.kui -o output.png

Why Katsuragi?

• LLM-friendly: Text-based format that AI agents can read, write, and iterate on
• Human-readable: Simple syntax anyone can understand without design tools
• Git-friendly: Version control your wireframes alongside code
• Zero design skills needed: Grid-based layout handles positioning automatically
• Instant output: Generate PNG/SVG in seconds via CLI

Use Cases

• Developer ↔ Stakeholder communication: Show rough UI ideas without Figma
• AI-assisted UI development: Let LLMs propose layouts in .kui format
• Quick prototyping: Sketch screen layouts before writing any frontend code
• Documentation: Embed wireframes in technical specs and PRs
• Design discussions: Iterate on layouts through text diffs
• Reverse engineering: Convert existing webpages to .kui wireframes with ktr fetch

When to Use

• Creating quick UI wireframes or mockups
• Discussing UI layouts with stakeholders
• Generating visual representations of UI designs
• Documenting UI structures in a text-based format

Quick Start

To generate a wireframe:

npx ktr input.kui -o output.png  # PNG output
npx ktr input.kui -o output.svg  # SVG output

Fetch Command

Convert existing webpages to .kui wireframes:

# Basic usage
npx ktr fetch https://example.com -o output.kui

# With viewport option (desktop, mobile, tablet)
npx ktr fetch https://example.com -o output.kui --viewport mobile

# With custom grid and ratio
npx ktr fetch https://example.com -o output.kui --grid 6x4 --ratio 4:3

Options

How It Works

1. Fetches HTML from the URL (no headless browser)
2. Extracts <meta name="theme-color"> as the primary color for the colors header
3. Extracts inline style colors (background-color, border-color) per element
4. Parses DOM to extract visual elements (header, nav, main, footer, buttons, inputs, etc.)
5. Auto-calculates optimal grid size based on element positions
6. Maps HTML elements to kui components with real content:
   • header, nav, footer, etc. → txt with semantic labels ("Header", "Navigation", "Footer")
   • button → btn with actual button text
   • input, textarea, select → input with placeholder or type-based label
   • img → img with alt text
   • h1-h6, p, span, label (with text) → txt with actual text content (truncated)
7. Applies extracted colors to component bg and border properties
8. Generates .kui file with cell assignments

Limitations

• No CSS parsing (structure-based analysis only)
• No JavaScript execution (SPA not supported)
• Maximum grid size: 26×26
• Text content is truncated for wireframe display (max 20-30 characters)

File Structure

Every .kui file follows this structure:

ratio: 16:9              // Canvas aspect ratio
grid: 4x3                // Grid dimensions (columns x rows)
gap: 8                   // Space between cells (optional)
padding: 16              // Canvas padding (optional)
colors: { name: "#hex" } // Color definitions (optional)

// Cell definitions
A1..B2: { type: component, property: value }

Grid System

Cells use Excel-style notation:

• Single cell: A1 (column A, row 1)
• Range: A1..B2 (merges cells from A1 to B2)
• Columns: A, B, C, D... (left to right)
• Rows: 1, 2, 3... (top to bottom)

Grid divides canvas equally. A 4x3 grid creates 4 equal columns and 3 equal rows.

Components

Common Properties

Color System

Define reusable colors in the header:

colors: { primary: "#3B82F6", danger: "#EF4444", accent: "orange" }

// Use with $ prefix
D3: { type: btn, value: "Submit", bg: $primary }

Supported formats: #RGB, #RRGGBB, CSS color names

Output Specifications

• Longest edge: Fixed at 1280px
• Aspect ratios: 16:9 → 1280×720, 4:3 → 1280×960, 9:16 → 720×1280

Syntax Reference

For complete syntax details, see references/syntax.md.

Examples

Login Form

ratio: 16:9
grid: 4x3
gap: 8
padding: 16
colors: { primary: "#3B82F6" }

// Header
A1..D1: { type: txt, value: "Login", align: center }

// Form fields
A2..D2: { type: input, label: "Email" }
A3..C3: { type: input, label: "Password" }

// Submit button
D3: { type: btn, value: "Login", bg: $primary }

Dashboard Layout

ratio: 16:9
grid: 4x3
gap: 8
padding: 16
colors: { secondary: "#f5f5f5", outline: "#333" }

// Navigation
A1: { type: img, alt: "Logo" }
B1..C1: { type: txt, value: "Dashboard", align: center }
D1: { type: btn, value: "Logout", border: $outline }

// Sidebar
A2..A3: { type: box, bg: $secondary }

// Main content area
B2..D2: { type: txt, value: "Welcome back!", align: left }
B3..D3: { type: box, border: $outline }

Mobile Profile (Vertical)

ratio: 9:16
grid: 3x5
gap: 8
padding: 16
colors: { primary: "#3B82F6", outline: "#333" }

// Header
A1..C1: { type: txt, value: "My App", align: center }

// Profile image
A2..C2: { type: img, alt: "Profile Photo" }

// User info
A3..C3: { type: txt, value: "John Doe", align: center }

// Actions
A4..C4: { type: btn, value: "Edit Profile", bg: $primary }
A5..C5: { type: btn, value: "Settings", border: $outline }

Workflow

1. Define the canvas - Set ratio and grid size based on target layout
2. Plan the grid - Sketch cell positions mentally or on paper
3. Write .kui file - Start with header, then define cells top-to-bottom
4. Generate output - Run npx ktr file.kui -o output.png
5. Iterate - Adjust grid, spacing, or components as needed

Best Practices

• Use meaningful color names in the colors block
• Add comments (//) to organize sections
• Start with larger merged cells for main areas, then refine
• Use gap for clean separation between elements
• Test with both SVG and PNG to choose the best format