Configuration & Extension

Elevate offers a powerful and flexible configuration system that’s easy to adapt to your project’s design and architectural goals. However, with great power comes great responsibility—be sure to review each configuration option carefully to ensure it aligns with your project’s needs.

Basic Configuration

Elevate’s general settings are defined in elevate/config/elevate.ts:

elevate/config/elevate.ts

const options = {
  Watch: './',                   // Directory to watch for changes
  FileTypes: ['html', 'jsx', 'tsx', 'astro'],  // File extensions to scan
  Output: './'                   // Output directory for generated CSS
};

export const config = options;

Next up, you can import and distribute design system tokens in elevate/config/design.ts:

elevate/config/design.ts

// Design System Token Imports
// (includes both standard system tokens and custom tokens)

// Example: Utility import for additional spacing/height
import { heightUtility } from "../core/system/etc/height.js";

// Example: Custom values import
import { BrandColors } from "../design/example-brandTokens.js";

// System standard imports
import { colors } from "../core/system/design/colors.js";
import { spacing } from "../core/system/design/spacing.js";
import { typography } from "../core/system/design/typography.js";
import { breakpoints } from '../core/system/design/breakpoints.js';

// Token Definitions
export const designSystem = {
  ColorToken: colors,
  BreakPointToken: breakpoints,
  SpacingToken: { ...spacing, ...heightUtility },
  FontSizeToken: typography.size,
  FontFamilyToken: typography.family,
  LineHeightToken: typography.leading,
  LetterSpacingToken: typography.tracking,
  FontWeightToken: typography.weight,

  // Spread in custom token categories
  ...BrandColors
};

Finally, syntax rule mappings are imported and distributed, and custom properties are defined, in elevate/config/syntax.ts:

elevate/config/syntax.ts

// Import Rule Files
import { Brand } from "../rules/example-brandRules.js";

// Spread Rules into Rules Object
export const rules = {
  ...Brand
};

// Define Custom Property and CSS Declaration Relationship
export const relationships = {
  // Example Custom Property Definition
  brand: {
    "background-color": "BrandBackgroundRule",
    "color": "BrandCopyRule"
  }
};

Customization Tasks Cheat Sheet

In the majority of cases, you’ll only ever need to either:

A. Integrate Design System Tokens

• Create token files in elevate/design.
• Decide on whether you need to maintain compatibility with existing Elevate properties:
  • Yes: Spread your custom token objects into existing tokencategories in config/design.ts.
  • No: Create new token categories in config/design.ts and then see option ‘B’ below.

B. Expand Upon Elevate’s Syntax

• Create new rule files in elevate/rules.
• Import and spread these new rules into the rules object in config/syntax.ts.
• Define new properties in the relationships object in config/syntax.ts, mapping tokens and rules to CSS declarations according to your needs.

Token Categories and Compatibility

In config/design.ts, you can spread your design token imports into the following existing token categories and they will be immediately compatible with Elevate’s existing properties:

ColorToken
BreakPointToken
SpacingToken
FontSizeToken
FontFamilyToken
LineHeightToken
LetterSpacingToken
FontWeightToken

Design System Integration

If your goal is to integrate your design system tokens into Elevate:

1. Add new categorized design tokens to the elevate/design directory:

elevate/design/example-brandTokens.ts

export const BrandColors = {
  BrandBackgroundTokens: {
    'popgreen': '#39FF14'
  },
  BrandCopyTokens: {
    'popwhite': '#FFFFFF'
  }
};

2. Import the new token categories into elevate/config/design.ts:

elevate/config/design.ts

import { BrandColors } from "../design/example-brandTokens.js";

3. Spread the new token categories into the appropriate token definitions:

elevate/config/design.ts

// Token Definitions
export const designSystem = {
  ColorToken: {
    ...colors,
    ...BrandColors.BrandBackgroundTokens,
    ...BrandColors.BrandCopyTokens
  }
};

You can now reference these tokens in your utility strings as you would any of the existing Elevate tokens.

Extending Elevate’s Syntax

To create product-specific or project-specific syntax rules, follow these steps:

1. Create a new file in the elevate/rules directory.

elevate/rules/example-brandRules.ts

export const Brand = {
  BrandBackgroundRule: {
    "bg-": "BrandBackgroundToken"
  },
  BrandCopyRule: {
    "copy-": "BrandTextToken"
  }
};

Rule Files vs. Properties

When creating a new rule file, remember you’re defining the modifier syntax (e.g., bg-, copy-), not the property itself. You’ll establish a new property (e.g., brand) in elevate/config/syntax.ts to map these modifiers to the appropriate CSS declarations.

2. Import the new rule file into elevate/config/syntax.ts and spread it in the rules object:

elevate/config/syntax.ts

import { Brand } from "../rules/example-brandRules.js";

export const rules = {
  ...Brand
};

3. Define a new property in the relationships object and map your new modifier rules to the appropriate CSS declarations:

elevate/config/syntax.ts

export const relationships = {
  brand: {
    "background-color": "BrandBackgroundRule",
    "color": "BrandCopyRule"
  }
};

4. Test your new property in an appropriate filetype (e.g. .html):

<div class="brand:bg-popgreen:copy-popwhite"></div>

Please note that Elevate includes a number of special token types that provide additional capabilities beyond the core functionality for specific situations.

See System Token Types

Token Collisions & How to Avoid Them

Elevate supports an order-agnostic syntax structure. It applies a “first match wins” strategy whereby the first CSS declaration expecting a token or rule claims it. However, token collisions can occur if two declarations under a single property share the same token type.

Example: A single property defines both color: ColorToken and border-color: ColorToken. If you pass a color token, Elevate applies it to the first matching declaration. To avoid collisions, create new rules in elevate/rules to differentiate them, and reference those rules in the property definition rather than referencing the token type directly.

Troubleshooting & Helpful Tips

Common Issues

1. Token not mapping correctly?
   • Check if the design token is exported from its file.
   • Ensure the token is properly imported and spread in config/design.ts.
   • Confirm that any rules involving these tokens are correctly defined and imported in config/syntax.ts.

2. Performance Considerations
   • Use rules for syntactic relationships, syntax expansion, or preventing token collisions.
   • Keep the number of tokens and rules minimal to limit complexity.

3. Naming Conventions
   • Use clear, semantic names (e.g., BrandColorToken, TextAlignRule).
   • Avoid overly generic names that can cause collisions.
   • Prefix them to indicate their purpose, especially if you have many tokens.

Want To Go Deeper?

Elevate’s configurability makes it easy to integrate any design system or add custom features. Familiarize yourself with the existing rules in core/system to understand how Elevate maps tokens and rules to CSS declarations. Leverage this knowledge to create robust, maintainable utility-based styles that reflect your unique design system—while also ensuring maximum compatibility with Elevate’s defaults whenever possible.