Sf Lwc

Salesforce Lightning Web Components

Expert frontend engineer specializing in Lightning Web Components for Salesforce. Generate production-ready LWC components using the PICKLES Framework for architecture, with proper data binding, Apex/GraphQL integration, event handling, SLDS 2 styling, and comprehensive Jest tests. Deploy components directly via Salesforce MCP server for seamless org integration.

Dispatch

Parse $ARGUMENTS to determine which workflow to run:

When the operation is missing or unclear, you MUST use AskUserQuestion before proceeding:

AskUserQuestion(question="What would you like to do?\n\n1. **Create** — scaffold a new Lightning Web Component\n2. **Update** — fetch, modify, validate, and redeploy\n3. **Validate** — score an existing LWC")

Do NOT guess the operation or default to one. Wait for the user's answer.

Execution modes

This skill supports four execution modes — see references/execution-modes.md for detection logic and full details, and references/mcp-pagination.md for handling large MCP responses.

All LWC operations go through MCP tools regardless of mode. The mode determines whether local tooling (filesystem, Jest, code execution) is available for post-processing and how large query results are retrieved.

Source encoding rules (read this before any deploy/update)

Salesforce uses two different APIs for LWC source code, and they expect different encodings. Mixing them up produces errors like XML parse error: Content is not allowed in prolog.: Source or Compilation failures.

When falling back from metadata_update to per-file Tooling API edits (see Tooling API fallback), do not re-encode. The Source you read with tooling_api_query is the same plain text you write back with tooling_api_dml.

Create LWC Workflow

Create a new Lightning Web Component following PICKLES architecture and Spring '26 best practices.

1. Gather requirements

Use AskUserQuestion to collect:

• Component purpose: one sentence description
• Target placement: App Page, Record Page, Home Page, or Flow Screen
• Data source: Lightning Data Service (LDS), Apex @wire, GraphQL, or none
• Target object(s) (if data-driven): which Salesforce objects
• Special requirements: dark mode, accessibility, LMS events, TypeScript, Agentforce discoverability, etc.

2. Check for existing component

Before generating, confirm nothing already exists with that name.

tooling_api_query(
  sObject="LightningComponentBundle",
  whereClause="DeveloperName = '<ComponentName>'",
  fields=["DeveloperName", "ApiVersion"]
)

If it already exists, suggest update <ComponentName> instead.

3. Generate the bundle

Apply the PICKLES framework from the sf-lwc skill. Generate all four files:

<componentName>.html

• SLDS 2 markup with lightning-* base components
• No hardcoded colors — use CSS styling hooks (--slds-g-* variables)
• Accessibility: ARIA labels/roles, keyboard navigation, lwc:if instead of ternary

<componentName>.js

• @wire decorators for data fetching (LDS or Apex)
• @api for parent→child props, CustomEvent for child→parent
• Error state handling for wire adapters
• No @track on primitives (unnecessary in modern LWC)

<componentName>.css

• CSS styling hooks only — no hardcoded hex or RGB values
• Dark mode ready via --slds-g-* variable fallbacks

<componentName>.js-meta.xml

• Correct targets for the intended placement
• targetConfigs with typed properties where applicable
• isExposed: true for App Builder drag-and-drop

4. Validate before deploying

Write each file to a temp directory and validate:

# Locate the validator
VALIDATOR=$(find ~/.claude/plugins -name "validate_slds.py" 2>/dev/null | grep sf-lwc | head -1)
# Or if CLAUDE_PLUGIN_ROOT is set:
# VALIDATOR="${CLAUDE_PLUGIN_ROOT}/skills/sf-lwc/scripts/validate_slds.py"

python3 "$VALIDATOR" "/tmp/<componentName>/<componentName>.html"
python3 "$VALIDATOR" "/tmp/<componentName>/<componentName>.css"
python3 "$VALIDATOR" "/tmp/<componentName>/<componentName>.js"

Fix any CRITICAL issues before proceeding. Advisory warnings can be noted in the report.

5. Deploy

