Feedback

Feedback specification

Feedback is one of Proto UI’s information channels. Its direction is Component → User. It carries perceivable information from a component to the user so the user can perceive the component’s existence, state, changes, and interaction results.

Without feedback, the User cannot perceive a component through Proto UI portable semantics. A component may receive props, handle events, keep state, and expose capabilities to the App Maker, but if it produces no feedback, the User cannot see, hear, feel, or understand what happened.

Feedback is not the same thing as “rendering.” render produces template structure; feedback describes how the component is perceived by the user. Much feedback is eventually realized visually, but semantically it is the Component → User information channel, not a synonym for a host styling mechanism.

Feedback APIs follow the setup / runtime split.

setup APIs declare or plan how the component can produce feedback. For feedback.style:

def.feedback.style.use(tw('inline-flex items-center opacity-100'));

This does not immediately mutate a real host node. It records a style plan during setup. The unUse returned by use() only removes that contribution during setup; it is not a runtime update mechanism or lifecycle disposer.

runtime APIs express runtime feedback effects. The v0 public runtime surface is the feedback.style patch escape hatch:

def.lifecycle.onMounted((run) => {
  run.feedback.style.patch(tw('opacity-50'));
});

Runtime feedback effects must not change template logic structure or content. They may update feedback, ideally through style flush only; entering render/update flow remains governed by Lifecycle / runtime update semantics.

feedback.style is the visual feedback surface cataloged in v0. It describes how the component changes appearance so the User can perceive state, changes, or interaction results.

def.feedback.style.use(tw('rounded-md bg-primary text-primary-foreground'));

These tokens are prototype-author-side Proto UI style tokens. They express prototype-internal visual intent. They are not DOM classes, CSS rules, data-pui-style tokens, or final adapter artifacts, and they do not need to correspond one-to-one with host output.

The translation layer may map style tokens to CSS, attributes, style decorators, host-private structures, or a completely different host mechanism. As long as the semantic intent of feedback.style is preserved, the final artifact shape belongs to the adapter or translation layer.

Author-side style tokens should express style intent only. They must not mix in state, events, selectors, or host realization logic.

tw('opacity-50'); // valid
tw('hover:opacity-50'); // invalid
tw('data-[open]:opacity-50'); // invalid

Forbidding : is not merely a parser limitation. It is a feedback channel purity rule. hover:bg-white puts state logic inside the style token; Proto UI wants that relationship expressed through clearer information channels and APIs.

To express “become translucent while hovered,” the recommended path is to compose rule with state, props, context, or other information sources and a feedback intent. An adapter or dedicated rule extension may generate selectors or data attributes in the final host output, but that is a translation-layer artifact, not a prototype-author-side style token.

run.feedback.style.patch/suppress/clearPatch is a runtime-only escape hatch. It is not the recommended primary path for dynamic styling; the preferred path remains rule + feedback + props/state/context. Patch exists for rare runtime repairs that do not fit naturally into rule declarations.

run.feedback.style.patch(tw('opacity-100'));
run.feedback.style.suppress(tw('bg-primary'));
run.feedback.style.clearPatch();

Each instance has one runtime style patch layer. patch() writes positive patches; suppress() writes negative patches; later writes win within the same semantic group, while different semantic groups remain independent. clearPatch() clears the patch layer and returns the final result to the base style semantic result produced by setup and rule.

The patch layer position is important:

setup style plan
  -> rule style intent
  -> runtime style patch
  -> translation layer
  -> host artifact

Patch is responsible for the final translatable style semantic result after setup/rule, but it does not directly override post-translation host artifacts. Adapters must consume the semantic result after patch is applied, rather than bypassing patch by consuming setup or rule intermediate results.

Template allows local nodes to carry style; this is one expression of feedback-only substructure not requiring extraction into an independent prototype. style can activate visual feedback, but it cannot also activate props, event, expose, context, or state.

If a substructure needs independent configuration, event handling, exposed capabilities, context, or state, it is no longer merely feedback-only and should usually become an independent prototype. Feedback flexibility should not be interpreted as permission for template to embed arbitrary prototypes.

Feedback coverage currently centers on feedback.style:

These tests focus feedback.style on how prototype-author-side semantic tokens move through setup, rule, patch, and translation, rather than on what the final host styling happens to look like.

• Core defines information channels, setup/runtime, and run handle foundations; Feedback is the Component → User channel.
• Template allows nodes to carry static style, but style semantics are defined by feedback.style.
• Lifecycle states that feedback runtime effects should not implicitly trigger render; style patch only requests style flush.
• Rule is not part of feedback, but it can express “when this condition holds, perform this feedback intent” declaratively.
• Props, State, and Context can provide conditions for dynamic feedback; Feedback owns the perceivable result delivered to the User.