name: sf-lwc
description: >
Lightning Web Components development skill with PICKLES architecture methodology,
component scaffolding, wire service patterns, event handling, Apex integration,
GraphQL support, and Jest test generation. Build modern Salesforce UIs with
proper reactivity, accessibility, dark mode compatibility, and performance patterns.
license: MIT
metadata:
version: "2.1.0"
author: "Jag Valaiyapathy"
scoring: "165 points across 8 categories (SLDS 2 + Dark Mode compliant)"
hooks:
PreToolUse:
- matcher: Bash
hooks:
- type: command
command: "python3 ${SHARED_HOOKS}/scripts/guardrails.py"
timeout: 5000
PostToolUse:
- matcher: "Write|Edit"
hooks:
- type: command
command: "python3 ${SKILL_HOOKS}/post-tool-validate.py"
timeout: 120000
- type: command
command: "python3 ${SHARED_HOOKS}/suggest-related-skills.py sf-lwc"
timeout: 5000
SubagentStop:
- type: command
command: "python3 ${SHARED_HOOKS}/scripts/chain-validator.py sf-lwc"
timeout: 5000

sf-lwc: Lightning Web Components Development

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.

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

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 resources/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 resources/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 resources/component-patterns.md

Lifecycle Hook Guidance

For complete code examples (Wire Service, GraphQL, Modal, Navigation, TypeScript), see:
- resources/component-patterns.md - Comprehensive patterns with full source code
- resources/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
⭐⭐⭐⭐   125-149 pts → Good component, minor styling issues
⭐⭐⭐     100-124 pts → Functional, needs SLDS cleanup
⭐⭐       75-99 pts  → Basic functionality, SLDS issues
⭐         <75 pts   → Needs significant work

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 resources/performance-guide.md

Jest Testing

Advanced testing patterns ensure robust, maintainable components.

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 resources/jest-testing.md

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 resources/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>

CLI Commands

Generate New Component

sf lightning generate component \
  --name accountDashboard \
  --type lwc \
  --output-dir force-app/main/default/lwc

Run Tests

# All tests
sf lightning lwc test run

# Specific component
sf lightning lwc test run --spec force-app/main/default/lwc/accountList/__tests__

# With coverage
sf lightning lwc test run -- --coverage

Flow Screen Integration

LWC components can be embedded in Flow Screens for custom UI experiences within guided processes.

Key Concepts

Quick Example

import { FlowAttributeChangeEvent, FlowNavigationFinishEvent } from 'lightning/flowSupport';

@api recordId;           // Input from Flow
@api selectedRecordId;   // Output to Flow
@api availableActions = [];

handleSelect(event) {
    this.selectedRecordId = event.detail.id;
    // CRITICAL: Notify Flow of the change
    this.dispatchEvent(new FlowAttributeChangeEvent(
        'selectedRecordId',
        this.selectedRecordId
    ));
}

handleNext() {
    if (this.availableActions.includes('NEXT')) {
        this.dispatchEvent(new FlowNavigationFinishEvent('NEXT'));
    }
}

For complete Flow integration patterns, see:
- docs/flow-integration-guide.md
- docs/triangle-pattern.md

Advanced Features

TypeScript Support (Spring '26 - GA in API 66.0)

Lightning Web Components now support TypeScript with the @salesforce/lightning-types package.

interface AccountRecord {
    Id: string;
    Name: string;
    Industry?: string;
}

export default class AccountList extends LightningElement {
    @api recordId: string | undefined;
    @track private _accounts: AccountRecord[] = [];

    @wire(getAccounts, { maxRecords: '$maxRecords' })
    wiredAccounts(result: WireResult<AccountRecord[]>): void {
        // Typed wire handling...
    }
}

Requirements: TypeScript 5.4.5+, @salesforce/lightning-types package

LWC in Dashboards (Beta - Spring '26)

Components can be embedded as custom dashboard widgets.

<targets>
    <target>lightning__Dashboard</target>
</targets>
<targetConfigs>
    <targetConfig targets="lightning__Dashboard">
        <property name="metricType" type="String" label="Metric Type"/>
        <property name="refreshInterval" type="Integer" default="30"/>
    </targetConfig>
</targetConfigs>

Note: Requires enablement via Salesforce Customer Support

Agentforce Discoverability (Spring '26 - GA in API 66.0)

Make components discoverable by Agentforce agents:

<capabilities>
    <capability>lightning__agentforce</capability>
</capabilities>

Best Practices:
- Clear masterLabel and description
- Detailed property descriptions
- Semantic naming conventions

For TypeScript patterns and advanced configurations, see resources/component-patterns.md

Cross-Skill Integration

Dependencies

Required:
- Target org with LWC support (API 45.0+)
- sf CLI authenticated

For Testing:
- Node.js 18+
- Jest (@salesforce/sfdx-lwc-jest)

For SLDS Validation:
- @salesforce-ux/slds-linter (optional)

Install: /plugin install github:Jaganpro/sf-skills/sf-lwc

Additional Resources

Documentation Files

External References

• PICKLES Framework (Salesforce Ben)
• LWC Recipes (GitHub)
• SLDS 2 Transition Guide
• SLDS Styling Hooks
• James Simone - Composable Modal
• James Simone - Advanced Jest Testing

License

MIT License. See LICENSE file.
Copyright (c) 2024-2025 Jag Valaiyapathy