openbridge-webcomponents ui-components.instructions.md

UI Components Instructions

These instructions apply to all general UI components: buttons, cards, forms/inputs, feedback indicators, navigation, menus/overlays, tables, and utility components.

Architecture

All UI components extend LitElement directly — there are no shared base classes or helper mixins. Each component is fully self-contained with its own variants, enums, events, and styles.

Elevation Variants via @mixin style

Full reference: IMPLEMENTATION_GUIDELINES.md § PostCSS

Most interactive components support elevation variants (flat, normal, raised, amplified, indent, selected). Apply them with the PostCSS mixin:

.wrapper {
  @mixin style style=flat visibleWrapperClass=.visible-wrapper;
  color: var(--on-flat-active-color);
}

.wrapper.variant-raised {
  @mixin style style=raised visibleWrapperClass=.visible-wrapper;
  color: var(--on-raised-active-color);
}

• Always specify visibleWrapperClass — it targets the inner visual element that receives border/background styles
• The outer wrapper is the touch target (transparent); the inner .visible-wrapper is the visual target (styled)
• Use variant-specific color variables: --on-flat-active-color, --on-normal-active-color, --on-raised-active-color, etc.
• Interactive state colors follow --{variant}-{state}-background-color / --{variant}-{state}-border-color (see full convention in IMPLEMENTATION_GUIDELINES.md)
• Use noClick for display-only sub-parts that need colors but no interactivity

Slot Conventions

Pattern	Usage
leading-icon, trailing-icon	Icon positions in buttons and inputs
icon, icon-left, icon-right	Generic icon containers
title, content	Main content areas in cards and modals
dialog-title, dialog-content	Dialog-specific content
cancel-label, done-label, option-label	Action button labels in modals