@salesforce/mcp-provider-lwc-experts 0.6.3 → 0.6.4

package/knowledge/slds/styling-hooks/categories/shadow.md

@@ -0,0 +1,489 @@
+# SLDS Shadow Styling Hooks
+
+**Category:** Visual Effects / Elevation  
+**Total Hooks:** 39 shadow-related hooks  
+**Purpose:** Create depth, elevation, and visual hierarchy through shadows
+
+---
+
+## Overview
+
+Shadow styling hooks provide consistent elevation and depth effects across SLDS components. Shadows help establish visual hierarchy, indicate interactive elements, and create the perception of layered content.
+
+**Key Principles:**
+
+- Use shadows to indicate elevation and interactivity
+- Higher numbered shadows (1→6) indicate greater elevation
+- Directional shadows control shadow placement (block/inline)
+- Focus shadows indicate keyboard interaction states
+- Maintain consistency in shadow usage across similar components
+
+---
+
+## Core Shadow Hooks (`--slds-g-shadow-*`)
+
+### Available Hooks
+
+| Hook                | Value                                                                                        | Description                         |
+| ------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------- |
+| `--slds-g-shadow-1` | `0px 0px 1.5px 0px #00000017, 0px 1.4px 1.5px 0px #00000017, 0px -1px 1px 0px #00000009`     | Minimal elevation - subtle shadow   |
+| `--slds-g-shadow-2` | `0px 0px 3px 0px #00000016, 0px 2.8px 3px 0px #00000016, 0px -1px 1.2px 0px #00000009`       | Low elevation - slight lift         |
+| `--slds-g-shadow-3` | `0px 0px 4.5px 0px #00000014, 0px 4.2px 4.5px 0px #00000017, 0px -1px 1.44px 0px #00000008`  | Medium elevation - clear separation |
+| `--slds-g-shadow-4` | `0px 0px 6.75px 0px #00000012, 0px 6.3px 6.75px 0px #00000012, 0px -1px 1.7px 0px #00000007` | High elevation - prominent lift     |
+| `--slds-g-shadow-5` | Complex value                                                                                | Higher elevation                    |
+| `--slds-g-shadow-6` | Complex value                                                                                | Maximum elevation                   |
+
+### Usage Guidance
+
+#### Shadow-1: Minimal Elevation
+
+**Use For:**
+
+- Subtle card separation
+- Low-priority containers
+- Flat designs with minimal depth
+
+```css
+.card-minimal {
+  box-shadow: var(--slds-g-shadow-1);
+}
+```
+
+#### Shadow-2: Low Elevation
+
+**Use For:**
+
+- Standard cards
+- List items with slight separation
+- Subtle hover states
+
+```css
+.card-default {
+  box-shadow: var(--slds-g-shadow-2);
+}
+
+.card-default:hover {
+  box-shadow: var(--slds-g-shadow-3);
+}
+```
+
+#### Shadow-3: Medium Elevation
+
+**Use For:**
+
+- Elevated cards
+- Dropdown menus
+- Popovers
+- Hover states from shadow-2
+
+```css
+.dropdown-menu {
+  box-shadow: var(--slds-g-shadow-3);
+}
+```
+
+#### Shadow-4: High Elevation
+
+**Use For:**
+
+- Modals
+- Dialogs
+- Floating action buttons
+- Critical overlays
+
+```css
+.modal {
+  box-shadow: var(--slds-g-shadow-4);
+}
+```
+
+#### Shadow-5 & Shadow-6: Maximum Elevation
+
+**Use For:**
+
+- Maximum emphasis overlays
+- Top-level dialogs
+- Critical alerts requiring immediate attention
+
+---
+
+## Directional Shadow Hooks
+
+### Block Direction (Vertical)
+
+Control shadow placement along the vertical axis:
+
+| Hook                           | Description                     |
+| ------------------------------ | ------------------------------- |
+| `--slds-g-shadow-blockstart-1` | Shadow at top edge (level 1)    |
+| `--slds-g-shadow-blockstart-2` | Shadow at top edge (level 2)    |
+| `--slds-g-shadow-blockstart-3` | Shadow at top edge (level 3)    |
+| `--slds-g-shadow-blockstart-4` | Shadow at top edge (level 4)    |
+| `--slds-g-shadow-blockend-1`   | Shadow at bottom edge (level 1) |
+| `--slds-g-shadow-blockend-2`   | Shadow at bottom edge (level 2) |
+| `--slds-g-shadow-blockend-3`   | Shadow at bottom edge (level 3) |
+| `--slds-g-shadow-blockend-4`   | Shadow at bottom edge (level 4) |
+
+**Use Cases:**
+
+- Fixed headers with shadow at bottom (blockend)
+- Floating elements with shadow at top (blockstart)
+- Sticky navigation bars
+
+```css
+.fixed-header {
+  box-shadow: var(--slds-g-shadow-blockend-2);
+}
+```
+
+### Inline Direction (Horizontal)
+
+Control shadow placement along the horizontal axis:
+
+| Hook                            | Description                    |
+| ------------------------------- | ------------------------------ |
+| `--slds-g-shadow-inlinestart-1` | Shadow at start edge (level 1) |
+| `--slds-g-shadow-inlinestart-2` | Shadow at start edge (level 2) |
+| `--slds-g-shadow-inlinestart-3` | Shadow at start edge (level 3) |
+| `--slds-g-shadow-inlinestart-4` | Shadow at start edge (level 4) |
+| `--slds-g-shadow-inlineend-1`   | Shadow at end edge (level 1)   |
+| `--slds-g-shadow-inlineend-2`   | Shadow at end edge (level 2)   |
+| `--slds-g-shadow-inlineend-3`   | Shadow at end edge (level 3)   |
+| `--slds-g-shadow-inlineend-4`   | Shadow at end edge (level 4)   |
+
+**Use Cases:**
+
+- Side navigation panels
+- Slide-out drawers
+- Edge-aligned popovers
+
+```css
+.side-panel-right {
+  box-shadow: var(--slds-g-shadow-inlinestart-3);
+}
+```
+
+---
+
+## Focus Shadow Hooks
+
+Indicate keyboard focus states with accessible shadows:
+
+| Hook                                   | Description                |
+| -------------------------------------- | -------------------------- |
+| `--slds-g-shadow-outline-focus-1`      | Outline-style focus shadow |
+| `--slds-g-shadow-outset-focus-1`       | Outset focus shadow        |
+| `--slds-g-shadow-inset-focus-1`        | Inset focus shadow         |
+| `--slds-g-shadow-insetinverse-focus-1` | Inset inverse focus shadow |
+
+### Usage Patterns
+
+#### Outline Focus (Most Common)
+
+For standard interactive elements:
+
+```css
+.button:focus {
+  outline: none;
+  box-shadow: var(--slds-g-shadow-outline-focus-1);
+}
+```
+
+#### Outset Focus
+
+For elements with existing shadows:
+
+```css
+.card-interactive:focus {
+  box-shadow: var(--slds-g-shadow-2), var(--slds-g-shadow-outset-focus-1);
+}
+```
+
+#### Inset Focus
+
+For input fields and contained elements:
+
+```css
+.input-field:focus {
+  box-shadow: var(--slds-g-shadow-inset-focus-1);
+}
+```
+
+#### Inverse Focus
+
+For elements on dark backgrounds:
+
+```css
+.dark-mode .button:focus {
+  box-shadow: var(--slds-g-shadow-insetinverse-focus-1);
+}
+```
+
+---
+
+## Inverse Shadow Hook
+
+| Hook                        | Description                            |
+| --------------------------- | -------------------------------------- |
+| `--slds-g-shadow-inverse-1` | Shadow for dark mode/inverted contexts |
+
+**Use For:**
+
+- Dark mode UI elements
+- Inverted color schemes
+- Light elements on dark backgrounds
+
+```css
+.dark-theme .card {
+  background: var(--slds-g-color-surface-inverse-1);
+  box-shadow: var(--slds-g-shadow-inverse-1);
+}
+```
+
+---
+
+## Best Practices
+
+### ✅ DO:
+
+1. **Use progressive elevation for hierarchy**
+
+   ```css
+   .card {
+     box-shadow: var(--slds-g-shadow-2);
+   }
+   .card:hover {
+     box-shadow: var(--slds-g-shadow-3);
+   }
+   ```
+
+2. **Combine shadows with focus states**
+
+   ```css
+   .interactive:focus {
+     box-shadow: var(--slds-g-shadow-2), var(--slds-g-shadow-outline-focus-1);
+   }
+   ```
+
+3. **Use directional shadows for edge placement**
+
+   ```css
+   .sticky-header {
+     box-shadow: var(--slds-g-shadow-blockend-2);
+   }
+   ```
+
+4. **Match shadow intensity to component importance**
+   - Subtle cards: shadow-1 or shadow-2
+   - Dropdowns/popovers: shadow-3
+   - Modals/dialogs: shadow-4
+
+### ❌ DON'T:
+
+1. **Don't mix shadow levels inconsistently**
+
+   ```css
+   /* Bad: Jumping from 1 to 4 */
+   .card {
+     box-shadow: var(--slds-g-shadow-1);
+   }
+   .card:hover {
+     box-shadow: var(--slds-g-shadow-4);
+   }
+   ```
+
+2. **Don't use high elevation for minor elements**
+
+   ```css
+   /* Bad: Excessive shadow for simple element */
+   .label {
+     box-shadow: var(--slds-g-shadow-4);
+   }
+   ```
+
+3. **Don't hard-code shadow values**
+
+   ```css
+   /* Bad */
+   box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+
+   /* Good */
+   box-shadow: var(--slds-g-shadow-2);
+   ```
+
+4. **Don't forget focus states**
+
+   ```css
+   /* Bad: No focus shadow */
+   .button:focus {
+     outline: none;
+   }
+
+   /* Good */
+   .button:focus {
+     outline: none;
+     box-shadow: var(--slds-g-shadow-outline-focus-1);
+   }
+   ```
+
+---
+
+## Common Patterns
+
+### Pattern 1: Card with Hover Effect
+
+```css
+.card {
+  background: var(--slds-g-color-surface-container-1);
+  border-radius: var(--slds-g-radius-border-1);
+  box-shadow: var(--slds-g-shadow-2);
+  transition: box-shadow 0.2s ease;
+}
+
+.card:hover {
+  box-shadow: var(--slds-g-shadow-3);
+}
+```
+
+### Pattern 2: Dropdown Menu
+
+```css
+.dropdown {
+  background: var(--slds-g-color-surface-container-1);
+  border: 1px solid var(--slds-g-color-border-1);
+  border-radius: var(--slds-g-radius-border-2);
+  box-shadow: var(--slds-g-shadow-3);
+}
+```
+
+### Pattern 3: Modal Dialog
+
+```css
+.modal {
+  background: var(--slds-g-color-surface-1);
+  border-radius: var(--slds-g-radius-border-2);
+  box-shadow: var(--slds-g-shadow-4);
+}
+
+.modal-backdrop {
+  background: rgba(0, 0, 0, 0.5);
+}
+```
+
+### Pattern 4: Interactive Button with Focus
+
+```css
+.button {
+  background: var(--slds-g-color-accent-container-1);
+  color: var(--slds-g-color-on-accent-1);
+  border: 1px solid var(--slds-g-color-border-accent-1);
+  border-radius: var(--slds-g-radius-border-1);
+  box-shadow: var(--slds-g-shadow-1);
+}
+
+.button:hover {
+  box-shadow: var(--slds-g-shadow-2);
+}
+
+.button:focus {
+  outline: none;
+  box-shadow: var(--slds-g-shadow-1), var(--slds-g-shadow-outline-focus-1);
+}
+```
+
+### Pattern 5: Fixed Header
+
+```css
+.fixed-header {
+  position: fixed;
+  top: 0;
+  background: var(--slds-g-color-surface-1);
+  box-shadow: var(--slds-g-shadow-blockend-2);
+  z-index: 100;
+}
+```
+
+---
+
+## Accessibility
+
+### Focus Visibility
+
+Always use focus shadows for keyboard navigation:
+
+```css
+.interactive-element:focus {
+  outline: none; /* Remove default outline */
+  box-shadow: var(--slds-g-shadow-outline-focus-1); /* Add SLDS focus shadow */
+}
+```
+
+### Color Independence
+
+Shadows provide depth cues independent of color, benefiting users with color vision deficiencies.
+
+### Reduced Motion
+
+Consider users with motion sensitivity when animating shadows:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .card {
+    transition: none;
+  }
+}
+```
+
+---
+
+## Complete Hook Reference
+
+### All 39 Shadow Hooks:
+
+**Main Shadows (6):**
+
+- `--slds-g-shadow-1` through `--slds-g-shadow-6`
+- `--slds-g-shadow-inverse-1`
+
+**Directional Block Shadows (8):**
+
+- `--slds-g-shadow-blockstart-1` through `--slds-g-shadow-blockstart-4`
+- `--slds-g-shadow-blockend-1` through `--slds-g-shadow-blockend-4`
+
+**Directional Inline Shadows (8):**
+
+- `--slds-g-shadow-inlinestart-1` through `--slds-g-shadow-inlinestart-4`
+- `--slds-g-shadow-inlineend-1` through `--slds-g-shadow-inlineend-4`
+
+**Focus Shadows (4):**
+
+- `--slds-g-shadow-outline-focus-1`
+- `--slds-g-shadow-outset-focus-1`
+- `--slds-g-shadow-inset-focus-1`
+- `--slds-g-shadow-insetinverse-focus-1`
+
+---
+
+## Quick Decision Guide
+
+**Choose shadow level based on:**
+
+- **Shadow-1:** Subtle separation, flat UI
+- **Shadow-2:** Standard cards, default state
+- **Shadow-3:** Elevated elements, dropdowns, hover states
+- **Shadow-4:** Modals, dialogs, critical overlays
+- **Shadow-5/6:** Maximum emphasis
+
+**Choose shadow type based on:**
+
+- **Standard shadows:** Most elements
+- **Directional shadows:** Fixed/sticky elements with specific edge placement
+- **Focus shadows:** Keyboard navigation states
+- **Inverse shadows:** Dark mode contexts
+
+---
+
+**References:**
+
+- Source: `/source-data/sds-metadata/styling-hooks/globalstylinghooks.metadata.json`
+- SLDS Documentation: [Elevation & Shadow](https://www.lightningdesignsystem.com/2e1ef8501/)