From 7c4bf0baa10f433439767f8ee5c3bd64c32b7aa4 Mon Sep 17 00:00:00 2001 From: showerbee Date: Fri, 10 Apr 2026 10:21:45 -0400 Subject: [PATCH] fix: quote YAML descriptions and improve color hook disambiguation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Quote description frontmatter in all three skills for valid YAML (inner double quotes now escaped) - Strengthen Step 4 directive: MUST read color-hooks guide before choosing a hook — linter suggestions are unranked - Add surface vs surface-container disambiguation table - Add accent hook context table and state progression - Add standalone-component exception for surface classification - Add modal background example to examples.md - Remove redundant brand-button example (covered by new context table) Made-with: Cursor --- skills/applying-slds/SKILL.md | 2 +- skills/uplifting-components-to-slds2/SKILL.md | 4 +- .../references/color-hooks-decision-guide.md | 39 ++++++++++++++----- .../references/examples.md | 18 +++++++++ skills/validating-slds/SKILL.md | 2 +- 5 files changed, 52 insertions(+), 13 deletions(-) diff --git a/skills/applying-slds/SKILL.md b/skills/applying-slds/SKILL.md index 28aa88b..17ca40a 100644 --- a/skills/applying-slds/SKILL.md +++ b/skills/applying-slds/SKILL.md @@ -1,7 +1,7 @@ --- 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". +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\"." --- # Applying SLDS diff --git a/skills/uplifting-components-to-slds2/SKILL.md b/skills/uplifting-components-to-slds2/SKILL.md index 03a5c43..9ddf84c 100644 --- a/skills/uplifting-components-to-slds2/SKILL.md +++ b/skills/uplifting-components-to-slds2/SKILL.md @@ -1,7 +1,7 @@ --- 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". +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\"." --- # Goal @@ -114,7 +114,7 @@ See [rule-no-slds-class-overrides.md](references/rule-no-slds-class-overrides.md ## Step 4: Choose the Right Hook -**Color hooks** require context-based selection — inspect the HTML to determine the element's role before choosing a hook family. See **[color-hooks-decision-guide.md](references/color-hooks-decision-guide.md)** for decision trees, all 5 hook families, and background-foreground pairing rules. +**Color hooks** require context-based selection. **REQUIRED: When any violation involves a color property (`color`, `background-color`, `background`, `fill`, `border-color`), you MUST read [color-hooks-decision-guide.md](references/color-hooks-decision-guide.md) BEFORE choosing a hook.** The linter lists possible hooks in no particular order — do NOT pick the first suggestion. The guide contains property-based rules that determine the correct hook. **Non-color hooks** are simpler — match the CSS value to the numbered scale. See **[non-color-hooks-decision-guide.md](references/non-color-hooks-decision-guide.md)** for value-to-hook lookup tables covering spacing, sizing, typography, borders, radius, and shadows. diff --git a/skills/uplifting-components-to-slds2/references/color-hooks-decision-guide.md b/skills/uplifting-components-to-slds2/references/color-hooks-decision-guide.md index 075a94f..8235372 100644 --- a/skills/uplifting-components-to-slds2/references/color-hooks-decision-guide.md +++ b/skills/uplifting-components-to-slds2/references/color-hooks-decision-guide.md @@ -74,6 +74,15 @@ Is this element a page foundation, an overlay (modal/popover/dropdown), or does | Exists within page's content flow | No | Yes | | Sits on top of an existing surface | No | Yes | +### Linter Lists Both? Use Context + +The linter lists hooks with similar color values in no particular order. When it suggests both `surface-N` and `surface-container-N`, check the element's DOM role: + +| Question | Answer | Hook | +|---|---|---| +| Does it sit on top of another visible surface? | Yes | `surface-container-*` | +| Is it the page/modal/overlay/component root? | Yes | `surface-*` | + ### Hook Types | Hook Type | Pattern | Use For | @@ -116,6 +125,8 @@ All three `on-surface` variants can appear on the same surface background. Choos | Sub-panel inside a card | `surface-container-2` | Nested container | | Modal / popover / dropdown | `surface-1` | Creates NEW stacking context — resets depth | +**Exception:** If a card/panel IS the component's entire visual footprint (notification bar, banner, standalone section with no visible parent surface), treat it as a surface, not a container. + ### State Progression The starting variant depends on which one matches the original default color — don't assume `-1`: @@ -143,7 +154,7 @@ Use when hardcoded dark-blue backgrounds (`#032d60`, `#03234d`) appear on light An element named `.card-container` might use `surface-*` if it's the page-level background, or `surface-container-*` if it's a card. **Always base the decision on structural DOM position, not naming conventions.** -Surface variants (1-2-3) are a light-to-dark aesthetic progression, NOT functional states. +Surface variants (1-2-3) are a light-to-dark aesthetic progression, NOT functional states. The linter's suggestion list is NOT ranked -- use element context, not list position. --- @@ -161,6 +172,24 @@ Is this element interactive or expressing brand identity? | Border | `border-accent-1` / `-2` / `-3` | High-emphasis brand borders | | On Accent | `on-accent-1` / `-2` / `-3` | Text on brand backgrounds | +### Context Determines Hook Type + +| Element Context | Hook | Example | +|---|---|---| +| Interactive container/button background | `accent-container-*` | Brand button `background-color` | +| Link text, icon fill (NOT on accent bg) | `accent-*` | Link `color`, icon `fill` | +| Text/icon ON an accent-container background | `on-accent-*` | Button label `color` | +| Border of an accent element | `border-accent-*` | Button `border-color` | + +`accent-*` is for **foreground** (text, icons). `accent-container-*` is for **background fills** of interactive containers. Determine what the element IS first, then the CSS property follows naturally. + +### Accent Container State Progression + +| Default | Hover/Active | +|---|---| +| `accent-container-1` | `accent-container-2` | +| `accent-container-2` | `accent-container-3` | + ### Why accent-2 is the default for links (not accent-1) `accent-1` may not meet 4.5:1 WCAG contrast on non-white backgrounds. `accent-2` passes on all standard surfaces — use it as the safe default for text links. Go up one for hover: `accent-2` → `accent-3`. @@ -416,14 +445,6 @@ border: var(--slds-g-sizing-border-1, 1px) solid var(--slds-g-color-border-1, #d } ``` -**Brand button:** -```css -.primary-action { - background: var(--slds-g-color-accent-container-1, #066afe); - color: var(--slds-g-color-on-accent-1, #ffffff); -} -``` - **Error alert (role="alert" + error class):** ```css .error-message { diff --git a/skills/uplifting-components-to-slds2/references/examples.md b/skills/uplifting-components-to-slds2/references/examples.md index b8575e5..77d2c8f 100644 --- a/skills/uplifting-components-to-slds2/references/examples.md +++ b/skills/uplifting-components-to-slds2/references/examples.md @@ -137,6 +137,24 @@ tile.css } ``` +### Modal Background + +**Before:** +```css +.modal-overlay { + background-color: #ffffff; +} +``` + +**Context:** Modal creates a new stacking context (overlay) → choose `surface-1`, NOT `surface-container-1`. + +**After:** +```css +.modal-overlay { + background-color: var(--slds-g-color-surface-1, #ffffff); +} +``` + ### Link Colors **Before:** diff --git a/skills/validating-slds/SKILL.md b/skills/validating-slds/SKILL.md index 678a6a3..4a10a2d 100644 --- a/skills/validating-slds/SKILL.md +++ b/skills/validating-slds/SKILL.md @@ -1,7 +1,7 @@ --- name: validating-slds 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). +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