DocsBack to homepage

Start Here

  • Getting Started
  • Key Concepts

Design Tokens

  • Token Types
  • Token Modes
  • Token Enforcement
  • Deprecated Tokens
  • Quality and Accessibility

Components

  • Component Builder
  • Composition Rules

Publishing

  • Publishing
  • Docs Mode
  • Changelog Notifications
  • Notifications and Alerts

Integrations

CLI & Data

  • CLI Reference
  • CLI Configuration
  • Import Formats
  • Importing Tokens
  • Export Formats

Tooling

  • Studio AI Assistant
  • Figma Plugin
  • API Reference
  • Webhooks

Account & Billing

  • Audit Log
  • Security and Access
  • Account Security
  • Pricing and Payments

Documentation

Component Composition Rules

Studio enforces a nesting hierarchy when you place atoms into slots on the canvas. If a placement breaks the rules, it is rejected immediately with an error message. This page explains the tier model and what to do when each violation fires.

The three-tier model

Every atom has a static tier (1, 2, or 3). The tier determines which atoms it can contain.

  • •Tier 1 — primitive atoms (icon, badge, text, spinner): self-contained, no nested atom children expected. The smallest building blocks.
  • •Tier 2 — composite atoms (button, input, tag): built from one or more Tier 1 atoms. Accept Tier 1 children in their slots, not Tier 2 or Tier 3.
  • •Tier 3 — layout atoms (card, dialog, toolbar): structural containers. Accept any tier.

The rule: a child's tier must be less than or equal to the host's tier. Plain HTML elements and unknown custom elements have no tier and are always accepted.

Violation: tier-violation

Fires when the child's tier is higher than the host's tier.

Error format:

[ReframeUI Composition] <host-tag> is Tier N and cannot contain <child-tag> (Tier M) in its "slot-name" slot.

Fix: place the child into a host at a higher or equal tier, or replace it with a lower-tier atom that fits the slot.

Violation: accepted-atoms-violation

Fires when a slot has an explicit allowlist and the placed atom is not on it. The component author sets this constraint in the Slots section of the Component Drawer.

Error format:

[ReframeUI Composition] <host-tag> slot "slot-name" does not accept <child-tag>. Allowed atoms: atom-a, atom-b.

Fix: place one of the listed allowed atoms into that slot. To see which atoms are accepted, open the Component Drawer and inspect the slot definition. If the constraint is wrong, edit the slot's accepted atoms list.

Violation: required-slot-missing

Fires when a slot is marked required and no content has been assigned to it.

Error format:

[ReframeUI Composition] <host-tag> requires content in the "slot-name" slot but none was provided.

Fix: drag any accepted atom into the slot. If the default slot is required, the component must have at least one child. To make a slot optional, open the Component Drawer and uncheck the Required toggle on the slot.

Where violations appear

Violations appear inline on the canvas as a red rejection indicator on the affected slot. The full error message is shown in the Component Drawer's Slot panel. In development, CompositionViolationError is also thrown and appears in the browser console with the complete violation list.

Note: Multiple violations can fire at once. Fix them in order from the first listed.

Continue reading: Component Builder or Quality and Accessibility.