# Avalonia Pro Max/preview Server > Use when the user wants to see and choose between visual design alternatives for an Avalonia app before implementation — generates 3 design variants as real .axaml files, renders each to PNGs at multiple viewport sizes (compact/wide × light/dark) using Avalonia.Headless, and serves an HTML comparison gallery via a local web server. The user reviews in their browser and tells the agent which varia… - **Type:** Skill - **Install:** `agentstack add skill-linuxdevel-avalonia-skills-preview-server` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [linuxdevel](https://agentstack.voostack.com/s/linuxdevel) - **Installs:** 0 - **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [linuxdevel](https://github.com/linuxdevel) - **Source:** https://github.com/linuxdevel/Avalonia-skills/tree/main/skills/avalonia/avalonia-pro-max/preview-server ## Install ```sh agentstack add skill-linuxdevel-avalonia-skills-preview-server ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Preview Server — Visual Variant Picker for Avalonia ## What this does Lets the agent show the user 2–3 design alternatives **as actual rendered Avalonia screens** (not HTML mockups), in a browser-based side-by-side comparison gallery. The user picks one and the agent then builds the chosen design out into the real app. Why "real Avalonia" matters: HTML mockups misrepresent how Avalonia's Skia renderer, FluentTheme, ControlThemes, acrylic, shadows and font rendering actually look. A user who approves an HTML mockup is often disappointed by the real app. Rendering the actual XAML guarantees fidelity. ## When to use ### Must use - User says: "show me some options", "what would this look like", "give me a few designs", "preview", "mockup" - Building a new screen/window where there are valid stylistic alternatives - Choosing between theme libraries (Fluent vs Suki vs Semi vs Material) - Big visual refactor before committing to one direction ### Skip - User has already specified an exact design - Tiny tweaks to existing UI (just edit it) - Pure backend / non-visual changes ## High-level flow ``` 1. Agent reads requirements (uses brainstorming skill if unclear) 2. Agent generates 3 variant .axaml files in .preview/variants/{1,2,3}/ 3. Agent runs render script renders each variant via Avalonia.Headless → .preview/output/{variant}/{viewport}-{theme}.png (e.g. 1/wide-light.png, 1/wide-dark.png, 1/compact-light.png, 1/compact-dark.png) 4. Agent runs serve script starts python http.server, builds index.html gallery, prints URL: http://localhost:PORT 5. User reviews in browser, replies "I like variant 2" 6. Agent stops the server, copies .preview/variants/2/* into the real project the chosen variant into the actual app ``` The user never has to install anything beyond what's already needed for Avalonia development plus Python (already required by `ui-ux-pro-max`). ## Prerequisites - .NET 8 / 9 SDK (Avalonia 12 target) - Python 3.8+ (for the gallery server) - A scratch project at `.preview/AvaloniaPreviewHost/` — the agent creates this on first use The scratch project is a bare Avalonia console app referencing: - `Avalonia` 12.x - `Avalonia.Themes.Fluent` - `Avalonia.Headless` - `Avalonia.Skia` (transitively required by Headless for image output) Optional packages added per variant if it uses them: `FluentAvalonia`, `SukiUI`, `Semi.Avalonia`, `Material.Avalonia`, `Lucide.Avalonia`, `Material.Icons.Avalonia`, `Svg.Skia`. ## Variant generation rules Generate exactly **3 variants** that are **meaningfully different**, not three shades of the same idea. Use this matrix: | Slot | Variant identity | Typical theme combo | |---|---|---| | **A — Conservative** | Safe, professional, native-feeling. Lowest risk pick. | `FluentTheme` + `FluentAvalonia` | | **B — Modern Flat** | Opinionated, low-chrome, accent-driven. "Linear/Vercel" energy. | `SukiUI` or `Semi.Avalonia` + custom tokens | | **C — Distinctive** | A bigger swing — bold accent, heavier type, denser layout, or a Material-spec take. | `Material.Avalonia` **or** `Semi.Avalonia` + bold accent **or** `SukiUI` dark with neon accent | If the user has already constrained the choice ("we're using Material"), generate 3 variants **within** that theme that differ in palette, density, or layout instead. Each variant must include: - The same target screen/window (so comparison is apples-to-apples) - A `Resources.axaml` with the variant's tokens - A `Styles.axaml` with shared component styles - The screen `.axaml` (e.g. `MainWindow.axaml` or `DashboardView.axaml`) - A short `README.md` explaining the design intent in 3–5 bullets Reference the `design-system`, `themes`, and `components` sub-skills for the actual XAML content. ## Workflow for the agent ### Step 1 — Confirm scope Before generating variants, confirm with the user: - Which screen(s) do you want previewed? (single window / specific page / whole shell) - Target window size? (default: 1280×800) - Any hard constraints? (must be dark, must be Fluent, etc.) - Mobile/tablet preview needed? (default: no — just desktop compact 800×600 + wide 1280×800) Skip if the user has already given enough detail. ### Step 2 — Scaffold the preview host (once per project) ```bash python3 skills/avalonia/avalonia-pro-max/preview-server/scripts/scaffold_host.py ``` Creates `.preview/AvaloniaPreviewHost/` if missing. Idempotent. ### Step 3 — Write the 3 variants Author the XAML files under `.preview/variants/{1,2,3}/`. The structure for each: ``` .preview/variants/1/ ├── README.md # 3-5 bullet design intent ├── Resources.axaml # tokens (theme dictionaries) ├── Styles.axaml # component styles ├── PreviewScene.axaml # the screen to render └── packages.txt # optional: extra NuGet refs needed (one per line) ``` The render script will inject `Resources.axaml` + `Styles.axaml` into the host App and load `PreviewScene.axaml` as the window content. ### Step 4 — Render to PNG ```bash python3 skills/avalonia/avalonia-pro-max/preview-server/scripts/render_variants.py ``` What it does: 1. For each `variants/{N}/`: - Reads `packages.txt` and adds any new NuGet refs to the host project - Copies the variant's `.axaml` files into `.preview/AvaloniaPreviewHost/Variant/` - Runs `dotnet run --project .preview/AvaloniaPreviewHost -- --variant N --viewport wide --theme light --out .preview/output/1/wide-light.png` - Repeats for: `wide-dark`, `compact-light`, `compact-dark` 2. Outputs total render time + path to gallery script Default viewports: - `wide`: 1280 × 800 - `compact`: 800 × 600 Mobile viewports if `--mobile` flag passed: - `phone`: 390 × 844 (iPhone 14) - `tablet`: 1024 × 1366 (iPad Pro) ### Step 5 — Serve the gallery ```bash python3 skills/avalonia/avalonia-pro-max/preview-server/scripts/serve_gallery.py ``` What it does: 1. Generates `.preview/output/index.html` from the gallery template — side-by-side cards per variant, with theme toggle (light/dark) and viewport toggle (wide/compact). 2. Starts `python -m http.server` on a free port (default 8765, falls back if taken). 3. Prints: ``` Preview gallery serving at: http://localhost:8765 Press Ctrl+C to stop. ``` 4. Optionally opens the URL via `xdg-open` / `open` / `start` if `--open` flag passed. The agent leaves the server running and tells the user: > I've put 3 design options on http://localhost:8765 — have a look and tell me which one to build (or describe what you'd change about one of them). ### Step 6 — Apply the chosen variant Once the user picks (e.g. "go with variant 2, but with a green accent instead of blue"): 1. Stop the preview server (`Ctrl+C` or kill the process the agent spawned). 2. Copy `.preview/variants/2/Resources.axaml`, `Styles.axaml`, and any necessary `.axaml` into the real project's `Resources/` and `Views/` folders. 3. Apply any tweaks the user asked for (accent swap, etc.). 4. Wire up via `App.axaml` (`StyleInclude` + `ResourceInclude`) — see `design-system`. 5. Optionally clean up `.preview/` or leave for next iteration. ### Step 7 — Iterate (optional) If the user says "I like variant 2 but make it tighter", generate 3 new variants based on variant 2 and re-run from Step 4. Keep iterations cheap — the host project is already scaffolded. ## File layout summary ``` / ├── .preview/ # gitignored │ ├── AvaloniaPreviewHost/ # scratch .NET project (scaffolded once) │ │ ├── AvaloniaPreviewHost.csproj │ │ ├── Program.cs # CLI: --variant N --viewport X --theme T --out P │ │ ├── App.axaml │ │ └── Variant/ # populated per render run │ │ ├── Resources.axaml │ │ ├── Styles.axaml │ │ └── PreviewScene.axaml │ ├── variants/ │ │ ├── 1/{Resources,Styles,PreviewScene}.axaml + README.md │ │ ├── 2/... │ │ └── 3/... │ └── output/ │ ├── index.html # gallery │ ├── 1/wide-light.png, wide-dark.png, compact-light.png, compact-dark.png │ ├── 2/... │ └── 3/... └── .gitignore # ensure .preview/ is excluded ``` ## Add to .gitignore The agent should ensure `.gitignore` contains: ``` .preview/ ``` ## Limits and honest caveats - **Custom title bars / acrylic / native chrome** render but won't show OS-specific behavior (window shadows, traffic lights). The screen content is accurate; the chrome may differ slightly per platform. - **Animation can't be screenshotted.** Document motion intent in the variant `README.md` instead. For motion previews, escalate to the `Avalonia WASM live preview` approach (not in this sub-skill — see "Future work" below). - **Fonts must be embedded** (`avares://`). System-installed-only fonts may render with fallback under headless Skia. - **First render is slow** (~10–30s — restoring NuGet + JIT). Subsequent renders are ~1–3s per PNG. - **Headless rendering uses software Skia** by default. Pixel output matches a real Avalonia window 99%+ for static UI; tiny anti-aliasing differences exist but are not user-visible at gallery scale. - **`ExperimentalAcrylicBorder` works under headless** but the blur source is a flat color (no real desktop background to sample), so the effect is approximate. ## Future work (not in this sub-skill) - **Live WASM preview** — compile each variant to `wasm` via `dotnet publish` and serve interactively. Higher fidelity (motion, hover, click) but +30–60s per variant build and requires `dotnet workload install wasm-tools`. - **Diff overlay** — render two variants and produce a pixel diff highlighting changes. - **Auto-screenshot on file change** — watch `variants/` and re-render on save for fast iteration. ## Common mistakes - **Generating three near-identical variants.** Defeats the purpose. Use the A/B/C identity matrix above. - **Different content per variant.** The variants must show the *same* screen so the user is judging style, not content. - **Forgetting `packages.txt`.** If variant uses `SukiUI`, the host won't compile without the reference. - **Not gitignoring `.preview/`.** Pollutes the repo with binary screenshots. - **Telling the user "click the button to pick"** when the gallery is purely visual. The user replies in chat — re-read this skill: selection is chat-based, not click-based. - **Leaving the server running after selection.** Stop it before continuing implementation. - **Rendering at only one viewport/theme.** Always render all four (wide/compact × light/dark) by default — that's the point of the comparison. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [linuxdevel](https://github.com/linuxdevel) - **Source:** [linuxdevel/Avalonia-skills](https://github.com/linuxdevel/Avalonia-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-linuxdevel-avalonia-skills-preview-server - Seller: https://agentstack.voostack.com/s/linuxdevel - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.