ui-wireframe-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Katsuragi UI Wireframe Generator

Katsuragi UI线框图生成工具

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

使用

.kui

文件语法生成基于文本的UI线框图。Katsuragi可将简洁的声明式文件转换为SVG/PNG图片，作为UI设计讨论的沟通媒介。

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

Install

安装步骤

bash

undefined

bash

undefined

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

undefined

npx ktr input.kui -o output.png

undefined

Why Katsuragi?

为什么选择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

LLM友好：基于文本的格式，AI Agent可读取、编写并迭代
易读性强：语法简洁，无需设计工具即可理解
Git友好：可将线框图与代码一同进行版本控制
无需设计技能：基于网格的布局自动处理元素定位
输出即时：通过CLI几秒内即可生成PNG/SVG图片

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
```

开发者与利益相关者沟通：无需Figma即可展示大致UI想法
AI辅助UI开发：让LLM以
```
.kui
```
格式提出布局方案
快速原型制作：在编写前端代码前勾勒屏幕布局
文档编写：将线框图嵌入技术规范和PR中
设计讨论：通过文本差异迭代布局方案
逆向工程：使用
```
ktr fetch
```
将现有网页转换为
```
.kui
```
线框图

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

创建快速UI线框图或原型图
与利益相关者讨论UI布局
生成UI设计的可视化表示
以文本格式记录UI结构

Quick Start

快速开始

To generate a wireframe:

bash

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

要生成线框图：

bash

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

Fetch Command

Fetch命令

Convert existing webpages to

.kui

wireframes:

bash

undefined

将现有网页转换为

.kui

线框图：

bash

undefined

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

undefined

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

undefined

Options

选项参数

Option	Description	Default
`-o, --output <file>`	Output .kui file path (required)	-
`--viewport <type>`	Target viewport: desktop, mobile, tablet	desktop
`--grid <grid>`	Override grid size (e.g., 4x3)	auto
`--ratio <ratio>`	Override aspect ratio (e.g., 16:9)	auto

选项	描述	默认值
`-o, --output <file>`	输出.kui文件路径（必填）	-
`--viewport <type>`	目标视口类型：desktop、mobile、tablet	desktop
`--grid <grid>`	自定义网格尺寸（例如：4x3）	auto
`--ratio <ratio>`	自定义宽高比（例如：16:9）	auto

How It Works

工作原理

Fetches HTML from the URL (no headless browser)
Extracts
```
<meta name="theme-color">
```
as the primary color for the
```
colors
```
header
Extracts inline style colors (
```
background-color
```
,
```
border-color
```
) per element
Parses DOM to extract visual elements (header, nav, main, footer, buttons, inputs, etc.)
Auto-calculates optimal grid size based on element positions
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)
Applies extracted colors to component
```
bg
```
and
```
border
```
properties
Generates
```
.kui
```
file with cell assignments

从URL获取HTML内容（无需无头浏览器）
提取
```
<meta name="theme-color">
```
作为
```
colors
```
头部的主色调
提取每个元素的内联样式颜色（
```
background-color
```
、
```
border-color
```
）
解析DOM结构提取视觉元素（header、nav、main、footer、按钮、输入框等）
根据元素位置自动计算最优网格尺寸
将HTML元素映射为带真实内容的kui组件：
- ```
header
```
  、
```
nav
```
  、
```
footer
```
  等 → 带语义标签的
```
txt
```
  组件（如"Header"、"Navigation"、"Footer"）
- ```
button
```
  → 带实际按钮文本的
```
btn
```
  组件
- ```
input
```
  、
```
textarea
```
  、
```
select
```
  → 带占位符或基于类型标签的
```
input
```
  组件
- ```
img
```
  → 带替代文本的
```
img
```
  组件
- ```
h1
```
  -
```
h6
```
  、
```
p
```
  、
```
span
```
  、
```
label
```
  （含文本）→ 带实际文本内容的
```
txt
```
  组件（内容会截断）
将提取的颜色应用到组件的
```
bg
```
和
```
border
```
属性
生成包含单元格分配的
```
.kui
```
文件

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)

不支持CSS解析（仅基于结构分析）
不支持JavaScript执行（无法处理SPA）
最大网格尺寸：26×26
文本内容会被截断以适配线框显示（最多20-30个字符）

File Structure

文件结构

Every

.kui

file follows this structure:

kui

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 }

每个

.kui

文件遵循以下结构：

kui

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.

单元格采用类似Excel的标记方式：

单个单元格：
```
A1
```
（A列，第1行）
单元格范围：
```
A1..B2
```
（合并从A1到B2的单元格）
列：A、B、C、D...（从左到右）
行：1、2、3...（从上到下）

网格将画布均等划分。4x3的网格会创建4个等宽列和3个等高行。

Components

组件

Type	Purpose	Key Properties
`txt`	Text label	`value` , `align`
`box`	Empty container	`bg` , `border`
`btn`	Button	`value` , `bg`
`input`	Form input	`label`
`img`	Image placeholder	`alt`

类型	用途	关键属性
`txt`	文本标签	`value` 、 `align`
`box`	空容器	`bg` 、 `border`
`btn`	按钮	`value` 、 `bg`
`input`	表单输入框	`label`
`img`	图片占位符	`alt`

Common Properties

通用属性

Property	Values	Default
`align`	`left` , `center` , `right`	`left`
`bg`	Color (hex, name, or `$ref` )	`#e0e0e0`
`border`	Color (hex, name, or `$ref` )	none
`padding`	Number (pixels)	`0`

属性	取值	默认值
`align`	`left` 、 `center` 、 `right`	`left`
`bg`	颜色（十六进制、颜色名称或 `$ref` ）	`#e0e0e0`
`border`	颜色（十六进制、颜色名称或 `$ref` ）	none
`padding`	数值（像素）	`0`

Color System

颜色系统

Define reusable colors in the header:

kui

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

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

Supported formats:

#RGB

#RRGGBB

, CSS color names

在头部定义可复用的颜色：

kui

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

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

支持的格式：

#RGB

、

#RRGGBB

、CSS颜色名称

Output Specifications

输出规格

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

最长边：固定为1280px
宽高比：
```
16:9
```
→ 1280×720，
```
4:3
```
→ 1280×960，
```
9:16
```
→ 720×1280

Syntax Reference

语法参考

For complete syntax details, see

references/syntax.md

完整语法细节请查看

references/syntax.md

。

Examples

示例

Login Form

登录表单

kui

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 }

kui

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

仪表盘布局

kui

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 }

kui

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)

移动端个人资料（竖屏）

kui

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 }

kui

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

工作流程

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

定义画布 - 根据目标布局设置宽高比和网格尺寸
规划网格 - 在脑中或纸上勾勒单元格位置
编写.kui文件 - 先编写头部信息，再从上到下定义单元格
生成输出文件 - 运行
```
npx ktr file.kui -o output.png
```
命令
迭代优化 - 根据需要调整网格、间距或组件

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

在
```
colors
```
块中使用有意义的颜色名称
添加注释（
```
//
```
）来划分不同区域
先为主要区域使用大的合并单元格，再进行细化
使用
```
gap
```
属性实现元素间的清晰分隔
同时测试SVG和PNG格式以选择最合适的输出类型