diff --git a/skills/applying-slds/SKILL.md b/skills/applying-slds/SKILL.md index 8b7e246..28aa88b 100644 --- a/skills/applying-slds/SKILL.md +++ b/skills/applying-slds/SKILL.md @@ -1,5 +1,6 @@ --- name: applying-slds +version: "1.0.0" description: Apply SLDS-compliant UI using the correct blueprints, styling hooks, utility classes, and icons. Use when building any UI that needs SLDS, choosing between Lightning Base Components and SLDS Blueprints, applying styling hooks for theming, using utility classes for layout and spacing, or selecting icons. Triggers include "build a modal", "create a form", "data table", "SLDS styling", "style with hooks", "add an icon". --- @@ -8,6 +9,8 @@ description: Apply SLDS-compliant UI using the correct blueprints, styling hooks The **Salesforce Lightning Design System (SLDS)** is a CSS framework with thousands of artifacts. This skill teaches agents how to find and correctly use them. > **Version:** This skill targets **SLDS v2**. Legacy `--lwc-*` tokens and `slds-*--modifier` syntax are deprecated. +> +> **Audit scope:** The companion `validating-slds` skill analyzer only scans `.css`, `.html`, and `.js` files. Use it directly for LWC and similar HTML/CSS/JS components; treat it as a partial signal for JSX/TSX or other framework-specific template formats and supplement with manual review. ## What is SLDS? @@ -30,10 +33,12 @@ The **Salesforce Lightning Design System (SLDS)** is a CSS framework with thousa - Which icon to use and from which category - SLDS naming conventions, class structure, hook syntax +**This skill includes basic accessibility reminders** (icon alt text, focus outlines, color-not-sole-indicator) in the validation checklists. Full WCAG compliance requires a dedicated accessibility review. + **This skill does NOT cover (use companion skills):** -- **Design decisions** -- visual hierarchy, composition, interaction patterns (design skill) -- **LWC mechanics** -- component structure, @wire, @api, lifecycle, events (LWC skill) -- **Accessibility** -- WCAG, ARIA patterns, keyboard navigation, focus management (a11y skill) +- **Design decisions** -- visual hierarchy, composition, interaction patterns +- **LWC mechanics** -- component structure, @wire, @api, lifecycle, events (not yet available) +- **Full accessibility** -- WCAG conformance, ARIA patterns, keyboard navigation, focus management, contrast ratios (not yet available) --- @@ -79,7 +84,7 @@ If no LBC exists (or not using LWC), select an SLDS Blueprint. See [references/c ## Hook Naming Traps -SLDS hook families do NOT all follow the same naming pattern. Agents frequently invent hooks that don't exist by assuming `{prefix}-{number}` works universally. **Always verify a hook exists** via `node scripts/search-hooks.cjs` or `metadata/hooks-index.json` before using it. +SLDS hook families do NOT all follow the same naming pattern. Agents frequently invent hooks that don't exist by assuming `{prefix}-{number}` works universally. **Always verify a hook exists** via the bundled `search-hooks.cjs` script or `metadata/hooks-index.json` before using it. ### Trap 1: Font size hooks are NOT numbered @@ -148,7 +153,7 @@ Use a consistent prefix for custom classes to avoid collision with SLDS: Custom hook namespacing: ```css :root { - --my-app-primary: var(--slds-g-color-brand-1); + --my-app-primary: var(--slds-g-color-accent-1); --my-app-card-padding: var(--slds-g-spacing-4); } ``` @@ -253,13 +258,7 @@ The linter catches hardcoded values, class overrides, and deprecated tokens. **F - All icons have accessibility text (A004) - Custom classes use `my-*` or `c-*` prefix (Q010) -**Step 4 (optional): Run the full quality audit** for a scored report before code review or deployment: - -```bash -node /scripts/analyze-quality.cjs -``` - -Or invoke the [validating-slds](../validating-slds/) skill. Target a B grade (≥80) or higher before marking work complete. +**Step 4 (optional): Run the full quality audit** using the `validating-slds` skill for a scored report before code review or deployment. Use it directly for LWC / HTML-CSS-JS components; for JSX/TSX outputs, treat the result as partial coverage only. Target a B grade (≥80) or higher before marking work complete. --- @@ -310,7 +309,7 @@ See [examples.md](examples.md) for worked examples demonstrating the full workfl ## Validation -See [checklists.md](checklists.md) for validation checklists aligned with the [validating-slds](../validating-slds/) skill. +See [checklists.md](checklists.md) for validation checklists aligned with the validating-slds skill. ## Resources diff --git a/skills/applying-slds/checklists.md b/skills/applying-slds/checklists.md index 23ef613..4b0d50b 100644 --- a/skills/applying-slds/checklists.md +++ b/skills/applying-slds/checklists.md @@ -1,8 +1,7 @@ # Validation Checklists -Run through these checks before finalizing any SLDS-authored component. Check IDs align with the [validating-slds](../validating-slds/) skill's quality-checks.md. +Run through these checks before finalizing any SLDS-authored component. Check IDs align with the validating-slds skill's quality-checks.md. ---- ## Theming & Styling (T-series) @@ -37,7 +36,7 @@ Code produced by this skill should score high on T-series checks. | **No !important** | No `!important` declarations | Q001 | | **No inline styles** | No `style="..."` in HTML | Q002 | | **Custom class prefix** | Custom classes use `my-*`, `c-*`, or namespace prefix | Q010 | -| **No SLDS naming** | Custom classes don't start with `slds-` | Q012 | +| **No dynamic SLDS class manipulation** | Avoid `.classList.add/remove/toggle('slds-*')` patterns in JS | Q012 | | **No magic numbers** | All numeric values have clear purpose | Q020 | --- diff --git a/skills/applying-slds/examples.md b/skills/applying-slds/examples.md index fb7f942..b2180e8 100644 --- a/skills/applying-slds/examples.md +++ b/skills/applying-slds/examples.md @@ -4,7 +4,6 @@ Worked examples showing the SLDS authoring workflow: from intent to artifact sel Each example follows the 5-phase workflow from SKILL.md and shows which files were consulted and why. ---- ## Example 1: Build a Confirmation Dialog @@ -37,7 +36,7 @@ The destructive action button needs error color to signal danger: ```bash node scripts/search-hooks.cjs --prefix "--slds-g-color-error-" -# Found: --slds-g-color-error-1 (#ea001e), --slds-g-color-on-error (#ffffff) +# Found: --slds-g-color-error-1 (#ea001e), --slds-g-color-on-error-1 (#ffffff) ``` **Result:** Use `variant="destructive"` on `lightning-button` inside the modal footer. The LBC handles the correct SLDS color hooks internally. @@ -101,23 +100,23 @@ node scripts/search-blueprints.cjs --search "badge" **Read YAMLs:** - `metadata/blueprints/components/cards.yaml` -- classes: `slds-card`, `slds-card__header`, `slds-card__body`, `slds-card__footer` -- `metadata/blueprints/components/badges.yaml` -- classes: `slds-badge`, modifiers: `slds-badge_success`, `slds-badge_warning`, `slds-badge_error` +- `metadata/blueprints/components/badges.yaml` -- classes: `slds-badge`, modifiers: `slds-badge_lightest`, `slds-badge_inverse` ### Phase 3: Apply Styling **Read:** `references/styling-decision-guide.md` -Card background and text use surface hooks. The status badge uses semantic SLDS modifier classes (no custom color needed). +Card background and text use surface hooks. The status is conveyed by badge text plus a custom status accent on the card, rather than invented badge modifiers. ```html -
+

