@salesforce/afv-skills 1.37.0 → 1.38.0

package/skills/experience-lwc-accessibility-validate/references/vision/sc-1-4-3-contrast.md

@@ -0,0 +1,25 @@
+## SC 1.4.3 - Contrast (Minimum) (Level AA)
+
+The visual presentation of text and images of text has a contrast ratio of at least 4.5:1, except for large text (at least 3:1), incidental text (part of inactive components, purely decorative, not visible, or part of a picture containing significant other visual content), and logotypes.
+
+You are a UI/UX accessibility expert specializing in color contrast analysis for WCAG 2.2 SC 1.4.3 compliance. Your job is to analyze Lightning Web Components (LWCs) to identify text contrast issues.
+
+Your task is to identify contrast issues by examining text colors against their backgrounds. Look for the following problems:
+
+CONTRAST ISSUES TO IDENTIFY:
+
+- Text with insufficient contrast ratio against background
+- Links with poor contrast that don't meet minimum requirements
+- Form labels, placeholders, and input text with low contrast or insufficient contrast ratio
+- Error messages, success messages, and status text with insufficient contrast
+- Button text, navigation text, and interactive elements with poor contrast
+- Table headers and content with insufficient contrast
+
+ANALYSIS APPROACH:
+
+1. Examine text colors against their background colors
+2. Identify contrast ratios that fall below WCAG requirements
+3. Consider the context and importance of the text
+4. Focus on real accessibility impacts for users with low vision
+
+For any issues you find, provide specific descriptions of the contrast problem and actionable recommendations for achieving proper contrast ratios.

