Mastering `cm-ui-preview`: The Complete Guide

The greatest tragedy in modern AI-driven development—often called “Vibe Coding”—is the moment you realize your application functions perfectly but looks like a generic bootstrap template from 2014. You’ve spent hours orchestrating complex backend logic, but the user interface feels hollow, the spacing is inconsistent, and the user experience (UX) is an afterthought.

This is the “Generic AI UI” trap. When you ask a standard LLM to “build a dashboard,” it defaults to the safest, most boring layout possible. To break free, you need more than a code generator; you need a design architect. Enter cm-ui-preview, the specialized skill in the Cody Master (CM) toolkit designed to bridge the gap between abstract requirements and high-fidelity, production-grade visual interfaces.

In this guide, we will dive deep into how cm-ui-preview functions, how it leverages the pencil MCP and cm-ux-master intelligence, and how you can use it to ensure your Vibe Coding projects aren’t just functional, but visually stunning.

Core Concepts: Why Design Before Code?

In the traditional development cycle, design happens in Figma and code happens in VS Code. In Vibe Coding, these two worlds often collide prematurely. Developers prompt for a feature and the AI spits out HTML/CSS immediately. The problem? Code is “heavy.” Changing a layout in code requires refactoring divs, adjusting flexbox properties, and fighting CSS specificity.

cm-ui-preview introduces a blueprinting phase. It uses the .pen file format—an encrypted, canvas-based design schema—to iterate on visuals before a single line of React or Tailwind is written.

The Power Trio

To master cm-ui-preview, you must understand the three pillars it stands upon:

pencil MCP (The Hands): This is the execution layer. It provides the tools to read, write, and manipulate .pen files. It handles operations like Insert, Update, Move, and Delete on a virtual canvas.
cm-ux-master (The Brain): This is the intelligence layer. It contains 48 UX Laws, 37 Design Tests, and Nielsen’s Heuristics. When cm-ui-preview generates a layout, it’s not guessing; it’s applying the “Law of Proximity” and the “Fitt’s Law” to ensure usability.
cm-ui-preview (The Orchestrator): This skill coordinates the two. It analyzes your project’s DESIGN.md, pulls in style guides, and directs pencil to build the visual preview.

How It Works: The Stitch Build Loop

The “Stitch Build Loop” is the iterative process cm-ui-preview uses to refine a design. Unlike a one-shot code generation, the Build Loop expects perfection through refinement.

Phase 1: Contextual Discovery

Before placing a single pixel, the skill invokes get_editor_state() and get_variables(). It needs to know if you already have a design system, what your primary colors are, and what the “vibe” of the project is. If you’re building a “Brutalist” dashboard, the spacing rules are vastly different than a “Minimalist” SaaS landing page.

Phase 2: Prompt Enhancement

When you give a directive like “Add a billing section,” cm-ui-preview doesn’t just pass that to the generator. It enhances the prompt using the cm-ux-master logic. It adds constraints for accessibility (WCAG compliance), ensures enough white space for “The Law of Common Region,” and selects appropriate UI patterns.

Phase 3: Canvas Manipulation

The skill then uses batch_design to execute operations. A typical operation set might look like this:

sidebar = I("root", { type: "frame", layout: "vertical", width: 280 })
U(sidebar, { background: "var(--bg-secondary)" })
G("hero_image", "ai", "A futuristic 3D abstract shape in purple and neon blue")

Phase 4: Visual Validation

Once the canvas is updated, the skill doesn’t just stop. It uses get_screenshot() to capture the result. This image is then analyzed by the AI (and you) to verify that the “vibe” is correct. If the buttons are too small or the contrast is off, the loop restarts.

Practical Example: Building a “Quantum Finance” Dashboard

Let’s walk through a real-world scenario. You are building a high-end financial analytics tool. You want a dashboard that feels sophisticated, dark-themed, and data-dense but readable.

Step 1: Initialize the Document

First, we open or create a .pen file.

// Internal logic of cm-ui-preview
open_document("dashboard.pen")

Step 2: Establish the Style Guide

We pull in a style guide that matches our persona.

