zul-writer

Original：🇺🇸 English

Translated

1 scriptsChecked / no sensitive code detected

Generates ZK Framework ZUL pages (.zul) through a structured 4-step workflow: requirements clarification, ZUL generation, validation, and controller generation. Supports both MVC (Composer-based) and MVVM (ViewModel-based) patterns, ZK 9/10, and visual analysis for screenshot-to-ZUL conversion. Use when the user asks to create a ZUL page, build ZK UI components (forms, grids, dashboards, borderlayouts), or convert an image/mockup to ZUL code.

8installs

Sourcezkoss-demo/agent-skill

Added on2026-03-30

NPX Install

npx skill4agent add zkoss-demo/agent-skill zul-writer

SKILL.md Content

View Translation Comparison →

ZUL Writer

Workflow Overview

This skill creates well-structured zul pages through a 4-step process:

Clarify Requirements - Gather page purpose, pattern, and layout needs
Generate ZUL - Create the ZUL file based on requirements
Validate ZUL - Verify correctness of the generated ZUL
Generate Controller Class - Create the corresponding Java class (ViewModel or Composer)

Alternative entry: When user provides a UI image (screenshot/mockup), perform the Visual Analysis below first, then proceed to the 4-step process.

Visual Analysis (for Images/Mockups)

When a UI screenshot or mockup image is provided, perform this analysis before starting the 4-step workflow:

Visual Breakdown: Identify all UI elements (layout, inputs, buttons, tables, navigation).
Component & Layout Strategy: Plan the ZK component mapping (refer to references/ui-to-component-mapping.md) and determine the overall layout (e.g.,
```
<borderlayout>
```
, nested
```
<vlayout>
```
).
Tab Content Scope: If tabs are present, determine content boundaries. Items switching with tabs must go INSIDE
```
<tabpanel>
```
. See assets/content-tabbox.zul.
Identify Custom Styling: Mark areas that require fallback HTML elements or custom CSS.

Transition: Use these findings to inform Step 1: Clarify User Requirements and eventually Step 2: Generate ZUL File.

Step 1: Clarify User Requirements

Ask targeted questions to understand needs. If starting from an image, use the results of the Visual Analysis to inform these questions.

Questions to Ask

1. ZK Version

Detect from user's project (check

pom.xml

ivy.xml

, or

build.gradle

for ZK dependency version). If not found, ask:

9 or before
10.x

2. Page Purpose

Data entry form
Data list/grid display
Dashboard with multiple sections
Dialog/popup window
Master-detail view
Search and results page
Other: [specify]

3. MVC or MVVM Pattern

Present both options with equal weight — do NOT mark either as "(Recommended)":

MVVM: ViewModel-based with
```
@bind
```
/
```
@command
```
data binding — testable, requires more ZK familiarity
MVC: Composer-based with
```
apply
```
and wired components — straightforward, beginner-friendly

4. Layout Requirements

Borderlayout (north/south/east/west/center)
Vertical layout (vlayout)
Horizontal layout (hlayout)
Grid-based layout
Tabbed layout (tabbox)
Combined layouts

5. ZK Charts (only when charts are needed)

If the ZUL page requires a

<charts>

component, follow references/charts-guidelines.md before generating any chart code.

6. Theme and Data Density

If a page is designed to show a high density of data, suggest to the user to use another free theme called

iceblue_c

, a compact theme that has smaller padding, margin, and font-size.

Step 2: Generate a ZUL File

Generation Guidelines

When generating the ZUL file, follow these technical guidelines:

Map UI Elements: Consult references/ui-to-component-mapping.md to choose the correct ZK components.
- Prioritize ZK components over native HTML.
- Use layout components like
```
<borderlayout>
```
  ,
```
<vlayout>
```
  , and
```
<hlayout>
```
  effectively.
Handle CSS Inclusion:
- If fallback native HTML elements (e.g.
```
<n:div>
```
  ) are used, identify and include the necessary CSS.
- Use the
```
<style>
```
  element for inline CSS; do not use the
```
<?style ?>
```
  processing instruction.
ZK Documentation:
- Query
```
zk-doc-mcp-server
```
  for detailed component info if available.
- Use ZK Javadoc for properties and event details.
Best Practices:
- Don't specify
```
hflex="min"
```
  on
```
<button>
```
  (it's
```
display: inline-block
```
  by default).
- Use meaningful IDs and follow the assets/template.zul structure.

Layout & Component Patterns

XML & Pattern Structures

Base Template: assets/template.zul
MVC Structure: assets/mvc-sample.zul
MVVM Structure: assets/mvvm-pattern-structure.zul

Sizing & Layouts

Flexible Sizing (hflex/vflex): assets/flexible-sizing.zul
Borderlayout Example: assets/borderlayout-example.zul

Common MVVM Patterns

Form with Validation
Data Grid with Selection
Master-Detail Pattern
Dialog/Popup

Step 3: Validate Generated ZUL

Run validation using the script from this skill's base directory (provided as "Base directory for this skill:" in the skill context header):

bash

python3 <skill-base-dir>/scripts/validate-zul.py <path-to-zul-file>

Example: if the skill base directory is

/Users/hawk/.claude/skills/zul-writer

, run:

bash

python3 /Users/hawk/.claude/skills/zul-writer/scripts/validate-zul.py path/to/file.zul

Layer 1: XML well-formedness (no dependencies)
Layer 2: XSD schema validation (requires
```
lxml
```
)
Layer 3: Attribute placement check (requires
```
lxml
```
) - catches misplaced attributes (e.g.
```
iconSclass
```
on
```
textbox
```
)
Layer 4: ZK 10 compatibility checks (only if target ZK version is 10)

Prerequisites

Layer 2 and 3 require

lxml

. The script handles this automatically — it will install

lxml

via

uv pip install

(preferred) or

pip install

if missing. No manual setup needed before running the script.

Post-Validation Checklist

Pattern Consistency

MVC: Uses
```
apply
```
attribute, no MVVM binding expressions
MVVM: Uses
```
viewModel
```
attribute, proper binding syntax
No mixing of patterns on same component

Best Practices

IDs are unique within each ID space owner (
```
<window>
```
,
```
<idspace>
```
)
Prefer
```
sclass
```
over inline styles
Prefer
```
hflex
```
/
```
vflex
```
over fixed dimensions
Include meaningful labels and tooltips for accessibility

Step 4: Generate Controller Class

Generate the corresponding Java controller class (ViewModel or Composer) for the ZUL page.

Controller Generation Guidelines

Pattern Consistency:
- Use ViewModel for MVVM patterns.
- Use Composer for MVC patterns.
Implementation Details: Follow the technical requirements in references/controller-guidelines.md.

MVC Pattern - Composer Class

assets/MyComposer.java

MVVM Pattern - ViewModel Class

assets/MyViewModel.java

Complete Examples & Patterns

For complex UI patterns like Kanban Boards or Dashboards, and for complete template examples, refer to references/use-case-guidelines.md.