@salesforce/afv-skills 1.11.0 → 1.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/package.json +1 -1
  2. package/skills/building-mobile-apps/SKILL.md +70 -0
  3. package/skills/implementing-ui-bundle-agentforce-conversation-client/SKILL.md +114 -198
  4. package/skills/implementing-ui-bundle-agentforce-conversation-client/references/agent-id-resolution.md +46 -0
  5. package/skills/implementing-ui-bundle-agentforce-conversation-client/references/style-tokens.md +18 -6
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@salesforce/afv-skills",
3
- "version": "1.11.0",
3
+ "version": "1.13.0",
4
4
  "description": "Salesforce skills for Agentforce Vibes",
5
5
  "license": "CC-BY-NC-4.0",
6
6
  "files": [
package/skills/building-mobile-apps/SKILL.md ADDED
@@ -0,0 +1,70 @@
1
+ ---
2
+ name: building-mobile-apps
3
+ description: "The entry point for building any Salesforce native mobile app on iOS or Android. TRIGGER when the user says: \"build a Salesforce iOS app\", \"add Salesforce login to my Android app\", \"set up Mobile SDK\", \"add MobileSync / SmartStore offline storage\", \"embed an Agentforce agent in my mobile app\", \"add Agentforce chat to iOS/Android\", or otherwise asks to create, extend, or integrate a Salesforce mobile experience in Swift or Kotlin (MSDK, Agentforce SDK, or both). SKIP when the user is building a non-Salesforce mobile app, using React Native / Flutter / Ionic without Salesforce integration, asking about generic mobile UI design, or working on a Salesforce-adjacent web/desktop surface (LWC, Experience Cloud, Mobile Publisher branding-only)."
4
+ license: Apache-2.0
5
+ metadata:
6
+ version: "1.0"
7
+ ---
8
+
9
+ # Salesforce Mobile
10
+
11
+ Route the user to the right SDK-family skill for building Salesforce-connected mobile apps. Do not implement features here; child skills own scenario detection and step-by-step instructions.
12
+
13
+ ## Before routing
14
+
15
+ Disambiguate on two dimensions: **SDK family** (Mobile SDK vs. Agentforce SDK) and **platform** (iOS vs. Android). They are not mutually exclusive — an app can use both SDKs.
16
+
17
+ If the user's intent could plausibly map to either SDK, ask before routing. Guessing wrong wastes the user's time because the child skills are platform- and SDK-specific.
18
+
19
+ ## Routing — which SDK family?
20
+
21
+ | User's situation | SDK |
22
+ |---|---|
23
+ | Authenticating end users to Salesforce, syncing records (MobileSync), storing data offline (SmartStore), biometric login, push notifications, REST integration | **Mobile SDK** |
24
+ | Embedding an Agentforce agent — chat UI, agent conversations, conversational features as the primary surface | **Agentforce SDK** |
25
+ | Both (data-driven app with an embedded agent) | **Mobile SDK first**, then **Agentforce SDK** layered on top |
26
+
27
+ ### Tiebreakers when both seem to apply
28
+
29
+ - Is the agent the *primary surface* (chat-first app), or a *feature inside* an otherwise data-driven app?
30
+ - Primary → Agentforce SDK
31
+ - Feature → Mobile SDK; embed the agent via Agentforce SDK alongside it
32
+ - Are end users authenticating into Salesforce data?
33
+ - Yes → Mobile SDK is required (Agentforce SDK can be added on top).
34
+ - No → Agentforce SDK alone is likely sufficient (it uses guest auth).
35
+ - Asking about offline storage, sync, REST, push, or biometrics? → Mobile SDK.
36
+ - Asking about agent conversations, chat UI, or streaming responses? → Agentforce SDK.
37
+
38
+ When still unclear, ask the user directly.
39
+
40
+ ## Routing — which platform?
41
+
42
+ | Platform | Mobile SDK skill | Agentforce SDK skill |
43
+ |---|---|---|
44
+ | iOS (Swift) | `ios-mobile-sdk` | `integrate-agentforce-ios` |
45
+ | Android (Kotlin) | `android-mobile-sdk` | `integrate-agentforce-android` |
46
+
47
+ If the user wants both platforms, route to each child skill separately — they are independent.
48
+
49
+ ## Combined workflows (Mobile SDK + Agentforce SDK)
50
+
51
+ When an app needs both:
52
+
53
+ 1. Route to the Mobile SDK platform skill first to scaffold and authenticate.
54
+ 2. Route to the Agentforce SDK platform skill to layer the agent surface.
55
+ 3. Treat each child skill's instructions as authoritative for its SDK; do not merge their steps. Each SDK owns its own auth setup, dependency installation order, and initialization sequence — interleaving them produces conflicting config and broken init order.
56
+
57
+ This sequencing is the only multi-skill logic this skill owns. Everything else lives inside the child skills.
58
+
59
+ ## Loading a child skill
60
+
61
+ Invoke the child skill by name through the harness. If it is not available locally, prompt the user to install it with `npx skills add <repo>`. If the user confirms (or has pre-authorized installs), run the command and load the child skill — do not make the user go figure out how to continue the workflow. If the user declines, stop and explain that the child skill owns the SDK's setup steps and the workflow cannot continue without it. Each child skill is published from a public repo:
62
+
63
+ | Skill | Repo | Install command |
64
+ |---|---|---|
65
+ | `ios-mobile-sdk` | [`forcedotcom/SalesforceMobileSDK-Templates`](https://github.com/forcedotcom/SalesforceMobileSDK-Templates) → `skills/ios-mobile-sdk/` | `npx --yes skills add forcedotcom/SalesforceMobileSDK-Templates --skill ios-mobile-sdk --yes` |
66
+ | `android-mobile-sdk` | [`forcedotcom/SalesforceMobileSDK-Templates`](https://github.com/forcedotcom/SalesforceMobileSDK-Templates) → `skills/android-mobile-sdk/` | `npx --yes skills add forcedotcom/SalesforceMobileSDK-Templates --skill android-mobile-sdk --yes` |
67
+ | `integrate-agentforce-ios` | [`salesforce/AgentforceMobileSDK-iOS`](https://github.com/salesforce/AgentforceMobileSDK-iOS) → `skills/integrate-agentforce-ios/` | `npx --yes skills add salesforce/AgentforceMobileSDK-iOS --skill integrate-agentforce-ios --yes` |
68
+ | `integrate-agentforce-android` | [`salesforce/AgentforceMobileSDK-Android`](https://github.com/salesforce/AgentforceMobileSDK-Android) → `skills/integrate-agentforce-android/` | `npx --yes skills add salesforce/AgentforceMobileSDK-Android --skill integrate-agentforce-android --yes` |
69
+
70
+ After install, load the child skill and let it take over. Do not inline the child skill's content — the child skill owns scenario detection, prerequisites, and step-by-step instructions.
package/skills/implementing-ui-bundle-agentforce-conversation-client/SKILL.md CHANGED
@@ -1,12 +1,11 @@
1
1
  ---
2
2
  name: implementing-ui-bundle-agentforce-conversation-client
3
- description: "MUST activate when the project contains a uiBundles/*/src/ directory and the task involves adding or modifying a chat widget, chatbot, or conversational AI. Use this skill when the user asks to add, embed, integrate, configure, style, or remove an agent, chatbot, chat widget, conversation client, or AI assistant. Covers styling (colors, fonts, spacing, borders), layout (inline vs floating, width, height, dimensions), and props (agentId, agentLabel, headerEnabled, showHeaderIcon, showAvatar, styleTokens). Activate when files under uiBundles/*/src/ import AgentforceConversationClient or when adding any chat or agent functionality to a page. Never create a custom agent, chatbot, or chat widget component."
3
+ description: "Use this skill when the user asks to add, embed, integrate, configure, style, or remove an agent, chatbot, chat widget, conversation client, or AI assistant in a UI Bundle project. Covers styling (colors, fonts, spacing, borders), layout (inline vs floating, width, height, dimensions), and props (agentId, agentLabel, headerEnabled, showHeaderIcon, showAvatar, styleTokens). TRIGGER when: project contains a uiBundles/*/src/ directory and the task involves adding or modifying a chat widget, chatbot, or conversational AI; files under uiBundles/*/src/ import AgentforceConversationClient; user asks to add any chat or agent functionality to a page. DO NOT TRIGGER when: user wants to create a custom agent, chatbot, or chat widget component from scratch; the project has no uiBundles directory."
4
4
  metadata:
5
5
  author: ACC Components
6
- version: "1.0"
6
+ version: "1.1"
7
7
  package: "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client"
8
8
  sdk-package: "@salesforce/agentforce-conversation-client"
9
- last-updated: 2025-04-01
10
9
  ---
11
10
 
12
11
  # Managing Agentforce Conversation Client
@@ -17,14 +16,11 @@ metadata:
17
16
 
18
17
  Before the component will work, the following Salesforce settings must be configured by the user. ALWAYS call out the prequisites after successfully embedding the agent.
19
18
 
20
- **Cookie settings:**
21
-
22
- - Setup → My Domain → Disable "Require first party use of Salesforce cookies"
23
-
24
19
  **Trusted domains (required only for local development):**
25
20
 
26
21
  - Setup → Session Settings → Trusted Domains for Inline Frames → Add your domain
27
- - Local development: `localhost:<PORT>` (e.g., `localhost:3000`)
22
+ - Local development: `localhost:5173` (default Vite dev server port)
23
+ - **Warning:** Remove this trusted domain entry before deploying to production.
28
24
 
29
25
  ## Instructions
30
26
 
@@ -38,6 +34,8 @@ grep -r "AgentforceConversationClient" --include="*.tsx" --include="*.jsx" --exc
38
34
 
39
35
  **Important:** Look for React files that import and USE the component (for example, shared shells, route components, or feature pages). Do NOT open files named `AgentforceConversationClient.tsx` or `AgentforceConversationClient.jsx` - those are the component implementation.
40
36
 
37
+ **If multiple files found:** Ask the user which component file they are referring to. Do not proceed until clarified.
38
+
41
39
  **If found:** Read the file and check the current `agentId` value.
42
40
 
43
41
  **Agent ID validation rule (deterministic):**
@@ -48,25 +46,99 @@ grep -r "AgentforceConversationClient" --include="*.tsx" --include="*.jsx" --exc
48
46
  **Decision:**
49
47
 
50
48
  - If `agentId` matches `^0Xx[a-zA-Z0-9]{15}$` and user wants to update other props → Go to Step 4 (update props)
49
+ - If `agentId` matches `^0Xx[a-zA-Z0-9]{15}$` and user asks to "embed" or "add" the chat client → Inform: "The Agentforce Conversation Client is already embedded in `<file>` with agent ID `<agentId>`. Would you like to change the agent or update other props?"
50
+ - Change agent → Step 2
51
+ - Update props → Step 4b
51
52
  - If `agentId` is missing, empty, or does NOT match `^0Xx[a-zA-Z0-9]{15}$` → Continue to Step 2 (need real ID)
52
53
  - If not found → Continue to Step 2 (add new)
53
54
 
54
- ### Step 2: Get agent ID
55
+ **If user reports an error:**
56
+
57
+ If the user says the component is "not working", "showing an error", or similar — ask them for the specific error message. Then proceed to Step 2 to cross-check the configured agentId against the org.
58
+
59
+ ### Step 2: Resolve and Validate Agent ID
60
+
61
+ #### Prerequisites
62
+
63
+ 1. **Verify sf CLI is available:**
64
+ ```bash
65
+ sf --version
66
+ ```
67
+ If fails:
68
+ - Inform: "The Salesforce CLI (`sf`) is not installed. It's needed to query available agents from your org."
69
+ - Ask: "Would you like me to install it?"
70
+ - Yes → Install via `npm install -g @salesforce/cli`, then continue.
71
+ - No → "You can find your agent ID manually in Setup → Agentforce Agents → click the agent name → copy the ID from the URL. Would you like to provide it now, or skip this step?"
72
+ - User provides ID → validate format (`^0Xx[a-zA-Z0-9]{15}$`), store it, proceed to Step 3.
73
+ - Skip → proceed to Step 4 with placeholder `<YOUR_AGENT_ID>`.
74
+
75
+ 2. **Verify org connectivity:**
76
+ ```bash
77
+ sf org display --json
78
+ ```
79
+ If fails:
80
+ - Inform: "No authenticated org found."
81
+ - Ask: "Would you like to connect to your org now? Run `sf org login web` to authenticate."
82
+ - User authenticates → retry the query, continue.
83
+ - User declines → "You can find your agent ID manually in Setup → Agentforce Agents → click the agent name → copy the ID from the URL. Would you like to provide it now, or skip this step?"
84
+ - User provides ID → validate format, store it, proceed to Step 3.
85
+ - Skip → proceed to Step 4 with placeholder `<YOUR_AGENT_ID>`.
86
+
87
+ **Note:** Even if the user provides their own agentId, the org must be connected for the agent to function at runtime. An agentId without a connected org will not work.
88
+
89
+ #### Query all Employee Agents
90
+
91
+ Run the SOQL query defined in `references/agent-id-resolution.md`.
92
+
93
+ #### Handle results
94
+
95
+ **No records at all:**
96
+ > "No Employee Agents found in this org. Create one in Setup → Agentforce Agents."
97
+
98
+ Ask user if they want to provide an agent ID manually or skip. If skip, proceed to Step 4 with placeholder `<YOUR_AGENT_ID>`.
99
+
100
+ **All agents are inactive:**
101
+ > Found Employee Agents but none are active:
102
+ > - Agentforce Sales Agent (0Xxxx000000001dCAA)
103
+ > - HR Assistant (0Xxxx0000000002BBB)
104
+ >
105
+ > To activate: Setup → Agentforce Agents → click the agent name → open in Agent Builder → press Activate.
106
+ > Then re-run this step.
107
+
108
+ Ask user if they want to provide an agent ID manually or skip. If skip, proceed to Step 4 with placeholder `<YOUR_AGENT_ID>`.
109
+
110
+ **Has active agents — Path A (fresh install / no existing agentId):**
111
+
112
+ Present only active agents for selection:
113
+ > Which agent should the chat widget use?
114
+ > 1. Property Manager Agent (0Xxxx0000000001CAA)
115
+ > 2. HR Assistant (0Xxxx0000000002BBB)
55
116
 
56
- If component doesn't exist or has an invalid placeholder value, ask user for their Salesforce agent ID.
117
+ - One agent → still confirm with user, do not auto-select.
118
+ - If user picks one → store the selected `Id` for use in Step 4.
119
+ - If user declines to pick ("skip", "no", "I don't want to set one") → accept it and move to next steps. Do not re-ask. In Step 4, use placeholder `<YOUR_AGENT_ID>` for fresh installs. For existing projects, leave the component as-is.
57
120
 
58
- Treat these as placeholder/invalid values:
121
+ **Has active agents — Path B (existing agentId from Step 1, passed format check):**
59
122
 
60
- - `"0Xx..."`
61
- - `"Placeholder"`
62
- - `"YOUR_AGENT_ID"`
63
- - `"<USER_AGENT_ID_18_CHAR_0Xx...>"`
64
- - Any value that does not match `^0Xx[a-zA-Z0-9]{15}$`
123
+ Cross-check the existing agentId against query results:
65
124
 
66
- Skip this step if:
125
+ - **ID found, agent is Active** → "Agent ID maps to 'Property Manager Agent' — active in the org." Proceed.
126
+ - **ID found, agent is Inactive** → "The configured agent 'Sales Agent' exists but is Inactive. To activate: Setup → Agentforce Agents → click the agent name → open in Agent Builder → press Activate. Or pick a different active agent:" → show active list.
127
+ - **ID not found at all** → "The configured agent (0Xxxx...) doesn't exist in this org — it may have been deleted or belongs to a different org. Pick a replacement:" → show active list. If no active agents available, show inactive list with activation instructions.
67
128
 
68
- - Component exists with a real agent ID
69
- - User only wants to update styling or dimensions
129
+ If user reported an error → surface the agent name even if active, so user can confirm it's the intended one.
130
+
131
+ #### Query error handling
132
+
133
+ If the SOQL query fails, surface the error message from the response directly to the user. Do not guess at the fix — just report what came back. For example:
134
+ > "The query failed with: `[error message from response]`. Check your org permissions or that the API version supports this object."
135
+
136
+ #### What this step does NOT do
137
+
138
+ - No fallback to GraphQL or Tooling API — SOQL only
139
+ - No auto-selection (always confirm with user)
140
+ - No programmatic activation (only via Setup UI)
141
+ - No file writes (that's Step 4)
70
142
 
71
143
  ### Step 3: Canonical import strategy
72
144
 
@@ -103,12 +175,18 @@ Determine which sub-step applies:
103
175
  import { AgentforceConversationClient } from "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client";
104
176
  ```
105
177
 
106
- 4. Insert the `<AgentforceConversationClient />` TSX into the component's return block. Place it as a sibling of existing content — do NOT wrap or restructure existing TSX. Use the real `agentId` obtained in Step 2:
107
- **Example:**
178
+ 4. Insert the `<AgentforceConversationClient />` TSX into the component's return block. Place it as a sibling of existing content — do NOT wrap or restructure existing TSX. Use the real `agentId` obtained in Step 2. If no agentId was resolved (user skipped Step 2), use the placeholder:
179
+
180
+ **With resolved agentId:**
108
181
  ```tsx
109
182
  <AgentforceConversationClient agentId="0Xx8X00000001AbCDE" />
110
183
  ```
111
184
 
185
+ **Without resolved agentId (user skipped):**
186
+ ```tsx
187
+ <AgentforceConversationClient agentId="<YOUR_AGENT_ID>" />
188
+ ```
189
+
112
190
  5. Do NOT add any other code (wrappers, layout components, new functions) unless the user explicitly requests it.
113
191
 
114
192
  #### 4b — Update existing
@@ -120,17 +198,12 @@ import { AgentforceConversationClient } from "@salesforce/ui-bundle-template-fea
120
198
  - **Change** prop values the user asked to update.
121
199
  - **Preserve** every prop and value the user did NOT mention — do not remove, reorder, or reformat them.
122
200
  - **Never** delete the component and recreate it.
123
- 4. If the current `agentId` is a placeholder (failed validation in Step 1) and a real agent ID was obtained in Step 2, replace the placeholder value:
201
+ 4. If Step 2 was triggered (cross-check or fresh selection) and a new agent ID was resolved, replace the existing agentId value with the new one.
202
+ 5. If the current `agentId` is already valid and the user did not ask to change it and Step 2 confirmed it is active, leave it as-is.
124
203
 
125
- ```tsx
126
- // Before
127
- <AgentforceConversationClient agentId="Placeholder" />
204
+ #### Post-Step-4 error handling
128
205
 
129
- // After
130
- <AgentforceConversationClient agentId="0Xx8X00000001AbCDE" />
131
- ```
132
-
133
- 5. If the current `agentId` is already valid and the user did not ask to change it, leave it as-is.
206
+ If the user reports an error after the component has been set up (e.g., "it's not working", "I see an error"), go to Step 2 to validate the configured agentId against the org. Cross-check whether the agent is active, exists, and belongs to the connected org.
134
207
 
135
208
  ### Step 5: Configure props
136
209
 
@@ -173,174 +246,7 @@ Adding or updating agent label:
173
246
  - NEVER apply styling via CSS files, `style` attributes, `className`, or wrapper elements. These approaches will not work and will be ignored by the component.
174
247
  - If the user requests a visual change that does not map to a token below, inform them that the change is not supported by the current token set.
175
248
 
176
- ### Container
177
-
178
- | Token name | UI area themed |
179
- | --------------------- | --------------------------- |
180
- | `fabBackground` | FAB button background color |
181
- | `containerBackground` | Chat container background |
182
- | `headerBackground` | Header background |
183
- | `containerWidth` | Chat container width |
184
- | `chatBorderRadius` | Chat border radius |
185
- | `layoutMaxWidth` | Layout max width |
186
-
187
- ### Agentforce Header
188
-
189
- | Token name | UI area themed |
190
- | ------------------------------- | ---------------------------------- |
191
- | `headerBlockBackground` | Header block background |
192
- | `headerBlockBorderBottomWidth` | Header border bottom width |
193
- | `headerBlockBorderBottomStyle` | Header border bottom style |
194
- | `headerBlockBorderBottomColor` | Header border bottom color |
195
- | `headerBlockBorderRadius` | Header corner radius |
196
- | `headerBlockPaddingBlock` | Header block padding (vertical) |
197
- | `headerBlockPaddingInline` | Header inline padding (horizontal) |
198
- | `headerBlockMinHeight` | Header minimum height |
199
- | `headerBlockBrandingGap` | Header branding area gap |
200
- | `headerBlockFontFamily` | Header font family |
201
- | `headerBlockFontWeight` | Header title font weight |
202
- | `headerBlockFontSize` | Header title font size |
203
- | `headerBlockLineHeight` | Header title line height |
204
- | `headerBlockTextColor` | Header text color |
205
- | `headerBlockIconDisplay` | Header icon display |
206
- | `headerBlockIconMargin` | Header icon margin |
207
- | `headerBlockIconColor` | Header icon color |
208
- | `headerBlockIconWidth` | Header icon width |
209
- | `headerBlockIconHeight` | Header icon height |
210
- | `headerBlockLogoMaxHeight` | Header logo max height |
211
- | `headerBlockLogoMaxWidth` | Header logo max width |
212
- | `headerBlockLogoMinWidth` | Header logo min width |
213
- | `headerBlockButtonHeight` | Header action button height |
214
- | `headerBlockButtonWidth` | Header action button width |
215
- | `headerBlockButtonPadding` | Header action button padding |
216
- | `headerBlockButtonBorderRadius` | Header action button border radius |
217
- | `headerBlockHoverBackground` | Header hover background |
218
- | `headerBlockActiveBackground` | Header active background |
219
- | `headerBlockFocusBorder` | Header focus border |
220
-
221
- ### Agentforce Welcome Block
222
-
223
- | Token name | UI area themed |
224
- | ----------------------------------- | -------------------------------- |
225
- | `welcomeBlockTextContainerWidth` | Welcome text container width |
226
- | `welcomeBlockFontFamily` | Welcome block font family |
227
- | `welcomeBlockFontSize` | Welcome block font size |
228
- | `welcomeBlockFontWeight` | Welcome block font weight |
229
- | `welcomeBlockLineHeight` | Welcome block line height |
230
- | `welcomeBlockLetterSpacing` | Welcome block letter spacing |
231
- | `welcomeBlockTextColor` | Welcome block text color |
232
- | `welcomeBlockPaddingVertical` | Welcome block vertical padding |
233
- | `welcomeBlockPaddingHorizontal` | Welcome block horizontal padding |
234
- | `welcomeBlockTextAnimationDuration` | Welcome text animation duration |
235
-
236
- ### Agentforce Messages
237
-
238
- | Token name | UI area themed |
239
- | -------------------------------- | ------------------------------------------------------- |
240
- | `messageBlockBorderRadius` | Message block border radius |
241
- | `avatarDisplay` | Avatar display property (e.g. `block`, `none`) |
242
- | `hideMessageActions` | Message actions display (e.g. `block`, `none` to hide) |
243
- | `hideCopyAction` | Copy action button display (e.g. `inline-flex`, `none`) |
244
- | `messageBlockPaddingContainer` | Message block container padding |
245
- | `messageBlockFontSize` | Message block font size |
246
- | `messageBlockBackgroundColor` | Message block background (base) |
247
- | `messageBlockInboundBorder` | Inbound message border |
248
- | `messageBlockOutboundBorder` | Outbound message border |
249
- | `messageBlockBodyWidth` | Message block body width |
250
- | `messageBlockPadding` | Message block padding |
251
- | `messageBlockContainerMarginTop` | Message block container top margin |
252
- | `messageBlockLineHeight` | Message block line height |
253
-
254
- ### Avatar visibility (behavioral config)
255
-
256
- Use `renderingConfig.showAvatar` to control whether avatars are rendered in message rows.
257
-
258
- - `showAvatar: true` (default) renders avatars.
259
- - `showAvatar: false` hides avatars by removing them from the DOM.
260
-
261
- ### Inbound message (agent → customer)
262
-
263
- | Token name | UI area themed |
264
- | ----------------------------------------- | --------------------------------- |
265
- | `inboundMessgeTextColor` | Inbound message text color (base) |
266
- | `messageBlockInboundBorderRadius` | Inbound message border radius |
267
- | `messageBlockInboundBackgroundColor` | Inbound message background |
268
- | `messageBlockInboundTextColor` | Inbound message text color |
269
- | `messageBlockInboundWidth` | Inbound message width |
270
- | `messageBlockInboundTextAlign` | Inbound message text alignment |
271
- | `messageBlockInboundHoverBackgroundColor` | Inbound message hover background |
272
-
273
- ### Outbound message (customer → agent)
274
-
275
- | Token name | UI area themed |
276
- | ------------------------------------- | ------------------------------- |
277
- | `messageBlockOutboundBorderRadius` | Outbound message border radius |
278
- | `messageBlockOutboundBackgroundColor` | Outbound message background |
279
- | `messageBlockOutboundTextColor` | Outbound message text color |
280
- | `messageBlockOutboundWidth` | Outbound message width |
281
- | `messageBlockOutboundMarginLeft` | Outbound message left margin |
282
- | `messageBlockOutboundTextAlign` | Outbound message text alignment |
283
-
284
- ### Agentforce Input
285
-
286
- | Token name | UI area themed |
287
- | ------------------------------------------ | ---------------------------------------------- |
288
- | `messageInputPadding` | Message input container padding |
289
- | `messageInputFooterBorderColor` | Message input footer border color |
290
- | `messageInputBorderRadius` | Message input border radius |
291
- | `messageInputBorderTransitionDuration` | Message input border transition duration |
292
- | `messageInputBorderTransitionEasing` | Message input border transition easing |
293
- | `messageInputTextColor` | Message input text color |
294
- | `messageInputTextBackgroundColor` | Message input text background color |
295
- | `messageInputFooterBorderFocusColor` | Message input footer focus border color |
296
- | `messageInputFocusShadow` | Message input focus shadow |
297
- | `messageInputMaxHeight` | Message input max height |
298
- | `messageInputLineHeight` | Message input line height |
299
- | `messageInputTextPadding` | Message input text padding |
300
- | `messageInputFontWeight` | Message input font weight |
301
- | `messageInputFontSize` | Message input font size |
302
- | `messageInputOverflowY` | Message input overflow Y |
303
- | `messageInputScrollbarWidth` | Message input scrollbar width |
304
- | `messageInputScrollbarColor` | Message input scrollbar color |
305
- | `messageInputActionsWidth` | Message input actions width |
306
- | `messageInputActionsPaddingRight` | Message input actions right padding |
307
- | `messageInputFooterPlaceholderText` | Message input placeholder text color |
308
- | `messageInputPlaceholderFontWeight` | Placeholder font weight |
309
- | `messageInputErrorTextColor` | Message input error text color |
310
- | `messageInputActionsGap` | Message input actions gap |
311
- | `messageInputActionsPadding` | Message input actions padding |
312
- | `messageInputActionButtonSize` | Message input action button size |
313
- | `messageInputActionButtonRadius` | Message input action button radius |
314
- | `messageInputFooterSendButton` | Message input send button color |
315
- | `messageInputSendButtonDisabledColor` | Message input send button disabled color |
316
- | `messageInputActionButtonFocusBorder` | Message input action button focus border |
317
- | `messageInputActionButtonActiveIconColor` | Message input action button active icon color |
318
- | `messageInputActionButtonActiveBackground` | Message input action button active background |
319
- | `messageInputSendButtonIconColor` | Message input send button icon color |
320
- | `messageInputFooterSendButtonHoverColor` | Message input send button hover color |
321
- | `messageInputActionButtonHoverShadow` | Message input action button hover shadow |
322
- | `messageInputFilePreviewPadding` | Message input file preview padding |
323
- | `messageInputTextareaMaxHeight` | Message input textarea max height |
324
- | `messageInputTextareaWithImageMaxHeight` | Message input textarea max height (with image) |
325
-
326
- ### Agentforce Error Block
327
-
328
- | Token name | UI area themed |
329
- | ---------------------- | ---------------------------- |
330
- | `errorBlockBackground` | Error block background color |
331
-
332
- Styling with styleTokens:
333
-
334
- ```tsx
335
- <AgentforceConversationClient
336
- agentId="0Xx..."
337
- styleTokens={{
338
- headerBlockBackground: "#0176d3",
339
- headerBlockTextColor: "#ffffff",
340
- messageBlockInboundBackgroundColor: "#4CAF50",
341
- }}
342
- />
343
- ```
249
+ For the complete list of available style tokens, consult `references/style-tokens.md`.
344
250
 
345
251
  **For complex patterns,** consult `references/examples.md` for:
346
252
 
@@ -363,3 +269,13 @@ If component doesn't appear or authentication fails, see `references/troubleshoo
363
269
  - Agent activation and deployment
364
270
  - Localhost trusted domains
365
271
  - Cookie restriction settings
272
+
273
+ ## Reference File Index
274
+
275
+ | File | When to read |
276
+ |------|-------------|
277
+ | `references/agent-id-resolution.md` | Step 2 — SOQL query structure, response format, activation path, manual lookup |
278
+ | `references/style-tokens.md` | Step 5 — Complete style token reference for all UI areas |
279
+ | `references/examples.md` | Step 5 — Layout patterns, sizing, theming combinations, host component examples |
280
+ | `references/constraints.md` | Step 4 — Invalid props, invalid styling approaches, files not to edit |
281
+ | `references/troubleshooting.md` | Post-setup — Agent activation, trusted domains, cookie settings |
package/skills/implementing-ui-bundle-agentforce-conversation-client/references/agent-id-resolution.md ADDED
@@ -0,0 +1,46 @@
1
+ # Agent ID Resolution
2
+
3
+ ## SOQL Query
4
+
5
+ ```bash
6
+ sf data query \
7
+ --query "SELECT BotDefinition.Id, BotDefinition.DeveloperName, BotDefinition.MasterLabel, Status FROM BotVersion WHERE BotDefinition.AgentType = 'AgentforceEmployeeAgent' ORDER BY BotDefinition.CreatedDate ASC" \
8
+ --json
9
+ ```
10
+
11
+ - Queries `BotVersion` (not `BotDefinition`) because only `BotVersion` has the `Status` field (`Active` / `Inactive`)
12
+ - Filters on `AgentType = 'AgentforceEmployeeAgent'` to return only Employee Agents (excludes Service Agents)
13
+
14
+ ## Response Structure
15
+
16
+ ```json
17
+ {
18
+ "status": 0,
19
+ "result": {
20
+ "records": [
21
+ {
22
+ "BotDefinition": {
23
+ "Id": "0Xxxx0000000001CAA",
24
+ "DeveloperName": "Property_Manager_Agent",
25
+ "MasterLabel": "Property Manager Agent"
26
+ },
27
+ "Status": "Active"
28
+ }
29
+ ]
30
+ }
31
+ }
32
+ ```
33
+
34
+ ## Activation Path
35
+
36
+ Agents cannot be activated programmatically:
37
+
38
+ > Setup → Agentforce Agents → click agent name → Agent Builder → Activate
39
+
40
+ ## Manual Lookup (without sf CLI)
41
+
42
+ > Setup → Agentforce Agents → click agent name → copy ID from URL
43
+
44
+ ## Validation
45
+
46
+ `agentId` must match: `^0Xx[a-zA-Z0-9]{15}$`
package/skills/implementing-ui-bundle-agentforce-conversation-client/references/style-tokens.md CHANGED
@@ -19,8 +19,14 @@ For the complete and always up-to-date list of all style tokens, see the tables
19
19
 
20
20
  | Token name | UI area themed |
21
21
  | --------------------- | --------------------------- |
22
- | `fabBackground` | FAB button background color |
23
- | `containerBackground` | Chat container background |
22
+ | `fabBackground` | FAB button background color |
23
+ | `fabForegroundColor` | FAB button text color |
24
+ | `fabFontSize` | FAB button text font size |
25
+ | `fabBorderRadius` | FAB button border radius |
26
+ | `floatingButtonImage` | FAB button custom icon image URL (img tag) |
27
+ | `floatingButtonImageAlt` | FAB button custom icon image alt text |
28
+ | `floatingButtonLabel` | FAB button label text |
29
+ | `containerBackground` | Chat container background |
24
30
  | `headerBackground` | Header background |
25
31
  | `containerWidth` | Chat container width |
26
32
  | `chatBorderRadius` | Chat border radius |
@@ -30,7 +36,9 @@ For the complete and always up-to-date list of all style tokens, see the tables
30
36
 
31
37
  | Token name | UI area themed |
32
38
  | ------------------------------- | ---------------------------------- |
33
- | `headerBlockBackground` | Header block background |
39
+ | `headerBlockBackground` | Header block background |
40
+ | `headerImageUrl` | Header custom icon image URL (img tag) |
41
+ | `headerImageAlt` | Header custom icon image alt text |
34
42
  | `headerBlockBorderBottomWidth` | Header border bottom width |
35
43
  | `headerBlockBorderBottomStyle` | Header border bottom style |
36
44
  | `headerBlockBorderBottomColor` | Header border bottom color |
@@ -80,6 +88,8 @@ For the complete and always up-to-date list of all style tokens, see the tables
80
88
  | Token name | UI area themed |
81
89
  | -------------------------------- | ------------------------------------------------------- |
82
90
  | `messageBlockBorderRadius` | Message block border radius |
91
+ | `agentAvatarUrl` | Agent avatar custom image URL (img tag) |
92
+ | `agentAvatarAltText` | Agent avatar custom image alt text |
83
93
  | `avatarDisplay` | Avatar display property (e.g. `block`, `none`) |
84
94
  | `hideMessageActions` | Message actions display (e.g. `block`, `none` to hide) |
85
95
  | `hideCopyAction` | Copy action button display (e.g. `inline-flex`, `none`) |
@@ -146,7 +156,7 @@ Use `renderingConfig.showAvatar` to control whether avatars are rendered in mess
146
156
  | `messageInputScrollbarColor` | Message input scrollbar color |
147
157
  | `messageInputActionsWidth` | Message input actions width |
148
158
  | `messageInputActionsPaddingRight` | Message input actions right padding |
149
- | `messageInputFooterPlaceholderText` | Message input placeholder text color |
159
+ | `messageInputFooterPlaceholderTextColor` | Message input placeholder text color |
150
160
  | `messageInputPlaceholderFontWeight` | Placeholder font weight |
151
161
  | `messageInputErrorTextColor` | Message input error text color |
152
162
  | `messageInputActionsGap` | Message input actions gap |
@@ -170,13 +180,15 @@ Use `renderingConfig.showAvatar` to control whether avatars are rendered in mess
170
180
  | Token name | UI area themed |
171
181
  | ---------------------- | ---------------------------- |
172
182
  | `errorBlockBackground` | Error block background color |
183
+ | `errorBlockIconColor` | Error block icon color |
173
184
 
174
185
  ## Token Categories
175
186
 
176
187
  Style tokens are organized by UI area:
177
188
 
178
- - **Header** : background, text color, hover, active, focus, border, font family
179
- - **Messages** : colors, padding, margins, border radius, fonts, body width
189
+ - **Container/FAB** : background, border radius, custom icon image (img tag), alt text
190
+ - **Header** : background, text color, hover, active, focus, border, font family, custom icon image (img tag), alt text
191
+ - **Messages** : colors, padding, margins, border radius, fonts, body width, custom agent avatar image (img tag), alt text
180
192
  - **Inbound messages** : background, text color, width, alignment, hover
181
193
  - **Outbound messages** : background, text color, width, alignment, margin
182
194
  - **Input** : colors, borders, fonts, padding, buttons, scrollbar, textarea, actions