metadata_create(
  type="LightningComponentBundle",
  metadata=[{
    "fullName": "<componentName>",
    "apiVersion": "66.0",
    "isExposed": true,
    "masterLabel": "<Component Label>",
    "lwcResources": {
      "lwcResource": [
        {"filePath": "lwc/<componentName>/<componentName>.js", "source": "<Base64-encoded JS>"},
        {"filePath": "lwc/<componentName>/<componentName>.html", "source": "<Base64-encoded HTML>"},
        {"filePath": "lwc/<componentName>/<componentName>.css", "source": "<Base64-encoded CSS>"}
      ]
    }
  }]
)

If metadata_create is unavailable and you fall back to per-resource Tooling inserts, create order matters: the JS module is the bundle's base file and must be POSTed first (bundle record → JS → HTML → CSS), otherwise the insert fails with No base file for markup://c:<name>. Full recipe: "Creating a bundle via Tooling API — create order matters" in the Update workflow below.

6. Report

Show the per-file validation scores and deployment status. If the component exposes lightning__agentforce capability, remind the user to add an agent action in Setup to make it discoverable.

Update LWC Workflow

Fetch, modify, validate, and redeploy an existing Lightning Web Component.

Parsing the request

The argument should be a component name followed by the requested changes: update accountDashboard add a search filter or update contactCard fix dark mode colors.

If no name is given, ask the user which component to update and what changes are needed.

1. Fetch the current bundle

metadata_read(
  type="LightningComponentBundle",
  fullNames=["c/<ComponentName>"]
)

If not found, suggest create <ComponentName> instead.

2. Read and understand

Review the existing files before making any changes. Understand:

• What the component currently does
• Existing SLDS classes, CSS variables, and styling patterns in use
• Wire adapters and data flow
• Event handling and component communication patterns
• What the requested change affects

3. Apply changes

Modify the relevant file(s) following sf-lwc skill guidelines:

• Preserve existing SLDS classes and wire patterns (update where relevant)
• Maintain accessibility attributes
• Do not introduce hardcoded colors — keep CSS hooks
• If changing targets in meta.xml, verify all existing placements remain valid

4. Validate before deploying

Write the modified file(s) to a temp directory and validate:

# Locate the validator
VALIDATOR=$(find ~/.claude/plugins -name "validate_slds.py" 2>/dev/null | grep sf-lwc | head -1)

# Validate each modified file (skip unchanged ones)
python3 "$VALIDATOR" "/tmp/<ComponentName>/<componentName>.html"
python3 "$VALIDATOR" "/tmp/<ComponentName>/<componentName>.css"
python3 "$VALIDATOR" "/tmp/<ComponentName>/<componentName>.js"

Fix any CRITICAL issues before proceeding.

5. Deploy

metadata_update(
  type="LightningComponentBundle",
  metadata=[{
    "fullName": "<ComponentName>",
    "apiVersion": "66.0",
    "isExposed": true,
    "masterLabel": "<Component Label>",
    "lwcResources": {
      "lwcResource": [
        {"filePath": "lwc/<ComponentName>/<ComponentName>.js", "source": "<Base64-encoded JS>"},
        {"filePath": "lwc/<ComponentName>/<ComponentName>.html", "source": "<Base64-encoded HTML>"},
        {"filePath": "lwc/<ComponentName>/<ComponentName>.css", "source": "<Base64-encoded CSS>"}
      ]
    }
  }]
)

If metadata_update reports a partial failure (e.g. had partial failures: All 1 operations failed), do NOT retry the bundle-level call with the same payload. Switch to the Tooling API fallback and update one resource at a time with plain-text Source. Re-running metadata_update with the same content will reproduce the same failure.

6. Report

Summarise the changes made and show the final validation scores per file.

Tooling API fallback — per-file edits

If metadata_update returns a partial failure or the bundle-level call is rejected (e.g. the targetConfigs validates differently against the org), you can update a single resource at a time via the Tooling API. The Source field on this path is plain text — do NOT Base64-encode it.

1. Resolve the bundle id and resource ids

tooling_api_query(
  sObject="LightningComponentBundle",
  fields=["Id", "DeveloperName"],
  whereClause="DeveloperName = '<ComponentName>'"
)

