Styling your app

The App Bridge UI Kit styles content inside your embedded app with tb- classes and light and dark themes. The stylesheet works with plain HTML and any framework. Optional form helpers, such as enhanced selects, file inputs, and date pickers, use JavaScript from the App Bridge SDK. Host-rendered controls are covered separately in UI primitives.

Link the stylesheet below and use tb- classes in your HTML. Load https://bridge.tringify.com/app-bridge@1.js before calling any TringifyBridge.ui helper. Styling your app does not grant access to host operations; use bridge.supports() after startup to check those capabilities.

The kit renders light by default and follows data-theme on the root element. Set it from the App Bridge context when your app boots, and keep it updated on theme:change.

Components use the CSS variables below for colors, borders, spacing, and corners. Setting data-theme="dark" on the root element switches their values automatically. Keep the defaults for a consistent Tringify appearance in both themes.

The kit supplies the type sizes below. Use heading classes for headings, labels for form controls, and description classes for supporting text. Body text inherits a 16px size.

Use one tb-page root; it fills the admin frame. Inside it, tb-page-header holds the title row, and tb-section blocks separate areas with a divider. Headings come in three sizes: tb-h1, tb-h2, and tb-h3.

tb-header is the view header idiom: an optional back control on the left, a title with an optional subtitle, and actions on the right. The back chevron is drawn by the stylesheet — the button element stays empty apart from its accessible label.

Configuration screens compose from tb-settings-stack, tb-settings-group, and tb-settings-row. A row's summary line pairs a title and current value with an action on the right; an optional tb-settings-row-editor expands below it for inline editing. Toggle the editor with the hidden attribute.

tb-field wraps a tb-label with its control. tb-field-grid lays fields out two per row; add tb-field-span to a field to span the full width. tb-field-help carries helper text and tb-charcount a character counter — add tb-charcount-over past the limit. For multi-line template editing, pair tb-textarea with clickable tb-varchip variable chips.

Forms compose from cards, the same shape Storeadmin's own product and vendor forms use: a tb-card per section with a tb-card-header (tb-card-title and optional tb-card-description) and the fields in tb-card-body. Field grids come in two (tb-field-grid), three (tb-field-grid-3), and four (tb-field-grid-4) columns, collapsing on small screens. Close the form with tb-form-actions. For a flat form without cards, tb-fieldset groups divide sections with rules instead.

For a select, keep a real <select class="tb-input"> inside its tb-field, then pass it to TringifyBridge.ui.enhanceSelect(). Give the native field a label and a name for form submission. A disabled, selected empty option acts as a placeholder and is omitted from the list. An enabled empty option remains selectable, for example “None”.

Selects. The enhanced list supports option groups, disabled options and groups, arrow keys, Home/End, and typing the start of a choice to focus it. Enter or Space selects; Escape closes without changing the value. It supports one choice only: multiple and size > 1 are rejected with INVALID_ARGUMENT. Options come from your own HTML; the helper does not fetch store records or provide remote search.

File pickers. enhanceFile(input, options) adds a browse-and-drop control, a list of every chosen filename and size, and Clear files. Use the native multiple and accept attributes. Drops with too many files or a type outside accept preserve the previous selection and show an error. The native input remains the source of files, input, and change events. Browser selection uses the platform file chooser; validate file content, type and size in your app and upload service. Choosing files does not upload them or add them to a store library. To choose existing Media or Site Assets, use the host media picker.

Character counters. enhanceCharCount reads the element's maxlength (or data-maxlength) and renders a live tb-charcount counter in Storeadmin's 12/80 format, flagging overflow with tb-charcount-over. Call the returned sync() after setting the value programmatically. To wire every limited field at once, call enhanceCharCounts(root?) — it sweeps the document (or a given element) for fields declaring maxlength or data-maxlength, skipping search inputs and fields marked data-charcount="off". Declare the limit on the field; the sweep does the rest.

Dates. Enhance a native <input type="date"> to choose one calendar day. The helper respects min, max, step, required, readonly, and disabled fields. Values remain YYYY-MM-DD calendar strings without a timezone conversion. Month and weekday names follow locale; the week starts according to that locale when the browser supports it, or Sunday otherwise. Set weekStartsOn explicitly for a fixed layout. Arrow keys move days, Home/End move within the week, Page Up/Down move months, and Shift + Page Up/Down move years. Enter or Space chooses a valid day. Today follows the field bounds and step; Clear is available when the field is optional. Escape and outside clicks dismiss without selecting. Date ranges, times, and datetimes are not provided.

