Skip to main content
The primitive catalog is the source vocabulary for BudsCollab apps. Treat it as the atomic UI and capability catalog: app builders, Eve, Codex skills, CLI scaffolds, docs, and registry review should all point back to this same model. The catalog has six layers:
  • UI primitives: cards, rows, badges, app icons, metrics, and action buttons.
  • Theme primitives: room-managed tokens, primitive hooks, app icon families, widget surfaces, wall frames, note presets, and score evidence.
  • Surface primitives: widget, fullscreen, dock, overlay, and chat panel.
  • Capability primitives: host data, connector reads, room state, safe actions, collaboration presence, and sandboxed code.
  • Safety primitives: permission boundary, renderer boundary, provenance, network policy, write policy, and review report.
  • Distribution primitives: saved widget, published widget, published wall, full app, sandbox project, and developer-owned repo.
The SDK source of truth is SDK_PRIMITIVE_LAYER_CATALOG. Each layer points to the concrete catalogs used by validation:
  • UI: SDK_JSON_RENDER_COMPONENT_ALLOWLIST
  • Theme: BUDSCOLLAB_ROOM_THEME_COMPONENT_PRIMITIVES, BUDSCOLLAB_ROOM_THEME_DESIGN_SYSTEM_REPORT, and BUDSCOLLAB_ROOM_THEME_NOTION_BENCHMARK_REPORT
  • Surfaces: APP_CREATOR_SURFACE_CATALOG
  • Capabilities: APP_CREATOR_CAPABILITY_CATALOG
  • Safety: APP_CREATOR_SANDBOX_SAFETY_GATES plus package validation.
  • Distribution: APP_CREATOR_DISTRIBUTION_TARGET_CATALOG and SDK_DISTRIBUTION_LIFECYCLE_CATALOG.

​
How to use it

Start with the smallest primitive set that can express the app:
  1. Pick surfaces: widget, fullscreen, dock, overlay, or chat panel.
  2. Pick UI primitives: cards, rows, badges, metrics, forms, and action buttons.
  3. Bind Theme primitives: inherit room tokens, use host card and app-icon hooks, and preserve widget, wall, and note preset controls.
  4. Pick capabilities: host data, connector reads, room state, safe actions, or collaboration presence.
  5. Pick safety gates: permission boundary, renderer boundary, provenance, network policy, write policy, and review report.
  6. Pick distribution target: personal widget, full app, sandbox project, or developer-owned repo.
Only move to sandboxed custom code when the app cannot be expressed with host-rendered primitives. Even then, the package still declares surfaces, capabilities, safety gates, and distribution target with the same SDK contract. The package should also keep room Theme as the design-system manager: generated or developer-owned BudsApps inherit Theme tokens, register a stable app identity and icon family, and carry 8+ design-system and Notion benchmark score evidence before review.