Create reusable Components

Make a visual Component reusable by giving it a small public contract, then place references to that source Component in Pages or other Components. An instance supplies props, variants, events, and children; it does not become an independently editable copy of the source tree.

Coverage: UI + MCP.

Decide what the parent controls

Start with a Component whose base layout already works. Divide its concerns into:

• Need: Caller-supplied value such as label, URL, disabled flag, or image · Use: Property

• Need: Component-owned runtime value such as open, count, or submitted · Use: State

• Need: Named visual choice a consumer selects · Use: Component variant

• Need: Content supplied into a layout region · Use: Children slot

• Need: Notification emitted to the parent · Use: Event

• Need: Validity information · Use: Validator

Do not expose every internal value. A smaller contract is easier to understand, test, and preserve through re-export.

Declare and connect the contract

1. Open the source Component and switch to Logic.

2. Add the required property, state, event, variant, child slot, or validator with an intentional export-safe name and type.

3. Bind properties to the relevant text, attributes, styles, inputs, or nested Component props.

4. Use internal states for behavior the caller should not manage directly.

5. Connect emitted events only where a parent needs a callback.

6. Add test cases for meaningful property and variant combinations.

7. Preview those combinations before placing the Component elsewhere.

Component variants are consumer-facing named choices. For a visual change driven internally by state, use a per-node style variant rather than adding a public Component variant merely to toggle it from logic.

Place an instance

In the parent Page or Component, add a Component node and choose the source Component. Then configure the fields the source exposes:

• supply property values;

• select Component variants;

• fill named children slots;

• connect child events to parent behavior;

• size and position the instance within the parent.

The instance points to the source file. Edit source hierarchy and defaults in the source Component; configure only its exposed contract and parent-owned placement on the instance.

Library Component instances reference foreign/read-only source. Make source changes in the owning project, then use the library/sync workflow to update the consumer.

Ask an agent

In the Website project, inspect <source component reference> and its current data structure before editing. Add only these public fields: <properties, variants, children, events>. Reuse any equivalent existing field, bind each field to the intended source element, and add test cases for <combinations>. Then place one instance in <parent file reference>, supply <values>, and preserve every unrelated parent element. Verify the source contract, instance configuration, Preview behavior, and generated source/parent code. Do not duplicate or detach the source tree.

Relevant MCP families include get-data-structure, slot-specific additions, binding and component-instance operations, test-case tools, Preview, and export-code. Exact IDs returned by the source contract must be used when configuring the instance.

Verify reuse at both levels

Check the source:

• field names, types, defaults, and enabled states;

• property and children bindings;

• variant layers and combinations;

• event emission and validation;

• test cases and generated public types.

Check the parent:

• the instance references the intended source file;

• supplied props and variants reach the source;

• child content appears in the intended slot;

• emitted events trigger the intended parent behavior;

• parent sizing does not distort the source's responsive behavior.

Inspect generated output for both files when the public contract changes.

Undo and side effects

Source-contract edits and instance configuration are design-file content changes, but they belong to different files and therefore different histories. Undo and verify the source and parent separately.

Renaming or deleting a public field can break parent instances or generated consumers. Search current project usage and inspect generated diagnostics before making that change. File deletion is not recovered through content undo.

Current limits

• A duplicate display name does not make two fields interchangeable; identity and generated names matter.

• Mockups do not expose a Component data-structure contract.

• A Code Component supplies handwritten source and has no editable visual element tree.

• A foreign library source is not edited from the consuming project.

• Generated consumers still need compatible React, styles, runtime helpers, and dependencies.