fe-lwc-skill 1.0.0

package/skill/rules/design-token-dxp.md

@@ -0,0 +1,230 @@
+# design-token-dxp
+
+**Impact: HIGH**
+
+> ⚠️ **Runtime:** `--dxp` hooks are available in **LWR runtime only** (Experience Cloud LWR sites). They do not work in Aura runtime or standard Lightning pages.
+
+Experience Cloud LWR sites expose `--dxp` CSS custom properties (styling hooks) that map directly to the Theme panel in Experience Builder. Using these hooks means a site admin can retheme the entire portal — colors, fonts, spacing — without a developer touching component CSS. Hardcoding values bypasses this system and causes visual regressions whenever the theme changes.
+
+> **Rule:**
+>
+> - For typography in HTML templates, use `dxp-text-*` CSS classes (e.g. `dxp-text-heading-xlarge`).
+> - For typography in component CSS, use `--dxp-s-text-*` hooks (e.g. `var(--dxp-s-text-heading-extra-large-font-size)`).
+> - For colors, use `--dxp-g-*` global color hooks — never hardcode hex values.
+> - For font-family and base font size overrides, use `--dxp-g-root-font-family` / `--dxp-g-heading-font-family`.
+> - Define a `:root` block in **Head Markup** (Experience Builder → Settings → Advanced → Head Markup) for site-wide token overrides. Do not repeat overrides inside individual component CSS files.
+> - Never use `--dxp-g-destructive` for brand colors — it is reserved for error/invalid states only.
+
+---
+
+## Typography — CSS Classes vs CSS Variables
+
+Two ways to apply text styles. Use the class approach in HTML templates; use the variable approach when overriding in CSS.
+
+### Heading classes & hooks
+
+| Level       | HTML class                | CSS variable (font-size)                     | CSS variable (font-family)                     |
+| ----------- | ------------------------- | -------------------------------------------- | ---------------------------------------------- |
+| Extra Large | `dxp-text-heading-xlarge` | `--dxp-s-text-heading-extra-large-font-size` | `--dxp-s-text-heading-extra-large-font-family` |
+| Large       | `dxp-text-heading-large`  | `--dxp-s-text-heading-large-font-size`       | `--dxp-s-text-heading-large-font-family`       |
+| Medium      | `dxp-text-heading-medium` | `--dxp-s-text-heading-medium-font-size`      | `--dxp-s-text-heading-medium-font-family`      |
+| Small       | `dxp-text-heading-small`  | `--dxp-s-text-heading-small-font-size`       | `--dxp-s-text-heading-small-font-family`       |
+| X-Small     | `dxp-text-heading-xsmall` | `--dxp-s-text-heading-extra-small-font-size` | `--dxp-s-text-heading-extra-small-font-family` |
+
+Each heading level also supports:
+
+- `--dxp-s-text-heading-[level]-font-weight`
+- `--dxp-s-text-heading-[level]-line-height`
+- `--dxp-s-text-heading-[level]-color`
+
+### Body / paragraph classes & hooks
+
+| Level           | HTML class             | CSS variable (font-size)             |
+| --------------- | ---------------------- | ------------------------------------ |
+| Paragraph 1     | `dxp-text-body-large`  | `--dxp-s-text-body-large-font-size`  |
+| Paragraph 2     | `dxp-text-body-medium` | `--dxp-s-text-body-medium-font-size` |
+| Caption / small | `dxp-text-body-small`  | `--dxp-s-text-body-small-font-size`  |
+
+Each body level also supports `--dxp-s-text-body-[level]-font-family` and `--dxp-s-text-body-[level]-line-height`.
+
+---
+
+## Color hooks
+
+| Family            | Hook                                            | Use case                                    |
+| ----------------- | ----------------------------------------------- | ------------------------------------------- |
+| Root              | `--dxp-g-root`                                  | Page / section background                   |
+| Root contrast     | `--dxp-g-root-contrast`                         | Text/icons on root background               |
+| Root interaction  | `--dxp-g-root-1`                                | Hover state on root background              |
+| Brand             | `--dxp-g-brand`                                 | Primary brand color (buttons, links, focus) |
+| Brand contrast    | `--dxp-g-brand-contrast`                        | Text/icons on brand background              |
+| Brand interaction | `--dxp-g-brand-1`                               | Hover state of brand elements               |
+| Success           | `--dxp-g-success`                               | Success badges, alerts, toasts              |
+| Destructive       | `--dxp-g-destructive`                           | Error / invalid states only                 |
+| Warning           | `--dxp-g-warning`                               | Warning badges, alerts                      |
+| Info              | `--dxp-g-info`                                  | Tooltips, popovers                          |
+| Neutral           | `--dxp-g-neutral`                               | Borders, shadows, disabled inputs           |
+| Neutral scale     | `--dxp-g-neutral-1` / `neutral-2` / `neutral-3` | Progressive neutral shades                  |
+
+> ⚠️ `neutral`, `warning`, `info`, `success`, and `destructive` **cannot be configured in the Theme panel** — override them manually in Head Markup only.
+
+> ⚠️ Always use the paired `*-contrast` hook for text/icons placed on a colored background to ensure accessible contrast ratios.
+
+---
+
+## Case 1: Hardcoded typography in HTML template
+
+**Incorrect — custom class with hardcoded font-size breaks when theme changes:**
+
+```html
+<!-- appointmentCard.html -->
+<!-- ❌ Custom class with hardcoded font-size — not tied to the site theme -->
+<template>
+  <h2 class="card-title">{appointment.Name}</h2>
+  <p class="card-body">{appointment.Summary__c}</p>
+</template>
+```
+
+```css
+/* appointmentCard.css */
+/* ❌ Hardcoded values — admin cannot update these from Theme panel */
+.card-title {
+  font-size: 18px;
+  font-family: "Inter", sans-serif;
+}
+.card-body {
+  font-size: 14px;
+}
+```
+
+**Correct — use `dxp-text-*` classes in the template:**
+
+```html
+<!-- appointmentCard.html -->
+<!-- ✅ dxp classes inherit from Theme panel — no CSS needed -->
+<template>
+  <h2 class="dxp-text-heading-medium">{appointment.Name}</h2>
+  <p class="dxp-text-body-large">{appointment.Summary__c}</p>
+</template>
+```
+
+```css
+/* appointmentCard.css — ✅ empty for typography, only add non-text custom styles */
+```
+
+---
+
+## Case 2: Typography override in component CSS
+
+When a custom CSS class needs to match a text style (e.g. a dynamically styled element):
+
+**Correct — use `--dxp-s-text-*` variables in CSS:**
+
+```css
+/* portalHero.css */
+.hero-title {
+  font-size: var(--dxp-s-text-heading-extra-large-font-size);
+  font-family: var(--dxp-s-text-heading-extra-large-font-family);
+  font-weight: var(--dxp-s-text-heading-extra-large-font-weight);
+  color: var(--dxp-s-text-heading-extra-large-color);
+}
+
+.hero-subtitle {
+  font-size: var(--dxp-s-text-body-large-font-size);
+  line-height: var(--dxp-s-text-body-large-line-height);
+  color: var(--dxp-g-root-contrast); /* ✅ contrast pair for root background */
+}
+```
+
+---
+
+## Case 3: Hardcoded color values
+
+**Incorrect:**
+
+```css
+/* ❌ Hardcoded hex — breaks when brand color changes in Theme panel */
+.cta-button {
+  background-color: #0070d2;
+  color: #ffffff;
+}
+
+/* ❌ Using destructive color for brand — wrong semantic */
+.brand-badge {
+  background-color: var(--dxp-g-destructive);
+}
+```
+
+**Correct:**
+
+```css
+/* ✅ Uses brand hooks — updates automatically when admin changes theme */
+.cta-button {
+  background-color: var(--dxp-g-brand);
+  color: var(--dxp-g-brand-contrast); /* ✅ always accessible on brand bg */
+}
+
+/* ✅ Correct semantic — destructive only for errors */
+.error-badge {
+  background-color: var(--dxp-g-destructive);
+  color: var(--dxp-g-destructive-contrast);
+}
+```
+
+---
+
+## Case 4: Global `:root` override in Head Markup
+
+Define site-wide token overrides once in Head Markup — not scattered across component CSS files.
+
+**Incorrect — overriding tokens inside a component:**
+
+```css
+/* appointmentCard.css */
+/* ❌ Only affects this component — leads to duplicated overrides everywhere */
+:host {
+  --dxp-g-heading-font-family: "Nunito", sans-serif;
+  --dxp-g-brand: #005fbb;
+}
+```
+
+**Correct — one `:root` block in Experience Builder → Settings → Advanced → Head Markup:**
+
+```html
+<!-- Head Markup -->
+<style>
+  :root {
+    /* Base font */
+    --dxp-g-root-font-family: "Nunito", "Salesforce Sans", arial, sans-serif;
+    --dxp-g-heading-font-family: "Nunito", "Salesforce Sans", arial, sans-serif;
+
+    /* Brand colors — configurable via Theme panel */
+    --dxp-g-brand: #005fbb;
+    --dxp-g-brand-contrast: #ffffff;
+
+    /* Semantic colors — must be set here, not configurable in Theme panel */
+    --dxp-g-success: #2e7d32;
+    --dxp-g-warning: #e65100;
+    --dxp-g-destructive: #c62828;
+    --dxp-g-neutral: #e5e5e5;
+  }
+</style>
+```
+
+---
+
+## Quick Decision Guide
+
+| Need                         | Approach                                                          |
+| ---------------------------- | ----------------------------------------------------------------- |
+| Heading style in HTML        | `class="dxp-text-heading-{xlarge\|large\|medium\|small\|xsmall}"` |
+| Body text in HTML            | `class="dxp-text-body-{large\|medium\|small}"`                    |
+| Typography in component CSS  | `var(--dxp-s-text-heading-[level]-font-size)` etc.                |
+| Brand / interaction color    | `var(--dxp-g-brand)` + `var(--dxp-g-brand-contrast)`              |
+| Error state color            | `var(--dxp-g-destructive)` — not for brand use                    |
+| Global font / color override | `:root {}` in Head Markup — not in component CSS                  |
+| Hardcode a hex value         | ❌ Never                                                          |
+
+---
+
+**Reference:** [--dxp Styling Hooks](https://developer.salesforce.com/docs/atlas.en-us.exp_cloud_lwr.meta/exp_cloud_lwr/brand_hooks.htm) · [Text Hooks](https://developer.salesforce.com/docs/atlas.en-us.exp_cloud_lwr.meta/exp_cloud_lwr/brand_hooks_text.htm) · [Color Hooks](https://developer.salesforce.com/docs/atlas.en-us.exp_cloud_lwr.meta/exp_cloud_lwr/brand_hooks_color.htm)

package/skill/rules/design-token-slds.md

@@ -0,0 +1,258 @@
+# design-token-slds
+
+**Impact: MEDIUM**
+
+SLDS (Salesforce Lightning Design System) provides a comprehensive set of utility classes for layout, spacing, typography, and borders. Using SLDS utilities keeps component CSS files minimal and ensures visual consistency with the rest of the Salesforce platform. Writing custom CSS for things SLDS already handles wastes time and creates maintenance debt.
+
+> **Rule:**
+>
+> - Reach for SLDS utility classes before writing any custom CSS.
+> - **Never write `display: flex`, `flex-direction`, `align-items`, or `gap` in CSS** — use `slds-grid` and its modifier classes instead. If you find yourself writing flexbox CSS, stop and look up the SLDS equivalent first.
+> - Use `slds-m-*` and `slds-p-*` for margins and padding before setting them in CSS.
+> - Use `slds-border_*` for borders; `slds-text-*` for typography utilities.
+> - Write custom CSS only when SLDS utilities genuinely cannot cover the requirement.
+> - Never override SLDS utility classes with `!important` — this creates specificity debt.
+
+---
+
+## Project CSS Variables
+
+Before writing any custom CSS value (color, font, spacing), read **both** project config files below. Replace `<site-name>` with the actual portal folder name found under `digitalExperiences/site/`.
+
+**1. Branding tokens** — colors, fonts, and spacing variables:
+
+```
+force-app/main/default/digitalExperiences/site/<site-name>/sfdc_cms__brandingSet/Build_Your_Own_LWR/content.json
+```
+
+**2. App page layout config** — page-level CSS variables and region settings:
+
+```
+force-app/main/default/digitalExperiences/site/<site-name>/sfdc_cms__appPage/mainAppPage/content.json
+```
+
+> ⚠️ **Important — read `headMarkup` key first.** This file contains a `headMarkup` key that holds a `<style>` block injected into the site's `<head>`. This is where site-wide CSS variable overrides live — values here take precedence over component-level CSS and branding tokens. Before writing any CSS override, check `headMarkup` to see if the variable is already defined there. If you need to override a CSS variable globally, add it to `headMarkup`, not inside a component's `.css` file.
+
+The `contentBody.values` node in the branding file contains all design tokens for the site. Keys map to `--dxp-*` CSS custom properties at runtime. Always use the corresponding `--dxp-*` variable in component CSS — never hardcode the raw value.
+
+Example — given this branding file structure:
+
+```json
+{
+  "contentBody": {
+    "values": {
+      "ButtonColor": "var(--dxp-g-brand)",
+      "ButtonBorderRadius": "0px",
+      "ButtonFontWeight": "500",
+      "FormElementBorderColor": "rgb(155, 155, 155)",
+      "FormElementBorderRadius": "8px",
+      "HeadingLargeFontSize": "1.625rem",
+      "HeadingLargeFontWeight": "700",
+      "BodyFontSize": "1rem",
+      "BodyLineHeight": "1.4",
+      "BackgroundColor": "rgb(255, 255, 255)"
+    }
+  }
+}
+```
+
+Then in component CSS use the corresponding `--dxp-*` hooks — **never** the raw values:
+
+```css
+/* ✅ correct — uses dxp hooks that map to the branding values above */
+.cta-button {
+  background-color: var(--dxp-g-brand); /* ButtonColor */
+  border-radius: var(--dxp-s-button-sizing-border-radius); /* ButtonBorderRadius */
+  font-weight: var(--dxp-s-button-text-font-weight); /* ButtonFontWeight */
+}
+
+.form-input {
+  border-color: var(--dxp-s-form-element-color-border); /* FormElementBorderColor */
+  border-radius: var(--dxp-s-form-element-sizing-border-radius); /* FormElementBorderRadius */
+}
+
+.section-heading {
+  font-size: var(--dxp-s-text-heading-large-font-size); /* HeadingLargeFontSize */
+  font-weight: var(--dxp-s-text-heading-large-font-weight); /* HeadingLargeFontWeight */
+}
+
+/* ❌ never hardcode raw values from contentBody.values */
+.cta-button {
+  background-color: #005fbb; /* ❌ */
+  border-radius: 0px; /* ❌ */
+}
+.form-input {
+  border-color: rgb(155, 155, 155); /* ❌ */
+  border-radius: 8px; /* ❌ */
+}
+```
+
+---
+
+## Case 1: Custom layout instead of `slds-grid`
+
+**Incorrect — custom flexbox reimplements what SLDS already provides:**
+
+```html
+<!-- appointmentList.html -->
+<!-- ❌ Custom CSS class for a standard flex row layout -->
+<template>
+  <div class="card-row">
+    <div class="card-col-left">
+      <p>{appointment.Name}</p>
+    </div>
+    <div class="card-col-right">
+      <p>{appointment.Date__c}</p>
+    </div>
+  </div>
+</template>
+```
+
+```css
+/* appointmentList.css — ❌ NEVER write layout CSS like this */
+.card-row {
+  display: flex; /* ❌ use slds-grid */
+  flex-direction: row; /* ❌ default for slds-grid */
+  align-items: center; /* ❌ use slds-grid_vertical-align-center */
+  gap: 1rem; /* ❌ use slds-m-* on children instead */
+}
+.card-col-left {
+  flex: 1; /* ❌ use slds-col */
+}
+.card-col-right {
+  flex: 0 0 auto; /* ❌ use slds-shrink-none */
+}
+```
+
+**Correct — use `slds-grid` utilities:**
+
+```html
+<!-- appointmentList.html -->
+<!-- ✅ SLDS handles the layout — no custom CSS needed -->
+<template>
+  <div class="slds-grid slds-grid_align-spread slds-grid_vertical-align-center">
+    <div class="slds-col">
+      <p>{appointment.Name}</p>
+    </div>
+    <div class="slds-col slds-shrink-none">
+      <p>{appointment.Date__c}</p>
+    </div>
+  </div>
+</template>
+```
+
+```css
+/* appointmentList.css — ✅ empty, or contains only non-layout custom styles */
+```
+
+### Common layout patterns → SLDS translation
+
+| What Figma shows           | CSS you would write ❌                        | SLDS equivalent ✅                          |
+| -------------------------- | --------------------------------------------- | ------------------------------------------- |
+| Row, space between         | `display:flex; justify-content:space-between` | `slds-grid slds-grid_align-spread`          |
+| Row, centered vertically   | `display:flex; align-items:center`            | `slds-grid slds-grid_vertical-align-center` |
+| Column stack               | `display:flex; flex-direction:column`         | `slds-grid slds-grid_vertical`              |
+| Item takes remaining space | `flex: 1`                                     | `slds-col`                                  |
+| Item fixed width           | `flex: 0 0 auto`                              | `slds-shrink-none`                          |
+| Gap between items          | `gap: 0.5rem`                                 | `slds-m-right_small` on each child          |
+| Wrap to next line          | `flex-wrap: wrap`                             | `slds-wrap` on `slds-grid`                  |
+
+---
+
+## Case 2: Custom spacing instead of `slds-m-*` / `slds-p-*`
+
+**Incorrect — hardcoded margin/padding in CSS:**
+
+```html
+<!-- patientCard.html -->
+<template>
+  <div class="card-wrapper">
+    <h2 class="card-heading">{patient.Name}</h2>
+    <p class="card-body">{patient.Summary__c}</p>
+  </div>
+</template>
+```
+
+```css
+/* patientCard.css — ❌ custom spacing that duplicates SLDS scale */
+.card-wrapper {
+  padding: 16px;
+  margin-bottom: 12px;
+}
+.card-heading {
+  margin-bottom: 8px;
+}
+```
+
+**Correct — SLDS spacing utilities on the element directly:**
+
+```html
+<!-- patientCard.html -->
+<!-- ✅ Spacing handled in markup — CSS file stays clean -->
+<template>
+  <div class="slds-p-around_medium slds-m-bottom_small">
+    <h2 class="slds-m-bottom_x-small">{patient.Name}</h2>
+    <p>{patient.Summary__c}</p>
+  </div>
+</template>
+```
+
+---
+
+## Case 3: Custom border instead of `slds-border_*`
+
+**Incorrect:**
+
+```css
+/* ❌ Custom border — not consistent with SLDS visual language */
+.status-badge {
+  border: 1px solid #dddbda;
+  border-radius: 4px;
+}
+```
+
+**Correct:**
+
+```html
+<!-- ✅ SLDS utility class -->
+<span class="slds-border_bottom slds-p-bottom_xxx-small">{status}</span>
+```
+
+---
+
+## SLDS utilities quick reference
+
+| Need                  | SLDS class                                        |
+| --------------------- | ------------------------------------------------- |
+| Flex row              | `slds-grid`                                       |
+| Flex column           | `slds-grid slds-grid_vertical`                    |
+| Grow column           | `slds-col`                                        |
+| Fixed-size column     | `slds-shrink-none`                                |
+| Align items center    | `slds-grid_vertical-align-center`                 |
+| Justify space-between | `slds-grid_align-spread`                          |
+| Margin (all sides)    | `slds-m-around_{size}`                            |
+| Margin (directional)  | `slds-m-top_{size}`, `slds-m-bottom_{size}`, etc. |
+| Padding (all sides)   | `slds-p-around_{size}`                            |
+| Padding (directional) | `slds-p-top_{size}`, `slds-p-bottom_{size}`, etc. |
+| Border                | `slds-border_{top\|bottom\|left\|right}`          |
+| Truncate text         | `slds-truncate`                                   |
+| Screen reader only    | `slds-assistive-text`                             |
+
+> **Size tokens:** `xxx-small`, `xx-small`, `x-small`, `small`, `medium`, `large`, `x-large`, `xx-large`
+
+---
+
+## When to write custom CSS
+
+Write custom CSS only when SLDS and `--dxp` hooks cannot cover the requirement:
+
+- Component-specific visual states not in SLDS (e.g. custom progress indicator)
+- Animations and transitions
+- CSS Grid layouts beyond what `slds-grid` supports
+- Overriding a third-party component's style via `::part()` or `:host`
+
+In all other cases, default to SLDS utilities first.
+
+---
+
+**Reference:** [SLDS Utility Classes](https://www.lightningdesignsystem.com/utilities/alignment/) · [SLDS Grid System](https://www.lightningdesignsystem.com/utilities/grid/)