tooling_api_query(
  sObject="LightningComponentResource",
  fields=["Id", "FilePath", "Format", "Source"],
  whereClause="LightningComponentBundleId = '<bundleId>'"
)

FilePath is on LightningComponentResource, NOT on LightningComponentBundle — querying the latter for FilePath will fail with No such column 'FilePath' on entity 'LightningComponentBundle'.

2. Update one resource at a time

tooling_api_dml(
  operation="update",
  sObject="LightningComponentResource",
  record={
    "Id": "<resourceId>",
    "Source": "<plain-text source — NOT Base64>"
  }
)

Common mistakes that produce Salesforce errors on this path:

*.js-meta.xml is also a LightningComponentResource and is updated the same way (plain text). Use it to change bundle-level properties (apiVersion, isExposed, targets, targetConfigs) when metadata_update is unavailable.

Creating a bundle via Tooling API — create order matters

When creating a component through per-resource Tooling inserts (rather than a single metadata_create call), the JS module is the bundle's base file and must be POSTed first — inserting the HTML first fails with No base file for markup://c:<name>. Create in this order:

1. LightningComponentBundle (the bundle record; its Metadata.targetConfigs is Base64 of the inner <targetConfig> XML — the one Base64 exception on the Tooling path)
2. JS resource (base file)
3. HTML resource
4. CSS resource

Resource Source values themselves remain plain text, per the encoding rules above.

3. Validate *.js-meta.xml content before writing

The js-meta.xml is XML that Salesforce validates strictly against the org's metadata. Common rejection causes:

Before sending the updated js-meta.xml:

• Do not invent userPermissions. If you need to gate visibility, use tooling_api_query on PermissionSet describes (or soql_query on PermissionSetTabSetting / known standard permissions) to confirm the name is real before referencing it. Standard SF user permissions (ViewSetup, ManageUsers, etc.) are safe; custom/named ones are not.
• Each <targetConfig targets="X"> must reference a target that's also present in the bundle's <targets> block.
• API version on <apiVersion> must be one the org supports — query an existing component if unsure.

4. Listing many LWC components in large orgs

metadata_list(type="LightningComponentBundle") returns one record per component plus per-file properties and can exceed the per-call response cap in orgs with many LWCs (the response then gets paginated to a 3-record preview). For enumeration, prefer the lightweight Tooling API list:

tooling_api_query(
  sObject="LightningComponentBundle",
  fields=["Id", "DeveloperName", "NamespacePrefix", "ApiVersion", "MasterLabel", "Description"],
  whereClause="NamespacePrefix = null"
)

This returns just the bundle metadata (no embedded sources), is small, and uses the same plain-text path as the per-file edits above.

Validate LWC Workflow

Validate one or more Lightning Web Components using the SLDS 2 static analysis pipeline and return a scored report.

Parsing the request

Validation script

# $CLAUDE_PLUGIN_ROOT is set by Claude Code. Other hosts: see references/execution-modes.md.
# If not set, find the script:
VALIDATOR=$(find ~/.claude/plugins -name "validate_slds.py" 2>/dev/null | grep sf-lwc | head -1)

Local file

python3 "$VALIDATOR" "<file_path>"

Component name (fetch from org)

1. Fetch the component bundle:

metadata_read(
  type="LightningComponentBundle",
  fullNames=["c/<ComponentName>"]
)

If not found, tell the user the component was not found in the org.

2. Write the bundle files to a temp directory:

Write /tmp/validate_<ComponentName>/<componentName>.html
Write /tmp/validate_<ComponentName>/<componentName>.css
Write /tmp/validate_<ComponentName>/<componentName>.js

3. Validate each file:

python3 "$VALIDATOR" "/tmp/validate_<ComponentName>/<componentName>.html"
python3 "$VALIDATOR" "/tmp/validate_<ComponentName>/<componentName>.css"
python3 "$VALIDATOR" "/tmp/validate_<ComponentName>/<componentName>.js"

4. Delete the temp directory after validation.

5. Aggregate scores: sum the per-file scores and show a combined report with per-category breakdown.

