@salesforce/afv-skills 1.13.0 → 1.15.0

package/skills/applying-slds/guidance/overviews/illustrations.md

@@ -0,0 +1,235 @@
+---
+id: slds.guidance.overview.illustrations
+title: Illustrations Overview
+description: Foundational guidance for implementing illustrations in SLDS interfaces
+summary: "Comprehensive illustration guidance covering empty states, informational states, and error states. Includes placement rules, sizing guidelines, accessibility requirements, and the one-illustration-per-page principle."
+
+artifact_type: overview
+domain: overviews
+topic: illustrations
+
+content_format: narrative
+complexity: foundational
+audience: [implementer, designer]
+
+tasks: [learn, choose, implement]
+
+refs:
+  - slds.guidance.accessibility.overview
+
+tags: [illustrations, empty-states, visual-design, user-experience]
+keywords: [illustrations, empty states, error states, informational states, visual messaging, actionable guidance]
+---
+
+# Illustrations Guidance for SLDS Implementation
+
+**Purpose:** This document provides the foundational principles and guidance for implementing illustrations in Salesforce Lightning Design System. When working with SLDS components and interfaces, follow these guidelines to ensure illustrations are used purposefully to enhance clarity, personality, and user engagement.
+
+---
+
+## About Illustrations
+
+Illustrations are engaging visuals that guide, inform, and delight users. In the Salesforce Lightning Design System (SLDS), they help communicate complex ideas, reinforce brand identity, and guide users through key moments in their journey. Illustrations are approachable and inclusive, reflecting the diversity of our users while aligning with the Salesforce brand.
+
+**Key Requirement:** To ensure accessibility best practices, illustrations must always enhance the textual content, not replace it. Use them sparingly and align with the purpose and tone of the screen or message.
+
+---
+
+## Core Principles
+
+When working with illustrations in UI interfaces, adhere to these four foundational principles:
+
+1. **Prioritize clarity and purpose.** Illustrations should soften negative impressions and provide context. Use them to help users understand the state of the system or to guide them through a workflow.
+2. **Accessibility is mandatory.** Illustrations must enhance textual content, never replace it. Always provide meaningful text alongside illustrations to ensure the experience is accessible to all users.
+3. **Maintain visual restraint.** Use illustrations sparingly to avoid distracting users. Follow the "one illustration per page" rule to maintain focus on the primary task.
+4. **Include actionable guidance.** Pair illustrations with clear, actionable UI text. If a page is empty, provide a link or button to help the user take the next step.
+
+---
+
+## Illustration Types
+
+Illustrations in SLDS generally communicate one of three conditions: empty, informational, or error. The specific illustration and accompanying text vary depending on the context.
+
+### Empty States
+Empty state illustrations provide context when a page or component has no data to display.
+
+**Use for:**
+- Empty object list views (opportunities, leads, cases, contacts)
+- Empty feeds (activity feeds, Chatter feeds)
+- Empty dashboards or reports
+- Blank canvas states requiring user action
+
+### Informational
+Informational illustrations support users as they explore new features, learn workflows, or encounter maintenance states.
+
+**Use for:**
+- System maintenance or scheduled downtime
+- Authentication or connection prompts
+- Onboarding and setup workflows
+- Feature discovery or walkthrough introductions
+
+### Error States
+Error state illustrations offer reassurance and guidance when something goes wrong.
+
+**Use for:**
+- Page not found (404 errors)
+- Access denied or permission errors
+- Data unavailable or loading failures
+- Lightning Experience compatibility issues
+- Broken links or deleted content
+- System failures or service disruptions
+
+---
+
+## Mobile Guidelines
+
+When using illustrations on mobile devices, adjustments are necessary to ensure a consistent experience within smaller viewports.
+
+- **Maximum Width:** 300px
+- **Maximum Height:** 180px
+- **UI Text:** Labels and body text must be shorter and use smaller font scales.
+
+---
+
+## Layouts
+
+Illustrations can surface within Salesforce products in three primary layout contexts:
+
+### Full Page
+Used for major system states like 404 errors or initial onboarding where the illustration is the primary focus of the entire viewport.
+
+### Main Body
+Used within the main content area of a page, often for empty states in list views or dashboards.
+
+### Panel or Sidebar
+Used in narrower containers like utility panels, sidebars, or docked composers.
+
+---
+
+## Recommended Specs
+
+The following specifications define the typography and sizing constraints for illustrations across desktop and mobile platforms.
+
+### Desktop Specs
+
+| Description | Styling Hooks | Value |
+|-------------|---------------|-------|
+| Title text | `--slds-g-font-scale-4` | - |
+| Body text | `--slds-g-font-scale-2` | - |
+| Text color | `--slds-g-color-on-surface-1` | - |
+| Maximum image width | - | 600px |
+| Maximum image height | - | 360px |
+
+### Mobile Specs
+
+| Description | Styling Hooks | Value |
+|-------------|---------------|-------|
+| Title text | `--slds-g-font-scale-3` | - |
+| Body text | `--slds-g-font-size-base` | - |
+| Text color | `--slds-g-color-on-surface-1` | - |
+| Maximum image width | - | 300px |
+| Maximum image height | - | 180px |
+
+---
+
+## UI Text Guidelines
+
+UI text for illustrations must be clear, concise, and helpful. While these examples serve as guidelines, text should always be adapted to the specific context.
+
+| State | Title | Body |
+|-------|-------|------|
+| Empty | Hmm… | No opportunities to display. |
+| Empty | Collaborate with others | No updates here yet. |
+| Informational | We are down for maintenance | Sorry for the inconvenience. We’ll be back shortly. |
+| Informational | You’re not connected to Google Drive | Let’s get you authenticated. [Connect to Google Drive] |
+| Error | Page not available | Maybe the page was deleted, the URL is incorrect, or something else went wrong. |
+| Error | You don’t have access to this page | If you think you should have access, ask your admin for help. |
+| Error | Data not available | The data you’re trying to access isn’t available. It might be due to a system error. |
+
+---
+
+## Usage and Best Practices
+
+### Recommended Usage (Where & Why)
+
+Illustrations are used to enhance scannability and provide visual context in specific scenarios. They are typically implemented in:
+
+- **Empty states:** To provide context and reduce the "dead end" feeling of a blank page, guiding users on how to populate data (e.g., list views, dashboards).
+- **Informational moments:** To support users during system maintenance, exploration of new features, or onboarding/setup workflows.
+- **Error states:** To soften the impact of system failures or restricted access and provide a clear path forward (e.g., 404 pages, lack of permissions).
+- **Feeds:** To encourage collaboration within activity or Chatter feeds.
+
+### Implementation Constraints
+
+To maintain SLDS visual consistency and performance, adhere to these constraints:
+
+- **One per page:** Use only one illustration per page. Multiple illustrations create visual clutter and distract from the primary task.
+- **Avoid small containers:** Do not use illustrations inside related lists, cards, or narrow components. Use plain inline text or icons for these areas.
+- **No direct action feedback:** Do not use illustrations as feedback for direct user actions. Toasts, popovers, or banners are better suited for these interactions.
+
+### Visual Standards
+
+#### Character Positioning
+
+Characters add personality but must not dominate the visual hierarchy of an illustration.
+
+#####  Do
+
+- Keep characters in the background to maintain focus on the message and system state.
+- Integrate characters as supporting elements that enhance the context without becoming the primary focal point.
+
+#####  Don't
+
+- Avoid placing characters at the forefront of an illustration, as it can distract from the functional purpose of the screen.
+- Never use characters as the sole indicator of the illustration's meaning.
+
+---
+
+## Implementation Workflow
+
+Follow this sequence when implementing illustrations in your components:
+
+### Step 1: Identify Illustration Need
+Determine the state you are communicating:
+- **Is the container empty?** (list views, feeds, dashboards)
+- **Is the state informational?** (maintenance, onboarding, configuration)
+- **Is there an error?** (page not found, no access, system failure)
+
+### Step 2: Select Illustration Type
+Choose an illustration that matches the tone and purpose identified in Step 1. Ensure the visual style is consistent with SLDS standards.
+
+### Step 3: Apply Recommended Specs
+Use the appropriate styling hooks for typography and respect the maximum dimensions for the target platform (Desktop vs. Mobile).
+
+### Step 4: Add Accompanying UI Text
+Write clear, concise, and actionable text. Ensure the body text includes a resolution path (e.g., a link to create a record or contact support).
+
+### Step 5: Validate Accessibility
+Ensure the illustration enhances the text and that all essential information is available via text. Verify that the layout works across different screen sizes and density settings.
+
+---
+
+## Pre-Implementation Checklist
+
+Before finalizing any illustration implementation, verify:
+
+| Requirement | Status |
+|-------------|--------|
+| **Classification & Selection** | |
+| Illustration type matches the system state (empty/informational/error) | [ ] |
+| Illustration chosen aligns with Salesforce approachable/inclusive brand | [ ] |
+| **Styling & Specs** | |
+| Typography uses recommended styling hooks (`--slds-g-font-scale-*`) | [ ] |
+| Maximum dimensions respected for target platform (600x360 desktop, 300x180 mobile) | [ ] |
+| One illustration per page limit maintained | [ ] |
+| **Content & Copy** | |
+| UI text provides clear title and helpful body content | [ ] |
+| Actionable resolution path provided (e.g., links or buttons) | [ ] |
+| **Accessibility** | |
+| Illustration enhances rather than replaces textual content | [ ] |
+| Sufficient contrast between text and background | [ ] |
+| **Context & Placement** | |
+| Layout context correctly identified (full page, main body, panel) | [ ] |
+| Illustration used outside of related lists and cards | [ ] |
+
+**Target outcome:** Purposeful, engaging illustrations that guide users through the Salesforce experience while maintaining brand consistency and accessibility standards.