tb-btn is the primary button. Variants compose: tb-btn-outline, tb-btn-ghost, tb-btn-icon, tb-btn-sm, and tb-btn-block. Disabled buttons need only the disabled attribute.

Use the tb-resource-list composition for searchable, paginated record lists. It matches Store Admin resource pages as one complete layout: tb-resource-list-toolbar contains the search and filters, tb-resource-list-content contains either a semantic tb-resource-table or a tb-resource-list-empty state, and tb-resource-list-footer contains the result range, page-size control, and first, previous, page, next, and last controls. Build an empty state with tb-resource-list-empty-title, tb-resource-list-empty-text, and, when an action is useful, tb-resource-list-empty-actions. Keep server-side search and pagination authoritative. Enhanced select menus measure the embedded viewport when opened and automatically appear above the trigger when there is not enough room below; apps do not need placement logic. Use tb-table for tables that do not need this list workflow; it shares the same Store Admin table styling. Any list with more than one page should use tb-resource-list-footer, not previous and next alone, so merchants can jump to a page or change the page size.

Use tb-tabs-scroll, tb-tabs, tb-tab, and tb-tabpanel for distinct views within one app page. The scroll wrapper keeps every tab reachable in a narrow embedded viewport. Give the tab list, tabs, and panels their corresponding ARIA roles and connect each tab to its panel with aria-controls and aria-labelledby. Set aria-selected on the active tab and hidden on inactive panels. For settings forms, place the editable controls in one tb-card with tb-card-header and tb-card-body, matching Store Admin Settings. For read-only record sets such as provider mappings, use tb-resource-list and tb-resource-table; add tb-resource-table-center when the first identity column should remain left-aligned while the remaining data columns are centered.

Tables go inside tb-table-wrap for the border and horizontal overflow. tb-table-cell-wrap lets a column wrap; tb-table-cell-actions right-aligns a compact actions column. For record lists that are not tabular, use tb-data-list rows; for headline numbers use tb-stat-grid — each tb-stat renders as its own card. tb-badge (with tb-badge-muted and tb-badge-solid) labels categories. For state, use tb-status-text, Store Admin's status indicator: a 7px dot beside foreground text. Add tb-status-success, tb-status-warning, tb-status-destructive or tb-status-info to color the dot; with no tone it stays neutral. tb-table uses Store Admin's list-table styling: a plain header row in medium-weight text, 14px rows and row dividers. When a row opens a record, add tb-table-row-link to the tr, give it tabindex="0", and open it on click and Enter instead of adding a View button. tb-table aligns columns by position: the first column reads left, the last aligns right, and every column between is centered under its heading. tb-table-center is no longer needed.

Row lists. tb-rowlist frames a divided stack of tb-rowlist-item records — the standard shape for per-record status screens. Pair each row's title with a tb-badge tb-badge-muted qualifier and a tb-status-text state; add a tb-status-* tone when the state needs color.

Group multiple row lists with standard tb-settings-group headers — one group per section. For dense read-only reference data (term → value), use tb-deflist, a two-column definition list inside a card; reach for a row list only when rows carry actions.

Drawer. Row-scoped editing and detail views slide in from the right with tb-drawer — the list underneath never reflows. Structure: a tb-drawer-root overlay holding a tb-drawer-backdrop and the tb-drawer sheet (tb-drawer-header with title + tb-drawer-close, a scrolling tb-drawer-body, and a pinned tb-drawer-footer for actions). To open: unhide the root, then add is-open on the next animation frame. To close: remove is-open, hide the root after the transition. Wire Escape and backdrop clicks to close. Rule of thumb: edit a row in a drawer; edit a whole resource on its own view. The stylesheet provides appearance and transitions; your app provides modal behavior. Give the drawer an accessible name, move focus inside on open, keep keyboard focus inside while it is modal, prevent interaction with the background, and restore focus to the trigger on close. Support Escape and reduced-motion preferences.

tb-tabs is a segmented tab list; mark the active tab with aria-selected true and pair each tab with a tb-tabpanel, hiding inactive panels with the hidden attribute. tb-toolbar holds search, filters and actions above a table, with tb-toolbar-group clustering related controls. A tb-search inside it fills the row, like Store Admin's list search; filters and actions wrap beside it. Page headers (tb-header) are separated from content by spacing, not a rule.

Prefer a skeleton over the spinner when the eventual layout is known: compose tb-skeleton blocks into that layout with the size utilities (tb-skeleton-title, tb-skeleton-text, tb-skeleton-btn, tb-skeleton-input, tb-skeleton-row, tb-skeleton-square, tb-skeleton-circle), or use tb-skeleton-list for a list of loading rows. The pulse matches Storeadmin's own skeletons and pauses under reduced-motion preferences.

