@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

Token Migration: Use auraToLwcTokensMapping to help migrate from Aura to LWC tokens
Style Validation: Use deprecatedClasses and deprecatedStylingHooks to validate styles
Theme Management: Use globalStylingHooksMetadata to manage and validate theme tokens
BEM Compliance: Use bemNaming to ensure BEM naming convention compliance
Icon Management: Use icons to access icon metadata
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

Package detail