package/skills/applying-slds/guidance/overviews/shadows.md

@@ -0,0 +1,176 @@
+---
+id: slds.guidance.overview.shadows
+title: Shadows and Elevation Overview
+description: Foundational guidance for implementing shadows and visual depth in SLDS
+summary: "Comprehensive shadow guidance covering elevation levels, component shadow mappings, directional shadows, and accessibility considerations. Explains box-shadow concepts and stacking order relationships."
+
+artifact_type: overview
+domain: overviews
+topic: shadows
+
+content_format: narrative
+complexity: foundational
+audience: [implementer, designer]
+
+tasks: [learn, choose, implement]
+
+refs:
+  - slds.guidance.hooks.shadows
+
+tags: [shadows, elevation, depth, visual-hierarchy, stacking]
+keywords: [box shadow, elevation levels, visual depth, stacking order, z-index, component shadows]
+---
+
+# Shadows and Elevation Guidance for SLDS Implementation
+
+**Purpose:** This document provides guidance for implementing shadows in Salesforce Lightning Design System. Shadows add depth and dynamic layers to the UI, making it look more interesting and less static. When implementing components and layouts, follow these guidelines to ensure visual hierarchy and elevation are communicated effectively.
+
+---
+
+## About Shadows
+
+### What is Box Shadow?
+
+The `box-shadow` CSS property adds a shadow effect to an element. This property sets values for horizontal and vertical offsets, blur radius, spread radius, and shadow color. The combination of these properties creates a shadow around the frame of an element.
+
+Box shadows indicate elevation and are applied to elements to show which elements are on top of one another. Elevation is applied to elements to show that surfaces can move on top of one another.
+
+The SLDS 2 design uses soft shadows to create a sense of depth and dimension in the user interface. They also help separate components from each other and create a more realistic look.
+
+The styling hook for shadows uses the label `shadow`.
+
+### Elevation System
+
+When applying a shadow, match the priority or stacking order of the elements. Elements with a higher stacking order or which appear on top of others on the page should have higher shadow values. Leverage the z-index property to manage stacking order, and ensure that the elements with the highest shadow value appear above others on the page.
+
+**Elevation Levels:**
+
+| Level | Shadow Hook | Description |
+|-------|-------------|-------------|
+| Base Level | No shadow | Components on the surface that don't cover other components |
+| Elevation Level 1 | `--slds-g-shadow-1` | Subtle depth |
+| Elevation Level 2 | `--slds-g-shadow-2` | Moderate depth |
+| Elevation Level 3 | `--slds-g-shadow-3` | Prominent depth |
+| Elevation Level 4 | `--slds-g-shadow-4` | Maximum depth |
+
+### Component Shadow Usage
+
+| Shadow Hook | Components |
+|-------------|------------|
+| `--slds-g-shadow-1` | Page headers, joined tables, filter panels, dropdowns, inline edit, images, slider handles |
+| `--slds-g-shadow-2` | Menu, docked form footer, docked utility bar, color picker, notifications |
+| `--slds-g-shadow-3` | Panel, docked composer, tooltip, toast |
+| `--slds-g-shadow-4` | Modal, popover, App Launcher |
+
+### Base Level (No Shadow)
+
+Components that are **base level** sit on the surface and don't cover up other components. Base level components do not have shadows in the SLDS 2 design.
+
+The background color of a base level component depends on the color of the surface it sits on:
+- On a gray surface: A base level component has a white background
+- On a white surface: A base level component has a white background with a border
+
+---
+
+## Shadow Types
+
+### Depth Shadows
+
+Depth shadows communicate elevation and visual hierarchy. They indicate which elements appear above others in the stacking order.
+
+**Hook Pattern:** `--slds-g-shadow-{n}` where `{n}` is the depth level
+
+- `shadow-1` through `shadow-4` provide increasing depth levels
+- `shadow-5` and `shadow-6` are aliases that inherit from `shadow-4`
+
+### Directional Shadows
+
+Directional shadow variants allow shadows to be cast in specific directions. These are useful for components that are positioned against edges of the screen.
+
+**Hook Pattern:** `--slds-g-shadow-{direction}-{n}` where `{direction}` is the shadow direction and `{n}` is the depth level
+
+**Directions:**
+- `block-start` — Upward shadow
+- `block-end` — Downward shadow (default direction, inherits from base shadow)
+- `inline-start` — Left shadow
+- `inline-end` — Right shadow
+
+### Focus Shadows
+
+Focus shadows provide visual feedback for keyboard navigation and accessibility. Focus states within the SLDS 2 design consist of a white border outline surrounded by a dark blue border outline. This style ensures that the focus state meets accessibility requirements for any background.
+
+**Hook Pattern:** `--slds-g-shadow-{type}-focus-1` where `{type}` is the focus style
+
+**Types:**
+- `outline-focus` — Simple outline focus
+- `outset-focus` — Double ring outset focus
+- `inset-focus` — Single ring inset focus
+- `inset-inverse-focus` — Double ring inset focus (inverse)
+
+### Inset Shadows (Component-Level)
+
+Button components use a hover bevel and inner shadow on click that is separate from the elevation system. Bevels and insets are only used on buttons and inputs where specified and shouldn't be used in custom situations.
+
+**Button shadows:**
+- `--slds-s-button-shadow-active` — Used on all buttons when pressed, regardless of color or border
+- `--slds-s-button-shadow-focus` — Focus state for buttons
+- `--slds-s-button-brand-shadow-hover` — Hover effect for brand buttons
+- `--slds-s-button-bordered-shadow-hover` — Hover effect for bordered/neutral buttons
+
+**Input shadows:**
+- `--slds-s-input-shadow-focus` — Used on active/focused input fields
+
+**Mark shadows (checkboxes, radios, toggles):**
+- `--slds-s-mark-shadow-checked` — Used on selected or active checkboxes, radio buttons, and checkbox toggles
+- `--slds-s-mark-shadow-focus` — Focus state for mark elements
+
+---
+
+## Available Styling Hooks
+
+> **For detailed usage patterns**, refer to the Shadows Styling Hooks documentation.
+
+### Global Shadow Hooks (`--slds-g-`)
+
+**Depth Shadows:**
+- `--slds-g-shadow-{1-6}`
+
+**Directional Shadows:**
+- `--slds-g-shadow-block-start-{1-4}`
+- `--slds-g-shadow-block-end-{1-4}`
+- `--slds-g-shadow-inline-start-{1-4}`
+- `--slds-g-shadow-inline-end-{1-4}`
+
+**Focus Shadows:**
+- `--slds-g-shadow-outline-focus-1`
+- `--slds-g-shadow-outset-focus-1`
+- `--slds-g-shadow-inset-focus-1`
+- `--slds-g-shadow-inset-inverse-focus-1`
+
+### Shared Shadow Hooks (`--slds-s-`)
+
+**Button Shadows:**
+- `--slds-s-button-shadow-focus`
+- `--slds-s-button-shadow-focus-inverse`
+- `--slds-s-button-shadow-active`
+- `--slds-s-button-brand-shadow-hover`
+- `--slds-s-button-bordered-shadow-hover`
+
+**Input Shadows:**
+- `--slds-s-input-shadow-focus`
+- `--slds-s-input-shadow-invalid`
+
+**Mark Shadows:**
+- `--slds-s-mark-shadow-focus`
+- `--slds-s-mark-shadow-checked`
+
+### Component Shadow Hooks (`--slds-c-`)
+
+**Button Variant Shadows:**
+- `--slds-c-button-success-shadow-hover`
+- `--slds-c-button-destructive-shadow-hover`
+- `--slds-c-button-inverse-shadow-hover`
+
+
+
+