tb-loading renders a centered spinner with a label while a view waits for data. tb-empty is the dashed empty state. tb-note carries an inline notice inside your page — for status that should sit above the app in Storeadmin's chrome, use bridge.banner.show() from UI primitives instead. Components carry no outer margins — wrap sibling blocks in tb-stack for vertical rhythm.

An app's home screen introduces the app, shows connection state, and walks the merchant through setup. These components cover that page so it reads like the rest of the admin: a first-run hero, a setup checklist, toned callouts, a connection card, a feature grid, and a themable icon set.

Hero. The first-run panel before anything is configured: tb-hero centers an icon well, a headline, one supporting sentence, and the primary call to action.

Setup steps. tb-steps numbers itself; each tb-step declares data-state as done, current, todo, or off. A done step's marker draws a check, the current step's marker is emphasized, and an off step dims. Put the step's action button in tb-step-action.

Callouts. Use tb-callout-info for non-actionable context; it is intentionally neutral so ordinary guidance does not look selected or branded. Reserve tb-callout-success for a completed positive state and tb-callout-warning for a consequence that needs attention. Lead with a matching tb-icon when the message deserves one.

Connect card. The connection status block: a mark well (an tb-icon or an <img>), the connected identity, a status line, and the connect or disconnect action. Set data-connected="true" to turn the status dot green.

Feature grid. "What this app does" tiles — a drawn icon, a short title, one supporting sentence. Use it instead of stat tiles when the content is capabilities, not metrics.

Icons. tb-icon glyphs are CSS masks painted with currentColor, so they inherit text color and follow the theme. Size them with font-size or tb-icon-lg. Mark decorative icons aria-hidden="true".

Empty states. tb-empty on its own is a single line of muted text. When the merchant can act on the emptiness, compose the optional parts instead: tb-empty-title names what is missing, tb-empty-text explains the consequence, and tb-empty-actions holds the button that resolves it. Use the plain one-line form only when there is genuinely nothing to do — a filtered list with no matches, for example.

One-time secrets. tb-secret shows a value the merchant can never see again — an API key or token at the moment it is minted. It is deliberately not an input: the value cannot be edited, it wraps instead of truncating so nothing is copied half-selected, and it is monospaced so 0/O and 1/l are distinguishable. Pair it with a copy control, because hand-transcribing a key is where the mistakes happen. Put it inside a tb-callout-warning and let the callout carry the "you will not see this again" framing — tb-secret renders the value, not the warning. Write the value with textContent, never value, and clear it when the merchant dismisses the callout so a re-render cannot bring it back.

Collapsed explanations. Use native <details class="tb-disclosure"> for supporting information that is useful on demand but should not compete with the page's primary form. Keep it collapsed by omitting open. The browser owns keyboard interaction and disclosure state; no app JavaScript is needed. Put the title and one-line preview in tb-disclosure-summary, and the expanded material in tb-disclosure-content. For a short ordered workflow, use tb-disclosure-list; it numbers itself and keeps each item compact. Do not use a disclosure to hide required fields, errors, or the current status.

Disclosures inside a frame. Add tb-disclosure-flush when a disclosure sits inside a card, a settings section or another disclosure. It drops the frame and keeps one top rule, so the region is boxed once. Use one level of framing per region: never put a tb-card inside a disclosure; place the content straight in tb-disclosure-content instead.

Inspect layouts. Use tb-split when a detail page should show facts beside a preview. Put the readable record in tb-split-main and the preview in tb-split-aside. Below 720px the columns stack. Keep headline counts in tb-stat-grid; put heterogeneous term → value data in tb-deflist (values wrap); put a homogeneous stack of records in tb-rowlist. For a read-only row, tb-rowlist-primary is the fact and tb-rowlist-meta is the secondary detail. Reach for a settings-row summary inside a row list only when the row also carries an action.

Scrollable previews. tb-media-frame letterboxes an image inside a 420px cap. Add tb-media-frame-scroll when the asset is much taller or wider than that cap — proofs, banners, print plates — so the preview keeps its aspect and the frame scrolls instead of shrinking the image. Use this modifier when the preview needs to remain scrollable.

A minimal embedded app page: the kit for appearance, the SDK for boot, theme, and session.

Use tb-tabs-scroll around a tb-tabs tab list and tb-tabpanel for its panels. tb-section is for stacked sections; it adds separators between sections and should not be used as the tab-panel layout.

