Styling with static CSS extraction in mind

[NicholasBoll]

Intro

The @workday/canvas-kit-styling-transform both optimizes runtime and can optionally extract out CSS into files.

• Runtime optimization: Pre-computes style hashing and saving styles inline as a string instead of objects. This hits a faster path inside @emotion/css
• Styles are extracted from createStyles and createStencil function calls and saved in .css files based on values statically extracted

Limitations

Styles have to be statically analyzed by the style transformer. The transform utilizes the TypeScript type checker for greater flexibility when compared to the static extraction process in Vanilla Extract. If the transform cannot statically analyze a style property, an error will be thrown.

For example:

let color= 'blue'; // color is a `string` type because of the `let`
const buttonStyles = createStyles({
  color: color // Unknown type. Received "string"
})

General rule of thumb for if a property will be understood by the static style transform: if you mouse over the property value, it should be a numeric literal (i.e. 10) or a string literal (i.e. 10px, 1rem, etc). If the type is something like string or number, the value cannot be statically parsed. The exception to this rule is variables created by createVars or vars in createStencil. The static style transformation will create a string literal for the variable names, cache that name, and apply statically during the transform.

The biggest impact will be externalized style objects and functions that return style objects. For example, the following will result in an error:

const sharedStyles: CSSObject = {
  padding: 12
}

function someFn(input: number): CSSObject {
  return { padding: input }
}

const foo = createStyles({
  ...sharedStyles, // error. `CSSObject` has properties without statically known values
  ...someFn(12), // error. `CSSObject` has properties without statically known values
})

For objects, the best way to fix to use as const on the type instead of more general types like CSSObject or React.CSSProperties.

const sharedStyles = {
  padding: 12
} as const

For functions, generics will have to be used:

function someFn<T extends number>(input: T) {
  return { padding: input }
}

If a function is more complex, consider using a custom transformation in your styling.config.ts function. For example, focusRing has a special transform function to use the runtime focusRing function with statically analyzed values to produce a static result.

Naming

Note: Naming is very important when authoring styles via createStyles or createStencil when CSS is extracted into CSS files.

The runtime optimization will still use CSS class names based on the hash to avoid collisions. This hash is the same hash created via @emotion/css. However, CSS extraction needs a human readable name to apply for authoring. The name of the CSS variable or CSS class name is extracted from the variable name itself. This means we need to be conscious of what that name is.

The naming algorithm goes something like this:

• Extract the string of the Identifier from the variable declaration: const Foo = createStyles({}) will be "Foo"
• Prepend any nested identifiers inside objects or function calls: const Foo = { Bar: createStyles({}) } will be "Foo-Bar"
• Run slugify on the name (dash-case): The above will become foo-bar
• Prepend the prefix set via the config: The above will become css-foo-bar ('css' is the default)
• Modifiers add -- to the class name and dash-case the modifier name/value pair:

  const Button = createStencil({
    modifiers: {
      size: {
        large: {}
      }
    }
  })
  // will create a class named `css-button--size-large`

• Certain postfix names are removed
  • Styles
  • Stencil
  • Modifiers
  • Vars
  • Compound

For example, const buttonStyles = createStyles({}) will produce the name "css-button".

createStyles or createStencil?

Both functions produce static CSS. However, createStencil should be the preferred styling function. It better organizes styles and creates a cascade barrier for variables. A cascade barrier means if you declare a variable, it's default will be inlined into the base styles which prevents nested CSS classes that use the same variable from cascading.

An example of CSS variable cascade:

CSS:

.card {
  color: var(--card-color)
}

HTML:

<div class="card" style="--card-color: red;">
  <div class="card">Also red color</div>
</div>

Stencils prevent component variables from cascading by adding in the default declared in the vars config:

TypeScript

const card = createStencil({
  vars: {
    color: 'red'
  }
})

const Card = ({children}) => <div className={card}>{children}</div>

// Some rendering Function
<Card style={{[card.vars.color]: 'green'}}>
  <Card /> // color is red here
</Card>

CSS

.css-card {
  --css-card-color: red;
  color: var(--css-card-color);
}

CSS variables are set by the rules of specificity. The style attribute has a higher specificity than the single class name. Remember this when doing CSS variable value overrides. Adding a psuedo-selector like &:hover is a higher specificity than the single class name and will override the base variable declaration.