Getting Started with Elevate CSS

This quick start guide is included to give you an opportunity to dive right into the world of Elevate CSS. With that said, however, it is highly recommended that you familiarize yourself with the configuration and specificity pages as well as they provide a deeper understanding of Elevate’s capabilities, functionality, and best practices as well as how to best leverage the framework for your specific needs.

Installation and Usage

Use NPM to Install Elevate
Terminal
```
npm install elevate-framework
```
Run the Elevate setup script
Terminal
```
npx elevate-framework prepare
```
Watch Files for Changes and Convert Elevate’s Syntax to CSS
Terminal
```
npm run elevate
```

Basic Configuration

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

const options = {
    Watch:'./elevate/templates', // Folder to watch for changes
    FileTypes:['html', 'jsx', 'tsx', 'astro'], //Valid filetypes to watch for changes
    Output:'./', //Where to put the compiled CSS
    Extend:[], //CSS files to include as well
    ClassRegex: [
        /class\s*=\s*"([^"]+)"/g, // Matches class="..."
    ]
}

export const config = options

What Are ‘Utility Strings’?

Basic Usage:

At the heart of Elevate’s syntax is what are called “utility strings”, which are used to describe styling and serve as the basis for CSS generation while simultaneously doubling as the actual CSS classes. This convention means that, by default, your CSS files only ever contain classes that are actually being used in your markup.

Unlike traditional utility frameworks which come packed with pre-defined utility classes, you are effectively writing CSS as you write utility strings in Elevate through the expression of property and modifier combinations - which are validated against your design system and a series of built-in conventions as well as your own custom syntax rules at build-time to ensure consistency.

The Utility String Format:

<div class = "property:modifier">

Direct Properties:

Direct properties are properties that do not require any modifier and that define a single CSS declaration. Generally used for layout and positioning.

<div class="block"> <!-- display: block -->

Compound Properties:

Compound properties are properties that require one or more modifiers to be applied. These properties are used to create more complex CSS declarations.

<div class="text:dark:bold:left">

<!--
.text\:dark\:bold\:left {
color: #2C2638;
font-weight: 700;
text-align: left;
}
-->

Practical Examples:

Bringing it all together, here are some examples of Elevate’s syntax in action:

<div class="text:purple font:bold">      <!-- Bold text with purple color -->
<div class="bg-color:purple">          <!-- Background color set to purple -->
<div class="row:x-center:y-start">  <!-- Row layout with specific alignment -->
<div class="absolute left:d12 z:10">  <!-- Absolute positioning, d12 from the left, and z-index of 10  -->

Breakpoints and Responsive Design

Elevate affords and enforces a mobile-first, organized syntax for responsive design:

<div class="text:purple p:d1:d2 /md/ text:right /lg/ @hover:[text:green:right]">

Universal classes are applied on the far-left and apply to all breakpoints by default unless overridden at a breakpoint. Breakpoints are specified using the /breakpoint/ syntax, allowing you to discern the responsive behavior of an element at a glance and keeping things organized by default.

Operator Flags

In order to allow for greater flexibility, Elevate supports a series of flags to further refine styling choices and to support more complex and dynamic behaviors while preserving semantic clarity.

The Contextual Flag [@]:

Allows complex, conditional styling for states, conditions, and other pseudo-classes or pseudo-elements:

<div class="@hover:[text:green:right_p:d1]">  <!-- Hover state changes text and adds padding. -->

Note that you can chain property modifier combinations with an underscore inside of the contextual flag’s brackets. This allows more concise expression of design intent. No more pseudo-class spam or unnecessary nesting!

See Currently Supported Selectors

The Extends Flag [-]:

Exempt certain classes from CSS generation (e.g. for JavaScript interactions, labelling, or applying non-compiled CSS classes):

<div class="-mySelector">

The Elements of Elevate

Elevate’s systems are driven by three distinct elements:

Design Tokens
- Purpose: Global, immutable design constraints.
- Location: design/ directory
- Configuration: elevate/config/design.ts and elevate/design
- Characteristics: Centralized values, enforce system-wide consistency.
Example:
design/example-brandTokens.ts
```
export const BrandColors = {

   //Define New Token Categories

   BrandBackgroundTokens: {
   'popgreen':'#39FF14'
   },

   BrandCopyTokens: {
   'popwhite': '#FFFFFF',
   }

}
```

Syntactic Rules
- Purpose: Property-specific structural validation and syntax construction or extension.
- Location: rules/ directory
- Configuration: elevate/config/syntax.ts and elevate/rules
- Characteristics: Validate property values, provide transformations, and structure or extend syntax.
Example:
rules/example-brandRules.ts
```
export const Brand = {

   BrandBackgroundRule: {
   "bg-": "BrandBackgroundToken"
   },

   BrandCopyRule: {
   "copy-": "BrandTextToken"
   }

}
```

Property Declarations
- Purpose: Mapping design system tokens and/or syntax rule mappings to CSS declarations.
- Location: config/ directory
- Configuration: elevate/config/syntax.ts
- Characteristics: Validate property values, provide transformations, and structure or extend syntax.
Example:
```
//Define Custom Property and CSS Declaration Relationship
 export const relationships = {
 //Example Custom Property Definition
 brand:
 { "background-color": "BrandBackgroundRule",
   "color": "BrandCopyRule" },
 };
```

This Is Elevate CSS:

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