docs: surface undocumented MCP design capabilities in agent instructions - #482

Summary

While building a real site over MCP (film-grain textures, tinted scrims and gradient overlays layered over a native Slider), the agent-facing design guide steered us wrong in ways the codebase didn't deserve — the capabilities were already there, just undocumented:

• effects.mixBlendMode, effects.filter, effects.backdropFilter are supported by the tool schema (lib/mcp/tools/shared-schemas.ts) and the class mapper (lib/tailwind-class-mapper.ts), but the Design Properties guide in lib/mcp/instructions.ts never mentions them. Agents reading the guide conclude blend modes are impossible natively and fall back to custom code or HTML embeds.
• backgrounds.backgroundImage accepts any CSS value including inline SVG data URIs (great for noise/grain textures), but the guide only documents backgroundColor, backgroundClip, and gradients.
• htmlEmbed sandboxing — embeds render as sandboxed auto-resizing iframes on published sites (components/LayerRendererPublic.tsx), so position: absolute/fixed overlays and parent-DOM scripts silently fail. Nothing warns agents about this; it cost us the most debugging time of anything in the build. Added a note on the element bullet and on the html_embed_code schema description.
• custom_attributes as an escape hatch — CSS with no design field (e.g. pointer-events: none for decorative overlays) can be set via a style custom attribute. Now mentioned alongside the design property docs.

With these few lines of guidance the same agent built all overlays as native layers on the first attempt — no embeds, no page custom code.

Changes

• lib/mcp/instructions.ts — document mixBlendMode / filter / backdropFilter, backgroundImage (+ size/position/repeat), htmlEmbed iframe sandboxing with recommended alternatives, and the custom_attributes style escape hatch
• lib/mcp/tools/layers.ts — extend the html_embed_code description with the sandbox caveat

Test plan

• tsc --noEmit and eslint --fix pass (pre-commit hooks)
• Text-only changes to instruction strings and one schema description; no behavior changes

Made with Cursor