Comma-separated list

Fetch all bundles in individual metadata_read calls (LightningComponentBundle doesn't support bulk reads reliably):

metadata_read(type="LightningComponentBundle", fullNames=["c/<Name1>"])
metadata_read(type="LightningComponentBundle", fullNames=["c/<Name2>"])

Validate each bundle (write → validate → delete). After all are validated, show a summary table sorted by score ascending (worst first):

All

1. List all deployed components. Prefer the lightweight Tooling API query — metadata_list exceeds the per-call response cap in larger orgs and returns only a paginated preview:

tooling_api_query(
  sObject="LightningComponentBundle",
  fields=["Id", "DeveloperName", "MasterLabel", "ApiVersion"],
  whereClause="NamespacePrefix = null"
)

2. Fetch and validate each component bundle in batches of 10.

Backoff strategy: If a batch read fails, fall back to individual reads for that batch.

3. Validate each bundle (write → validate → delete).
4. Show the summary table sorted by combined score ascending.
5. Highlight any components averaging below 100/165 (61%) as requiring attention.

Core Responsibilities

1. Component Scaffolding: Generate complete LWC bundles (JS, HTML, CSS, meta.xml)
2. PICKLES Architecture: Apply structured design methodology for robust components
3. Wire Service Patterns: Implement @wire decorators for data fetching (Apex & GraphQL)
4. Apex/GraphQL Integration: Connect LWC to backend with @AuraEnabled and GraphQL
5. Event Handling: Component communication (CustomEvent, LMS, pubsub)
6. Lifecycle Management: Proper use of connectedCallback, renderedCallback, etc.
7. Jest Testing: Generate comprehensive unit tests with advanced patterns
8. Accessibility: WCAG compliance with ARIA attributes, focus management
9. Dark Mode: SLDS 2 compliant styling with global styling hooks
10. Performance: Lazy loading, virtual scrolling, debouncing, efficient rendering
11. the Salesforce MCP server Deployment: Deploy via metadata_create with validation

Salesforce MCP Integration

Workflow

Deployment Process

1. Generate LWC bundle files (JS, HTML, CSS, meta.xml)
   ↓
2. User reviews generated code (PICKLES + SLDS 2 validation)
   ↓
3. Call org_init() to authenticate with target org
   ↓
4. Call metadata_create with:
   - type: "LightningComponentBundle"
   - metadata: [{ fullName: "c/componentName", ...bundle files }]
   ↓
5. Component deployed to org
   ↓
6. Validation: tooling_api_query to verify LightningComponentBundle metadata

MCP Tools Mapping

Required Initialization

ALWAYS start with:

org_init()

Call with no parameters — uses the default org. If a default is configured, confirm with the user before proceeding. If no default is configured, ask for the Salesforce user/alias. (org_init is a convention — see the Tool-name mapping in references/execution-modes.md.)

Fast Path (Simple Requests)

For simple, self-contained components (static display, single-field input, basic wrapper, quick prototype), bypass the full PICKLES design methodology and 165-point scoring while still performing initialization and mandatory checks, then generate + deploy:

1. Call org_init() (always required)
2. Generate the LWC bundle (JS, HTML, CSS, meta.xml)
3. Run basic checks (accessibility attributes, no hardcoded colors)
4. Deploy via metadata_create
5. Verify deployment

Use the fast path when: the request is explicit, the component is self-contained with no complex data binding, and there are no ambiguous requirements.

Use the full PICKLES workflow when: the component involves Apex/GraphQL integration, complex state management, cross-component communication, or underspecified requirements.

PICKLES Framework (Architecture Methodology)

The PICKLES Framework provides a structured approach to designing robust Lightning Web Components. Apply each principle during component design and implementation.

┌─────────────────────────────────────────────────────────────────────┐
│                     🥒 PICKLES FRAMEWORK                            │
├─────────────────────────────────────────────────────────────────────┤
│  P → Prototype    │  Validate ideas with wireframes & mock data    │
│  I → Integrate    │  Choose data source (LDS, Apex, GraphQL, API)  │
│  C → Composition  │  Structure component hierarchy & communication │
│  K → Kinetics     │  Handle user interactions & event flow         │
│  L → Libraries    │  Leverage platform APIs & base components      │
│  E → Execution    │  Optimize performance & lifecycle hooks        │
│  S → Security     │  Enforce permissions, FLS, and data protection │
└─────────────────────────────────────────────────────────────────────┘

Quick Reference

For detailed PICKLES implementation patterns, see references/component-patterns.md

Key Component Patterns

Wire vs Imperative Apex Calls

Quick Decision: Use @wire for read-only display with auto-refresh. Use imperative for user actions, DML, or when you need control over timing.

For complete comparison with code examples and decision tree, see references/component-patterns.md

Data Source Decision Tree

Communication Patterns

Communication Pattern Quick Reference

┌─────────────────────────────────────────────────────────────────────┐
│              LWC COMMUNICATION - MADE SIMPLE                        │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Parent → Child     │  [Parent] ─────→ [Child]   │  @api properties │
│                                                                     │
│  Child → Parent     │  [Child] ─────→ [Parent]   │  Custom Events   │
│                                                                     │
│  Sibling Components │  [A] → [Parent] → [B]      │  Events + @api   │
│                                                                     │
│  Unrelated          │  [Comp 1] ←─LMS─→ [Comp 2] │  Message Service │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Decision Tree:

• Same parent? → Use parent as middleware (events up, @api down)
• Different DOM trees? → Use Lightning Message Service
• LWC ↔ Aura/VF? → Use Lightning Message Service

For complete sibling communication code example, see references/component-patterns.md

Lifecycle Hook Guidance

For complete code examples (Wire Service, GraphQL, Modal, Navigation, TypeScript), see:

• references/component-patterns.md - Comprehensive patterns with full source code
• references/lms-guide.md - Lightning Message Service deep dive

SLDS 2 Validation (165-Point Scoring)

The sf-lwc skill includes automated SLDS 2 validation that ensures dark mode compatibility, accessibility, and modern styling.

Scoring Thresholds:

✅ 150-165 pts → Production-ready, full SLDS 2 + Dark Mode
⚠️ 100-149 pts → Good component, minor styling issues to address
❌  <100 pts   → Needs significant SLDS 2 cleanup before deploy

Exemption for trivial components: Simple display components, wrappers, and prototypes are exempt from the <100 block threshold. Score them for informational purposes but do not block deployment. Basic accessibility and dark mode checks still apply regardless of complexity.

CLI usage: validate_slds.py validates a single file (not a directory):

python scripts/validate_slds.py path/to/component.html    # Human-readable report
python scripts/validate_slds.py path/to/component.css      # CSS validation
python scripts/validate_slds.py path/to/component.js       # JS validation
python scripts/validate_slds.py path/to/component.html --json  # JSON output

Note: The local SLDS validator catches styling and pattern issues but cannot detect server-side compile errors (e.g. invalid component references like lightning-formatted-phone-number or inaccessible schema imports). Always verify deployment succeeds after local validation passes.

Dark Mode Readiness

Dark mode is exclusive to SLDS 2 themes. Components must use global styling hooks to support light/dark theme switching.

Dark Mode Checklist

• No hardcoded hex colors (#FFFFFF, #333333)
• No hardcoded RGB/RGBA values
• All colors use CSS variables (var(--slds-g-color-*))
• Fallback values provided for SLDS 1 compatibility
• No inline color styles in HTML templates
• Icons use SLDS utility icons (auto-adjust for dark mode)

Global Styling Hooks (Common)

Example Migration:

/* SLDS 1 (Deprecated) */
.my-card {
  background-color: #ffffff;
  color: #333333;
}

/* SLDS 2 (Dark Mode Ready) */
.my-card {
  background-color: var(--slds-g-color-surface-container-1, #ffffff);
  color: var(--slds-g-color-on-surface, #181818);
}

For complete styling hooks reference and migration guide, see references/performance-guide.md

Jest Testing

Advanced testing patterns ensure robust, maintainable components. Tests are generated alongside component code.

Essential Patterns

// Render cycle helper
const runRenderingLifecycle = async (reasons = ['render']) => {
  while (reasons.length > 0) {
    await Promise.resolve(reasons.pop());
  }
};

// DOM cleanup
afterEach(() => {
  while (document.body.firstChild) {
    document.body.removeChild(document.body.firstChild);
  }
  jest.clearAllMocks();
});

// Proxy unboxing (LWS compatibility)
const unboxedData = JSON.parse(JSON.stringify(component.data));
expect(unboxedData).toEqual(expectedData);

Test Template Structure

import { createElement } from 'lwc';
import MyComponent from 'c/myComponent';
import getData from '@salesforce/apex/MyController.getData';

jest.mock(
  '@salesforce/apex/MyController.getData',
  () => ({
    default: jest.fn(),
  }),
  { virtual: true }
);

describe('c-my-component', () => {
  afterEach(() => {
    /* DOM cleanup */
  });

  it('displays data when loaded successfully', async () => {
    getData.mockResolvedValue(MOCK_DATA);
    const element = createElement('c-my-component', { is: MyComponent });
    document.body.appendChild(element);
    await runRenderingLifecycle();
    // Assertions...
  });
});

For complete testing patterns (ResizeObserver polyfill, advanced mocks, event testing), see references/jest-testing.md

Local Test Execution

# All tests
npm run test

# Specific component
npm run test -- accountList

# With coverage
npm run test:coverage

Accessibility

WCAG compliance is mandatory for all components.

Quick Checklist

<!-- Accessible dynamic content -->
<div aria-live="polite" class="slds-assistive-text">{statusMessage}</div>

For comprehensive accessibility guide (focus management, ARIA patterns, screen reader testing), see references/accessibility-guide.md

Metadata Configuration

meta.xml Targets

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>66.0</apiVersion>
    <isExposed>true</isExposed>
    <masterLabel>Account Dashboard</masterLabel>
    <description>SLDS 2 compliant account dashboard with dark mode support</description>
    <targets>
        <target>lightning__RecordPage</target>
        <target>lightning__AppPage</target>
        <target>lightning__HomePage</target>
        <target>lightning__FlowScreen</target>
        <target>lightningCommunity__Page</target>
        <target>lightning__Dashboard</target> <!-- Spring '26 Beta -->
    </targets>
    <targetConfigs>
        <targetConfig targets="lightning__RecordPage">
            <objects>
                <object>Account</object>
            </objects>
            <property name="title" type="String" default="Dashboard"/>
            <property name="maxRecords" type="Integer" default="10"/>
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>

Deployment via MCP

Step 1: Initialize & Generate

FIRST: Call org_init:

Use: org_init()

If you need to override the default connection, pass your MCP server's org/user connection parameters explicitly.

Then generate the LWC bundle:

User: "Generate an accountDashboard LWC component for displaying account metrics"

Agent:
1. Generates accountDashboard.js (with @wire, event handling)
2. Generates accountDashboard.html (SLDS 2 structure)
3. Generates accountDashboard.css (dark mode variables)
4. Generates accountDashboard.meta.xml (targets and config)
5. Generates accountDashboard.test.js (Jest tests)
6. Validates against PICKLES framework (165-point score: ~155 pts)
7. Shows code preview to user

Step 2: Deploy via metadata_create

The metadata_create call requires a flat metadata structure with Base64-encoded sources in lwcResources:

metadata_create(
  type="LightningComponentBundle",
  metadata=[{
    "fullName": "accountDashboard",
    "apiVersion": "66.0",
    "isExposed": true,
    "masterLabel": "Account Dashboard",
    "description": "SLDS 2 compliant account metrics dashboard",
    "lwcResources": {
      "lwcResource": [
        {
          "filePath": "lwc/accountDashboard/accountDashboard.js",
          "source": "<Base64-encoded JS source>"
        },
        {
          "filePath": "lwc/accountDashboard/accountDashboard.html",
          "source": "<Base64-encoded HTML source>"
        },
        {
          "filePath": "lwc/accountDashboard/accountDashboard.css",
          

…(truncated)