enhanceTabs(tablist, { onChange(tab) {} }) manages selection, hidden panels, keyboard focus, arrow keys and Home/End. Horizontal lists follow text direction; use aria-orientation="vertical" for vertical lists. Disabled tabs are skipped. Give each tab and panel a unique ID. Initialize nested lists separately. Call sync() after replacing tabs and destroy() before removing the component.

Use tb-input-action for an input and its action button, and tb-text-preserve for readable message previews that retain line breaks. Use a fieldset.tb-fieldset to disable a related group of fields without browser-default borders. A <legend> can name the group.

For selects, associate a <label> with the original <select>, add any aria-describedby or validation attributes, then call ui.enhanceSelect(select). The Kit connects the label and help text to the visible picker and hides the native duplicate from assistive technology. Its destroy() method restores the native field. Keep application validation and save/network behavior in the app; use App Bridge's Save/Discard bar for unsaved settings.

Initialize each helper once after its input is in the document. Keep the native field for FormData, validation, values, and events. Labels and help text follow the visible control, disabled fieldsets disable it, and a native form reset restores its display. Call sync() after changing .value or .files programmatically; property assignments do not emit browser events. Call destroy() before unmounting to remove listeners and restore the original field. Select and date handles also provide close(). Required fields expose their invalid state on the visible control when native validation runs; display any app-specific error message beside the field.

Counters follow input and change events, form resets, and changed limits. Their count matches native maxlength behavior, which counts UTF-16 code units; some symbols use more than one unit. Call sync() after assigning a field value in code and destroy() before removing the control. Tabs and counters are UI helpers, not resource pickers. Provider accounts, pickup mappings, feed fields, and provider-approved message templates are app-owned controls; the host does not supply custom options for them.

Use tb-form-page for create and edit screens. It matches Store Admin's Product form: section cards in tb-form-page-main (two thirds) beside settings cards in tb-form-page-aside (one third), stacking into one column below 1024px. Build each card as tb-card tb-form-section; its body spaces fields 16px apart. Pair fields with tb-form-row, or use tb-form-row-3 and tb-form-row-4 for short numeric fields. Wrap a repeatable item, such as a placement area, in tb-form-item with a tb-form-item-header for its title and Remove action. Mark required labels with <span class="tb-required" aria-hidden="true">*</span>. Put Cancel and Save in the header's tb-header-actions, and add tb-header-sticky so they stay visible while the form scrolls.

For app settings, follow Store Admin's Settings > General: stack section cards in tb-settings-page, add tb-form-section-loose so fields sit 24px apart, and finish with one tb-form-footer holding the Save button at the bottom right. Keep one topic per card and pair related numbers with tb-form-row.

Wrap a checkbox in <label class="tb-check"> to get Store Admin's checkbox and a label row; use tb-switch for settings that take effect as a toggle. Date inputs enhanced with TringifyBridge.ui.enhanceDate use Store Admin's calendar. When a date is optional, offer common choices in a select (for example 30 days, 90 days, 1 year) and show the calendar only for a custom date.

UI Kit 1.0.72 uses Inter to match Store Admin. The font is served from bridge.tringify.com; if your app has a Content Security Policy, allow font-src https://bridge.tringify.com. A system font is used when Inter cannot load. For Settings, wrap section cards in tb-settings-page and add tb-form-section-loose to each tb-card tb-form-section. This gives fields 24px of separation and labels 8px before their controls. Place one Save action in tb-form-footer below the cards. Use tb-callout-info for a quiet informational note; warning and success messages keep their distinct treatments.

Use tb-stat-strip for a small set of headline counts. Each tb-stat-tile has a white card surface and can include a decorative tb-stat-icon. Use any UI Kit tb-icon inside it. Add data-tone="green" or data-tone="violet" to change the icon color; the default is blue. Keep a visible label with each value.

Place tb-banner elements in tb-banner-grid. Set data-size to square (or 1x1), rectangle (or 2x1), 2x2, 3x1, or 3x2. These sizes describe column-by-row spans on a wide three-column layout; banners become full-width cards on narrow screens. Use data-tone="ink" for a dark plain banner. You can also set --tb-banner-bg and --tb-banner-fg on an individual banner to match your app.'s palette.

For an image banner, add tb-banner--image and an <img class="tb-banner-image">; the Kit adds a text-legibility gradient. Put the eyebrow, title, supporting text, and optional icon inside tb-banner-content. A direct tb-banner-link makes the full banner clickable. Give the link an accessible name, and put any separate buttons in tb-banner-actions rather than inside that full-banner link. Keep essential words as HTML text, not baked into the image.

