@salesforce/afv-skills 1.1.0 → 1.3.0

package/skills/generating-experience-lwr-site/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: generating-experience-lwr-site
+description: Creates, modifies, or manages Salesforce Experience Cloud LWR sites via DigitalExperience metadata. Always trigger when users mention Experience sites, LWR sites, DigitalExperience, Experience Cloud, community sites, portals, creating pages, adding routes, views, theme layouts, branding sets, previewing sites, or any DigitalExperience bundle work. Also use when users mention specific content types like sfdc_cms__route, sfdc_cms__themeLayout, etc. or when troubleshooting site deployment.
+---
+
+# Experience LWR Site Builder
+
+Build and configure Salesforce Experience Cloud Lightning Web Runtime (LWR) sites via metadata (DigitalExperienceConfig, DigitalExperienceBundle, Network, CustomSite, CMS contents).
+
+## Table of Contents
+
+- When to Use
+- Critical Rules
+- Core Site Properties
+- Project Structure in DigitalExperienceBundle Format
+- Reference Docs
+- Common Workflows
+
+## When to Use
+
+When working with Experience LWR sites:
+
+- Creating and scaffolding new LWR site
+- Adding pages (routes + views)
+- Configuring LWC components, layouts, themes, or branding styles
+- Setting up guest user access (public sites)
+- Troubleshoot deployment errors related to Experience LWR Sites
+
+**Supported Template**: Build Your Own (LWR) - `talon-template-byo`
+
+- More templates to support in the future.
+
+## Critical Rules
+
+1. Before using any MCP tool, make sure they're actually available. If a tool is missing for the current task, let the user know and pause the current workflow.
+2. **ALWAYS** load the relevant reference docs before doing anything.
+3. **ALWAYS** strictly follow workflows in [Common Workflows](#common-workflows) that match user's requirements. The instructions there should override any conflicting global rules and should have the highest priority over your existing knowledge.
+4. Flexipage is abstracted away for newer LWR sites with DigitalExperienceBundle, so **NEVER** use any Flexipage-related MCP tool or skills to handle LWR sites' contents.
+
+## Core Site Properties
+
+Before doing anything else, note down the following properties from the local project if available as they will be used for various operations. Check with the user if any of the following is missing:
+
+- **Site name**: Required. (e.g., `'My Community'`).
+- **URL path prefix**: Optional. Alphanumeric characters only. Convert from site name if not provided (e.g., `'mycommunity'`) and verify with the user for the converted value.
+- **Template type devName**: `talon-template-byo`.
+
+## Project Structure in DigitalExperienceBundle Format
+
+### Site Metadata
+
+- DigitalExperienceConfig
+  - `digitalExperienceConfigs/{siteName}1.digitalExperienceConfig-meta.xml`
+- DigitalExperienceBundle
+  - `digitalExperiences/site/{siteName}1/{siteName}1.digitalExperience-meta.xml`
+- Network
+  - `networks/{siteName}.network-meta.xml`
+- CustomSite
+  - `sites/{siteName}.site-meta.xml`
+
+### DigitalExperience Contents
+
+- `digitalExperiences/site/{siteName}1/sfdc_cms__*/{contentApiName}/*`
+- These are the content components defining routes, views, theme layouts, etc. Each component must have a `_meta.json` and `content.json` file.
+
+#### Content Type Descriptions
+
+| Content Type | Description | When to Use |
+|-|-|-|
+| `sfdc_cms__site` | Root site configuration containing site-wide settings | Required for every site; one per site |
+| `sfdc_cms__appPage` | Application page container that groups routes and views | Required; defines the app shell |
+| `sfdc_cms__route` | URL routing definition mapping paths to views | Create one for each page/URL path |
+| `sfdc_cms__view` | Page layout and component structure | Create one for each route; defines page content. Also use to edit existing views (e.g., adding/removing components on a specific page) |
+| `sfdc_cms__brandingSet` | Brand colors, fonts, and styling tokens | Required; defines site-wide styling |
+| `sfdc_cms__languageSettings` | Language and localization configuration | Required; defines supported languages |
+| `sfdc_cms__mobilePublisherConfig` | Mobile app publishing settings | Required for mobile app deployment |
+| `sfdc_cms__theme` | Theme definition referencing layouts and branding | Required; one per site |
+| `sfdc_cms__themeLayout` | Page layout templates used by views | Create layouts for different page structures. Also use to edit existing theme layouts (e.g., updating theme layout, add a component that's persistent across pages) |
+
+**Important:** Creating any new pages require BOTH `sfdc_cms__route` AND `sfdc_cms__view`.
+
+## References
+
+Reference docs within the skill directory. Note that these are **local** and not MCP.
+
+- [bootstrap-template-byo-lwr.md](docs/bootstrap-template-byo-lwr.md) - Site creation, template defaults
+- [configure-content-route.md](docs/configure-content-route.md) - Route creation (custom/object pages)
+- [configure-content-view.md](docs/configure-content-view.md) - View creation/editing (custom/object pages)
+- [configure-content-themeLayout.md](docs/configure-content-themeLayout.md) - Theme layout creation + theme sync
+- [configure-content-brandingSet.md](docs/configure-content-brandingSet.md) - Branding with color patterns/WCAG
+- [handle-component-and-region-ids.md](docs/handle-component-and-region-ids.md) - **UUID generation (CRITICAL)** for component and region ids used in views and themeLayout.
+- [handle-ui-components.md](docs/handle-ui-components.md) - Component discovery, schemas, insertion, configuration
+
+## Common Workflows
+
+- See [References](#references) for detailed capabilities.
+- **Always** follow the steps defined in the workflows sequentially whether the task is small, big, quick, or complex.
+
+### Creating a New Site
+
+**Rules**:
+
+- **NEVER** generate the files manually.
+
+**Steps** (Follow the steps sequentially. Do not skip any step before proceeding):
+
+- [ ] **ALWAYS** read [bootstrap-template-byo-lwr.md](docs/bootstrap-template-byo-lwr.md) within the skill directory. Do not proceed to the next step without loading the file.
+- [ ] Follow the bootstrap doc strictly on site creation
+
+### Creating and Editing Standard or Object Pages
+
+**Steps** (Follow the steps sequentially. Do not skip any step before proceeding):
+
+- [ ] Load [configure-content-route.md](docs/configure-content-route.md)
+- [ ] Load [configure-content-view.md](docs/configure-content-view.md)
+- [ ] Load [handle-component-and-region-ids.md](docs/handle-component-and-region-ids.md)
+- [ ] Follow the instructions of the above docs strictly to accomplish user's goal
+
+### Adding UI Components to Pages
+
+**Steps** (Follow the steps sequentially. Do not skip any step before proceeding):
+
+- [ ] Read and follow [handle-ui-components.md](docs/handle-ui-components.md) to add LWCs to LWR sites.
+- [ ] Load and follow [handle-component-and-region-ids.md](docs/handle-component-and-region-ids.md) to handle id generation
+- [ ] Read and follow [configure-content-themeLayout.md](docs/configure-content-themeLayout.md) if a component has one of the following requirements:
+  - needs to be "sticky" and persistent across pages
+  - is used as a theme layout
+
+### Creating Theme Layouts
+
+**Steps** (Follow the steps sequentially. Do not skip any step before proceeding):
+
+- [ ] Read and follow strictly [configure-content-themeLayout.md](docs/configure-content-themeLayout.md).
+
+### Configuring Branding
+
+**Steps** (Follow the steps sequentially. Do not skip any step before proceeding):
+
+- [ ] Read and follow strictly [configure-content-brandingSet.md](docs/configure-content-brandingSet.md) to configure background colors, foreground colors, button colors, and other branding colors that affect all pages.
+
+### CUD Operations on DigitalExperience Contents
+
+- Users can perform create, update, delete operations on DigitalExperience Contents.
+
+**Steps** (Follow the steps sequentially. Do not skip any step before proceeding):
+
+- [ ] Determine what content types the user wants to modify
+- [ ] Read and follow strictly the reference doc related to the target content types if the doc exists. e.g., if modifying `sfdc_cms__route`, load [configure-content-route.md](docs/configure-content-route.md).
+- [ ] **Always** Read [handle-component-and-region-ids.md](docs/handle-component-and-region-ids.md) if creating or modifying view or theme layout
+- [ ] **Always** Call `execute_metadata_action` to get the schema and examples for that content type **after** loading the corresponding reference docs.
+  - **Call once per content type per user request**: If you're creating/modifying multiple items of the same content type (e.g., creating 3 routes), you only need to call `execute_metadata_action` ONCE for that content type. Reuse the schema and examples for all items of that type within the same user request.
+  - For each unique content type you need to work with, **always** call `execute_metadata_action` using the following:
+
+```json
+{
+  "metadataType": "ExperienceSiteLwr",
+  "actionName": "getSiteContentMetadata",
+  "parameters": {
+    "contentType": "<content type from table above>",
+    "shouldIncludeExamples": true
+  }
+}
+```
+
+### Retrieving Site URLs After Deployment
+
+After successfully deploying the site using `sf project deploy`, use the `execute_metadata_action` MCP tool to get the preview and builder URLs:
+
+```json
+{
+  "metadataType": "ExperienceSiteLwr",
+  "actionName": "getSiteUrls",
+  "parameters": {
+    "siteDevName": "<site developer name>"
+  }
+}
+```
+
+The site developer name can be found in the CustomSite filename (e.g., `sites/MySite.site-meta.xml` → developer name is `MySite`).
+
+If the site is not found, an error message will be returned indicating that the site may not be deployed. Ensure the site has been successfully deployed before calling this action.
+
+### Validation & Deployment
+
+Use `sf` CLI to validate and deploy. Access help docs by attaching `--help`, e.g.:
+
+- `sf project deploy --help`
+- `sf project deploy validate --help`
+
+Note that metadata types are space-delimited.
+
+**Validate**:
+`sf project deploy validate --metadata DigitalExperienceBundle DigitalExperience DigitalExperienceConfig Network CustomSite --target-org ${usernameOrAlias}`
+
+**Deploy**:
+`sf project deploy start --metadata DigitalExperienceBundle DigitalExperience DigitalExperienceConfig Network CustomSite --target-org ${usernameOrAlias}`

package/skills/generating-experience-lwr-site/docs/bootstrap-template-byo-lwr.md

@@ -0,0 +1,224 @@
+# Build Your Own (LWR) Template
+
+**Use when** creating a new site or retrieving default values for site metadata.
+
+## Table of Contents
+
+- Bootstrap Options
+- Default Values Reference
+
+## Bootstrap Options
+
+**IMPORTANT**: First site setup initializes services. Warn user - recommend Option 1 for first site.
+
+Ask user to choose:
+
+1. Create in org, then download metadata
+2. Scaffold locally before deploying
+
+### Option 1: Create in Org
+
+```bash
+sf community create --name "{siteName}" --template-name 'Build Your Own (LWR)' --url-path-prefix "{prefix}"
+```
+
+After creation, retrieve metadata using sf CLI.
+
+### Option 2: Scaffold Locally
+
+```bash
+sf template generate digital-experience site --name "{siteName}" --template-name 'Build Your Own (LWR)' --url-path-prefix "{prefix}"
+```
+
+Generates metadata with defaults: DigitalExperienceConfig, DigitalExperiences, Network, CustomSite, and content (route, view, themeLayout, etc.).
+
+#### Post-Creation Config
+
+After site metadata is generated, use MCP tool `execute_metadata_action` to fetch additional information about the template:
+
+```json
+{
+  "metadataType": "ExperienceSiteLwr",
+  "actionName": "getSiteTemplateMetadata",
+  "parameters": { "templateDevName": "talon-template-byo" }
+}
+```
+
+If result provides `disabledViews`, delete both view and route directories.
+
+**Example**: If `disabledViews` includes "tooManyRequests":
+
+- Delete: `digitalExperiences/site/{siteDevName}/sfdc_cms__view/tooManyRequests/`
+- Delete: `digitalExperiences/site/{siteDevName}/sfdc_cms__route/Too_Many_Requests/`
+
+---
+
+## Default Values Reference
+
+**Note**: CLI generates these. Listed for reference only - use CLI first.
+
+### Metadata Defaults
+
+**DigitalExperienceConfig**:
+
+```yaml
+label: {siteName}
+urlPathPrefix: {siteUrlPathPrefix}
+space: site/{siteName}1
+```
+
+**DigitalExperienceBundle**:
+
+```yaml
+label: {siteName}1
+modules: [sfdc_cms__collection, sfdc_cms__mobilePublisherConfig]
+```
+
+**Network**:
+
+```yaml
+allowInternalUserLogin: false
+allowMembersToFlag: false
+changePasswordTemplate: unfiled$public/CommunityChangePasswordEmailTemplate
+disableReputationRecordConversations: true
+emailSenderAddress: {adminEmailAddress}
+emailSenderName: {siteName}
+embeddedLoginEnabled: false
+enableApexCDNCaching: true
+enableCustomVFErrorPageOverrides: false
+enableDirectMessages: true
+enableExpFriendlyUrlsAsDefault: false
+enableExperienceBundleBasedSnaOverrideEnabled: true
+enableGuestChatter: false
+enableGuestFileAccess: false
+enableGuestMemberVisibility: false
+enableImageOptimizationCDN: true
+enableInvitation: false
+enableKnowledgeable: false
+enableLWRExperienceConnectedApp: true
+enableMemberVisibility: false
+enableNicknameDisplay: true
+enablePrivateMessages: false
+enableReputation: false
+enableShowAllNetworkSettings: false
+enableSiteAsContainer: true
+enableTalkingAboutStats: true
+enableTopicAssignmentRules: true
+enableTopicSuggestions: false
+enableUpDownVote: false
+forgotPasswordTemplate: unfiled$public/CommunityForgotPasswordEmailTemplate
+gatherCustomerSentimentData: false
+headlessForgotPasswordTemplate: unfiled$public/CommunityHeadlessForgotPasswordTemplate
+headlessRegistrationTemplate: unfiled$public/CommunityHeadlessRegistrationTemplate
+networkMemberGroups:
+  - profile: admin
+networkPageOverrides:
+  - changePasswordPageOverrideSetting: Standard
+  - forgotPasswordPageOverrideSetting: Designer
+  - homePageOverrideSetting: Designer
+  - loginPageOverrideSetting: Designer
+  - selfRegProfilePageOverrideSetting: Designer
+newSenderAddress: admin@company.com
+picassoSite: {siteName}1
+selfRegistration: false
+sendWelcomeEmail: true
+site: {siteName}
+siteArchiveStatus: NotArchived
+status: UnderConstruction
+tabs:
+  - defaultTab: home
+  - standardTab: Chatter
+urlPathPrefix: {siteUrlPathPrefix}vforcesite
+welcomeTemplate: unfiled$public/CommunityWelcomeEmailTemplate
+```
+
+**CustomSite**:
+
+```yaml
+active: true
+allowGuestPaymentsApi: false
+allowHomePage: false
+allowStandardAnswersPages: false
+allowStandardIdeasPages: false
+allowStandardLookups: false
+allowStandardPortalPages: true
+allowStandardSearch: false
+authorizationRequiredPage: CommunitiesLogin
+bandwidthExceededPage: BandwidthExceeded
+browserXssProtection: true
+cachePublicVisualforcePagesInProxyServers: true
+clickjackProtectionLevel: SameOriginOnly
+contentSniffingProtection: true
+enableAuraRequests: true
+fileNotFoundPage: FileNotFound
+genericErrorPage: Exception
+inMaintenancePage: InMaintenance
+indexPage: CommunitiesLanding
+masterLabel: {siteName}
+redirectToCustomDomain: false
+referrerPolicyOriginWhenCrossOrigin: true
+selfRegPage: CommunitiesSelfReg
+siteType: ChatterNetwork
+urlPathPrefix: {siteUrlPathPrefix}vforcesite
+```
+
+### Content Defaults
+
+apiNames and other metadata of site contents:
+
+**sfdc_cms__appPage**:
+
+- mainAppPage
+
+**sfdc_cms__brandingSet**:
+
+- Build_Your_Own_LWR
+
+**sfdc_cms__languageSettings**:
+
+- languages
+
+**sfdc_cms__mobilePublisherConfig**:
+
+- mobilePublisherConfig
+
+**sfdc_cms__theme**:
+
+- Build_Your_Own_LWR
+
+**sfdc_cms__route**:
+
+| Route | apiName | routeType | urlPrefix | urlName | viewId | configurationTags |
+|-------|---------|-----------|-----------|---------|--------|-------------------|
+| Home | Home | home | "" | home | home | |
+| Login | Login | login-main | login | login | login | |
+| Register | Register | self-register | SelfRegister | register | register | |
+| Forgot_Password | Forgot_Password | forgot-password | ForgotPassword | forgot-password | forgotPassword | |
+| Check_Password | Check_Password | check-password | CheckPasswordResetEmail | check-password | checkPasswordResetEmail | |
+| Error | Error | error | error | error | error | |
+| Service_Not_Available | Service_Not_Available | service-not-available | service-not-available | service-not-available | serviceNotAvailable | allow-in-static-site |
+| Too_Many_Requests | Too_Many_Requests | too-many-requests | too-many-requests | too-many-requests | tooManyRequests | too-many-requests, allow-in-static-site |
+| News_Detail__c | News_Detail__c | managed-content-sfdc_cms__news | news | news-detail | newsDetail | |
+
+**sfdc_cms__view**:
+
+| View | apiName | viewType | urlName | themeLayoutType |
+|------|---------|----------|---------|-----------------|
+| home | home | home | home | Inner |
+| login | login | login-main | login | Inner |
+| register | register | self-register | register | Inner |
+| forgotPassword | forgotPassword | forgot-password | forgot-password | Inner |
+| checkPasswordResetEmail | checkPasswordResetEmail | check-password | check-password | Inner |
+| error | error | error | error | Inner |
+| serviceNotAvailable | serviceNotAvailable | service-not-available | service-not-available | ServiceNotAvailable |
+| tooManyRequests | tooManyRequests | too-many-requests | too-many-requests | ServiceNotAvailable |
+| newsDetail | newsDetail | managed-content-sfdc_cms__news | news-detail | Inner |
+
+**sfdc_cms__site**:
+
+- {siteName}1
+
+**sfdc_cms__themeLayout**:
+
+- scopedHeaderAndFooter
+- snaThemeLayout

package/skills/generating-experience-lwr-site/docs/configure-content-brandingSet.md

@@ -0,0 +1,131 @@
+# Content Type: sfdc_cms__brandingSet
+
+**Use when** user explicitly requests creating/updating branding set.
+
+## Table of Contents
+
+- Core Principles
+- Generation Guidelines
+- Branding Property Patterns
+
+## Core Principles
+
+1. **Purpose**: Manage site-wide branding properties (colors, fonts, etc.).
+2. **Site Association**: Branding sets are linked to the site configuration.
+
+## Generation Guidelines
+
+### 1. Directory Structure
+
+1. **Location**: `digitalExperiences/site/[SITE_NAME]/sfdc_cms__brandingSet/[BRANDING_SET_NAME]/`
+2. **Required Files**:
+  - `_meta.json` - Metadata file defining the API name and type
+  - `content.json` - Content file defining the configuration and layout
+3. **Naming Convention**: Underscore-separated names (e.g., `Branding_Set`).
+
+### 2. _meta.json Structure
+
+The `_meta.json` file must contain:
+
+```json
+{
+  "apiName": "[BRANDING_SET_NAME]",
+  "type": "sfdc_cms__brandingSet",
+  "path": "brandingSets"
+}
+```
+
+**Rules**:
+
+- `apiName`: Must match the directory name exactly (e.g., `Branding_Set`)
+
+### 3. content.json Structure
+
+The `content.json` file must contain:
+
+```json
+{
+  "type": "sfdc_cms__brandingSet",
+  "title": "[DISPLAY_TITLE]",
+  "contentBody": {},
+  "urlName": "[URL_NAME]"
+}
+```
+
+**Field Definitions**:
+
+- `type`: **Required**. Represents the content type. The only supported value is `"sfdc_cms__brandingSet"`.
+- `title`: **Required**. Human-readable display title (e.g., Branding Set).
+  - Maximum length is **100 characters**.
+  - Must be **unique** within the space's brandingSet content items.
+- `contentBody`: Include all `required` properties from `schemaDefinition`. Use `examplesOfContentType` for reference.
+  - `brandingSetType`: Represents whether the color palette is for the entire site or a specific section.
+    - `APP`: The branding set applies to the entire site. There can be only one branding set of this type.
+    - `SCOPED`: A `SCOPED` branding set can be applied only to a section component for granular overrides.
+  - `definitionName`: **Required**. Represents the name for the branding set used in the site or template’s theme.
+    - **Build Your Own (LWR)**: uses `talon-template-byo:branding`
+    - **Microsite**: uses `microsite-template-marketing:branding`
+  - `values`: **Required**. Represents a map (object) of branding values (colors, fonts, etc.) that can be applied to a site.
+    - **Format**: An object containing key-value pairs that represent branding-set values.
+    - **Patterns**: See the "Branding Property Patterns" section for details on value relationships.
+- `urlName`: Lowercase with hyphens (e.g., `branding-set`)
+
+**Rules**:
+
+- Before any actions, *always* call `execute_metadata_action` to get the full schema and examples per the skill document.
+
+### 4. Naming Conventions Summary
+
+| Field | Format | Example |
+|-------|--------|--------|
+| Directory/apiName | Underscore-separated | `Branding_Set` |
+| title | Human-readable | `Branding Set` |
+| urlName | Lowercase-hyphens | `build-your-own-lwr` |
+
+### 5. Generation Checklist
+
+- [ ] Directory and `_meta.json` follow naming conventions (1, 2)
+- [ ] `content.json` has all required fields (3)
+- [ ] `contentBody` follows the schema provided by `execute_metadata_action`
+
+## Branding Property Patterns
+
+When generating or validating `contentBody.values`, follow these established patterns for consistency:
+
+### 1. Color Scaling Patterns (The "Rule of 3")
+
+Salesforce uses a numeric suffix system (`Color`, `Color1`, `Color2`, `Color3`) to create a tonal palette.
+
+- **Darkening Trend**: As the suffix number increases, the color becomes progressively darker.
+  - Example: `BackgroundColor` (#ffffff) → `_BackgroundColor1` (#ebebeb) → `_BackgroundColor2` (#c2c2c2) → `_BackgroundColor3` (#858585).
+- **Contrast/Foreground Colors**: Every base color has a corresponding `ForegroundColor` to ensure accessibility.
+  - **WCAG Compliance**: Ensure a color contrast ratio of at least **4.5:1** between the background and foreground colors for standard text.
+  - Dark base colors usually have white (#ffffff) foregrounds.
+  - Light base colors (like `_NeutralColor`) usually have black (#000000) foregrounds.
+
+### 2. Font Size Hierarchy
+
+- **Base vs. Small**: The `Small` variant is typically **75%** of the base size.
+  - Example: `BodyFontSize` (1rem) → `BodySmallFontSize` (0.75rem).
+- **Heading Scale**: Headings follow a standard typographic scale:
+  - `HeadingExtraLarge`: 2.5rem
+  - `HeadingLarge`: 1.75rem (~70% of XL)
+  - `HeadingMedium`: 1.25rem (~50% of XL)
+  - `HeadingSmall`: 1.125rem
+
+### 3. Design Token Mapping
+
+Prefer using **DXP Design Tokens** over hardcoded values where possible:
+
+- **Fonts**: Use `var(--dxp-s-html-font-family)` for base, body, and button fonts.
+- **Brand Alignment**: Use `var(--dxp-g-brand)` for primary brand colors and links.
+
+### 4. Component Consistency
+
+- **Buttons**: Maintain consistent `BorderRadius` (e.g., 4px) across all button sizes (Small, Medium, Large).
+- **Form Elements**: `FormElementLabelFontSize` and `FormElementTextFontSize` should match.
+
+### 5. Spacing and Ratios
+
+- **Device Ratios**: Desktop spacing (padding/spacers) is typically **1.33x** larger than mobile spacing.
+  - Example: `ColumnSpacerSizeDesktop` (1rem) vs `ColumnSpacerSizeMobile` (0.75rem).