@salesforce-ux/sds-metadata/README.md

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

# @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

```bash
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
```typescript
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
```javascript
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
```typescript
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