package/skills/applying-slds/guidance/overviews/spacing.md

@@ -0,0 +1,216 @@
+---
+id: slds.guidance.overview.spacing-and-sizing
+title: Spacing and Sizing Overview
+description: Foundational principles for spacing and sizing decisions in SLDS
+summary: "Comprehensive spacing and sizing guidance covering the 4-point grid system, spacing scales, sizing scales, and responsive design patterns. Includes implementation workflow and pre-implementation checklist."
+
+artifact_type: overview
+domain: overviews
+topic: spacing-and-sizing
+
+content_format: narrative
+complexity: foundational
+audience: [implementer, designer]
+
+tasks: [learn, choose, implement]
+
+refs:
+  - slds.guidance.hooks.spacing
+
+tags: [spacing, sizing, layout, grid, margins, padding, dimensions]
+keywords: [4-point grid, spacing scale, sizing scale, margins, padding, gaps, responsive design, layout]
+---
+
+# Spacing and Sizing Guidance for SLDS Implementation
+
+**Purpose:** This document provides the foundational principles and constraints for all spacing and sizing decisions in Salesforce Lightning Design System. When implementing components and layouts, follow these guidelines to ensure visual harmony, hierarchy, and consistency across all experiences.
+
+---
+
+## Core Principles
+
+When working with spacing and sizing in UI interfaces, adhere to these foundational principles:
+
+1. **Establish harmony through consistency.** Spacing and sizing create predictable patterns that help users navigate interfaces efficiently. Use the spacing and sizing styling hooks consistently to create visual rhythm and balance.
+
+2. **Create hierarchy through deliberate spacing.** Strategic use of space directs user attention, differentiates grouped elements from unrelated ones, and establishes clear relationships between components.
+
+3. **Ensure scalability and responsiveness.** Components must adapt seamlessly across devices and screen sizes. Use relative units and the SLDS styling hooks to support responsive design patterns.
+
+---
+
+## Spacing Fundamentals
+
+### What is Spacing?
+
+Spacing controls the empty areas around or within components, such as margins, padding, and gaps between elements. In the context of styling hooks, spacing refers to padding or margins applied around an element.
+
+**Spacing defines these visual aspects:**
+- Proper alignment of components
+- Clear differentiation of grouped and unrelated elements
+- White space that directs user attention to key content or actions
+
+### Benefits of Effective Spacing
+
+Effective spacing provides these benefits:
+- **Improves readability** by preventing visual clutter and creating breathing room
+- **Reduces cognitive load** by establishing clear visual relationships
+- **Enhances usability** by making interactive elements easier to target and distinguish
+
+### The 4-Point Grid System
+
+SLDS spacing follows a modular scale based on multiples of 4, aligning with the 4-point grid system. This mathematical foundation ensures consistent spacing relationships throughout the interface.
+
+**System Architecture:**
+- Base unit: 0.25rem (4px equivalent)
+- Scale progression: Each step increases in predictable increments
+- Values are relative to root font size for scalability
+
+### Density-Aware Spacing
+
+SLDS provides density-aware spacing hooks that automatically adapt when the system switches between comfy and compact display density settings. These hooks ensure components respond appropriately to user density preferences.
+
+**Hook Patterns:**
+- **All-Sides:** `--slds-g-spacing-var-{size}` - Applies equally to top, bottom, left, right
+- **Vertical (Block):** `--slds-g-spacing-var-block-{size}` - Top and bottom margins or padding
+- **Horizontal (Inline):** `--slds-g-spacing-var-inline-{size}` - Left and right margins or padding
+
+Where `{size}` represents the scale value appropriate for your spacing need.
+
+> **For complete density-aware hook details** including comfy and compact values, refer to the Spacing and Sizing Styling Hooks documentation.
+
+---
+
+## Sizing Fundamentals
+
+### What is Sizing?
+
+Sizing refers to the dimensions of a component, such as height, width, or size variants. In the context of styling hooks, sizing refers to the fixed height or width of an element. When sizes are consistent, it's easier for users to predict where things will be on the page. This predictability makes the interface easier to use.
+
+**Sizing defines these aspects:**
+- Physical dimensions of elements like buttons, icons, and cards
+- Scalable size options (small, medium, large) to accommodate different contexts
+- Responsive behavior to ensure designs function well on all screen sizes
+
+### Benefits of Consistent Sizing
+
+Consistent sizing provides these benefits:
+- **Creates predictability** by establishing recognizable component sizes
+- **Enhances usability** by making interactive targets appropriately sized
+- **Supports responsiveness** by providing size options that scale appropriately
+
+### The 8-Point Grid System
+
+While spacing uses a 4-point grid, sizing aligns with an 8-point grid system using multiples of 8. This ensures dimension values work harmoniously with the spacing system while providing appropriate scaling for component dimensions.
+
+**System Architecture:**
+- Smaller increments for precise control (1-9)
+- Larger increments for major dimensions (10-16)
+- Values are relative to root font size for scalability
+
+---
+
+## Understanding Padding vs. Margin
+
+When implementing layouts, understand the distinction between padding and margin as they serve different purposes:
+
+**Padding:**
+- Controls **internal spacing** within a component
+- Creates breathing room between a container's edge and its content
+- Affects the component's total dimensions (when using border-box)
+- Use spacing hooks for padding values
+
+**Margin:**
+- Defines **external spacing** around a component
+- Creates separation between adjacent elements
+- Does not affect the component's own dimensions
+- Use spacing hooks for margin values
+
+**Design systems follow a consistent margin strategy** so that components interact predictably and maintain harmonious spacing throughout the interface. Apply spacing values systematically rather than arbitrarily to maintain this consistency.
+
+---
+
+## Implementation Workflow
+
+Follow this sequence when implementing any spacing or sizing solution:
+
+### Step 1: Identify the Spacing/Sizing Need
+
+Determine what you're trying to accomplish:
+- **For spacing:** Is this internal space (padding) or external space (margin)?
+- **For spacing:** Does this need to adapt to density settings (use density-aware hooks)?
+- **For sizing:** Are you setting dimensions (height/width) for an element?
+- **For sizing:** Is this for a small element (icon, button) or larger container?
+
+### Step 2: Choose the Appropriate Scale
+
+Evaluate the visual hierarchy and relationship:
+- **Smaller values (1-4):** Compact layouts, tight spacing, small elements
+- **Medium values (5-8):** Standard spacing, common component sizes
+- **Larger values (9-12/16):** Section spacing, large containers, major divisions
+
+### Step 3: Apply the Styling Hook
+
+Use the appropriate hook for your context:
+- **Standard spacing:** `--slds-g-spacing-*` for fixed spacing values
+- **Density-aware spacing (all sides):** `--slds-g-spacing-var-*` for adaptive spacing
+- **Density-aware vertical spacing:** `--slds-g-spacing-var-block-*` for top/bottom adaptive spacing
+- **Density-aware horizontal spacing:** `--slds-g-spacing-var-inline-*` for left/right adaptive spacing
+- **Element sizing:** `--slds-g-sizing-*` for dimensions
+
+### Step 4: Handle Exceptions
+
+If no standard hook matches the requirement:
+1. Document why standard patterns don't apply
+2. Evaluate if a combination of hooks could achieve the goal
+3. Ensure the custom approach maintains visual consistency
+4. Flag for design system team review
+
+### Step 5: Validate Implementation
+
+Before finalizing, verify the implementation using the Pre-Implementation Checklist below to ensure all spacing and sizing requirements are met.
+
+---
+
+## Pre-Implementation Checklist
+
+Before generating or modifying any spacing or sizing related code, verify:
+
+| Requirement | Status |
+|-------------|--------|
+| **Need Identification** | |
+| Spacing need identified (padding vs. margin, internal vs. external space) | [ ] |
+| Sizing need identified (element dimensions vs. container size) | [ ] |
+| Determined if spacing should adapt to density settings | [ ] |
+| **Hook Selection & Scale** | |
+| Appropriate hook selected from defined scale (no hard-coded pixel values) | [ ] |
+| Scale value chosen matches visual hierarchy (1-4 compact, 5-8 standard, 9-12/16 sections) | [ ] |
+| Correct hook type selected (spacing vs. spacing-var vs. sizing) | [ ] |
+| **Grid System Alignment** | |
+| Spacing aligns with 4-point grid system | [ ] |
+| Sizing aligns with 8-point grid system | [ ] |
+| **Proper Hook Usage** | |
+| Spacing hooks used only for margins/padding (not dimensions) | [ ] |
+| Sizing hooks used only for dimensions (not spacing) | [ ] |
+| Semantic styling hooks used (no hard-coded values) | [ ] |
+| **Density & Responsiveness** | |
+| Density-aware hooks used when components need to adapt | [ ] |
+| Density-aware hooks selected support both comfy and compact modes where applicable | [ ] |
+| Layout responsive design requirements applied for viewport adaptability | [ ] |
+| Works across all viewport sizes | [ ] |
+| **Visual Consistency** | |
+| Visual hierarchy maintained through spacing choices | [ ] |
+| Component spacing consistent with similar elements | [ ] |
+| Follows established patterns for similar components | [ ] |
+
+**Target outcome:** Harmonious, predictable interfaces that maintain visual consistency and adapt seamlessly across devices, screen sizes, and user density preferences.
+
+---
+
+## Related Documentation
+
+For detailed implementation guidance, refer to:
+- **Spacing and Sizing Styling Hooks** - For complete hook listings, density-aware values, and usage patterns
+- **Color Overview** - For understanding how spacing interacts with visual depth and surface layering
+- **Accessibility Overview** - For ensuring spacing supports touch targets and keyboard navigation
+