@salesforce-ux/sds-metadata

A package that simplifies the management, distribution, and usage of Salesforce Design System metadata. This package ensures that developers and designers can easily access and integrate design system metadata into their workflows.

Installation

npm install @salesforce-ux/sds-metadata

Features

This package provides TypeScript type definitions for various Salesforce Design System metadata, including:

• Aura to LWC token mappings
• BEM naming conventions
• Deprecated classes and styling hooks
• Global styling hooks
• LWC token data
• SLDS classes and styling hooks
• Value to styling hooks mappings

Type Definitions

Core Types

• AuraToLwcTokensMapping: Maps Aura tokens to their LWC equivalents
• BEMNaming: BEM naming convention mappings
• DeprecatedClasses: List of deprecated CSS classes
• DeprecatedStylingHooks: List of deprecated styling hooks
• GlobalStylingHooks: Global, component, and shared styling hooks
• LwcTokenData: Information about LWC tokens including deprecation status and replacements
• LwcToSldsTokensMapping: Maps LWC tokens to SLDS tokens
• SldsClasses: List of SLDS CSS classes
• SldsPlusClasses: List of SLDS+ CSS classes
• SldsPlusStylingHooks: Global, component, and shared SLDS+ styling hooks
• ValueToStylingHooksMapping: Maps values to their corresponding styling hooks

Styling Hook Properties

The StylingHookProperties type includes:

• category: The category of the styling hook
• external: Whether the hook is external
• scope: The scope of the hook
• properties: List of CSS properties
• values: Record of values
• aliases: Record of aliases

Usage

The package provides TypeScript type definitions and metadata for Salesforce Design System. Here are some common usage patterns:

ES Modules (ESM) Usage

import metadata from '@salesforce-ux/sds-metadata';

// Access Aura to LWC token mappings
const auraToLwcTokens = metadata.auraToLwcTokensMapping;

// Get BEM naming conventions
const bemNaming = metadata.bemNaming;

// Check deprecated classes
const deprecatedClasses = metadata.deprecatedClasses;
if (deprecatedClasses.includes('slds-button--brand')) {
  console.log('This class is deprecated');
}

// Access styling hooks
const stylingHooks = metadata.sldsStylingHooks;
console.log(stylingHooks['--sds-c-color-background']);

// Get SLDS classes
const sldsClasses = metadata.sldsClasses;
console.log(sldsClasses.includes('slds-button')); // Check if a class exists

// Access SLDS+ specific data
const sldsPlusClasses = metadata.sldsPlusClasses;
const sldsPlusHooks = metadata.sldsPlusStylingHooks;

CommonJS Usage

const metadata = require('@salesforce-ux/sds-metadata');

// Access token mappings
const auraToLwcTokens = metadata.auraToLwcTokensMapping;
const lwcToSlds = metadata.lwcToSlds;

// Get styling hooks
const globalHooks = metadata.globalStylingHooksMetadata;
const deprecatedHooks = metadata.deprecatedStylingHooks;

// Access value to styling hooks mappings
const cosmosHooks = metadata.valueToStylingHooksCosmos;
const sldsHooks = metadata.valueToStylingHooksSlds;

TypeScript Usage with Type Definitions

import type { 
  AuraToLwcTokensMapping,
  GlobalStylingHooks,
  LwcTokenData,
  StylingHookProperties
} from '@salesforce-ux/sds-metadata';

import metadata from '@salesforce-ux/sds-metadata';

// Type-safe access to metadata
const auraToLwc: AuraToLwcTokensMapping = metadata.auraToLwcTokensMapping;
const globalHooks: GlobalStylingHooks = metadata.globalStylingHooksMetadata;

// Type checking for styling hooks
const hookProperties: StylingHookProperties = globalHooks.global['--sds-c-color-background'];

Common Use Cases

1. Token Migration: Use auraToLwcTokensMapping to help migrate from Aura to LWC tokens
2. Style Validation: Use deprecatedClasses and deprecatedStylingHooks to validate styles
3. Theme Management: Use globalStylingHooksMetadata to manage and validate theme tokens
4. BEM Compliance: Use bemNaming to ensure BEM naming convention compliance
5. Icon Management: Use icons to access icon metadata
6. SLDS+ Integration: Use sldsPlusClasses and sldsPlusStylingHooks for SLDS+ specific features

Best Practices

• Use ES modules (import/export) for new projects
• Use type definitions for TypeScript projects to get full type safety
• Check for deprecated classes and hooks before using them
• Use the provided mappings to maintain consistency across components
• Validate styling hooks against the type definitions