Month: February 2026

日本語版 README

Turn UI ideas into wireframes with a text format AI actually understands.

• Developers discussing UI with non-technical stakeholders
• Engineers using AI coding assistants (Claude Code, Cursor, Aider)
• Teams who want git-diffable UI specs

---
config:
  themeVariables:
    xyChart:
      plotColorPalette: "#9CA3AF, #3B82F6, #F87171"
---
xychart-beta
    title "Tokens per wireframe (login example)"
    x-axis ["Natural Lang", "ASCII", ".kui", "HTML"]
    y-axis "Tokens" 0 --> 400
    bar [102, 84, 0, 0]
    bar [0, 0, 120, 0]
    bar [0, 0, 0, 330]

.kui hits the sweet spot between efficiency and reliability:

50% fewer tokens than HTML, with the same precision.

→ Full comparison with 3 patterns

Write a .kui file:

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

A1..D1: { type: txt, value: "Login", align: center }
A2..D2: { type: input, label: "Email" }
A3..C3: { type: input, label: "Password" }
D3: { type: btn, value: "Login", bg: $primary }

Run one command:

npx ktr login.kui -o login.png

Get this:

If this tool saves you time:

Star this repo to help others find it!

# One-time use (no install)
npx ktr input.kui -o output.png

# Global install
npm install -g katsuragi

Tip: ktr is a shorter alias for katsuragi – use whichever you prefer.

# Create a sample file
cat > hello.kui  'EOF'
ratio: 16:9
grid: 2x2
A1: { type: txt, value: "Hello Katsuragi!", align: center }
A2..B2: { type: btn, value: "Get Started" }
EOF

# Generate image
katsuragi hello.kui -o hello.png

# Output SVG to stdout
ktr input.kui

# Save to file (format auto-detected from extension)
ktr input.kui -o output.svg
ktr input.kui -o output.png

# Explicit format
ktr input.kui -f png -o output.png

# Batch conversion
ktr *.kui -d ./output -f png

# Read from stdin
cat input.kui | ktr -o output.png

CLI Options:

Katsuragi uses a text format because AI can read and write it.

• Easy to copy/paste – No binary format, no special tools needed
• Fits in context windows – .kui files are small, AI can hold entire layouts in memory
• Diff-friendly – Changes are trackable in git, easy to review
• No vendor lock-in – Works with any LLM (ChatGPT, Claude, Gemini, local models)

1. Add .kui spec to your project (in AGENTS.md, system prompt, or project docs)
2. Ask AI: “Create a login wireframe in .kui format”
3. AI generates the .kui file
4. Run ktr login.kui -o login.png
5. Share the image, discuss, iterate
6. AI updates the .kui based on feedback

• Claude Code – Add spec to CLAUDE.md
• Cursor – Add to project rules
• Aider – Include in context
• Any LLM CLI – Paste spec in system prompt or AGENTS.md

Here's the .kui format specification:
[paste the syntax section below]

Create a mobile app wireframe for a task management app.
Use 2x5 grid (ratio 9:16).
Include: header with title, task list area, and floating action button.

Once the AI knows the format, it can generate and modify .kui code reliably.

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

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

// Form
A2..D2: { type: input, label: "Email" }
A3..C3: { type: input, label: "Password" }
D3: { type: btn, value: "Submit", bg: $primary }

• ratio – Aspect ratio of the canvas (e.g., 16:9, 4:3, 1:1, 9:16)
• grid – Grid divisions as columns x rows (e.g., 4x3 creates columns A-D and rows 1-3)
• Cell references use Excel-style notation: A1, B2, C3
• Range notation: A1..B3 (top-left to bottom-right)

ratio: 16:9
grid: 3x2
gap: 8
padding: 24

A1: { type: box }
B1: { type: box }
C1: { type: box }
A2..C2: { type: txt, value: "Content area", padding: 16 }

• gap – Spacing between cells (in pixels, default: 0)
• padding – Canvas margin (in pixels, default: 0)
• Per-cell padding – Override content padding for individual cells

Use // for comments:

// This is a comment
A1: { type: txt, value: "Hello" }  // End-of-line comment

Define a color theme and use $name references:

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

A1: { type: btn, value: "Submit", bg: $primary }
A2: { type: btn, value: "Delete", bg: $danger, border: $accent }
B1: { type: box, bg: "#f0f0f0", border: "#ccc" }
B2: { type: box, bg: lightblue }

Color formats:

• HEX: #RGB or #RRGGBB (e.g., #f00, #3B82F6)
• CSS color names: red, blue, lightblue, orange, etc.
• Theme reference: $name (requires colors: definition)

• align: left (default), center, right

Use \n for line breaks:

A1: { type: txt, value: "Line 1\nLine 2\nLine 3" }

Or use backticks for multi-line strings:

A1: { type: txt, value: `
  Welcome to
  Katsuragi
` }

Note: Automatic text wrapping is not supported. For long text, manually insert \n at desired break points.

The longest edge is fixed at 1280px. The shorter edge is calculated from the ratio:

• 16:9 → 1280 × 720
• 4:3 → 1280 × 960
• 1:1 → 1280 × 1280
• 9:16 → 720 × 1280 (mobile)

• Open Source: AGPL-3.0 (free if you open-source your code)
• Commercial Products: Free to use for building commercial products
• Commercial License Required: Only when embedding Katsuragi into SaaS platforms or distributing as closed-source

Example: Using Katsuragi to create wireframes for your commercial app? Totally free. Integrating Katsuragi into your design tool SaaS? Commercial license required.

For commercial licensing, contact En-Links LLC.

This software uses the following open-source libraries:

Katsuragi is built on the shoulders of giants:

• libvips by John Googley-Fletcher and contributors – The fast image processing engine that powers our PNG generation
• sharp by Lovell Fuller – Making libvips accessible from Node.js with an elegant API
• commander.js by TJ Holowaychuk – The standard for building Node.js CLI tools

Copyright © 2025 En-Links LLC