Zul Writer

ZUL Writer

Workflow Overview

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

1. Clarify Requirements - Gather page purpose, pattern, and layout needs
2. Generate ZUL - Create the ZUL file based on requirements
3. Validate ZUL - Verify correctness of the generated ZUL
4. Generate Controller Class - Create the corresponding Java class (ViewModel or Composer)
5. Preview & Self-Review - Render the page to an image and check it against the requirements

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

Run only the steps the request needs

The five steps are entry points, not a chain. A page built from nothing needs all of them; most other requests need one or two. Someone who hands you a finished .zul and asks what it looks like wants Step 5 and nothing else — interviewing them about MVC vs MVVM, or "improving" their markup on the way past, answers a question they did not ask and costs them a page they were happy with.

A model-driven page runs Step 5 twice, and the second time is not a fix round. The numbered steps are the order for a page whose data is still in the markup; once Step 5 has settled the layout, the extraction pass in Step 2 moves that data into the controller and one more --run-controllers render checks it. So the shape is 1 → 5, then back to 2 → 4 → 5 once. That last loop is easy to forget precisely because it runs backwards through the numbers.

"Why does this look wrong?" is a diagnosis request, not a validation one. The two rows sit together because they are so easy to confuse: why won't this page parse and why is this icon a blank box read alike, and Step 3 answers only the first. <label sclass="z-icon-bell"/> is valid ZUL — the validator passes it and reports the page clean, which is precisely how a real defect gets closed as "no problem found". A page that renders wrong while validating clean is the case Step 3 cannot see. The markup is already written; the question is what the browser did to it, and only a render can answer that. Go to Step 5 and probe the element, so the measurement names the cause before you touch the markup — opening with a guess costs a round and can "fix" the wrong line convincingly. Naming the cause is the whole answer to a "why"; the edit is a separate question, and it is the user's to ask.

The steps you skip still feed the ones you run — Step 4 needs to know whether the page is MVC or MVVM, Step 5 needs something to judge the render against. Read those out of the file and the user's message rather than restarting Step 1: an existing .zul already states its pattern, its layout and its ZK version far more reliably than an interview would. Ask only what you genuinely cannot infer.

Called in for one step, report rather than rewrite. Validating or rendering a page you did not write surfaces things nobody asked you to change. Say what you found, then make only the edit that was requested — or wait to be told to fix the rest. The exception is the defect that blocks the step itself: a page that will not parse cannot be rendered, so name it and offer the fix.

Visual Analysis (for Images/Mockups)

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

1. Visual Breakdown: Identify all UI elements (layout, inputs, buttons, tables, navigation).
2. 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>).
3. Tab Content Scope: If tabs are present, determine content boundaries. Items switching with tabs must go INSIDE <tabpanel>. See assets/content-tabbox.zul.
4. 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.

Ask only what is still open. The request, the project and any existing file answer several of these already — a version in pom.xml, a pattern visible in the markup you were pointed at, a layout described in the prompt — and re-asking those reads as though you did not look.

Sometimes there is nobody to ask — a scripted run, a batch job, a user who has gone quiet. That is not a reason to stop, and it is not a licence to invent an answer either: see When there is no one to ask after the 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

The line between them is exact, so there is never a page you cannot classify: MVC applies a Composer (apply="com.foo.MyComposer"), MVVM sets a ViewModel and uses binding syntax (viewModel="@id('vm') @init('com.foo.MyVM')" plus @load/@bind/@command). Either one is a controller, and it governs the component it is set on and every descendant of it.

Write one pattern per page. ZK permits mixing them and some projects do, but a mixed page has no single answer to "where does this value come from", which is the question both the extraction pass and the Step 5 self-review depend on. If the user asks for both, ask which one the page's data should follow.

If this question goes unanswered, see When there is no one to ask below — it is the one question where the project's existing pages get a say before the default does.

4. Static Data or Model-Driven

Ask this as its own question. It is independent of MVC/MVVM — that choice decides where behaviour lives, this one decides where data lives — and it changes the order the work happens in:

• Static data: the text and rows are written in the ZUL — <label value="Acme Corp"/>, and rows spelled out as <row> in a grid, <listitem> in a listbox, <treeitem> in a tree. Right for a layout, a mockup, a demo, anything whose content is fixed.
• Model-driven: the controller supplies them — a Composer calling setModel() on a component it wired, or a ViewModel the page reads through @load/@bind and a bound model. Right for anything backed by real data.

