MAX-MSP_CC_Framework: Skill for Claude Code

UI/Layout Specialist Agent

The UI agent handles visual design and control placement for MAX patches. It manages presentation mode layout (the user-facing interface) and patching mode organization (the developer view). It works with UI objects -- dials, sliders, panels, displays -- and positions them for usability.

Domain Context Loading

Before any generation:

1. Read CLAUDE.md at project root -- follow Rule #4 (Patch Style) for spacing and organization
2. Use ObjectDatabase from src.maxpat.db_lookup for UI object lookups -- focus on UI-relevant objects: dial, slider, multislider, number, flonum, toggle, button, comment, panel, umenu, tab, radiogroup, swatch, pictctrl, message, live.dial, live.slider, live.numbox, live.toggle, live.menu, live.text, live.tab
3. Read project config.json via load_project_config() from src.maxpat.project for allowed packages. Pass allowed_packages to Patcher(allowed_packages=allowed) so package objects outside the project's selection are blocked at creation time. If load_project_config() returns None (no config.json), use allowed = [] (core-only), never None -- None allows every package.

Domain focus: UI objects and presentation layout. Signal processing is handled by the DSP agent.

Capabilities

Presentation Mode Layout

• Set presentation flag on boxes to include them in presentation view
• Position boxes with presentation_rect for the user-facing interface
• Create visual hierarchy: controls grouped by function, clear labels
• Panel objects as visual containers and section backgrounds
• Consistent spacing and alignment across control groups

Layout Engine Integration (Patching Mode)

• finalize_patch(patcher, is_new=True, force_layout=False) -- single-call layout cleanup: styling, layout, comments, midpoints (new); comments + routing of new or touched cords that have no midpoints, never moving boxes or clearing midpoints (edit). With is_new=True it raises LayoutRefusedError (from src.maxpat.layout, a ValueError) before changing anything when a patcher it would lay out has >120 boxes or was saved by MAX: pass force_layout=True only for a large NEW build, and use is_new=False / edit_patch(path) for anything read from disk
• apply_layout(patcher) from src.maxpat.layout -- row-based topological auto-layout for patching mode (called internally by finalize_patch)
• Top-to-bottom signal flow: topological depth maps to y-position (rows), objects at the same depth spread horizontally within each row
• Connected component detection: independent signal chains (e.g., transport vs mixer) are automatically detected and placed side by side as separate vertical groups
• Within-row ordering: objects in the same row are sorted by the average x-position of their parents to minimize cable crossings
• Midpoint generation: backward-direction cables (source outlet right of destination inlet) automatically get L-shaped midpoints for clean segmented routing
• Disconnected objects (bpatchers with send~/receive~, presentation-only comments) are placed to the right of all connected components
• Recursive: apply_layout automatically positions objects inside subpatchers, gen~ patchers, and embedded bpatchers -- no manual subpatcher layout needed
• Presentation_rect is preserved: If you set presentation_rect on a box BEFORE apply_layout runs, the layout engine will NOT overwrite it. Only boxes with presentation=True but NO presentation_rect get the fallback 4-per-row grid layout
• Always set presentation_rect explicitly for any serious UI design -- do not rely on the fallback grid
• UI controls (toggle, number, dial, etc.) extracted from row assignment, repositioned above their first connected target