Skip to content

Migrating from Enhance Styles

Cole Peters edited this page Jul 31, 2024 · 1 revision

Migrating from Enhance Styles version 6 (our predecessor) to Paramour is fairly straightforward. Breaking changes are limited to the configuration file, and the naming of several generated custom properties.

Configuration file

We’ve chosen to write the configuration file for Paramour in JavaScript; Enhance Styles used a JSON configuration file. Additionally, the structure and naming of some of the configuration file’s properties have changed.

Format

Start by renaming your configuration file to use a .mjs extension rather than a .json extension.

Next, reformat the contents of the file to export a JavaScript object. For example, given the following minimal configuration file written in JSON:

{
  "fonts": {
    "sans": "Helvetica Neue, sans-serif"
  }
}

…the configuration would be reformatted to look like this:

export default {
  fonts: {
    sans: 'Helvetica Neue, sans-serif'
  }
}

Note that, since you’re now exporting a JavaScript object, property names don’t need to be quoted by default, and additional conventions such as comments and trailing commas can be used.

Property structure and naming

The following objects and properties have been updated in structure and/or naming:

Borders and border radii

The borders object now contains the radii property in addition to the widths property.

Before:

{
  "borders": {
    "widths": [1, 2, 4]
  },
  "radii": [2, 8, 16, 9999]
}

After:

borders: {
  widths: [1, 2, 4],
  radii: [2, 8, 16, 9999]
}

Queries → breakpoints

The object previously named queries is now named breakpoints, as it is intended specifically for enumerating breakpoint based media queries.

Before:

{
  "queries": {
    "lg": "48em"
  }
}

After:

breakpoints: {
  lg: '48em'
}

Properties → custom properties

The object previously named properties is now named customProperties for clarity.

Before:

{
  "properties": {
    "lineLength": "52ch"
  }
}

After:

customProperties: {
  lineLength: '52ch'
}

Color and theme

The specification of colors in general has been overhauled for Paramour in the interest of clarity.

Previously, colors defined in the theme object specified a base color for generated color scales (e.g. redred-100, red-200, etc), while colors defined in colors acted as spot colors (e.g. crimsoncrimson). Additionally, the reserved properties theme.fore, theme.back, theme.accent, and theme.error were used to specify colors for light-dark support, with the additional reserved property theme.dark used to override the automatically generated dark mode variants.

For Paramour, color now acts as a parent object for all color related configuration. color.scales is used for specifying base colors for generated color scales, while color.spots is used for specifying one off spot colors. We have temporarily removed the theme property and support for automatic light-dark colors as this resulted in some confusion for users; we’re investigating the best way to reintroduce this functionality in an additive fashion in an upcoming release.

Before:

{
  "color": {
    "crimson": "#eb0052"
  },
  "theme": {
    "red": "#ff0000",
    "green": "#00ff00"
  }
}

After:

color: {
  spots: {
    crimson: '#eb0052'
  },
  scales: {
    red: '#ff0000',
    green: '#00ff00',
  },
}

Custom property naming

Custom property naming in Enhance Styles suffered from inconsistent hyphenation patterns, which also didn't line up with hyphenation patterns used in matching class names. For example, the space and type scale custom properties used a double hyphen to indicate a negative index in the space/type scales (--space--1, --space-0, --space-1, etc), while the matching class names used a single hyphen to indicate negative indexes (e.g. .m-1, .m0, .m1, etc).

For Paramour, we have converged on the hyphenation patterns already in use in Enhance Styles’ class names, and updated the patterns used in generated custom properties to reflect this. In short: custom properties with numbers use a hyphen before the number to indicate a negative value; positive values have no hyphen before the number.

To account for this, you'll need to find the affected custom properties you’ve referenced in your scoped element styles or global CSS (if any) and update their names.

The following groups of custom properties have been renamed; refer to the 'before' and 'after' examples for guidance on renaming:

Module Before After
Color scales var(--red-100) var(--red100)
Type scale var(--text--1), var(--text-1) var(--text-1), var(--text1)
Space scale var(--space--1), var(--space-1) var(--space-1), var(--space1)