A component gets its rows from one of these, never both. Setting a model discards the rows written in the markup, silently, so literal rows left beside a model are markup that displays nothing at all.

Either answer still gets a controller in Step 4. Model-driven pages are additionally built in two passes — see Model-driven pages in Step 2.

5. Layout Requirements

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

6. 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.

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

When there is no one to ask

Every question above has an answer to fall back on, so an unanswered question costs a stated choice rather than the whole run:

Name every default you used, in the final report. A default is worth having because it is predictable and can be checked afterwards; a default nobody is told about is neither.

What the project already does (question 3 only)

A project where every existing page is MVVM is evidence, not a guess — adding one MVC page to it makes the codebase worse in a way the default cannot see. So for question 3, and only question 3, look before falling back:

uv run <skill-base-dir>/scripts/detect-pattern.py <project-root>

It reads the ZUL side only, because that is the side where both patterns declare themselves in an attribute. The Java side cannot be counted honestly: a ViewModel is a plain class, @Init is optional so counting it misses ViewModels that do without one, and counting Composer subclasses sweeps in every base class and helper that was never applied to a page.

PATTERN: mixed (MVC 6, MVVM 2)
USE: mvc -- the project uses both, so it has no single answer to give

Follow the project only when it is unanimous — PATTERN: mvc or PATTERN: mvvm. Anything else, including a lopsided 6-to-2, leaves the MVC default standing, because a project that already mixes patterns is not telling you which one it wants. Either way, say in the report what the scan found and which answer you used.

The other six questions do not work this way. A pattern is one architectural decision that holds across a codebase; a page's purpose and layout are different on every page, and the ZK version comes from the build file rather than from a survey.

Step 2: Generate a ZUL File

Generation Guidelines

When generating the ZUL file, follow these technical guidelines:

1. 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.

2. Style through classes, not through style attributes:

   • Put the page's CSS in one <style> element near the top of the file — not the <?style ?> processing instruction — and attach it with sclass on ZK components (class on native n: elements). Name each class for what the thing is (sclass="stat-card"), and give the page's classes a short prefix of their own so they cannot collide with ZK's z- classes or with another page's CSS.
   • Why this is not just taste. A style attribute is rendered onto the widget's own element, where it outranks every rule any stylesheet can write: the page stops being themeable, CSS written later silently loses to it, and no :hover, :focus or @media rule can ever reach it. Declarations pasted onto a dozen components also drift into a dozen near-identical values, where one class is edited once and every instance follows.
   • When a class looks like it "doesn't work", the theme is out-specifying it — .z-button is more specific than .my-btn, so the theme wins. Qualify the selector (.my-page button.my-btn { … }) rather than reaching for style; that reach is exactly how a page ends up inline-styled all the way down.
   • Size and spacing belong to the component, not to the CSS. hflex/vflex, width, height, spacing and valign are the component's own API and cooperate with ZK's layout engine; recreating them in CSS is how flex layouts break. Let the component own the box and the class own the appearance.
   • One honest exception: a value that only exists at runtime. A colour or width that comes from data (style="@load('background-color:'.concat(tag.color))") cannot be a static class. Keep that one declaration inline and leave the rest in the class.
   • If fallback native HTML elements (e.g. <n:div>) are used, include the CSS they need in that same <style> block.

3. Ask the schema before you write — it is bundled, exact, and free:

   Before writing a component you have not used before, or putting an attribute on a component you have not put it on before, ask:

   uv run <skill-base-dir>/scripts/validate-zul.py --describe <component> [--attr <name>] --zk-version <detected-version>
   

   # Does <charts> take sclass?  -> no: className or zclass
   uv run ~/.claude/skills/zul-writer/scripts/validate-zul.py --describe charts --attr sclass
   # Does <togglebutton> exist in ZK 10?  -> no such component
   uv run ~/.claude/skills/zul-writer/scripts/validate-zul.py --describe togglebutton
   

   Do this instead of guessing between two spellings you both half-remember. The usual failure here is not ignorance of how to build a grid — it is knowing three plausible spellings and picking a wrong one. Validation catches that afterwards, at the cost of a whole round; the same schema asked first answers immediately and locally. An attribute absent from the printed list is not accepted, however plausible it looks.

   One limit to respect: the bundled schema is a 10.x document. For a ZK 9 target its absences are suggestive, not conclusive, and it says so when that applies.