get_style_guide(tags=["dark-mode", "fintech", "glassmorphism"], name="Quantum_Theme")

Step 3: Generating the Layout

We issue the directive: “Create a main dashboard view with a sidebar, a top navigation bar, and a grid of four financial metric cards.”

cm-ui-preview will translate this into a sequence of pencil operations. It will use the Bento Grid pattern, which is currently a high-signal design trend. It will ensure the metric cards have a consistent border-radius (e.g., 16px) and subtle glassmorphism effects (backdrop-blur).

Step 4: The Validation Gate

After batch_design finishes, the skill calls snapshot_layout. This gives us the exact coordinates of every element.

Metric Card 1: x: 300, y: 100, w: 400, h: 200
Metric Card 2: x: 720, y: 100, w: 400, h: 200

The AI checks: Is the gutter between cards exactly 20px? Does it follow the 8pt grid system? If yes, it proceeds to show you the screenshot.

The Secret Sauce: `cm-ux-master` Integration

The reason cm-ui-preview is superior to standard AI coding is its deep integration with cm-ux-master. Every design decision is backed by a “Law.”

The Doherty Threshold: The UI is designed to ensure that if data takes time to load, there are skeletal placeholders immediately. cm-ui-preview will actually design these “Skeleton Screens” into the .pen file.
Hick’s Law: If your navigation has too many items, the skill will suggest a “Mega Menu” or a categorized sidebar to reduce cognitive load.
Harvester v4: This is a component within cm-ux-master that can “harvest” visual styles from existing high-quality websites. If you point it at a site you love, cm-ui-preview can adapt those tokens (colors, shadows, typography) into your new design.

Best Practices & Tips

To get the most out of cm-ui-preview, follow these professional standards:

1. Be Specific About the “Vibe”

Don’t just say “make it look good.” Use design terminology.

Poor: “Make a login page.”
Better: “Generate a centered login card using a Neo-Brutalist style with heavy black borders (#000000), a 4px offset shadow, and a high-contrast yellow button.”

2. Leverage Variables

Always use get_variables and set_variables. Hard-coding hex codes is the fastest way to create a maintenance nightmare. By defining --primary-color in the .pen file, cm-ui-preview can ensure that every generated component adheres to your brand.

3. Use the “Directional Search” for Space

When adding a new feature to an existing screen, use find_empty_space_on_canvas. Example: “Find 500x300px of empty space on the right side of the main frame to insert the new ‘Recent Activities’ widget.” This prevents the AI from overlapping nodes, which is a common failure in automated design.

4. Iterate in Batches

Don’t try to build a 10-page app in one go. Build the “Shell” (Sidebar/Nav) first, validate it, then move to the “Content Area.” This keeps the pencil operations under the 25-op limit for maximum reliability.

Troubleshooting Common Issues

”The Preview is Empty”

This usually happens if you haven’t set a root parent node. Every design needs a frame. If you’re building a web app, ensure you start with a 1440x900px frame.

”The Styles Don’t Match My CSS”

Remember: .pen files are the blueprint. Once the design is finalized, you must use the cm-implement skill (or a sub-agent) to “read” the .pen file and generate the corresponding React/Tailwind code. The .pen file itself does not output CSS directly; it outputs a structure that the AI then interprets into CSS.

Conclusion: The Future of High-Craft Vibe Coding

cm-ui-preview is not just a “nice-to-have” utility; it is the fundamental infrastructure for High-Craft Vibe Coding. It moves the AI from a junior developer who just writes code that “works,” to a senior design engineer who understands that software is a visual and emotional experience.

By separating the design phase into the .pen canvas, you gain the ability to iterate rapidly without the overhead of code refactoring. You can explore dozens of layouts, test different color palettes with replace_all_matching_properties, and ensure your UX is flawless—all before you commit to the implementation.

Mastering this skill means you are no longer limited by your own CSS skills or the LLM’s generic defaults. You are now a director of aesthetics, a vibe architect who can manifest professional-grade interfaces as fast as you can think of them.

Now, go open a .pen file and start building something beautiful.

Mastering cm-ui-preview: The Complete Guide