Borgiq Form Builder

BorgIQ Form Builder

Build forms and interface pages — the primary user-facing surface in BorgIQ workflows. Pair this skill with the hub borgiq-builder (which handles flow wiring) and, when fields produce or consume structured data, borgiq-json-schema-builder.

Mental model

Interface pages are the form surface of BorgIQ. Two actors share one page-configuration schema:

Interfaces are forms, not standalone apps. Using an interface with no form fields (just display + webViewer) is no longer recommended — for interactive dashboards, SPAs, or bespoke layouts, build an app instead (see the borgiq-react-app-builder skill). The webViewer component embeds an external page or custom HTML inside a form, but it does not replace forms.

Key decisions

1. InterfaceTrigger vs InterfaceActor. Does the form start the flow (Trigger) or sit inside it (Actor)? An InterfaceActor's meta port emits a URL that you can route to email/Slack and event fires when the user submits — this is the canonical async-approval pattern.
2. Form width. formWidth: full for data-dense layouts; half for focused single forms; third for very simple inputs (a single email field, a yes/no).
3. Single page vs multi-step. Group within one page using section and collapse. Reach for a wizard (chained InterfaceActors or onSubmit: nextInterface) only when steps depend on prior answers or the form is long enough that users would abandon a single page.
4. Validation strategy. required: true for mandatory, readOnly: true for display-only context, conditional fields for branching logic. Validation is client-side at submission.
5. Theme. Native page chrome is themed by the page config (themeColor, backgroundColor) — pick from themes.md (10 pre-built — Modern Minimalist, Ocean Depths, etc.). Custom HTML inside a webViewer is themed differently: use the app theme library (react-app-themes.md, default hearth) — it's plain CSS, no React required.
6. webViewer scope. Use it to embed external pages or hand-written HTML/CSS within the form (e.g., a help panel, a third-party widget). Don't try to rebuild the form itself in webViewer — use the native components.

Workhorse components

Reach for these first; they cover ~80% of forms.

See references/interface-pages.md for the full 40+ component catalog, including selection (multiSelect, chips), date/time, arrays, dynamic defaults, and conditional fields.

Anti-patterns

1. Interfaces as standalone apps. No form fields, just webViewer/markdown for display? That's a deprecated pattern — build an app via the borgiq-react-app-builder skill instead.
2. Arbitrary spacing or hex colors. The theme's spacing scale and tokens are the contract. Hard-coded padding: 17px or color: #4A90E2 outside the theme is a smell.
3. Missing interaction states. Every button needs hover/focus/disabled; every list needs loading/empty/error. Forms without states feel like screenshots.
4. Sidebar with a different background color. Fragments the visual space. Same background, subtle border for separation.
5. Skipping the squint test. Blur your eyes — if the hierarchy isn't visible and surfaces aren't distinguishable, the design isn't intentional yet.

Theming, briefly

Two surfaces, two mechanisms:

• Native page + form components are themed by the page config (themeColor, backgroundColor); pick a palette from references/themes.md. Dark mode is supported via data-theme="dark".
• Custom HTML inside a webViewer uses the app theme library — references/react-app-themes.md. It's framework-agnostic CSS (custom properties + class recipes), so it works in the webViewer's raw HTML+CSS with no React and no CDN: paste the Base Contract + one theme block (default hearth, or the theme closest to the page's palette) into the webViewer's styles, build markup on the recipe classes, and use Tabler icons as inline SVG with stroke="currentColor". Never hard-code colors — tokens only, and dark mode comes wired in.

Wiring to downstream actors

Form submissions are emitted as structured data; downstream actors consume specific fields:

# Downstream HttpRequestActor accessing form data
inputs:
  customerName: ${{ msg.signup_form.body.fullName }}
  customerEmail: ${{ msg.signup_form.body.email }}

The body keys come from your key: declarations on each component in the page config. Define them with care — they're the API contract between the form and the rest of the flow.

References

When to hand off to other spokes