4. ZK Documentation:

   • Query the zk-doc MCP server (tool: search_zk_docs) for detailed component info if available.
   • Use ZK Javadoc for properties and event details.

5. Best Practices:

   • Prefer hflex/vflex over fixed pixel widths for responsive layouts. hflex="min" sizes a component to fit its content — useful for a <button> sitting beside an hflex="1" field (see assets/flexible-sizing.zul).
   • Use meaningful IDs and follow the assets/template.zul structure.
   • Never put -- inside an XML comment. XML forbids it anywhere between <!-- and -->, so the <!-- ---------- Left column ---------- --> separator that is perfectly good Java style is a hard parse error in a ZUL. Use =: <!-- ===== Left column ===== -->.

Model-driven pages: write the data in, then take it out

A page whose values come from a controller cannot show you itself until that controller runs. Until then @load(vm.customer) renders as dimmed expression text and a bound model renders as a couple of placeholder rows — so column widths, wrapping, card heights and whether a row of stats fits are all being judged against text that is not the text the page will hold. That is how a page passes Step 5 and still comes out wrong the first time it is run for real.

Which of the two paths you are on is a lookup, not a question. Do not ask the user; the answer is in front of you. A page you are writing from nothing needs a controller you have not written yet — in ZK a Composer or ViewModel belongs to a page, not to a shared service layer, so a new page means a new controller and the two-pass path below. Only an existing .zul can already name a class, and then you open it: if it exists and compiles, there is nothing to extract — render with --run-controllers from the start and judge the real data.

What counts as data. A value that changes when the data changes is data. A word that stays put no matter what the data says is chrome, and chrome belongs in the ZUL permanently — column headers, button captions, section titles, units, empty-state messages, validation hints. Cell values, list items, counts, amounts and status labels are data. The test is not "is it text": it is would this word still be right tomorrow, against tomorrow's rows.

Pass 1 — literal data, real shape

Write the first version with literal values, shaped like the data that will replace them: a name of realistic length, a price with its real digits, enough rows to fill the region. Rows go in as markup — <row> in a grid, <listitem> in a listbox, <treeitem> in a tree. Literals render as themselves, so the Step 5 screenshot is the page the user will actually get, and this pass is cleaner than a bound one: with no @load anywhere there is not a placeholder on the page.

The controller you write in Step 4 for this pass holds behaviour, not data — the event handler, the @Command, the wiring. Putting the data in it now cancels the whole point of the pass: Step 5 would render real rows through --run-controllers and you would be back to judging the layout against text you never checked.

Iterate here until the layout and the styling are right.

A chart has no Pass 1. <charts> has no literal form — a series cannot be spelled out in the markup the way a <row> can — so the two-pass shape does not exist for it. Write the chart's data into the controller from the start and render that region with --run-controllers from its first render, while the rest of the page still goes through the literal pass. The cost is that this page's first render now depends on the controller compiling, so read the CONTROLLERS: line before concluding anything about a chart that is missing: a stale .class looks exactly like a chart that was never drawn.

Pass 2 — extraction, after Step 5 has settled the layout

This is the one action in the workflow that runs after Step 5 rather than before it, so it is easy to skip. Its trigger is "the layout is settled", which is a Step 5 outcome. Four actions, in order:

1. Move each literal into the controller as a field, getter or list.

2. Point the ZUL at it. MVVM replaces the value with the binding that reads it (@load(vm.customer.name), model="@load(vm.items)"). MVC has no ZUL-side expression at all: the Composer wires the component by its id and calls setModel(...), so the ZUL keeps the id and gains nothing else.

   A <template name="model"> is the exception, and the two patterns read it differently. A template repeats markup per item, so it needs an expression whichever pattern the page is:

   Page	Inside the template	The template variable
   MVVM	@load(node.data.name)	the binder honours var="node"
   MVC	${each.data.name} — plain EL	always each; a custom var is silently ignored

   Get that the wrong way round and it costs a round, because an unresolvable variable renders as empty text rather than an error: ${node.data.name} on an MVC tree produced a tree with correct structure, indentation, open state and selection, and every label blank. Only a probe with ${each.name} gave a real message — Property 'name' not found on type DefaultTreeNode — which is also what names the second half of the rule: for a grid or listbox template each is the item itself (${each.action}), but for a tree it is the TreeNode, so the data is one hop further in (${each.data.action}).

