# Max LVL Builder: brand and interface handoff

Web edition 3.0 · September 2026

Use this with the candidate's `PLAN.md`. The studio proposes the visual and interaction expression of that plan and supplies reusable working code. The candidate remains the implementation target when the owner authorizes that work. This deliverable has not changed the candidate, its PLAN, another client site, or the Build Standards library.

For the current complete implementation assignment, use [BUILDER-OVERNIGHT-HANDOFF.md](BUILDER-OVERNIGHT-HANDOFF.md) with the PLAN. [BUILDER-PLAN-REVIEW.md](BUILDER-PLAN-REVIEW.md) supplies the evidence behind its corrections. Build all requested tools through completion in the same run, including their supporting models, writers and integrations. Existing structures may be substantially changed or replaced where they hold back the intended experience; preserve user work and real-data meaning while updating affected callers and persistence together.

## What the company does, and who each experience serves

Max LVL Media connects the real value of a business with an appropriate customer. Strategy, stories, video, websites, advertising, follow-up, and software contribute to that connection. The founder's filmmaking, acting, and storytelling shape the quality of observation, emotional honesty, performance, composition, and pacing. The company's audience is established for each offer; filmmaking is not the client niche implied by that creative background.

There are three separate contexts. Max LVL's own marketing speaks to one business owner. Work for a client speaks to one of that client's customers, in the client's voice. The Builder speaks to the person doing the work. A website rendered inside the Builder retains its own identity and recipient. UI instructions, operator notes, prototype explanations, and internal marketing frameworks do not become the customer's page copy.

Use [BRAND-STRATEGY.md](BRAND-STRATEGY.md) for the complete audience, transformation, copywriting, VVV, and VALUE foundation. The working interface should make creative judgment easier: see the work, choose something, understand it, make a change, compare, keep or undo it, and move on with confidence.

## The intended visual result

Open the studio's `/builder/` and `/components/` pages before implementation. The software should feel like a thoughtful creative application. Its working canvas is spacious; its controls are legible; its panels are named and physically distinguishable. Warmth comes from useful language, imagery, deliberate choices, and the sense that the tool understands the work.

The dark theme starts with Midnight Blue Steel #0C1520, panel #142230, raised surface #203244, Paper #F7F7F2, and secondary text #BBC9D5. The light theme starts with Paper #F7F7F2, white panels, #E9EEF2 raised surfaces, #142230 primary text, and #485D70 secondary text. The live application profile is in `../ui.tokens.json`, implemented by `../css/foundation.css`. Both themes have separate edge, focus, selection, and status values. These are Builder shell and library options; apply the [experience guide's theme scope](EXPERIENCE-SYSTEM.md#4-type-themes-and-visual-hierarchy) to artifacts created in the app.

The exact identity reds are #D84D48 on dark and #AF282B on light. The logo black is #09131B. Use the supplied SVG geometry in the matching working export, at its intrinsic aspect ratio. The source files are preserved in `../assets/masters`; differences and roles are recorded in `../source/logo-assets.json`. The supplied Builder lockup named “On Light BG” actually contains the dark-background artwork. Its working filename reflects the artwork. Use a suitable dark holding area until an actual light Builder lockup is supplied.

Keep depth in Rare #254B8E and Epic #603A8C. Legendary amber #D98B28 is brighter and more saturated, with deep shadow #6B3B10 and golden highlight #FFC15A. In the collage direction, use amber in localized material and light rather than broad CTA or form backgrounds. These are creative art colors. They are not universal status codes, subscription tiers, or a reason to turn every interface into game UI. The functional selection and focus colors are adapted for readability, separate from art bodies.

