sf-industry-commoncore-flexcard

What this skill does

# sf-industry-commoncore-flexcard: OmniStudio FlexCard Creation and Validation

Expert OmniStudio engineer specializing in FlexCard UI components for Salesforce Industries. Generate production-ready FlexCard definitions that display at-a-glance information with declarative data binding, Integration Procedure data sources, conditional rendering, and proper SLDS styling. All FlexCards are validated against a **130-point scoring rubric** across 7 categories.

## Core Responsibilities

1. **FlexCard Authoring**: Design and build FlexCard definitions with proper layout, states, and field mappings
2. **Data Source Binding**: Configure Integration Procedure data sources with correct field mapping and error handling
3. **Test Generation**: Validate cards against multiple data states (populated, empty, error, multi-record)
4. **Documentation**: Produce deployment-ready documentation with data source lineage and action mappings

## Document Map

| Need | Document | Description |
|------|----------|-------------|
| **Best practices** | [references/best-practices.md](references/best-practices.md) | Layout patterns, SLDS, accessibility, performance |
| **Data binding** | [references/data-binding-guide.md](references/data-binding-guide.md) | IP sources, field mapping, conditional rendering |

---

## CRITICAL: Orchestration Order

FlexCards sit at the presentation layer of the OmniStudio stack. Ensure upstream components exist before building a FlexCard that depends on them.

```
sf-industry-commoncore-omnistudio-analyze → sf-industry-commoncore-datamapper → sf-industry-commoncore-integration-procedure → sf-industry-commoncore-omniscript → sf-industry-commoncore-flexcard (you are here)
```

FlexCards consume data from Integration Procedures and can launch OmniScripts. Build the data layer first, then the presentation layer.

---

## Key Insights

| Insight | Detail |
|---------|--------|
| **Configuration fields** | `OmniUiCard` uses `DataSourceConfig` for data source bindings and `PropertySetConfig` for card layout, states, and actions. There is NO `Definition` field on `OmniUiCard` in Core namespace. |
| **Data source binding** | Data sources bind to Integration Procedures for live data; the IP must be active and deployed before the FlexCard can retrieve data |
| **Child card embedding** | FlexCards can embed other FlexCards as child cards, enabling composite layouts with shared or independent data sources |
| **OmniScript launching** | FlexCards can launch OmniScripts via action buttons, passing context data from the card's data source into the OmniScript's input |
| **Designer virtual object** | The FlexCard Designer uses `OmniFlexCardView` as a virtual list object (`/lightning/o/OmniFlexCardView/home`), separate from the `OmniUiCard` sObject where card records are stored. Cards created via API may not appear in "Recently Viewed" until opened in the Designer. |

---

## Workflow (5-Phase Pattern)

### Phase 1: Requirements Gathering

Before building, clarify these with the stakeholder:

| Question | Why It Matters |
|----------|---------------|
| What is the card's purpose? | Determines layout type and data density |
| Which data sources are needed? | Identifies required Integration Procedures |
| What object context does it run in? | Determines record-level vs. list-level display |
| What actions should the card expose? | Drives button/link configuration and OmniScript integration |
| What layout best fits the use case? | Single card, list, tabbed, or flyout |
| Are there conditional display rules? | Fields or sections that appear/hide based on data values |

### Phase 2: Design & Layout

#### Card Layout Options

| Layout Type | Use Case | Description |
|-------------|----------|-------------|
| **Single Card** | Record summary | One card displaying fields from a single record |
| **Card List** | Related records | Repeating cards bound to an array data source |
| **Tabbed Card** | Multi-context | Multiple states displayed as tabs within one card |
| **Flyout Card** | Detail on demand | Expandable detail panel triggered from a summary card |

#### Data Source Configuration

Each FlexCard data source connects to an Integration Procedure (or other source type) and maps response fields to display elements.

```
FlexCard → Data Source (type: IntegrationProcedure)
         → IP Name + Input Mapping
         → Response Field Mapping → Card Elements
```

- Map IP response fields to card display elements using `{datasource.fieldName}` merge syntax
- Configure input parameters to pass record context (e.g., `{recordId}`) to the IP
- Set data source order when multiple sources feed the same card

#### Action Button Design

| Action Type | Purpose | Configuration |
|-------------|---------|---------------|
| **Launch OmniScript** | Start a guided process | OmniScript Type + SubType, pass context params |
| **Navigate** | Go to record or URL | Record ID or URL template with merge fields |
| **Custom Action** | Platform event, LWC, etc. | Custom action handler with payload mapping |

#### Conditional Visibility

- Show/hide fields based on data values using visibility conditions
- Show/hide entire card states based on data source results
- Display empty-state messaging when data source returns no records

### Phase 3: Generation & Validation

1. Generate the FlexCard definition JSON
2. Validate all data source references resolve to active Integration Procedures
3. Run the 130-point scoring rubric (see Scoring section below)
4. Verify merge field syntax matches IP response structure
5. Check accessibility attributes on all interactive elements

### Phase 4: Deployment

1. Ensure all upstream Integration Procedures are deployed and active
2. Deploy the FlexCard metadata (`OmniUiCard`)
3. Activate the FlexCard in the target org
4. Embed the FlexCard in the target Lightning page, OmniScript, or parent FlexCard

### Phase 5: Testing

Test each FlexCard against multiple data scenarios:

| Scenario | What to Verify |
|----------|---------------|
| **Populated data** | All fields render correctly, merge fields resolve |
| **Empty data** | Empty-state message displays, no broken merge fields |
| **Error state** | Graceful handling when IP returns an error or times out |
| **Multi-record** | Card list renders correct number of items, pagination works |
| **Action buttons** | OmniScript launches with correct pre-populated data |
| **Conditional fields** | Visibility rules toggle correctly based on data values |
| **Mobile** | Card layout adapts to smaller viewport widths |

---

## Generation Guardrails

Avoid these patterns when generating FlexCard definitions:

| Anti-Pattern | Why It's Wrong | Correct Approach |
|--------------|---------------|-----------------|
| Referencing non-existent IP data sources | Card fails to load data at runtime | Verify IP exists and is active before binding |
| Hardcoded colors in styles | Breaks SLDS theming and dark mode | Use SLDS design tokens and CSS custom properties |
| Missing accessibility attributes | Fails WCAG compliance | Add `aria-label`, `role`, and keyboard handlers |
| Excessive nested child cards | Performance degrades with deep nesting | Limit to 2 levels of nesting; flatten where possible |
| Ignoring empty states | Broken UI when data source returns no records | Configure explicit empty-state messaging |
| Hardcoded record IDs | Card breaks across environments | Use merge fields and context-driven parameters |

---

## Scoring Rubric (130 Points)

All FlexCards are validated against 7 categories. **Thresholds**: ✅ 90+ (Deploy) | ⚠️ 67-89 (Review) | ❌ <67 (Block - fix required)

| Category | Points | Criteria |
|----------|--------|----------|
| **Design & Layout** | 25 | Appropriate layout type, logical field grouping, responsive design, consistent spacing, clear visual hierarchy |
| **Data Binding** | 20 | Correct IP references, proper merge field syntax, input parameter mapping, multi-source coordination |
| **Actions & Navi