3. Delete the literal rows. They are not harmless leftovers. Setting a model — bound or through setModel(), full or empty — discards the rows written in the markup, silently and with no warning, so the page renders correctly while the markup keeps rows that display nothing. Nobody looking at the image can see this, which is why literal-rows-discarded in Step 5's LAYOUT block measures it for you.

4. Change nothing else — same components, same sclass, same hflex. Extraction moves values, not structure, so if the page shifts afterwards the extraction is what to look at.

Two schema complaints to expect here, both false positives of the bundled XSD rather than anything wrong with the page — Layer 2 is stricter than ZK is:

• A <tree> whose only child is the <template> fails: treeType demands a treecols or treechildren the moment the tree has any child at all. Add an empty <treechildren/> and it passes. The model still fills the tree, and an empty element is not a literal row.
• A <listbox> carrying literal <listitem>s without a <listhead> fails the same way. A <listhead> is usually wanted anyway.

A <grid> with <columns> plus a template is accepted as written. See the B1 group in test/known-failures.txt for the rest of this class.

Then re-render once with --run-controllers to confirm it did not. That render checks the extraction, not the layout, so it is not a fix round — and anything it does find is fixed on Pass 2's own budget, not on what is left of Pass 1's. See How many rounds in Step 5.

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). Pass the ZK version detected in Step 1 via --zk-version so Layer 4 checks match the target:

uv run <skill-base-dir>/scripts/validate-zul.py --zk-version <detected-version> <path-to-zul-file>

Example: if the skill base directory is ~/.claude/skills/zul-writer and the project targets ZK 10.3.0, run:

uv run ~/.claude/skills/zul-writer/scripts/validate-zul.py --zk-version 10.3.0 path/to/file.zul

• Layer 1: XML well-formedness (no dependencies). Multi-root fragments are auto-wrapped in <zk> before validating.
• Layer 2: XSD schema validation (requires lxml)
• Layer 3: Attribute placement check (requires lxml) - catches misplaced attributes (e.g. iconSclass on textbox)
• Layer 5: inline-style advisory — lists static style="..." attributes that belong in a <style> class attached with sclass. It reports and never fails the run, so treat each line as a defect to fix rather than noise to pass over; a data-driven style="@load(...)" is skipped on purpose.
• Layer 4: version compatibility checks for the target ZK version — removed/deprecated API for all targets, plus ZK-10-only API (e.g. dropped <fragment>, or new accept/responsive attributes) gated by --zk-version. Defaults to 10 if omitted.
• Layer 6: runtime semantics — markup that is legal by every static measure and still throws while the page is being built. Today that is a literal selectedIndex: <combobox selectedIndex="0"/> passes Layers 1-5 and dies with Out of bound: 0 while size=0. The index is applied before the component's own children are attached, before any controller runs and before the binder sets a model — so on combobox, listbox, radiogroup and tabbox it throws whatever the markup says. Writing the items out does not help, and neither does model="...": a model-driven <listbox model="@load(vm.items)" selectedIndex="0"> throws identically. Express the selection instead — value="..." on a readonly combobox, selected="true" on the <listitem> / <radio> / <tab>, or a controller call after the model is in place. selectedIndex="-1" is not the universal escape hatch it reads as. Measured identically on ZK 9.6.6 and ZK 10.3.0.1: <tabbox selectedIndex="-1"> still dies with No tab at all, because the setter wants a <tabs> child that does not exist yet — no literal value is safe on a tabbox. <cardlayout selectedIndex="-1"> dies with Out of bound: -1 while size=2: its cards are attached first, so it bounds-checks the value and has no "nothing selected" state; a card index inside 0..cards-1 is fine. selectbox tolerates every literal value, with a model and without one, so the layer says nothing about it at all.
• Layer 7: controller cross-check — only runs when you pass --controller (see Step 4).

Prerequisites

Layer 2 and 3 require lxml. uv run handles this automatically via the script's PEP 723 inline metadata — it provisions lxml in an ephemeral environment, so no manual setup is needed. If uv is unavailable, run with a plain interpreter instead and the script self-installs lxml as a fallback:

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

(On Windows, use python instead of python3.)

Usage Tracking

Running this script also fires an anonymous, aggregate usage ping (skill name + version only, no identifier) on a background thread — it never delays or blocks validation. Opt out with DO_NOT_TRACK=1 or TRACK_URL="", or per-run with --dev — which is what runs made while developing or testing the skill itself should pass, so they are not counted as usage.

Asked only to validate