Account Name

- Active + Active
@@ -160,7 +159,7 @@ In React (non-LWC), use the SVG blueprint pattern: ### Phase 5: Validate - Card uses exact blueprint classes (`slds-card`, `slds-card__header`, etc.) -- Badge uses SLDS modifier (`slds-badge_success`) not custom color +- Badge uses a real blueprint modifier (`slds-badge_lightest`), not an invented status variant - Custom border uses `my-*` prefix and hook with fallback - Icon uses `slds-assistive-text` for accessibility - No hardcoded colors @@ -188,6 +187,19 @@ node scripts/search-blueprints.cjs --search "illustration" ### Phase 3: Apply Styling +**Verify grid and spacing utilities** before using them: + +```bash +node scripts/search-utilities.cjs --search "slds-grid" +# Found: slds-grid (category: grid, css: display: flex) + +node scripts/search-utilities.cjs --search "slds-text-heading_large" +# Found: slds-text-heading_large (category: typography) + +node scripts/search-utilities.cjs --search "slds-text-body_small" +# Found: slds-text-body_small (category: typography) +``` + **Grid layout** uses utility classes (see `references/utilities-quick-ref.md`): ```html diff --git a/skills/applying-slds/references/styling-decision-guide.md b/skills/applying-slds/references/styling-decision-guide.md index f025d09..2b8336f 100644 --- a/skills/applying-slds/references/styling-decision-guide.md +++ b/skills/applying-slds/references/styling-decision-guide.md @@ -70,10 +70,11 @@ Before picking a hook, classify what the color is for: | Role | Hook prefix | Examples | |------|-------------|----------| -| Surface (backgrounds) | `--slds-g-color-surface-*` | Page bg, card bg, modal bg | +| Surface (backgrounds) | `--slds-g-color-surface-*` | Page bg, modal bg, top-level panels | +| Surface container (nested surfaces) | `--slds-g-color-surface-container-*` | Card bg, embedded panels, list items | | On-surface (text on surfaces) | `--slds-g-color-on-surface-*` | Body text, headings, icons | -| Container (interactive bg) | `--slds-g-color-container-*` | Button bg, input bg, tab bg | -| Accent (emphasis) | `--slds-g-color-accent-*` | Primary button, selected tab | +| Accent (emphasis) | `--slds-g-color-accent-*` | Primary emphasis, selected state text/icons | +| Accent container (accent backgrounds) | `--slds-g-color-accent-container-*` | Buttons, selected tabs, emphasized controls | | Border | `--slds-g-color-border-*` | Dividers, card borders | | Error | `--slds-g-color-error-*` | Validation errors | | Success | `--slds-g-color-success-*` | Confirmation states | diff --git a/skills/applying-slds/references/utilities-quick-ref.md b/skills/applying-slds/references/utilities-quick-ref.md index 433876d..dfb38e5 100644 --- a/skills/applying-slds/references/utilities-quick-ref.md +++ b/skills/applying-slds/references/utilities-quick-ref.md @@ -88,9 +88,11 @@ Responsive: `slds-small-size_*`, `slds-medium-size_*`, `slds-large-size_*` - `slds-hide` -- hide element (`display: none`) - `slds-show` -- show element (`display: block`) - `slds-show_inline` -- show inline -- `slds-hidden` -- visually hidden but accessible +- `slds-hidden` -- hidden via `visibility: hidden`; occupies space and is not a screen-reader helper - `slds-assistive-text` -- screen-reader only text +Use `slds-assistive-text`, not `slds-hidden`, when content should remain available to assistive technology. + ### Truncation - `slds-truncate` -- single-line truncation with ellipsis diff --git a/skills/applying-slds/scripts/search-blueprints.cjs b/skills/applying-slds/scripts/search-blueprints.cjs index d2031a2..8fb335e 100644 --- a/skills/applying-slds/scripts/search-blueprints.cjs +++ b/skills/applying-slds/scripts/search-blueprints.cjs @@ -12,50 +12,9 @@ const fs = require('fs'); const path = require('path'); -const yaml = require !== undefined ? null : null; // yaml parsing below const BLUEPRINTS_DIR = path.join(__dirname, '..', 'metadata', 'blueprints', 'components'); -function parseYaml(text) { - const lines = text.split('\n'); - const result = {}; - let currentKey = null; - let currentArray = null; - let currentObj = null; - let indent = 0; - - for (const line of lines) { - const trimmed = line.trimEnd(); - if (!trimmed || trimmed.startsWith('#')) continue; - - const match = trimmed.match(/^(\s*)([\w_]+):\s*(.*)$/); - if (match) { - const spaces = match[1].length; - const key = match[2]; - let value = match[3].replace(/^["']|["']$/g, '').trim(); - - if (spaces === 0) { - currentKey = key; - currentArray = null; - currentObj = null; - if (value) { - result[key] = value; - } else { - result[key] = {}; - } - } else if (currentKey && spaces > 0) { - if (typeof result[currentKey] === 'object' && !Array.isArray(result[currentKey])) { - if (value) { - result[currentKey][key] = value; - } - } - } - } - } - - return result; -} - function loadBlueprints() { const blueprints = []; if (!fs.existsSync(BLUEPRINTS_DIR)) { diff --git a/skills/uplifting-components-to-slds2/SKILL.md b/skills/uplifting-components-to-slds2/SKILL.md index 7818725..03a5c43 100644 --- a/skills/uplifting-components-to-slds2/SKILL.md +++ b/skills/uplifting-components-to-slds2/SKILL.md @@ -1,5 +1,6 @@ --- name: uplifting-components-to-slds2 +version: "1.0.0" description: Migrate Lightning Web Components from SLDS 1 to SLDS 2 by running the SLDS linter and fixing violations. Use this skill whenever users mention SLDS 2, SLDS uplift, linter violations, LWC token migration, class overrides, hardcoded CSS values that need SLDS hook replacement, or styling hook selection. Covers all styling hook categories — color, spacing, sizing, typography, borders, radius, and shadows. Also use when users mention no-hardcoded-values, no-slds-class-overrides, lwc-to-slds-hooks, no-deprecated-tokens-slds1, or ask about SLDS component migration — even if they don't explicitly say "uplift" or "migration". --- @@ -32,7 +33,7 @@ Color hooks require the most judgment (context-dependent selection). Non-color h # Workflow ``` -1. Run SLDS linter with auto-fix -> Handles simple violations automatically +1. **REQUIRED — ALWAYS run first:** npx @salesforce-ux/slds-linter@latest lint --fix . — NEVER skip this step. This handles simple violations automatically. 2. Review linter output -> Identify remaining manual fixes needed 3. Fix by violation type -> Use per-rule reference guides 4. Choose the right hook -> Context-first, inspect HTML before deciding @@ -40,6 +41,7 @@ Color hooks require the most judgment (context-dependent selection). Non-color h ``` ## Step 1: Run SLDS Linter +MANDATORY: This step is NOT optional. ```bash npx @salesforce-ux/slds-linter@latest lint --fix . diff --git a/skills/uplifting-components-to-slds2/references/examples.md b/skills/uplifting-components-to-slds2/references/examples.md index 1e49638..b8575e5 100644 --- a/skills/uplifting-components-to-slds2/references/examples.md +++ b/skills/uplifting-components-to-slds2/references/examples.md @@ -30,12 +30,12 @@ dataTable.css **Before:** ```css .slds-table { - border-collapse: separate; - border-spacing: 0; + border-width: var(--slds-g-sizing-border-1, 1px); + border-radius: var(--slds-g-radius-border-2, 0.25rem); } .slds-table .slds-button { - padding: 0.5rem 1rem; + padding: var(--slds-g-spacing-2, 0.5rem) var(--slds-g-spacing-2, 1rem); } ``` @@ -48,12 +48,12 @@ dataTable.css **After:** ```css .dataTable-table { - border-collapse: separate; - border-spacing: 0; + border-width: var(--slds-g-sizing-border-1, 1px); + border-radius: var(--slds-g-radius-border-2, 0.25rem); } .dataTable-table .dataTable-button { - padding: 0.5rem 1rem; + padding: var(--slds-g-spacing-2, 0.5rem) var(--slds-g-spacing-2, 1rem); } ``` diff --git a/skills/validating-slds/SKILL.md b/skills/validating-slds/SKILL.md index 40b81ac..678a6a3 100644 --- a/skills/validating-slds/SKILL.md +++ b/skills/validating-slds/SKILL.md @@ -1,42 +1,33 @@ --- name: validating-slds -description: >- - Audit Lightning Web Components for SLDS compliance and produce a scored quality - report. Runs the SLDS linter, analyzes CSS for theming hook usage and pairing, - checks HTML for accessibility attributes, and scores findings across categories - into an overall grade. Use when asked to "score my component", "SLDS scorecard", - "quality report", "audit SLDS compliance", "how good is my SLDS", "check - component quality", "rate my component", "evaluate my component", "is this - component ready to ship?", "look at my LWC for issues", "audit this before I - submit", "review my component before code review", or any time a user wants a - quality assessment or production-readiness check on an LWC or SLDS component. - Not for fixing violations (use slds-uplift) or building new components (use - slds-authoring). +version: "1.0.0" +description: Audit Lightning Web Components for SLDS compliance and produce a scored quality report. Runs the SLDS linter, analyzes CSS for theming hook usage and pairing, checks HTML for accessibility attributes, and scores findings across categories into an overall grade. Use when asked to "score my component", "SLDS scorecard", "quality report", "audit SLDS compliance", "how good is my SLDS", "check component quality", "rate my component", "evaluate my component", "is this component ready to ship?", "look at my LWC for issues", "audit this before I submit", "review my component before code review", or any time a user wants a quality assessment or production-readiness check on an LWC or SLDS component. Not for fixing violations (use uplifting-components-to-slds2) or building new components (use applying-slds). --- # SLDS Quality Audit -Audit Lightning Web Components for SLDS compliance and produce a scored quality scorecard. Combines SLDS linter output with supplementary static analysis to catch what the linter misses. +Audit Lightning Web Components for SLDS compliance and produce an automated scorecard plus a required manual review gate. Combines SLDS linter output with supplementary static analysis to catch what the linter misses. ## Scope Also valid for: auditing SLDS compliance across a project or component set, and before/after quality comparison after making changes. Not for: -- **Fixing** linter violations — use `slds-uplift` instead -- **Building** new components — use `slds-authoring` instead +- **Fixing** linter violations — use `uplifting-components-to-slds2` instead +- **Building** new components — use `applying-slds` instead - **Just running the linter** — run `npx @salesforce-ux/slds-linter@latest lint .` directly - **Full WCAG accessibility audit** — this skill checks attribute presence only (labels, alt text, focus indicators), not contrast ratios, keyboard flows, or screen reader behavior +- **Framework-specific template auditing** beyond `.css`, `.html`, and `.js` files — JSX/TSX/Vue/Svelte outputs need additional manual review --- ## Quality Validation Process ``` -1. Run SLDS Linter → Collect violation counts (linter's job) +1. Run SLDS Linter → Collect violation counts (linter's job) 2. Run Analyze Script → Check what linter doesn't cover (supplementary) -3. Agent Review → Manual review prompts (not automatable) -4. Score & Grade → Combine linter + script + review findings +3. Agent Review → Required manual review gate +4. Score & Grade → Compute automated score + final recommendation 5. Generate Report → Produce formatted scorecard ``` @@ -67,7 +58,7 @@ Overall (linter unavailable) = (Theming × 0.29) + (Accessibility × 0.29) ## Step 2: Run Supplementary Analysis -Run the analyze script to catch issues the linter doesn't cover: +Run the analyze script to catch issues the linter doesn't cover. The bundled analyzer scans `.css`, `.html`, and `.js` files only: ```bash node scripts/analyze-quality.cjs @@ -80,10 +71,10 @@ The script outputs JSON with findings organized by severity. It checks: | Check | What It Catches | Severity | |-------|----------------|----------| | Missing fallbacks | `var(--slds-g-*)` without a fallback value | Critical | -| Invented hooks (T051) | `--slds-g-*` tokens not found in `hooks-index.json` | Critical | +| Invented hooks (T051) | `--slds-g-*` tokens not found in `hooks-index.json` (requires `--hooks-index`) | Critical | | Hook pairing | Background hooks without matching foreground hooks | Warning | | `!important` | Specificity overrides | Warning | -| Magic pixel values | Hardcoded `px` not using spacing hooks | Info | +| Magic pixel values | Hardcoded `px` not using spacing hooks | Warning | | High z-index | z-index values > 99 | Warning | | Outline removal | `outline: none` without alternative focus style | Warning | @@ -92,7 +83,7 @@ The script outputs JSON with findings organized by severity. It checks: | Check | What It Catches | Severity | |-------|----------------|----------| | Inline style assignment | `.style.*=` direct property assignment | Warning | -| SLDS class manipulation | Dynamic `.classList.add('slds-*')` manipulation | Info | +| SLDS class manipulation | Dynamic `.classList.add('slds-*')` manipulation | Warning | ### HTML Checks @@ -105,7 +96,7 @@ The script outputs JSON with findings organized by severity. It checks: | Positive tabindex | `tabindex` values other than 0 or -1 | Warning | | Clickable divs | `
` instead of `