Mixins / foldkit-mixins

How slots, styles, and behaviors fit together

There are five building blocks:

ConceptMeaning
SlotA named extension point in a view: root, input, label, trigger.
SlotsThe contract listing which extension points exist and what each permits.
StyleAppearance attached to a slot: classes, inline declarations, and CSS rules.
BehaviorElement-level interaction attached to a slot (attributes and optional Mount).
SlotViewA pure Foldkit view that renders slots and resolves attached mixins.

Style and Behavior both compile to a Mixin. The resolver combines their contributions and throws a diagnostic on ambiguous ownership instead of silently choosing a winner.

Styling follows a left-to-right pipeline where each step is type-checked by the one before it:

tokens -> ref -> pieces -> slots -> sheet

Theme.tokens holds the shipped values; Theme.ref reads them by name; a Style piece is built from the refs; Style.forSlots puts pieces on a Slot; and Style.stylesheet collects rules into cascade layers (Style and Themes as typed knobs).

Where to find each topic

You want toRead
Make a view customizableQuick start, Slots
Restyle a view or install a themeStyle, Themes as typed knobs
Add behavior to an elementBehavior
Add a key route to a widgetKeys (routes, mixins:key-conflict)
Declare and check accessibility rulesObligations (A11y.conform)
Run rendered pattern checksConformance (Conformance)
Inspect what a view's attachments doDescribing a view
Redraw only what changedParts, Regions
Test a view or emit static CSSTesting and static output

To build a component of your own from Slots, primitives and a recipe, one concept at a time, follow Authoring components.

Why not just className and props?

A class name says only "append this string." A slot is a typed public customization point. It can say:

  • this point is a text input rather than an arbitrary element;
  • it publishes input but not click;
  • callers may set aria-invalid but may not replace the structural role;
  • this point is internal and cannot be targeted publicly;
  • two independent behaviors may not both own the same event.

That matters once a design system, a feature, accessibility logic and product-specific behavior all need to customize the same view without knowing about each other.

When to attach mixins vs use model state

Use mixins when a view should be restyled or decorated where it is used, not only where it is defined, and you want those customizations checked.

Typical examples are a design system styling a feature component, a tooltip attached by a caller, analytics on an existing action, ARIA decoration, a focus trap, a ResizeObserver, keyboard behavior, or a reusable visual recipe.

Keep widget state (open/selected/value) in a Foldkit Model or Submodel: transitions belong in update, network calls run as Message → Command, and element-scoped DOM effects belong in a Mount. If a Behavior seems to need state, promote that state to a Submodel.