AI Component Contracts
This page defines the safe assumptions an AI agent may make about Monster components before it starts inventing integration logic.
What Agents May Assume
Component pages are the source of truth for options, events, methods and examples. If a behavior is not documented, an agent should treat it as uncertain and verify it before depending on it.
Contracts should bias toward explicit HTML and documented APIs, not hidden DOM knowledge or guesswork about internals.
Default Rules
HTML first
If the documented component API can express the use case with markup and data-monster-option-*, stay in HTML.
JavaScript for behavior
Add JavaScript for events, async work, orchestration and programmatic state, not for replacing an existing declarative API.
Docs beat inference
Use documented examples, summaries and API tables before inspecting internals or synthesizing new patterns.
Uncertain means verify
If an event name, method or option is not documented, validate it in the playground or source before using it.
Contract Layers
Use the component summary for intent. It tells you what the component is for, not every possible implementation detail.
Prefer documented options and data-monster-option-* attributes over ad-hoc DOM manipulation.
Use documented custom events for runtime integration. Treat undocumented events as unstable.
If a page or example shows imperative methods, those are safer than guessing private internals.
Examples are executable contracts. Reuse and adapt them before starting from scratch.
The playground is the final verification layer when runtime behavior matters.
Do And Do Not
Use component pages as the contract
That includes the API table, examples and fragments. They are stronger evidence than assumptions from tag names.
Do not rely on internal DOM
A component may change its internal structure without changing its public API.
Prefer explicit event wiring
Use documented custom events and clear listeners instead of vague polling or mutation observers.
Do not create fake showcase logic
Show the real feature of the component. Avoid demo scaffolding that hides whether the component itself is doing the work.
Core Runtime Layers
The base layer for Monster web components. Agents may assume lifecycle, templating and public option/property handling start here. Do not infer private shadow structure from it.
The control layer for interactive form-oriented components. When a component derives from this layer, prefer its documented value, state and option API over custom DOM plumbing.
The DOM templating and binding layer. Use it when the task is about data-driven replacement, attribute binding, insertion or synchronized input state. Do not reimplement the same pattern with ad-hoc DOM mutation if Updater already covers it.
AI Notes On The Core Layers
CustomElement is the public shell
Treat options, properties, methods and events documented on the page as stable. Treat internal template markup as implementation detail unless the docs expose it as part of the contract.
CustomControl is for value-driven controls
When you work with selects, switches or similar controls, assume the component already solves focus, value and interaction concerns better than a hand-rolled wrapper.
Updater is the preferred binding engine
When the task mentions dynamic templates, repeated items or path-based content replacement, point agents toward Updater instead of imperative DOM patching.
Verify before composing layers
If a task combines custom controls with Updater and runtime scripting, check a real example or playground behavior before assuming the composition pattern.
Five Reference Controls
Select
Default reference for choice controls. Use it to learn option mapping, markup-first configuration and playground-safe imports.
API Button
Reference for async action flows, success/failure events and runtime orchestration without building custom request widgets.
Button Bar
Reference for responsive action groups and overflow behavior. Use it when actions must adapt to narrow containers.
Quantity
Reference for numeric control behavior, bounded values and small interaction surfaces in dense UI.
Toggle Switch
Reference for boolean or mapped value state. Use it for clean semantic toggles instead of custom checkbox skins.
How Agents Should Use The Five Controls
Prefer this for the canonical single-choice pattern. Reuse existing examples before inventing another dropdown architecture.
Use this when the primary user action is a request lifecycle with loading, success and failure states.
Use this when multiple actions compete for limited width. Check the overflow behavior in embedded examples.
Use this for explicit numeric stepping, not as a generic text input substitute.
Use this for clear state changes. If business values differ from true/false, document the mapping instead of hiding it.
If one of these five already matches the task shape, choose it first. The point is predictable documentation and lower invention cost.
Next Steps
AI Getting Started
Return there for file structure, imports and playground-safe execution.
Component Example
Use a real component page to inspect summary, API and examples together.
AI Styling Rules
Read this before adding custom CSS or visual wrappers around a component example.
Playground
Use it to verify that the contract you inferred actually holds at runtime.