Report the layers that failed, quote the lines the script names, and say what each one means — then stop. A validation request is a request to be told what is wrong; edit the file when the user asks for the fix, or when fixing it is the task you were already on.

Post-Validation Checklist

Pattern Consistency

• MVC: Uses apply attribute, no MVVM binding expressions
• MVVM: Uses viewModel attribute, proper binding syntax
• One pattern for the whole page, not one per component
• No component carries both a model and literal rows — see Model-driven pages in Step 2

Best Practices

• IDs are unique within each ID space owner (<window>, <idspace>)
• Appearance lives in <style> classes attached with sclass; the only style attribute left is one whose value comes from data. Layer 5 lists any others it found
• 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.

Generate it for a static-data page too. The values may be fixed, but the page will still have to do something, and what a developer needs from you is the shape of that attachment: how a Composer wires a component and listens for its event, how a ViewModel declares a @Command and what the ZUL writes to invoke it. Leaving it out withholds the one part that is ZK-specific and hard to guess. So include at least one working handler on something the page really has — the Save button, the row selection, the search box — acting on the values already in the markup.

Behaviour now, data later. Whether the page is static or model-driven, what you write here is the page's behaviour. On a model-driven page the data is still in the markup at this point and belongs there until the layout is settled — so no setModel(), no getter backing a bound model, not yet. Both arrive in the extraction pass (see Model-driven pages in Step 2), and this step runs a second time to receive them. Writing the data in now is the single easiest way to lose the literal pass without noticing: Step 5 would render real rows and the layout would never be judged against anything you checked.

Except a chart. <charts> has no literal form, so its model belongs here from the first render while everything else on the page stays literal — see A chart has no Pass 1 in Step 2. Stripping a chart's data back out to obey the paragraph above leaves an empty chart that reports no error.

Controller Generation Guidelines

1. Pattern Consistency:

   • Use ViewModel for MVVM patterns.
   • Use Composer for MVC patterns.

2. Implementation Details: Follow the technical requirements in references/controller-guidelines.md.

3. Cross-check the wiring against the ZUL before you finish. Re-run the validator with --controller, which turns on Layer 7:

   uv run <skill-base-dir>/scripts/validate-zul.py <path-to-zul> --controller <path-to-controller>
   

   It reports two defects that nothing else in this workflow can see — not the other layers, not the Step 5 render:

   • a @Wire field whose type is a different component than the id it names. This compiles, passes every validation layer, renders correctly, and then throws ClassCastException the first time the field is used. An earlier run shipped @Wire Label on an <a> and only caught it by re-reading its own composer.
   • a @Wire field naming an id no component in the ZUL declares. The field stays null and the first use throws NullPointerException.

   Layer 7 stays silent wherever it cannot be certain — component families where one class inherits from another (Textbox/Combobox, Checkbox/Radio, Box/Hbox, Row/Group, Listitem/Listgroup, Button/Combobutton), base-class field types like Component, collections, non-#id selectors, and pages containing an <include>. A silent Layer 7 is not a guarantee of correct wiring; it means nothing it can prove is wrong.

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.

Step 5: Preview & Self-Review

Render the finished page to an image, look at it, and check it against the requirements gathered in Step 1. Steps 2–4 only ever see markup; this is the only step that sees what the page actually looks like.

Asked only for a preview, there are no Step 1 answers to judge against — so judge the render against the page's own markup and whatever the user said they expected, describe what you see, and report the image path. The What to fix list below still tells you what counts as a defect worth mentioning; it does not license editing a file the user asked you to look at rather than change.

Run the preview script from this skill's base directory (same convention as Step 3):

uv run <skill-base-dir>/scripts/preview-zul.py <path-to-zul-file>

Example: if the skill base directory is ~/.claude/skills/zul-writer/ and the page lives in a Maven webapp, run:

uv run ~/.claude/skills/zul-writer/scripts/preview-zul.py src/main/webapp/index.zul

Where the image goes: the current working directory. With no --out, the PNG is written to the directory you are working in, named after the page — index.zul gives ./index-preview.png — and the SCREENSHOT: line reports the exact path. Leave it there. This image is not a scratch file: it is the one visual artifact of the whole workflow, the thing the user opens to see whether the page matches what they asked for, so it belongs beside their work where they can click it, keep it, or delete it. Sending it to a temp or scratchpad directory instead hides it behind a path they would have to be told about and cannot find again later. Re-renders overwrite the same file, so the path stays valid across fix rounds and is still the right one to report at the end. Pass --out only when the user names a destination, or when a corpus/CI job needs the images collected somewhere.

