Writing a Custom Primitive Prototype

A leaf Prototype represents a protocol subject with a clear boundary and an independent information-flow responsibility. Button and Toggle are two relatively clear current examples.

This guide explains authoring structure. Existing governed subjects proceed directly from their current P/T graph. For a genuinely new Base subject, research, a candidate graph, draft entities, implementation probes, and tests may proceed immediately; the one unresolved semantic decision is whether Proto UI admits that independent subject as a Base identity. Use Implementing a Governed Base Semantic Slice to carry either path through coherent delivery.

Do not begin by copying source. For Button, read in this order:

1. lifecycle, criteria, relations, and sources in P-BASE-BUTTON;
2. cases and executable mappings in T-BASE-BUTTON-0001;
3. packages/prototypes/base/src/button/button.proto.ts;
4. packages/prototypes/base/test/as-button.test.ts and applicable Adapter evidence; and
5. package exports, CLI, documentation, and demos.

P-BASE-BUTTON is currently draft. Source is implementation evidence, not authority above the applicable entity.

Button has two official authoring entries:

• the base-button direct Prototype; and
• the asButton authored asHook.

They share setupButton(def) instead of maintaining two versions of Button semantics. That arrangement realizes P-BASE-BUTTON-AUTHORING-ENTRIES; it is not a fixed template that every Prototype must copy.

The current implementation includes:

• def.props.define() for disabled;
• def.state.bool() for states such as disabled, hovered, and pressed;
• asFocusable() for focused, focusVisible, and the focus method;
• def.event.on() for pointer routes and press.commit;
• def.expose.state(), def.expose.method(), and def.expose.event() for outward surfaces; and
• asAccessible() for Button role, name, state, and action.

The former def.state.fromInteraction() example no longer describes the current Button implementation and must not be used as the example for this guide.

def declares the setup-time plan: props, state, events, exposes, accessibility, rules, and lifecycle hooks. run appears inside runtime callbacks and provides access to current props, context, lifecycle, and outward effects.

For example:

def.event.on('press.commit', (run) => {
  if (disabled.get()) return;
  run.expose.emit('click');
});

The event route is registered during setup; the outward signal is emitted through run when the event occurs.

Do not treat “exports a Prototype but no asHook” as a universal error. Ask:

• Does the applicable P catalog direct and authored-asHook forms as two entries of one protocol?
• Should both entries share the complete protocol surface and implementation?
• Does the hook serve only its owning protocol rather than becoming cross-Prototype substrate?
• Would the entry introduce ungoverned options, merge, or configure semantics?

D-PROTOTYPE-ENTITY-NAMING-0001 requires existing entries for one protocol to be cataloged in the same P entity; it does not require every direct Prototype to generate an asHook. D-AS-HOOK-CONFIGURABLE-AUTHORED-0001 also keeps ordinary configurable authored asHooks in governed future design space.

A source file is only one part of delivery. A governed leaf or clearly marked candidate normally follows:

governed identity or candidate draft
→ P criteria and relations
→ T cases and executable tests
→ implementation and public exports
→ CLI facade generation
→ bilingual docs and real public-package demo
→ applicable WC / React / Vue evidence

The three current Adapter previews verify one Web host profile; they do not automatically prove multi-host conformance.

If implementation needs a new public prop/event/state, changes ownership, requires a raw host object, or exposes a contradiction between P/T and implementation, update the candidate or governed graph, tests, and evidence together instead of widening source alone. Continue the reversible work through fresh review. Escalate only when the evidence requires admission of a different new Base identity; keep that identity draft while the admission choice is unresolved.

• For a compound family, read Writing a Compound Prototype
• For a design-language projection, read Building a Styled Library on Top of Base
• Before opening a pull request, use the Prototype Author Checklist