Red is identity and, where explicitly labeled, destructive intent. Normal selection is blue. Quiet working buttons, contextual blue actions, and a deliberate brand-red marketing CTA can coexist. Red action buttons use white text on the tested action-red roles in the chosen profile. Identity red remains unchanged in the supplied logo artwork. Use the [experience guide](EXPERIENCE-SYSTEM.md#purpose-labels-and-quotation-treatment) for purpose tags and quotation corners.

## Reusable source and adaptation

| Owner | Purpose | Use in candidate |
|---|---|---|
| `public/css/foundation.css` + `ui.tokens.json` | Application profile, fonts, shared browser styles | Map tokens into the single candidate theme owner. Scope generic selectors during integration. |
| `public/css/builder.css` + `public/js/builder.js` | Shared Builder shell, Website/Patterns and People specimens | Load both workspace modules below before the shell; adapt panels, headers, selection and interactions to real state and services. |
| `public/css/builder-automation.css` + `public/js/builder-automation.js` | Automation canvas, sample flows and step inspector | Required Builder dependency; preserve graph meaning, editable drafts and host callbacks when integrating. |
| `public/css/builder-creative.css` + `public/js/builder-creative.js` | Creative library, comparison and placement controls | Required Builder dependency; implement asset saving, role/source binding and affected output updates behind the placement callback. |
| `public/css/components.css` + `public/js/components.js` | Panel anatomy and complete interaction specimens | Reuse component behavior and code recipes, then integrate with candidate lifecycle. |
| `brand.tokens.json` + `brand.css` | Extended marketing/brand profile | Use where the brand itself is the experience, or map compatible primitives. Do not load a second contradictory application role owner. |
| `public/examples/home-service.html` and `public/examples/retirement.html` | Standalone scene-led websites | Reuse composition and interactions with actual client strategy, evidence, and branding. |
| `source/logo-assets.json` | Asset mapping | Select by actual background and role, preserve geometry and sources. |

Load `public/css/foundation.css`, then the Builder shell and both workspace stylesheets. Load the classic scripts `public/js/builder-automation.js` and `public/js/builder-creative.js` before `public/js/builder.js`; `src/layouts/Studio.astro` demonstrates the order. `window.MLBuilder.mount(host)` creates the shared shell and mounts those required workspace modules. `window.MLComponents.mount(host)` mounts the separate component lab with its own stylesheet.

Before mounting an extracted Builder, supply `window.ML.toast(message)` and `window.ML.copy(text)`. The first announces visible status; the second handles copying with truthful success feedback and an accessible manual-copy fallback if clipboard access is unavailable. `public/js/studio.js` supplies these adapters in this entry. In the candidate, map them to the application's own notification and clipboard services instead of importing the studio presentation. Without these adapters, the specimen's notices and Copy brief action have no destination.

The workspace APIs are `MLAutomation.mount({library, stage, inspector, onSelect, notify})` and `MLCreative.mount({library, stage, inspector, onSelect, notify, onPlace})`. The three hosts are body regions inside the shell's named panels; the shell owns their headers, resizing and visibility. Workspace instances retain their state while hidden. Automation observes its available width and fits when first shown; manual zoom is preserved until Fit is chosen again. The modules require local assets and foundation CSS. No bundler, remote fonts, or network calls are required. Browser-local state demonstrates continuity; it is not the candidate's storage contract. Integration must deliver the actual lifecycle, persistence, writers and provider behavior, extending or replacing existing implementations where necessary.

Prototype data and functions must remain visibly separate from actual services. A local demonstration of approval, placement, contact preparation, or a draft does not establish a production endpoint. The studio's sample people and measurements are fictional. Avoid replacing working candidate behavior with a visual stub.

## The shell: establish the room before furnishing it

The inspected candidate is `C:/ClaudeCode/projects/.mlm-work/max-lvl-website-builder`. The source PLAN calls for a shared document canvas and identifies flat surfaces, tiny controls, missing gutters, unresizable regions, duplicated node presentations, and an oversized empty agent area as problems. Read current code before adapting the specimen; the PLAN describes intended changes and can lag an individual workspace's actual write paths.

Relevant integration points inspected for this direction:

- `integration/workspaces.mjs`: workspace registry and shared meaning.
- `panel/panel-host.js`: mount, focus, leaving a workspace, mode changes, capture/restore, and destroy.
- `panel/workspace-dom.js`: unified document-host direction.
- `app/main.mjs` and `app/ui/frame.js`: application and frame composition.
- `panel/creative-panels.js`, `panel/pattern-panels.js`, `panel/automation-panels.js`: existing domain surfaces to inspect and substantially redesign where needed, carrying forward useful behavior and user work.

Use a single application document with named panel regions; retain the native website view where the platform requires it. All panels share a compact header structure: name, meaningful mode, state, contextual actions. The following dimensions and type counts are specimen baselines, adjustable through the supplied branding and actual rendered results. The PLAN's header starts at 28px; touch layouts can enlarge targets or relocate controls. The specimen folds a local region to a labeled 28px rail and the persistent agent to a 44px rail. Hover alone never reveals the only route to essential controls.

The specimen separates adjacent panels with a 6px gutter and a distinct 1px edge. Implement resize handles with pointer capture, limits, keyboard adjustment, and a visible active state. Persist the layout under site and workspace identity. A narrow viewport must adapt the arrangement into focused views, a drawer, or panel navigation; it must not simply crush four desktop columns onto a phone.

The proposed eight-size product scale (10, 11, 13, 14, 16, 20, 26, 34) supplies a consistent starting point. Reserve the smallest sizes for secondary metadata. Main instructions and edited prose need comfortable reading sizes. Headers, numbers, and line lengths should reflect the task rather than a collection of unrelated font values. DM Sans provides the working voice; Newsreader belongs to an editorial artifact or an intentional creative moment, not every control.

The agent is persistent, useful, and proportionate. Its empty state shows what can be brought into a conversation and keeps the composer within reach. Selection can be attached with a named context chip that the person can inspect or remove. Switching workspace preserves the draft and the relevant context. Context is information, not permission to make a change or a restriction that blinds the agent to authorized relevant work.

Application-level actions belong in the shell. Put preview/build/deployment context and any consequential production actions in distinct, clearly labeled locations. A selection change should never look like a deploy choice. Setup is a global settings surface. Notes can live in the contextual agent drawer; Documents becomes the home for durable plans.

## Four connected specimen paths

### Website and Patterns

The website is a real creative stage, accompanied by instruments. Pages, reusable patterns, the selected section, viewport controls, source context, and content editing each have a legible place.

The studio demonstrates selecting content and changing a headline/CTA in the inspector, with immediate visible changes in the preview. It also demonstrates choosing a pattern or artwork and carrying a placed image back into the website. Deliver real persistence and undo, adding or changing declared writers and schemas with their consumers where needed. A direct edit should not invoke a language model when a deterministic update is already defined.

The future pattern catalog needs facets, search, background-generated thumbnails, device and variant chips, a large selected example, and content details. Names and meaningful actions appear before thumbnails are ready. Pattern health and editable fields belong near the selected object. Avoid both a giant empty preview and a catalog compressed into a tiny generic sidebar.

The pages tree must support its actual CRUD and link-impact behavior. Viewport controls include explicit Width × Height in CSS pixels, presets/custom sizes, orientation swap, separate Fit/100% presentation, a ruler and the planned second viewport. Fitting a large page into a smaller panel preserves the page dimensions and responsive breakpoint. Status identifies unsaved edits, local saved state, preview build state, and published state separately. A changed headline is not a publication.

### Automations

Use one node canvas with a clear start, labeled edges, readable steps, visible branch lanes, and a shared inspector. The PLAN's serpentine left-to-right layout can wrap rows while branches remain understandable and converge intentionally. A parallel path cannot be flattened into a misleading list.

The specimen demonstrates node selection, local step editing, adding a step, and undo. The candidate has draft reorder/add-email/add-wait/save/build behavior, but its presence does not complete the intended automation engine. Expand or replace that path with a graph contract that preserves IDs, actions, conditions, branch ordering and merge meaning through save, reopen, build and supported execution.

Zoom at the pointer, pan, fit, selection, marquee, keyboard navigation, add-on-edge, and in-node edits should use shared behavior across Automations, Funnels, and Interactivity when those meanings match. They are production implementation work beyond the specimen's supported controls. Include a non-drag path for every structural edit. Selected, draft, valid, warning, and failed are separate states.

Keep the library, canvas, step inspector, and run history distinct. A simulated local trace must say so. Live test/run actions need their actual target, effect, state, and retry semantics. The canvas should reveal cause and effect, not just decorate a list.

### Creative

Make the image large enough to judge. Use a visual library, a viewer, making controls, and a details inspector with roles and provenance. A comparison slider allows the person to inspect a candidate against the current choice. Keep aspect ratio, crop, and destination context visible before placement.

The studio demonstrates selection, comparison, approval/placement, and a connection back to the page. Integration must resolve asset identity, assign or create the role/source binding, update required derived outputs and affected previews, preserve the previous version, and distinguish draft approval from deployment. The inspected `assets.save` writer only saves image bytes and provenance; it does not implement placement. Deliver the complete create/import, compare, place, reopen and revert path, including missing favicon/social roles. Actual generation uses the configured client and job lifecycle. Loading should show a useful job state, not an indefinite empty image. Cancellation, failure, retry, variation, extend/crop, and duplicate prevention need their real service behavior.

A generated image is a proposed asset, never documentary proof of a real client, technician, customer, or result. Store prompt, source/candidate relationships, dimensions, and usage rights. Actual client portrait or testimonial content needs real provenance. Local SVG masters retain their exact geometry.

### Lists / People

Lists are first-class objects, with declared, rule-based, journey and manual membership. Build the supporting model as part of the tool. People can belong to multiple lists, and an empty list has its own identity. The workspace should make membership, journey stage, score meaning, and last relevant activity understandable without crowding the main table.

The specimen uses fictional people, search and filters, selected profiles, and local state to demonstrate the visual behavior. QMM already has people and memberships; its first-class list catalog and the intended experience still need implementation. Develop the interface and necessary model, writers and persistence in the same effort. Rule summaries explain why a person matches; a score has a definition and any decay/time basis. Anonymous calculator activity connects to the person's history when identity becomes available. Time-based negative rules and decay evaluate as time passes, not only when another action arrives.

## Specific direction for the remaining workspaces

| Workspace | Composition | Meaningful behavior |
|---|---|---|
| Branding | Parts rail + Guide / Tokens / Assets / Compare stage + inspector | Edit an atom; show effect and measured contrast; replace/generate an asset with history; present, export, and audit. |
| Interactivity | Pipeline canvas with component → guards → endpoint → records → messages → automations → tracking → destinations | Select a stage, edit declared settings, inspect a local trace, follow an error to its source. |
| Email | Full-height catalog + composition/preview stage + contextual tools | New reusable message, layout/content composition, subject/preheader, recipient preview, variants, persistence and selection from Automations. |
| Tracking | Linked analytic panels with shared range, comparison, filters, metric, and grouping | Drill from meaningful aggregate to journey evidence; define metrics; show fresh/partial/empty/error states. |
| Funnels | Cohort-aware graph and supporting evidence | Branch drop-off, time between steps, denominator and cohort meaning; six distinct planned tools keep their own jobs. |
| Advertising | Campaign relationship view, selected ad/creative, account status, settings | Clearly identify Meta/Google account context, local changes, provider response, and live versus draft state. |
| Calendar | Campaign bars in month/week/quarter/agenda, compact edit popover | Move or resize with undo and keyboard alternatives; show overlapping campaigns and timezone meaning. |
| Search | Declared address/metadata editor with SERP and structured previews | Inspect sitemap, robots, redirects, schema, GEO/AEO context; avoid treating a visual preview as search placement. |
| Reports | Six subject-specific views using the shared insights query | Range/compare/filters, chart/table switching, export and schedule with actual data and job state. |
| Documents | Searchable durable source list and reading/editing canvas | Bring relevant plans into context; preserve source and conflict information; keep notes contextual. |
| Setup | Full settings canvas reachable from shell | Configure and test integrations with honest connection states, explicit targets, and safe credential handling. |

A shared insights query can use `{range, compare, filters[], metric, groupBy}` and cached definitions. Shared data does not require identical page arrangements. A funnel answers where people leave; a report helps assess a subject; tracking explains a journey. Choose each composition around that question.

## Complete states and human language

Every production component needs the states that matter to its behavior. Separate loading, empty, invalid, failed, offline, stale, partially successful, unsaved, saved locally, built, and published. Never claim “saved” after a failed persistence operation or “sent” after a local preparation step. An unknown provider result needs a status check before a retry that could duplicate an effect.

Copy should connect state to useful action. “This image did not finish. Your prompt and previous version are still here.” is more useful than “Generation error.” A failed workspace should have a concise explanation and a relevant action such as Retry, Copy details, or Ask Claude. Avoid a generic empty sentence repeated in every workspace.

For edited forms, retain values, place errors by fields, and identify what fixes them. Dialogs have a descriptive title, a clear primary action, Escape where dismissal is appropriate, focus containment, and return focus. Drawers have consistent close behavior and preserve context. Toasts support transient confirmation; consequential or unresolved errors remain available in the relevant surface.

## Motion, responsiveness, and access

The MotionSites inspiration is compositional: authored scenes, large editorial type, floating decision surfaces, sequenced imagery, interactive comparisons, and purposeful response. The implementation here is original. Public gallery references are listed in [motion-reference.md](motion-reference.md); no paid prompts or source code were copied.

Keep control feedback approximately 140–240ms and one-off expressive reveals approximately 500–850ms when suitable. Show essential content immediately. Respect reduced motion; ordinary scrolling, keyboard access, and readable final states survive without an animation. Avoid sustained ambient movement inside a busy working canvas.

Use semantic controls, visible focus, accessible names, keyboard alternatives to dragging, and text accompanying status color. Target WCAG 2.2 AA where applicable, with text contrast at least 4.5:1 for normal text, 3:1 for large text and necessary non-text boundaries, and appropriately sized or spaced targets. Decorative panel edges can be quieter than the controls that depend on boundaries to be identifiable. Test actual compositions over imagery, not only flat token pairs.

The candidate's planned shortcuts include Ctrl+K command palette, Ctrl+1…9 workspace choice, Ctrl+\\ agent, Ctrl+Alt+N regions, F folding, Ctrl+Enter sending, Escape dismissing, Space panning, and Ctrl+scroll zooming. Adopt only where the current platform can implement them reliably and without hijacking text editing. Describe supported shortcuts in the UI and ensure actions remain available without them. The local specimen does not claim to implement every planned shortcut.

## Integration order and evidence

Establish the shared shell, theme roles, panel anatomy and lifecycle, then deliver complete named workspace experiences with their supporting machinery. Develop independent tools and shared foundations concurrently where useful. Missing data models do not postpone interface design or require another prompt. Build and connect what the finished tool needs in the same assignment; stages are internal checkpoints, and implementation continues through the entire PLAN.

Validate with actual work: open a page, select a section, change copy, switch views, return, compare an image, place it, undo, edit an automation branch, save/reload, and filter a list. Add failure and stale-state checks where these operations depend on services. Review at desktop and narrow widths, in both themes, with keyboard and reduced motion. The result is ready when the behavior, state, and visible artifact agree.

For any supplied specimen, preserve a known working baseline while adapting. The important evidence is a person completing the work with clear results. Deliver the implemented and tested paths under the overnight handoff's finish line, identifying only precise remaining external dependencies when they exist.