If this session wrote the page's controller, append --run-controllers (read the next paragraph before you do — it executes project code):

uv run ~/.claude/skills/zul-writer/scripts/preview-zul.py --run-controllers src/main/webapp/index.zul

When to pass --run-controllers. Pass it when this session wrote the page's controller (Step 4's composer or ViewModel): the sample data in it is yours, running it is what turns a skeleton screenshot into a judgeable one, and the flag makes bound values, model-bound rows and composer-filled labels real. It is also the render that checks an extraction: after moving a page's literals into its controller (Step 2), this is what shows the page still looks like the one you approved. Do not pass it for a page whose controller you did not write — the flag executes arbitrary project code from the project's classpath (constructors, service calls, whatever doAfterCompose does), so it is opt-in per render and never a default. If the controller has not been compiled yet, build first (mvn compile / gradle classes); the script warns when no compiled classes are on the classpath. Add --controller-timeout <seconds> only if a legitimately slow page keeps degrading (the default budget is 10 s for the whole render).

Viewport: --width, --height, --full-page. The default viewport is 1280x900; the SIZE: line in the output always says which viewport the render actually used.

• Match the mockup's width. When the user supplied a screenshot or mockup, pass --width at approximately that image's pixel width, so the two images compare like for like — a 1600 px mockup means --width 1600. Rendering the 1280 default against a wider mockup adds differences that are yours, not the page's, and you will spend fix rounds on them. Match the layout width, not the file's pixel count: halve a high-DPI export, and do not follow a thumbnail far below 1024 unless you mean to test a narrow viewport — a very narrow render manufactures clipped-text findings that the same markup does not produce at desktop width.
• --full-page when the page flows past the fold — long forms, stacked reports, anything meant to scroll. It stitches the whole scrollable page into the PNG.
• --height when the page is a vertical flex shell. A page whose root region is vflex is exactly viewport-tall by construction, so --full-page cannot show more of it: raise --height instead. hflex is a width and does not do this — an hflex page flows past the fold like any other, and there --full-page is the right flag. A --full-page capture that comes back exactly as tall as the SIZE: viewport is telling you the page is flex-sized, not truncated.

uv run ~/.claude/skills/zul-writer/scripts/preview-zul.py --width 1600 --full-page --run-controllers src/main/webapp/index.zul

The script resolves the project's ZK jars (Maven, Gradle, or stock ZK when the file belongs to no project), renders the page through ZK's own engine, and writes a PNG. Requires Java 17+ and Google Chrome or Microsoft Edge. On first use it downloads the render helper (zk-preview-launcher.jar, 500 KB), verifies its SHA-256, and caches it under `/.cache/zul-writer/`; later runs need no network.

Then read the PNG with your image-reading tool and compare it against the Step 1 answers. If the user started from a screenshot or mockup, re-read that image too and compare the two side by side.

When there is no preview

The script exits 2 and prints one line beginning PREVIEW_SKIPPED: — no ZK jars resolvable, no Java 17+, no browser, or the helper could not be downloaded. This is not a defect in the ZUL. Report it in one line — "Skipped the rendered preview: <reason>" — and finish the task normally.

Never describe a screenshot you did not see, and never let a skipped preview stand in for a passed one.

The NEXT: line says what would enable a preview. If that looks fixable from here, spend one retry on it — appending --debug prints the resolved classpath, every helper command line and the renderer's own output to stderr (stdout is unchanged), which is usually enough to see why. Then stop and report the skip either way.

Read the CONTROLLERS: line first

It is one line in the output, and the judging rules below invert on it:

Read the LAYOUT: block first

A browser measured these, so they are facts, not opinions — read them before you open the PNG. Each line is rule | locator | measurement:

LAYOUT: 3 findings
  - zero-size         | a[label="Settings"] | 0x0 with text but no box
  - clipped-text      | a[label="Documents"] | text needs 77px, box is 48px
  - viewport-overflow | grid.gp-wide | page scrollWidth 2005 > viewport 1280; widest offender 2000px

The locator is the ZUL id when the component has one (label#breadcrumbCurrent), otherwise the component plus a distinguishing attribute (a[label="Settings"]) or its style class (grid.gp-wide). It never names a generated id, so it is always something you can find in your own markup.

…(truncated)