package/skills/experience-lwc-accessibility-validate/scripts/contrast-ratio.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+"""WCAG 2.2 SC 1.4.3 / 1.4.11 contrast-ratio calculator.
+
+Computes the exact WCAG contrast ratio between a foreground and a background
+color so the accessibility reviewer never has to approximate relative luminance
+by hand (which is unreliable and has produced inconsistent findings). The
+reviewer resolves the two colors from the component's HTML/CSS, then invokes
+this script; the printed verdict is authoritative.
+
+Usage:
+  contrast-ratio.py FOREGROUND BACKGROUND [--large] [--json]
+
+Arguments:
+  FOREGROUND   Text color. Accepts #RGB, #RRGGBB, rgb(r,g,b) or rgba(r,g,b,a).
+  BACKGROUND   Background color. Must be opaque (#RGB/#RRGGBB/rgb()); used as
+               the compositing base when FOREGROUND carries an alpha channel.
+
+Options:
+  --large      Classify the text as large-scale (>=24px, or >=18.66px bold),
+               which uses the 3:1 threshold instead of 4.5:1 for the primary
+               PASS/FAIL. Both thresholds are always reported regardless.
+  --json       Emit a machine-readable JSON object instead of the text report.
+
+Exit codes:
+  0  Ratio meets the applicable threshold (PASS)
+  1  Ratio is below the applicable threshold (FAIL)
+  2  Argument / parse error
+"""
+
+import argparse
+import json
+import re
+import sys
+
+_STANDARD_THRESHOLD = 4.5
+_LARGE_THRESHOLD = 3.0
+
+
+def _parse_color(value):
+    """Return (r, g, b, a) with channels in 0-255 and alpha in 0.0-1.0."""
+    s = value.strip()
+
+    m = re.fullmatch(r"#([0-9a-fA-F]{3})", s)
+    if m:
+        r, g, b = (int(c * 2, 16) for c in m.group(1))
+        return r, g, b, 1.0
+
+    m = re.fullmatch(r"#([0-9a-fA-F]{6})", s)
+    if m:
+        h = m.group(1)
+        return int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16), 1.0
+
+    m = re.fullmatch(
+        r"rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*(?:,\s*([\d.]+)\s*)?\)",
+        s,
+    )
+    if m:
+        r, g, b = (int(round(float(m.group(i)))) for i in (1, 2, 3))
+        a = float(m.group(4)) if m.group(4) is not None else 1.0
+        for ch in (r, g, b):
+            if not 0 <= ch <= 255:
+                raise ValueError(f"channel out of range in '{value}'")
+        if not 0.0 <= a <= 1.0:
+            raise ValueError(f"alpha out of range in '{value}'")
+        return r, g, b, a
+
+    raise ValueError(
+        f"unrecognized color '{value}' — use #RGB, #RRGGBB, rgb(), or rgba()"
+    )
+
+
+def _composite(fg, bg):
+    """Alpha-composite fg over an opaque bg; return an opaque (r, g, b)."""
+    fr, fgc, fb, fa = fg
+    br, bgc, bb, _ = bg
+    if fa >= 1.0:
+        return fr, fgc, fb
+    return (
+        round(fr * fa + br * (1 - fa)),
+        round(fgc * fa + bgc * (1 - fa)),
+        round(fb * fa + bb * (1 - fa)),
+    )
+
+
+def _relative_luminance(rgb):
+    """WCAG relative luminance for an opaque sRGB (r, g, b) triple."""
+    def _lin(c):
+        c /= 255.0
+        return c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4
+
+    r, g, b = (_lin(c) for c in rgb)
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b
+
+
+def contrast_ratio(foreground, background):
+    """Exact WCAG contrast ratio between two color strings (>= 1.0)."""
+    fg = _parse_color(foreground)
+    bg = _parse_color(background)
+    if bg[3] < 1.0:
+        raise ValueError(
+            f"background '{background}' is translucent — its rendered color "
+            "depends on the layer beneath it and cannot be determined. Resolve "
+            "the effective opaque background and pass that instead."
+        )
+    fg_rgb = _composite(fg, bg)
+    l1 = _relative_luminance(fg_rgb)
+    l2 = _relative_luminance(bg[:3])
+    lighter, darker = (l1, l2) if l1 >= l2 else (l2, l1)
+    return (lighter + 0.05) / (darker + 0.05)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(add_help=True)
+    parser.add_argument("foreground")
+    parser.add_argument("background")
+    parser.add_argument("--large", action="store_true")
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args(argv)
+
+    try:
+        ratio = contrast_ratio(args.foreground, args.background)
+    except ValueError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+
+    threshold = _LARGE_THRESHOLD if args.large else _STANDARD_THRESHOLD
+    passes = ratio >= threshold
+    result = {
+        "foreground": args.foreground,
+        "background": args.background,
+        "ratio": round(ratio, 2),
+        "textClass": "large" if args.large else "standard",
+        "threshold": threshold,
+        "passesStandard": ratio >= _STANDARD_THRESHOLD,
+        "passesLarge": ratio >= _LARGE_THRESHOLD,
+        "verdict": "PASS" if passes else "FAIL",
+    }
+
+    if args.as_json:
+        print(json.dumps(result))
+    else:
+        print(
+            f"{result['ratio']}:1  {result['verdict']} "
+            f"({result['textClass']} text, threshold {threshold}:1)  |  "
+            f"standard 4.5:1 {'pass' if result['passesStandard'] else 'fail'}, "
+            f"large 3:1 {'pass' if result['passesLarge'] else 'fail'}"
+        )
+
+    return 0 if passes else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/experience-lwc-design-generate/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: experience-lwc-design-generate
+description: "Use when you need to create a brand new Lightning Web Component from a Figma design, a Product Requirements Document, or another design artifact — orchestrating the five-phase workflow (gather requirements → generate code → optimize → lint/format/compile → test) and stitching together the specialized skills for SLDS, LDS, base components, optimization, and testing. Use this skill whenever the user mentions building a new LWC from Figma, building an LWC from a PRD, generating an LWC from a design or screenshot, or migrating an Aura component as a fresh LWC build. DO NOT TRIGGER when refactoring an existing LWC (use experience-lwc-generate), for Aura → LWC in-place migration (out of scope for this skill), for standalone SLDS token or styling work (use design-systems-slds-apply), or for standalone data-layer work (use experience-lds-best-practices-apply or experience-lds-data-requirements-generate)."
+metadata:
+  version: "1.0"
+  cliTools:
+    - tool: ["eslint"]
+      semver: ">=8.0"
+    - tool: ["prettier"]
+      semver: ">=2.0"
+    - tool: ["python3"]
+      semver: ">=3.8"
+  relatedSkills:
+    - design-systems-slds-apply
+    - experience-lds-best-practices-apply
+    - experience-lds-data-requirements-generate
+    - experience-lwc-accessibility-validate
+    - experience-lwc-base-components-integrate
+    - experience-lwc-generate
+    - experience-lwc-rtl-validate
+    - experience-lwc-runtime-observe
+    - experience-lwc-security-validate
+    - experience-lwc-typescript-migrate
+---
+<!-- adk-managed-skill -->
+
+# Creating LWC Components from Design
+
+Orchestrate the end-to-end creation of a new Lightning Web Component from a design input (Figma, PRD, Aura source, or user description). This is the top-level workflow skill — it sequences the specialized sibling skills that own each stage. Org-aware data (LDS schema introspection, design-frame inspection) is resolved by handing off to `experience-lds-data-requirements-generate` or via design-tool URLs the user provides.
+
+## When to Use
+
+- Building a brand-new LWC from a Figma frame, PRD, or written spec.
+- Migrating an Aura component to LWC as a fresh build (in-place Aura → LWC porting is out of scope for this skill).
+- Creating a component whose requirements are still partly implicit and need distillation into a PRD before coding.
+
+Do NOT use this skill for:
+- Refactoring an existing LWC (use `experience-lwc-generate`).
+- Aura → LWC in-place migration (out of scope for this skill).
+- Pure styling or data-layer work (use the specialized skills directly).
+
+## Prerequisites
+
+- At least one design input: Figma URL, PRD markdown, Aura component source, or a textual spec.
+- Target path (module folder) for the new LWC.
+- For data-backed components: access to the org so `experience-lds-data-requirements-generate` and `experience-lds-best-practices-apply` can resolve the schema and adapter shapes.
+
+## Knowledge Bases
+
+- [references/prd-analysis-template.md](references/prd-analysis-template.md) — PRD section skeleton (copy it verbatim when producing a PRD).
+- [references/figma-to-prd-blueprint.md](references/figma-to-prd-blueprint.md) — Figma-specific guidance for translating a frame into PRD sections (componentName/tagName, contentRequirements, dataRequirements, interactions, componentCommunication, states, accessibility/responsiveness/styling/localization/security). Read this before Phase 1.2 when the input is a Figma design.
+
+## Workflow (mandatory five phases)
+
+### Phase 1 — Gather PRD & requirements
+
+**Goal:** produce a consolidated PRD that every later phase consumes.
+
+1. **Obtain raw requirements** — collect the PRD, design spec, Figma URL, Aura source, or user text.
+2. **Figma → PRD** (if applicable): follow [references/figma-to-prd-blueprint.md](references/figma-to-prd-blueprint.md) for the full Figma-frame analysis and PRD section guidelines. Inputs you need from the user: the Figma URL, a screenshot of the target frame, and (if Dev Mode is available) the metadata export for the node. Translate into the PRD skeleton from [references/prd-analysis-template.md](references/prd-analysis-template.md) using the section-by-section guidance in the blueprint.
+3. **Aura → PRD** (if migrating): enumerate the Aura component's functionality that must be preserved — markup, controller/helper actions, events, attributes, and wired data — and feed that inventory into the PRD as explicit requirements. (In-place Aura → LWC porting is out of scope; this step only captures behavior for a fresh build.)
+4. **Data requirements** (if the component reads/writes data): hand off to `experience-lds-data-requirements-generate`. That skill produces a validated data specification (object/field API names, recommended LDS API, implementation approach). Paste its output verbatim into the PRD.
+5. **Adapter exploration**: hand off to `experience-lds-best-practices-apply` for the adapter selection rules (UI API vs GraphQL vs Apex) and the recommended wiring for the chosen approach.
+6. **Naming**: `componentName` must be camelCase (e.g., `productCard`) and `tagName` must be its kebab-case form (e.g., `product-card`). Validate both with the bundled script — do not eyeball the check:
+
+   ```bash
+   "<skill_dir>/scripts/check-component-name.sh" <componentName> <tagName>
+   ```
+
+   The script exits nonzero (with an actionable stderr message) if either name is malformed or if the kebab form of `componentName` does not equal `tagName`.
+
+**Deliverable:** a comprehensive PRD covering purpose, content, data, interactions, states, a11y, responsiveness, styling direction, localization, and security. Keep it checked into the workspace (e.g., `packages/skills/<skill>-workspace/<iteration>/PRD.md`).
+
+### Phase 2 — Generate component code
+
+**Goal:** initial `.html`, `.js`, `.css`, `.js-meta.xml` that strictly reflect the PRD.
+
+1. Hand off to `experience-lwc-generate` with the PRD content as the spec. That skill owns PRD → code translation (events, getters, `@api`, `.js-meta.xml`, AI metadata) and is the authoring source of truth.
+2. Use the SLDS decision hierarchy from `design-systems-slds-apply`:
+   1. Prefer a matching Lightning Base Component (`experience-lwc-base-components-integrate`).
+   2. Otherwise pick an SLDS Blueprint or utility class (per `design-systems-slds-apply`).
+   3. Otherwise write custom CSS using SLDS styling hooks (also covered in `design-systems-slds-apply`).
+3. Re-confirm the authoring baseline by walking the `experience-lwc-generate` checklist before proceeding.
+4. Translate every PRD data requirement to either a wire adapter (UIAPI / GraphQL) or an explicit TODO.
+5. Adhere strictly to the PRD:
+   - Only include features and behaviors the PRD describes.
+   - Mark uncertain areas with `// TODO:` comments that quote the PRD language raising the ambiguity.
+   - Add extensive code comments explaining intent.
+   - Do not split the component into more sub-components than the PRD implies.
+
+**Deliverable:** a first-pass LWC bundle in the target path.
+
+### Phase 3 — Optimize component
+
+**Goal:** apply performance, maintainability, and best-practice fixes.
+
+1. Walk the optimization checklist below before any other review:
+   - Single responsibility, encapsulation, reusability.
+   - Minimize DOM operations; batch updates via properties.
+   - Audit event handlers and lifecycle hook usage (`renderedCallback` guards).
+   - Consider lazy loading for heavy children.
+2. Hand off to `experience-lwc-generate` for the LWC best-practices review pass (anti-patterns, reactivity, composition).
+3. Hand off to the compliance suite for the pre-ship review — `experience-lwc-accessibility-validate` (a11y), `experience-lwc-security-validate` (LWS + Product Security), and `experience-lwc-rtl-validate` (RTL i18n). Run them together for the full quality pass.
+4. If the component touches data, hand off to `experience-lds-best-practices-apply` for cache/consistency and referential-integrity checks.
+5. Apply every accepted finding. Keep the PRD as the source of truth — do not add scope under the guise of optimization.
+
+### Phase 4 — Lint, format, compile-check
+
+Condition: only run steps whose tooling is configured in the project.
+
+1. **Detect project tooling** — invoke the bundled detection script from the project root and read its `<tool>=yes|no` lines. Do NOT eyeball `package.json` / dotfiles in prose:
+
+   ```bash
+   "<skill_dir>/scripts/detect-project-tools.sh" <projectRoot>
+   ```
+
+   Sample output:
+
+   ```text
+   eslint=yes
+   prettier=yes
+   cursor-rules=no
+   lwc-compiler=yes
+   ```
+
+   Run the substeps below only for tools reported `yes`; skip the rest.
+2. **ESLint** (if `eslint=yes`) — run and fix all violations.
+3. **Prettier** (if `prettier=yes`) — run for consistent formatting.
+4. **Cursor rules** (if `cursor-rules=yes`) — apply every rule the project ships.
+5. **LWC compiler** (if `lwc-compiler=yes`) — run via local dev server or SFDX; resolve every syntax/template error before moving on.
+
+**Deliverable:** clean, validated component code.
+
+### Phase 5 — Create tests
+
+Hand off to `experience-lwc-accessibility-jest-run` for automated accessibility Jest coverage; add general-purpose Jest coverage in the same pass following the `experience-lwc-generate` test guidance, plus UTAM page object generation if the team requires it.
+
+**Deliverable:** the LWC bundle with a passing test suite at or above the project's coverage threshold.
+
+## Definition of Done
+
+A new component built from this workflow is "done" only when **every** item below is true. Treat this as the canonical readiness checklist — copy it into the PR description so reviewers can confirm each line.
+
+**Code completion** — no implementation gaps:
+
+1. Every PRD requirement is either implemented or explicitly annotated with a `TODO:` and a linked tracking item. No silent gaps.
+2. No `TODO`, `FIXME`, or `console.log` / `console.table` / `alert()` left in production paths.
+3. No commented-out code blocks, no empty function bodies, no placeholder values, no dummy data, no unreferenced imports.
+4. No `lwc:dom="manual"` regions or third-party-library escape hatches without a comment explaining why a native LWC pattern wasn't used.
+
+**Compliance and quality:**
+
+5. `.js-meta.xml` AI metadata passes the audit in `experience-lwc-generate` (component-wide `<ai><description>` set, plus an `<ai><property name="…" aiDescription="…"/></ai>` entry for every `@api` member exposed through `<targetConfig>`; no marketing language).
+6. SLDS styling passes `design-systems-slds-apply` verification — no raw hex / px values, only styling hooks and SLDS utility classes.
+7. Accessibility pass complete: `experience-lwc-accessibility-validate` for source review + `experience-lwc-accessibility-jest-run` for automated tests, both green.
+8. Security + RTL pass complete: `experience-lwc-security-validate` + `experience-lwc-rtl-validate`, both green.
+
+**Data + tests:**
+
+9. Data layer verified against the referenced LDS adapters (every wire / imperative call is documented in the PRD's data section and matches one of the adapters from `experience-lds-best-practices-apply` or `experience-lds-data-requirements-generate`).
+10. Jest tests green at the required coverage level for the project. New tests cover every `@api` surface, every dispatched event, and every error path (failed wire, failed apex, validation rejection).
+11. UTAM page objects produced for any UI flow that needs cross-component browser-level testing (skip if not needed).
+
+## Cross-References
+
+- Skills chained by this workflow (in phase order):
+  - `experience-lds-data-requirements-generate` — Phase 1.4 data spec (and Phase 1.5 adapter exploration alongside `experience-lds-best-practices-apply`).
+  - `design-systems-slds-apply`, `experience-lwc-base-components-integrate` — Phase 2 styling decisions.
+  - `experience-lwc-generate` — Phase 2 authoring baseline + Phase 3 best-practices review + Phase 5 AI-metadata audit.
+  - `experience-lds-best-practices-apply` — Phase 2/3 data-layer adapter selection and consistency review.
+  - `experience-lwc-accessibility-validate`, `experience-lwc-security-validate`, `experience-lwc-rtl-validate` — Phase 3 a11y/security/RTL review.
+  - `experience-lwc-accessibility-jest-run` — Phase 5 automated a11y test generation.
+  - Optional: add o11y instrumentation as a separate pass once the component stabilizes.
+  - `experience-lwc-typescript-migrate` — optional once JS is green.
+  - When the new component ships behind a flag, gate it with a feature flag during rollout.
+  - `experience-lwc-api-docs-generate` — once the public API surface is stable.
+- Org-aware inputs used by this workflow:
+  - Figma URL + screenshot (and, if available, the developer's Dev Mode metadata export) — Phase 1.2 Figma input.
+  - `experience-lds-data-requirements-generate` owns the org-schema introspection and data-spec validation used in Phase 1 when the component needs org-backed data — hand off to that skill rather than duplicating its work here.
+
+## Examples
+
+**Phase 1 PRD skeleton (fill from the Figma/PRD/Aura input)**
+
+```text
+Component: productCard (<product-card>)
+Purpose: Render a compact summary of a product with quick actions.
+
+Content requirements
+- Hero image (Product.HeroImage__c)
+- Title (Product.Name)
+- Subtitle (Product.Tagline__c)
+- Primary CTA button ("Add to cart")
+- Secondary CTA icon button ("Favorite")
+
+Data requirements
+- Input: @api recordId (Product Id)
+- Adapter: getRecord (UIAPI) with fields Name, Tagline__c, HeroImage__c
+- Events out: addtocart{detail.recordId}, favorite{detail.recordId, detail.value}
+
+States
+- Loading (data not yet resolved)
+- Error (adapter error)
+- Empty (no record found)
+- Default
+
+Accessibility
+- Title uses <h3>
+- Icon-only button carries aria-label="Favorite"
+- Card is a labelled region (role="group", aria-labelledby)
+
+Responsiveness
+- Full width < 480px
+- Side-by-side image + text >= 480px
+
+Styling
+- Uses lightning-card wrapper
+- Surface color: --slds-g-color-surface-container-1
+- Shadow: --slds-g-shadow-1
+```
+
+**Phase 2 skeleton**
+
+```javascript
+import { LightningElement, api, wire } from 'lwc';
+import { getRecord } from 'lightning/uiRecordApi';
+import NAME from '@salesforce/schema/Product__c.Name';
+import TAGLINE from '@salesforce/schema/Product__c.Tagline__c';
+import HERO from '@salesforce/schema/Product__c.HeroImage__c';
+
+const FIELDS = [NAME, TAGLINE, HERO];
+
+export default class ProductCard extends LightningElement {
+    @api recordId;
+
+    @wire(getRecord, { recordId: '$recordId', fields: FIELDS })
+    record;
+
+    get hasRecord() { return this.record?.data != null; }
+    get isLoading() { return !this.record; }
+    get hasError()  { return !!this.record?.error; }
+    get name()      { return this.record?.data?.fields?.Name?.value ?? ''; }
+    get tagline()   { return this.record?.data?.fields?.Tagline__c?.value ?? ''; }
+    get heroUrl()   { return this.record?.data?.fields?.HeroImage__c?.value ?? ''; }
+
+    handleAddToCart() {
+        this.dispatchEvent(new CustomEvent('addtocart', { detail: { recordId: this.recordId }, bubbles: true, composed: true }));
+    }
+    handleFavorite(event) {
+        this.dispatchEvent(new CustomEvent('favorite', { detail: { recordId: this.recordId, value: event.detail.value }, bubbles: true, composed: true }));
+    }
+}
+```
+
+## Verification
+
+- Every PRD section is traceable to at least one block of code or an explicit TODO.
+- Phases 1–5 were executed in order; no step was skipped.
+- Accessibility, SLDS, data-layer, and AI metadata reviews all pass.
+- Coverage meets or exceeds the project's threshold.
+- The component renders correctly in `experience-lwc-runtime-observe` across the responsive breakpoints enumerated in the PRD.

package/skills/experience-lwc-design-generate/references/figma-to-prd-blueprint.md

@@ -0,0 +1,66 @@
+# Figma → PRD Blueprint
+
+You are a specialized assistant focused on converting Figma designs into a LWC Component.
+
+TASK: Analyze the provided Figma frame and generate a complete PRD following the specified structure, then hand off to `experience-lwc-generate` to generate the LWC Component.
+
+## PRD Generation Process
+
+1. Analyze the Figma frame carefully, identifying all visual elements, interactions, data structures, and component relationships
+2. Extract relevant component information including:
+   - Visual hierarchy and content elements
+   - Interactive elements and their behaviors
+   - Data requirements and dependencies
+   - Design patterns and styling information
+   - Accessibility considerations
+   - Responsive behaviors
+3. Organize this information according to the PRD blueprint schema
+4. Generate a comprehensive markdown document that fully describes the component requirements
+
+## Guidelines for Key Sections
+
+### componentName and tagName
+
+- Use a descriptive name based on the component's purpose
+- Follow naming conventions: camelCase for componentName (e.g., `productCard`) and kebab-case for tagName (e.g., `product-card`)
+
+### contentRequirements
+
+- Identify all visual elements in the Figma frame that display content
+- Document text blocks, images, icons, buttons, and other UI elements
+- Explain what each element displays and why it's necessary
+
+### dataRequirements
+
+- Determine what data is needed to power each content element
+- Identify where the data should come from (properties, events, etc.)
+- Document how the data will be used
+
+### interactions
+
+- Document all user interactions visible in the design (clicks, hovers, etc.)
+- Describe the expected behavior for each interaction
+- Explain the purpose behind each interaction
+
+### componentCommunication
+
+- Identify events the component should emit or listen for
+- Describe what data should be passed in these communications
+- Explain why this communication is necessary
+
+### states
+
+- Identify different visual states shown in the design (default, hover, active, error, etc.)
+- Document conditions that trigger state changes
+- Explain the purpose of each state
+
+### accessibility, responsiveness, styling, localization, and security
+
+- Extract any relevant information from the design
+- Make reasonable assumptions where the design doesn't specify these aspects
+- Provide detailed requirements that align with best practices
+- For styling, follow SLDS patterns: use Lightning Base Components where possible (see `experience-lwc-base-components-integrate`), then SLDS Blueprints, then SLDS styling hooks (see `design-systems-slds-apply`)
+
+## Output Format
+
+Provide the complete PRD as a valid markdown document. Ensure all required fields are completed with detailed, specific information extracted from the Figma design.

package/skills/experience-lwc-design-generate/references/prd-analysis-template.md

@@ -0,0 +1,17 @@
+# Your task
+
+Review {{SUBJECT}} and identify {{DOMAIN}} issues.
+Return your analysis as report in SARIF JSON format with no additional text or explanation.
+
+## Instructions for identifying {{DOMAIN}} issues.
+
+The instructions below provide list of possible issues with the explanation how to find and report those.
+Each section corresponds to a specific issue and describes what patterns to look for.
+
+{{INSTRUCTIONS}}
+
+## Requirements to output
+
+- Return ONLY valid JSON without any additional information
+- Do not write JSON to a file, just respond with it
+- List of results should be empty if no issues were found

package/skills/experience-lwc-design-generate/scripts/check-component-name.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# Validates that the two names an LWC bundle requires are in the correct
+# case conventions and are consistent with each other:
+#
+#   componentName — camelCase (e.g. `productCard`)
+#   tagName       — kebab-case (e.g. `product-card`)
+#
+# Also verifies the kebab-case form of `componentName` equals `tagName`,
+# so `productCard` / `product-card` passes but `productCard` /
+# `productcard` (missing dash) does not.
+#
+# Usage:
+#   <skill_dir>/scripts/check-component-name.sh <componentName> <tagName>
+#
+# Exit codes:
+#   0 — both names conform to their conventions and are consistent
+#   1 — validation failure (message on stderr describing which rule failed)
+#   2 — usage error
+
+set -euo pipefail
+
+fail() {
+  echo "check-component-name: $*" >&2
+  exit 1
+}
+
+if [ "$#" -ne 2 ]; then
+  echo "usage: $0 <componentName> <tagName>" >&2
+  exit 2
+fi
+
+component_name="$1"
+tag_name="$2"
+
+python3 - "$component_name" "$tag_name" <<'PY'
+import re
+import sys
+
+component_name, tag_name = sys.argv[1], sys.argv[2]
+
+CAMEL_RE = re.compile(r"^[a-z][a-zA-Z0-9]*$")
+KEBAB_RE = re.compile(r"^[a-z][a-z0-9]*(-[a-z0-9]+)+$")
+
+errors = []
+
+if not CAMEL_RE.match(component_name):
+    errors.append(
+        f"componentName `{component_name}` is not camelCase — must start with a "
+        "lowercase letter and contain only letters/digits (e.g. `productCard`)."
+    )
+
+if not KEBAB_RE.match(tag_name):
+    errors.append(
+        f"tagName `{tag_name}` is not kebab-case — must start with a lowercase "
+        "letter and contain at least one `-` separator with lowercase segments "
+        "(e.g. `product-card`)."
+    )
+
+if not errors:
+    # componentName -> expected kebab-case: insert `-` before each interior
+    # uppercase letter and lowercase everything.
+    expected = re.sub(r"([A-Z])", r"-\1", component_name).lower()
+    if expected != tag_name:
+        errors.append(
+            f"tagName `{tag_name}` does not match componentName `{component_name}` "
+            f"— expected kebab-case form `{expected}`."
+        )
+
+if errors:
+    for e in errors:
+        print(f"check-component-name: {e}", file=sys.stderr)
+    sys.exit(1)
+
+print(f"check-component-name: OK ({component_name} / {tag_name})")
+PY