UI Kit 1.0.73 adds tb-steps-cards for a short onboarding sequence. Put it alongside tb-steps; each tb-step contains a tb-step-marker, tb-step-body, and optional tb-step-action. Set data-state to current, done, todo, or off. The marker shows the step number or a completion check, and the cards stack on narrow screens. Use tb-steps without the card class when a compact list fits better. Give action buttons descriptive labels.

Include a step only when your app can tell when it is complete. After the sequence is finished, replace the checklist with useful management links. Keep optional Settings actions outside the completion sequence.

UI Kit 1.0.74 places a counted field's help text and character count on one caption row when the input and tb-field-help are in the same tb-field. Call TringifyBridge.ui.enhanceCharCounts(document) after the fields exist. If you set an input's .value in code, call the returned counter handle's sync(); assigning .value does not fire an input event. For an enhanced select, use <option value="" disabled selected>Choose…</option> for a prompt that cannot be selected from the menu. Leave an empty option enabled only when it represents a real choice such as “None”.

To select existing store records, open a host resource picker with bridge.resourcePicker.open(); the UI Kit does not draw its rows or page controls. Product, Brand, Vendor, Category, Collection, Product Attribute, and Product Tags pickers use their catalog icons, show the current page, and offer page-size choices. A search or page-size change starts again on page 1, and selections remain chosen across pages. See Dialogs and pickers for the picker contract.

Put a list's search and its filters in one tb-toolbar: a tb-search, then one tb-toolbar-group per set of related filters. From UI Kit 1.0.76 a group keeps its controls side by side and, when the row runs out of room, wraps under the search as a whole, so selects never stack into a narrow column. Enhanced selects and dates (ui.enhanceSelect, ui.enhanceDate) size to their content inside a toolbar. For a date filter use tb-date-range: one bordered control with an optional label, the two date inputs and a dash. Enhance each input with ui.enhanceDate as usual; inside a range the pickers lose their own border. On narrow screens each group takes the full width.

Style the action with UI Kit's tb-btn tb-btn-outline classes. After await bridge.ready(), hide the button if !bridge.supports('navigate'); otherwise call bridge.billing.openPricing() from its click handler and handle promise errors through your normal app feedback. The host checks unsaved changes before leaving the app. See App Bridge getting started and UI Kit.

Most merchants are not technical. Open your app's home page by saying what the app does for them, then show the next thing to do. UI Kit 1.0.77 adds tb-hero-feature for that welcome banner: an eyebrow (tb-hero-eyebrow), a headline, one or two sentences in everyday words and the next action, inside tb-hero-body, beside one piece of artwork (<img class="tb-hero-art" alt="">). On narrow screens the artwork moves above the copy. Use artwork without text or currency symbols, so it reads the same in every language and country.

Below the banner, show how far the merchant has come with tb-progress, then the steps (tb-steps tb-steps-cards). Set --tb-progress to the percentage done and keep the aria-valuenow and aria-valuemax values in step with it. From 1.0.77 the step to do next is marked in ink rather than color: its card gets a dark border and a filled marker, and finished steps sit on a muted background. Mark exactly one step current. For each step, say why it matters in one sentence and make its button name the action, such as "Connect Google" rather than "Continue".

Guide merchants through tasks that happen outside your app, such as finding an ID in another service, with a tb-disclosure holding a numbered tb-disclosure-list: one short title (tb-disclosure-item-title) and one sentence (tb-disclosure-item-text) per step. Put context that is not a step, such as why the task matters, in a paragraph above the list rather than numbering it. Name things the way the other service names them on screen. From UI Kit 1.0.80 the step text always sits beside its number; earlier versions could wrap it into the number column. For text only screen readers should hear, such as a table caption or the name of an icon-only button, use tb-sr-only.

Put tb-flow on a view's content (UI Kit 1.0.78): every block after the first gets the same 16px gap, whatever it is, so a callout above a list or a disclosure above a table never touches. Use tb-flow-loose to separate whole sections (40px, 32px on phones), and group a heading with its description in a <header> so they stay together. Prefer it to margins on individual components.

From App Bridge 1.0.62, ui.enhanceSelect adds a search box to the top of the menu when a select has more than 10 options, such as a list of countries or languages. Typing filters the options and ignores accents, so "cote" finds Côte d'Ivoire; Arrow Down moves into the list and Enter picks the first match. Set data-search="true" or data-search="false" on the select to override the length rule. Order long lists for people: put the most likely choice first, such as the store's own country, then sort the rest by name rather than by code. Search inputs show an ink clear button instead of the browser's blue one (UI Kit 1.0.80).