@salesforce/afv-skills 1.13.0 → 1.15.0

package/skills/applying-slds/guidance/overviews/display-density.md

@@ -0,0 +1,366 @@
+---
+id: slds.guidance.overview.display-density
+title: Display Density Overview
+description: Foundational guidance for implementing comfy and compact density modes in SLDS
+summary: "Comprehensive display density guidance covering comfy vs compact settings, density-aware styling hooks, and responsive component design. Includes implementation workflow and common pitfalls."
+
+artifact_type: overview
+domain: overviews
+topic: display-density
+
+content_format: narrative
+complexity: foundational
+audience: [implementer, designer]
+
+tasks: [learn, choose, implement]
+
+refs:
+  - slds.guidance.hooks.spacing
+  - slds.guidance.hooks.typography
+
+tags: [display-density, comfy, compact, responsive, user-preferences]
+keywords: [comfy mode, compact mode, density-aware, user preferences, responsive design, data density, form layout]
+---
+
+# Display Density Guidance for SLDS Implementation
+
+**Purpose:** This document provides the foundational principles and guidance for implementing display density in Salesforce Lightning Design System. When working with SLDS components and interfaces, follow these guidelines to ensure consistent user experiences across both comfy and compact density settings.
+
+---
+
+## About Display Density
+
+Display density controls the spacing and layout of interface elements within a given screen area. Salesforce Lightning Design System 2 (SLDS 2) offers two density settings: **comfy** and **compact**.
+
+**Comfy** (the default setting) places labels on top of fields and adds more space between page elements, creating a spacious view with increased vertical and horizontal spacing. **Compact** increases visual density with labels on the same line as fields and less space between lines, allowing more information to be visible simultaneously.
+
+**Key Requirement:** Because users select which display density setting to use, design Salesforce interfaces to work well in both settings. Display density is a user preference that must be supported universally across all implementations.
+
+---
+
+## Core Principles
+
+When working with display density in UI interfaces, adhere to these foundational principles:
+
+1. **Respect user preferences.** Display density is a user-controlled setting, not a design decision. Interfaces must function equally well in both comfy and compact modes, as users select their preferred density based on their needs and workflows.
+
+2. **Design for both settings from the start.** Implement components with density-aware styling hooks to ensure seamless adaptation. Retrofitting density support is more complex than building it in from the beginning.
+
+3. **Maintain accessibility across densities.** Both comfy and compact modes must meet WCAG standards. Touch targets, text readability, and visual hierarchy must remain accessible regardless of the density setting.
+
+4. **Use density-aware styling hooks strategically.** Not every element needs to adapt to density changes. Identify which components truly benefit from density responsiveness—typically data-dense elements like tables, lists, forms, and navigation.
+
+---
+
+## Comfy Setting
+
+Comfy is the default density setting in Salesforce. The comfy setting offers a spacious view with increased vertical and horizontal spacing, and vertically stacked form elements.
+
+### Benefits of Comfy Setting
+
+The comfy setting provides these benefits:
+
+- **Better accommodation for localized content** with longer text strings, reducing truncation and improving internationalization support
+- **Enhanced visual separation** for improved accessibility, particularly benefiting users with cognitive disabilities or those who benefit from clear visual grouping
+- **Reduced cognitive load and better scannability**, particularly beneficial for new users learning the system or users navigating complex workflows
+
+### Comfy Setting Guidelines
+
+When implementing components for comfy mode, address these factors:
+
+- **Critical information prominence:** Ensure that critical information remains prominent despite additional whitespace. The increased spacing should enhance, not diminish, the visibility of important content.
+- **Localized content testing:** Test with localized content to verify that spacing accommodates longer text strings common in languages like German or Finnish.
+- **Vertical scrolling requirements:** Elements use more vertical space in comfy mode, which may increase scrolling requirements for long forms or data-heavy screens.
+
+---
+
+## Compact Setting
+
+Compact mode creates a denser view with reduced spacing between elements, more information visibility in the viewport, and horizontally stacked form elements.
+
+### Benefits of Compact Setting
+
+The compact setting provides these benefits:
+
+- **Improved efficiency** when working with large data sets, allowing users to see and compare more records without scrolling
+- **Reduced scrolling** for data-heavy screens, improving workflow efficiency for power users
+- **More information visible simultaneously**, supporting tasks that require viewing multiple data points at once
+
+### Compact Setting Guidelines
+
+When implementing components for compact mode, address these critical factors:
+
+- **Touch target accessibility:** Verify that touch targets remain large enough for comfortable interaction, meeting minimum size requirements of 44×44 pt/dp/px for mobile and 24×24 CSS pixels for desktop (with 44×44 recommended for Salesforce mixed environments).
+- **Text readability:** Ensure that text remains readable with reduced spacing, maintaining appropriate line height and letter spacing for legibility.
+- **Horizontal layout behavior:** Test how horizontal layouts behave in narrower viewports, ensuring form elements that stack horizontally don't create usability issues on smaller screens.
+
+---
+
+## User Control of Density
+
+To personalize the look of Lightning Experience, users can change their display density setting through their profile menu. After a user changes their display density setting, the page automatically refreshes to apply the new density. Salesforce administrators can also set org-wide defaults.
+
+**Implementation Requirement:** When designing and developing interfaces, ensure that the interface adapts appropriately to both density settings. Components must respond gracefully to density changes without breaking layouts or compromising functionality.
+
+---
+
+## Density-Aware Styling Hooks
+
+Use density-aware styling hooks when specific areas, components, spacing, and typographical elements require the ability to adapt or respond to a user's density setting. Density-aware styling hooks are denoted by **"var"** in the naming convention (e.g., `--slds-g-spacing-var-1`) and act as responsive variables that change their values when the density setting changes.
+
+### Elements That Benefit from Density-Aware Hooks
+
+Implement density-aware styling hooks for these element types:
+
+- **Data-dense components** like tables, lists, and grids where information density directly impacts usability
+- **Form layouts and field arrangements** where spacing affects scannability and completion efficiency
+- **Card and container padding** where internal spacing adapts to user preference
+- **Navigation and toolbar spacing** where compact spacing supports power users while comfy spacing aids discoverability
+
+### Matching Hooks to Properties
+
+When implementing density-aware styling hooks, match the styling hooks with the appropriate CSS properties:
+
+- **For all-sides spacing (top-bottom-left-right):** Use `--slds-g-spacing-var-[size]`
+- **For horizontal spacing (left-right):** Use `--slds-g-spacing-var-inline-[size]`
+- **For vertical spacing (top-bottom):** Use `--slds-g-spacing-var-block-[size]`
+- **For font sizes:** Use `--slds-g-font-scale-var-[size]`
+- **For font line height:** Use `--slds-g-font-lineheight-var-base`
+
+### Implementation Example
+
+When the system detects a density change, properties using density-aware hooks automatically adapt:
+
+```css
+/* This hook provides different values based on density setting */
+.my-component {
+  padding: var(--slds-g-spacing-var-4);
+  /* Comfy: 1rem | Compact: 0.5rem */
+}
+```
+
+---
+
+## Available Density-Aware Styling Hooks
+
+The following sections list all density-aware styling hooks available in SLDS. For detailed usage patterns, dos and don'ts, and accessibility requirements for spacing-related hooks, refer to the Spacing and Sizing Styling Hooks documentation.
+
+### Density-Aware Spacing (All Sides)
+
+These density-aware styling hooks control spacing applied equally to all sides of an element (top, bottom, left, right) when the system switches between comfy and compact display density settings.
+
+**Hook Pattern:** `--slds-g-spacing-var-{size}` where `{size}` is the spacing size
+
+> **Reference:** See Spacing and Sizing Styling Hooks for complete usage guidance, accessibility requirements, and implementation patterns.
+
+### Density-Aware Vertical Spacing (Block Axis)
+
+These density-aware styling hooks control spacing along the vertical (block) axis when the system switches between comfy and compact display density settings. This spacing corresponds to top and bottom margins or paddings.
+
+**Hook Pattern:** `--slds-g-spacing-var-block-{size}` where `{size}` is the spacing size
+
+> **Reference:** See Spacing and Sizing Styling Hooks for complete usage guidance, accessibility requirements, and implementation patterns.
+
+### Density-Aware Horizontal Spacing (Inline Axis)
+
+These density-aware styling hooks control spacing along the horizontal (inline) axis when the system switches between comfy and compact display density settings. This spacing corresponds to left and right margins or paddings.
+
+**Hook Pattern:** `--slds-g-spacing-var-inline-{size}` where `{size}` is the spacing size
+
+> **Reference:** See Spacing and Sizing Styling Hooks for complete usage guidance, accessibility requirements, and implementation patterns.
+
+### Density-Aware Line Height
+
+This density-aware styling hook controls the line height when the system switches between comfy and compact display density settings.
+
+**Hook Pattern:** `--slds-g-font-lineheight-var-base`
+
+### Density-Aware Font Scale
+
+These density-aware styling hooks control the font scale when the system switches between comfy and compact display density settings.
+
+**Hook Pattern:** `--slds-g-font-scale-var-{size}` where `{size}` is the density-aware scale step
+
+---
+
+## Responsive Density
+
+Density settings control global spacing, but different screen sizes require additional responsive adjustments. Combine density-aware hooks with responsive design patterns to create interfaces that adapt to both user preferences and device constraints.
+
+### Implementing Responsive Density
+
+When building responsive components, follow this approach:
+
+1. **Use SLDS standard CSS media queries** (30em, 48em, 64em, 80em) to define responsive breakpoints
+2. **Apply appropriate SLDS density-aware styling hooks** within each media query breakpoint
+3. **Test thoroughly** across device sizes in both density settings to ensure layouts work in all combinations
+
+### Responsive Density Example
+
+Use this pattern for implementing responsive table cell padding that adapts to both viewport size and density setting:
+
+```css
+/* Default (Mobile-first) padding */
+.my-custom-table td,
+.my-custom-table th {
+  padding: var(--slds-g-spacing-var-1); /* Smallest padding for narrow screens */
+}
+
+/* Medium screens and up (768px+) */
+@media (min-width: 48em) {
+  .my-custom-table td,
+  .my-custom-table th {
+    /* Increase padding for tablets / small laptops */
+    padding: var(--slds-g-spacing-var-3);
+  }
+}
+
+/* Large screens and up (1024px+) */
+@media (min-width: 64em) {
+  .my-custom-table td,
+  .my-custom-table th {
+    /* Use larger padding for standard desktops */
+    padding: var(--slds-g-spacing-var-4);
+  }
+}
+```
+
+---
+
+## Custom Component Guidelines
+
+When building custom components that need to respond to density, follow these guidelines to ensure consistent behavior with SLDS standards.
+
+### Design Guidelines
+
+When implementing custom density-aware components:
+
+- **Analyze similar SLDS components:** Review how existing SLDS components adapt to density and follow similar patterns for consistency
+- **Identify which elements need to adapt:** Not everything needs to respond to density changes. Focus density adaptation on spacing, typography, and form layouts
+- **Use appropriate styling hooks:** Select hooks that match the property's purpose (spacing-var for padding/margin, font-scale-var for text sizing)
+- **Test in both density settings:** Verify that your component works well in both comfy and compact modes before finalizing implementation
+
+### Testing Custom Density Implementation
+
+When validating custom density implementations, ensure that interfaces work well across display density settings:
+
+- **Test the same screens in both comfy and compact settings** to verify visual consistency and functional parity
+- **Check rendering in different screen regions and viewports** to ensure responsive density works across device sizes
+- **Verify that touch targets remain accessible in compact setting**, meeting minimum size requirements (44×44 pt/dp/px recommended for Salesforce)
+- **Confirm that text remains readable and hierarchy is maintained** with reduced spacing in compact mode
+- **Verify that localized content displays properly** in both density settings, particularly for languages with longer text strings
+
+---
+
+## SLDS Components with Built-in Density Support
+
+SLDS includes several components with built-in density adaptation that automatically respond to density changes through density-aware styling hooks.
+
+### Components with Automatic Density Adaptation
+
+The following components include density-aware styling hooks that enable automatic adjustments for different display densities:
+
+- [Cards](https://www.lightningdesignsystem.com/2e1ef8501/p/33cd77-cards)
+- [File selector](https://www.lightningdesignsystem.com/2e1ef8501/p/77d584-file-selector)
+- [Tabs](https://www.lightningdesignsystem.com/2e1ef8501/p/1152cf-tabs)
+
+### Component Blueprints with Configurable Density Support
+
+When using component blueprints, use the standard SLDS markup patterns and CSS classes. The following component blueprints include density-aware styling hooks:
+
+- [Cards](https://www.lightningdesignsystem.com/2e1ef8501/p/33cd77-cards)
+- [Feed](https://v1.lightningdesignsystem.com/components/feeds/)
+- [File selector](https://www.lightningdesignsystem.com/2e1ef8501/p/77d584-file-selector)
+- [Page header](https://v1.lightningdesignsystem.com/components/page-headers/)
+- [Path](https://v1.lightningdesignsystem.com/components/path/)
+- [Split view](https://v1.lightningdesignsystem.com/components/split-view/)
+- [Tabs](https://www.lightningdesignsystem.com/2e1ef8501/p/1152cf-tabs)
+
+> **Reference:** To access component blueprints, see the [Salesforce Lightning Design System 1](https://v1.lightningdesignsystem.com/) website.
+
+---
+
+## Implementation Workflow
+
+Follow this sequence when implementing density-aware components:
+
+### Step 1: Determine Density Requirement
+
+Identify whether your component needs density adaptation:
+- **Does the component contain data-dense elements?** (tables, lists, grids)
+- **Does spacing significantly impact usability?** (forms, cards, navigation)
+- **Will users benefit from density control?** (power users vs. new users)
+
+If the answer is yes to any of these, implement density-aware hooks.
+
+### Step 2: Select Appropriate Hooks
+
+Choose the correct density-aware hooks for your use case:
+- **For padding/margin on all sides:** Use `--slds-g-spacing-var-*`
+- **For vertical spacing only:** Use `--slds-g-spacing-var-block-*`
+- **For horizontal spacing only:** Use `--slds-g-spacing-var-inline-*`
+- **For text sizing:** Use `--slds-g-font-scale-var-*`
+- **For line height:** Use `--slds-g-font-lineheight-var-base`
+
+### Step 3: Implement with Appropriate Scale
+
+Apply hooks with appropriate scale values:
+- **Smaller values (1-4):** For compact elements, tight spacing
+- **Medium values (5-8):** For standard component spacing
+- **Larger values (9-12):** For section spacing and major divisions
+
+### Step 4: Validate Implementation
+
+Before finalizing, verify the implementation using the Pre-Implementation Checklist below to ensure all requirements are met across both density settings.
+
+---
+
+## Pre-Implementation Checklist
+
+Before generating or modifying any display density related code, verify:
+
+| Requirement | Status |
+|-------------|--------|
+| **Analysis & Planning** | |
+| Component analyzed to determine if density adaptation is beneficial | [ ] |
+| Similar SLDS components reviewed for density patterns | [ ] |
+| Identified which elements need to adapt vs. remain fixed | [ ] |
+| **Hook Selection** | |
+| Appropriate density-aware hooks selected (spacing-var, font-scale-var, etc.) | [ ] |
+| Hooks matched to correct CSS properties (spacing for margin/padding, font-scale for text) | [ ] |
+| Appropriate scale values chosen (1-4 compact, 5-8 standard, 9-12 sections) | [ ] |
+| No hard-coded spacing or sizing values (all use styling hooks) | [ ] |
+| **Testing: Comfy Mode** | |
+| Component tested in comfy density setting | [ ] |
+| Visual hierarchy maintained with increased spacing | [ ] |
+| Localized content accommodated (longer text strings) | [ ] |
+| Critical information remains prominent despite additional whitespace | [ ] |
+| **Testing: Compact Mode** | |
+| Component tested in compact density setting | [ ] |
+| Touch targets meet minimum size requirements (44×44 pt/dp/px recommended) | [ ] |
+| Text remains readable with reduced spacing and line height | [ ] |
+| Horizontal layouts work in narrower viewports | [ ] |
+| **Cross-Density Validation** | |
+| Visual consistency maintained - component maintains its visual identity in both modes | [ ] |
+| Functional parity confirmed - all functionality works equally well in both densities | [ ] |
+| Component behavior consistent with similar SLDS components | [ ] |
+| **Responsive & Accessibility** | |
+| Responsive breakpoints tested with both density settings | [ ] |
+| Component works across viewport sizes in both densities | [ ] |
+| Accessibility standards met in both modes (WCAG 2.1 AA) | [ ] |
+
+**Target outcome:** Interfaces that respect user density preferences while maintaining accessibility, visual consistency, and functional parity across both comfy and compact settings.
+
+---
+
+## Related Documentation
+
+For detailed implementation guidance and related concepts, refer to:
+
+- **Spacing and Sizing Styling Hooks** - For complete density-aware spacing hook details, usage patterns, dos and don'ts, and accessibility requirements
+- **Spacing and Sizing Overview** - For foundational spacing and sizing principles and the grid system architecture
+- **Accessibility Overview** - For ensuring touch targets, contrast, and keyboard navigation work across density settings
+- **Typography Guidance** (when available) - For font-scale density hooks and line height implementation patterns
+- **Color Overview** - For understanding how spacing and density interact with visual hierarchy and surface layering
+
+

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

@@ -0,0 +1,240 @@
+---
+id: slds.guidance.overview.icons
+title: Icons Overview
+description: Foundational principles and guidance for implementing icons in SLDS
+summary: "Comprehensive icon guidance covering utility, object, action, doctype, and custom icons. Includes icon selection decision tree, accessibility requirements, and visual specifications."
+
+artifact_type: overview
+domain: overviews
+topic: icons
+
+content_format: narrative
+complexity: foundational
+audience: [implementer, designer]
+
+tasks: [learn, choose, implement]
+
+refs:
+  - slds.guidance.icons
+  - slds.guidance.accessibility.overview
+
+tags: [icons, iconography, utility-icons, object-icons, accessibility]
+keywords: [icon types, utility icons, object icons, action icons, icon accessibility, informational icons, decorative icons]
+---
+
+# Icons Guidance for SLDS Implementation
+
+**Purpose:** This document provides the foundational principles and guidance for implementing icons in Salesforce Lightning Design System. When working with SLDS components and interfaces, follow these guidelines to ensure consistent, readable, and accessible iconography across all experiences.
+
+---
+
+## About Icons
+
+Icons are symbols used to represent features, functionality, or content. They provide visual cues that help users navigate and interact with the interface more efficiently. Salesforce icon design blends professional and playful qualities, prioritizing simplicity, approachability, and legibility.
+
+**Key Requirement:** To ensure an inclusive experience, implement icon accessibility by distinguishing between informational and decorative icons.
+
+---
+
+## Core Principles
+
+When working with icons in UI interfaces, adhere to these four foundational principles:
+
+1. **Choose the correct icon type for the context.** Match the icon category (utility, object, action, doctype, or product) to its specific functional role in the UI.
+2. **Ensure accessibility compliance.** Distinguish between informational icons (requiring labels) and decorative icons (hidden from screen readers).
+3. **Maintain visual consistency.** Follow SLDS standards for stroke weight, corner radius, and color usage to ensure a cohesive system.
+4. **Follow the grid system and keyline shapes.** Align icons to the 8pt grid and use approved keyline shapes to maintain visual balance and weight.
+
+---
+
+## Icon Types
+
+SLDS includes five distinct icon types, each optimized for specific use cases and platforms.
+
+### 1. Utility Icons
+Utility icons are simple, single-color glyphs that identify labels and actions. They are the most commonly used icons across all device types.
+
+**Use for:**
+- UI-specific actions (Close, Search, Edit, Settings)
+- Global headers and navigation elements
+- Button groups, alerts, and toasts
+- Feed interactions (Share, Like, Comment)
+
+**Anatomy and Specs:**
+- **Grid Sizes:** 16x16px (small), 24x24px (standard).
+- **Stroke Weight:** 1px (for 16px), 2px (for 24px).
+- **Standard Scales:** 16x16, 24x24, 32x32, 48x48, and 60x60px.
+- **Color:** No fixed background shape; can be any color (typically matches adjacent text).
+
+**SLDS 2 Note:** Utility icons remain unchanged from SLDS 1.
+
+### 2. Object Icons (Standard and Custom)
+Object icons represent Salesforce entities. Standard icons are for core objects (e.g., Accounts), while custom icons represent customer-created objects.
+
+**Use for:**
+- Representing records in list views, search results, and page headers.
+- Identifying entity types in related lists and cards.
+
+**Anatomy and Specs:**
+- **Background Shape:** White glyph on a solid colored circular background.
+- **Grid Size:** 60x60px.
+- **Stroke Weight:** 6px.
+- **Corner Radius:** 6px (for glyph details).
+
+**SLDS 2 Note:** The background shape for standard object icons has updated from a square to a **circle**.
+
+> ** Accessibility Warning:** Not all custom object icons meet WCAG color contrast guidelines. Always pair them with text as decorative elements.
+
+### 3. Action Icons
+Action icons represent the primary ways users accomplish tasks on touch devices. They appear exclusively in the mobile action bar.
+
+**Use for:**
+- Touch-device specific actions (New Lead, Log a Call, Share Post).
+- Mobile action bar interactions.
+
+**Anatomy and Specs:**
+- **Background Shape:** White glyph on a colored circle.
+- **Grid Size:** 48x48px.
+- **Stroke Weight:** 4px.
+- **Artboard:** 52x52px with a 32x32px icon live area.
+
+### 4. Doctype Icons
+Doctype icons represent document file formats and are used when a file preview is unavailable.
+
+**Use for:**
+- Identifying file types (PDF, Word, Excel, Sheets, etc.).
+- Feeds, publishers, cards, and related lists where files are attached.
+
+**Anatomy and Specs:**
+- **Background Shape:** Vertical rectangle (56x64px) with a folded corner (earflap).
+- **Glyph:** White glyph or text abbreviation of the file extension.
+- **Corner Radius:** 6px.
+
+### 5. Product Icons
+Product icons represent official Salesforce applications and feature product-specific branding.
+
+**Use for:**
+- App Launcher (Desktop) at 48x48px.
+- Mobile device home screens and app headers.
+
+**Anatomy and Specs:**
+- **Glyph:** Two-color branded glyph on a white background.
+- **Stroke:** 4px rounded stroke weight.
+
+---
+
+## Accessibility
+
+Screen readers handle icons based on their functional role.
+
+### Informational Icons
+Icons that convey important information not present in surrounding text (e.g., a standalone button icon).
+- **Requirement:** Must include an `aria-label` or assistive text.
+- **Description Rule:** Describe the *purpose* (e.g., "Upload File"), not the *appearance* (e.g., "paperclip").
+
+### Decorative Icons
+Icons that reinforce adjacent text or provide purely visual interest.
+- **Requirement:** Must use an empty `alt=""` tag or be hidden from screen readers.
+- **Behavior:** Screen readers will skip these to avoid redundant announcements.
+
+---
+
+## Grid System and Keyline Shapes
+
+SLDS icons are built on an 8pt grid system to ensure visual consistency across the entire library. Icons utilize four standard keyline shapes based on BPMN diagram conventions:
+- **Circle**
+- **Square**
+- **Vertical Rectangle**
+- **Horizontal Rectangle**
+
+These shapes ensure that icons across different categories maintain consistent visual weight when appearing together.
+
+---
+
+## Mobile Tap Targeting
+
+When designing for mobile, ensure icons are easy to select by providing adequate spacing.
+- **Minimum Target Size:** Maintain a minimum tap target of 44x44px.
+- **Spacing:** Add generous padding around icons in touch environments to prevent accidental taps.
+
+---
+
+## Usage and Best Practices
+
+### Recommended Usage
+
+| Context | Recommended Icon Type |
+|---------|-----------------------|
+| Generic UI Actions | Utility Icons |
+| Record Representation | Object Icons |
+| Mobile Action Bar | Action Icons |
+| File Attachments | Doctype Icons |
+| App Navigation | Product Icons |
+
+### Implementation Constraints
+
+- **Utility Color Matching:** Always match utility icon color to adjacent text (e.g., use `on-surface-3` if the title is that color).
+- **White Glyphs:** Use only white glyphs for Object and Action icons.
+- **Standard Scaling:** Only scale icons to standard sizes (16, 24, 32, 48, 60px). Avoid scaling outside these increments.
+
+### Visual Standards (Dos and Don’ts)
+
+#### Utility Icons
+- ** Do:** Scale to standard pixel sizes (16x16, 24x24, etc.).
+- ** Do:** Use front-facing solid shapes for clarity.
+- ** Don't:** Use outlines or angled/dimensional views.
+- ** Don't:** Make icons overly complicated for small scales.
+
+#### Object Icons
+- ** Do:** Use white glyphs on approved colored backgrounds.
+- ** Do:** Use approved BPMN keyline shapes.
+- ** Don't:** Use unapproved background shapes or non-white glyphs.
+
+#### Doctype Icons
+- ** Do:** Represent the earflap without a visible gap.
+- ** Don't:** Add a gap or separation to the icon's earflap.
+
+---
+
+## Recommended Specs Summary
+
+| Icon Type | Grid Size | Stroke Weight | Corner Radius | Artboard Size |
+|-----------|-----------|---------------|---------------|---------------|
+| Utility (S) | 16x16px | 1px | 1px | 52x52px |
+| Utility (M) | 24x24px | 2px | 2px | 52x52px |
+| Object | 60x60px | 6px | 6px | 100x100px |
+| Action | 48x48px | 4px | 4px | 52x52px |
+| Doctype | 56x64px | - | 6px | 56x64px |
+| Product | 48x48px | 4px | - | - |
+
+---
+
+## Implementation Workflow
+
+Follow this sequence when implementing icons:
+
+1. **Identify Icon Need:** Determine the semantic role (action, record type, file, etc.).
+2. **Select Icon Type:** Choose the category that matches the role (e.g., Utility for actions).
+3. **Apply Sizing and Color:** Use standard scales and match colors to context (for Utility).
+4. **Implement Accessibility:** Add `aria-label` for informational icons; use empty `alt` for decorative.
+5. **Validate:** Check against the pre-implementation checklist for compliance.
+
+---
+
+## Pre-Implementation Checklist
+
+| Requirement | Status |
+|-------------|--------|
+| **Type Selection** | |
+| Icon type matches functional role (Utility/Object/Action/Doctype/Product) | [ ] |
+| **Sizing & Specs** | |
+| Icon scaled to standard size (16/24/32/48/60px) | [ ] |
+| Anatomy specs (stroke, radius) match the chosen scale | [ ] |
+| **Color & Consistency** | |
+| Utility icon color matches adjacent text | [ ] |
+| Object/Action icons use white glyphs on colored backgrounds | [ ] |
+| **Accessibility** | |
+| Informational icons have descriptive `aria-label` (purpose, not look) | [ ] |
+| Decorative icons have empty `alt=""` or are hidden | [ ] |
+| **Mobile** | |
+| Touch target meets minimum 44x44px requirement | [ ] |