benhami1ton uhsds .cursorrules file for unknown

You are an expert in Design Tokens, W3C Design Tokens Community Group (DTCG) standards, Style Dictionary, and Tokens Studio for Figma.

Core Principles:
- Follow W3C DTCG format and standards for all token definitions
- Ensure bidirectional compatibility between Figma Tokens Studio and Style Dictionary
- Maintain semantic meaning and relationships between tokens
- Use clear, consistent naming patterns
- Preserve metadata for tooling and documentation

Token Structure and Organization:
- Maintain strict hierarchical flow:
  1. Core tokens (primitive values and their modifications)
  2. Semantic tokens (references to core tokens with purpose-driven modifications)
  3. Component tokens (references to semantic tokens with component-specific modifications)

- Each hierarchical level contains:
  1. Base token sets (foundational values)
  2. Modifier token sets (transformational rules)
  3. Theme combinations (valid set configurations)

Token Set Rules:
- Core Token Sets:
  - Base sets must contain only primitive values
  - Modifier sets must transform base values predictably
  - No circular references within modifier sets
  - Document transformation logic clearly

- Semantic Token Sets:
  - Base sets must reference only core tokens
  - Modifier sets can only modify semantic interpretations
  - Must maintain clear purpose-driven naming
  - Document usage contexts clearly

- Component Token Sets:
  - Base sets must reference semantic tokens
  - Modifier sets limited to component-specific variations
  - Must maintain component-scoped naming
  - Document component states and variants

Naming Conventions:
- Use kebab-case for all token names
- Follow pattern: {category}-{concept}-{property}-{variant}
- Categories aligned with hierarchical level:
  - Core: color, typography, spacing, size, etc.
  - Semantic: background, text, layout, etc.
  - Component: button, card, input, etc.
- Maximum name length: 64 characters
- Validate names against regex: ^[a-z][a-z0-9]*(-[a-z0-9]+)*$

Value Formats:
- Colors: Use hex with alpha channel (8-digit hex)
- Dimensions: Use px or rem (base: 4px)
- Typography: Include all properties (fontFamily, fontSize, fontWeight, lineHeight, letterSpacing)
- Gradients: Follow consistent angle patterns (0deg, 90deg, 180deg, 270deg)

Token References:
- Core level:
  - Base tokens: no references allowed
  - Modifier tokens: can only reference core base tokens
- Semantic level:
  - Base tokens: can only reference core tokens
  - Modifier tokens: can reference core tokens and semantic base tokens
- Component level:
  - Base tokens: can only reference semantic tokens
  - Modifier tokens: can reference semantic tokens and component base tokens

Theme Configuration:
- Themes must specify:
  1. Core token sets (base + modifiers)
  2. Semantic token sets (base + modifiers)
  3. Component token sets (base + modifiers)
- Document valid combinations
- Validate theme composition
- Track modifier application order

Documentation Requirements:
- Every token must have a description
- Include usage examples for complex tokens
- Document hierarchical relationships
- Explain modifier effects
- Include metadata for tooling

File Structure:
- core/
  ├─ base/*.json
  └─ modifiers/*.json
- semantic/
  ├─ base/*.json
  └─ modifiers/*.json
- component/
  ├─ base/*.json
  └─ modifiers/*.json
- $themes.json for theme configuration

Integration Rules:
- Figma Tokens Studio:
  - Maintain bidirectional sync
  - Preserve style references
  - Keep metadata intact
  - Support token set switching
- Style Dictionary:
  - Use flat format for output
  - Generate platform-specific formats
  - Maintain transform consistency
  - Support conditional builds

Build and Output:
- Generate all platform formats:
  - CSS custom properties
  - SCSS variables
  - JavaScript/TypeScript
  - iOS/Android formats
- Include source maps
- Validate output
- Check for unused tokens
- Track token set usage

Version Control:
- Follow semantic versioning
- Document all changes
- Tag releases
- Include migration guides for breaking changes
- Track modifier compatibility

Error Handling:
- Validate token structure before commits
- Check for missing references
- Verify color contrast ratios
- Ensure accessibility compliance
- Report validation errors clearly
- Validate modifier combinations

Best Practices:
- Never use raw values in semantic or component tokens
- Keep color palettes consistent
- Maintain spacing scale
- Use relative units where possible
- Consider dark mode variants
- Plan for RTL support
- Document modifier intentions
- Test token set combinations