Today I am thrilled to announce the release of CodyFrame v4!

It's been 18 months since our last major release. I'll be honest: during this time, I was expecting more adoption. Our CodyFrame v3 node module is downloaded around 10K times monthly. At the time CodyFrame v3 was released, CodyFrame v2 was downloaded around 7K times per month. Even though there's been a slight increase, the nearly flat download curve has caused us to pause and think.

Over the past year, we've been interviewing users of CodyFrame to identify areas for improvement. All the feedback can be summed up in one quote:

"Even though I love the components, it's not easy to customize {feature-name} in CodyFrame", where {feature-name} could be the typography scale, the breakpoints, the utility classes and so on.

Because we strive for ‘smart’ solutions, sometimes we end up making them overly complicated. Ultimately, we concluded that a better framework should be smart, yet also intuitive and easy to use.

The intuitive CSS framework #

Let's take a look at what's changed! CodyFrame v4 consists of only a few SASS files, which should be imported in the following order:

@use 'reset'; // ← reset
@use 'config' as *; // ← customize the framework

// ↓ copy & modify these templates locally
@use 'typography';
@use 'icons';
@use 'buttons';
@use 'forms';

// ← import here the CodyHouse components

@use 'util'; // ← utility classes

The reset file is used to remove browser inconsistencies.

The typography, icons, buttons, and forms files provide a foundation to create the global style of your project. These can be imported locally and used as templates.

The util file contains all the utility classes.

Finally, we have the major change: the config file.

In CodyFrame v4, you can customize something by passing either a variable or a map to the config module.

Here's an example:

@use 'config' as * with (
  $breakpoints: (
    'sm': '48rem',
    'md': '64rem',
    'lg': '80rem'
  ),
  $spacing: (
    '3xs': '0.25rem',
    '2xs': '0.375rem',
    'xs': '0.5rem',
    'sm': '0.75rem',
    'md': '1.25rem',
    'lg': '2rem',
    'xl': '3.25rem',
    '2xl': '5.25rem',
    '3xl': '8.5rem'
  ),
  $font-family: (
    'primary': 'Inter, system-ui, sans-serif'
  ),
  $font-size: (
    'xs': '0.6875rem',
    'sm': '0.8125rem',
    'base': '1rem',
    'md': '1.1875rem',
    'lg': '1.4375rem',
    'xl': '1.75rem',
    '2xl': '2.0625rem',
    '3xl': '2.5rem'
  ),
  $aspect-ratio: (16 9, 3 2, 4 3, 5 4, 1 1),
  $border-radius: (
    'sm': '0.1875em',
    'md': '0.375em',
    'lg': '0.75em'
  )
);

No more need to browse through the framework files to locate the CSS variables to update. No more manual creation of utility classes!

All the CSS variables* and utility classes are automatically created when you update the config module in your style.scss file.

The configuration file also includes all SASS mixins and functions, so it must be imported into all components. It essentially replaces the base.scss file from CodyFrame v3.

*The CSS variables are created in the util file.

CSS #

If you'd rather ditch SASS, import the framework CSS files:

@import 'https://unpkg.com/codyframe/main/css/reset.css'; /* ← reset */

/* ↓ copy & modify these templates locally */
@import 'typography.css';
@import 'icons.css';
@import 'buttons.css';
@import 'forms.css';

/* ← import here the CodyHouse components */

@import 'https://unpkg.com/codyframe/main/css/util.css'; /* ← utility classes */

Obviously, you'd give up the advanced configuration options. To customize the framework, you should overwrite the CSS variables.

Support for CodyFrame v3 #

CodyFrame v4 has breaking changes, so each component will be available in two versions: one for v3, and one for v4. We will continue supporting CodyFrame v3.

How to upgrade from CodyFrame v3 to v4 #

This guide quickly explains how to upgrade from CodyFrame v3 to v4.

First, we created a new repository for v4, so make sure to install the new module if you wish to upgrade:

# using npm
npm i codyframe

# using Yarn
yarn add codyframe

1. Naming convention #

In CodyFrame v4, we replaced 'xxxxs' with '4xs', 'xxl' with '2xl' and so on in all the variables and utility classes. For example, margin-x-xxs becomes margin-x-2xs and var(--space-xxxl) becomes var(--space-3xl).

You can either bulk change the multiple Xs, or, if you prefer to keep the old naming convention, pass the $spacing map to the config module in your style.scss file. More info on the spacing documentation page.

@use 'config' as * with (
  $spacing: (
    'xxxs': '0.25rem',
    'xxs': '0.375rem',
    'xs': '0.5rem',
    'sm': '0.75rem',
    'md': '1.25rem',
    'lg': '2rem',
    'xl': '3.25rem',
    'xxl': '5.25rem',
    'xxxl': '8.5rem'
  )
);

2. Buttons #

The :root variables in the custom-style/_buttons.scss file of CodyFrame v3 no longer exist. Use plain values in the buttons.scss file of CodyFrame v4. If you copy/paste the content of the buttons.scss file of v3 into the one of v4, make sure to add (from the base/_buttons.scss file of CodyFrame v3):

.btn {
  position: relative;
  display: inline-flex;
  justify-content: center;
  align-items: center;
  white-space: nowrap;
  text-decoration: none;
  font-size: 1em;
  padding: var(--space-2xs) var(--space-sm);
  border-radius: var(--radius-md);
}

3. Colors #

Define your colors by passing the $colors map to the config module. More info here.

4. Forms #

Delete the :root variables in the custom-style/_forms.scss file and add plain values for padding, font-size and border radius. Check the forms.scss file in CodyFrame v4 if you need a reference.

5. Icons #

Make sure to update the icon--{size} utility classes in the icons.scss file of v4 with the icon sizes used in your current v3 project. The CSS custom properties are no longer needed, but keep them if you're using them in your CSS.

.icon--3xs {
  --size: 8px;
}

.icon--2xs {
  --size: 12px;
}

.icon--xs {
  --size: 16px;
}

.icon--sm {
  --size: 20px;
}

.icon--md {
  --size: 24px;
}

/*... */

6. Spacing #

To preserve the spacing scale of your v3 project, pass the $spacing map to the config module. More info here.

The --component-padding variable and the relative padding classes (e.g., padding-x-component) no longer exist. Replace them with var(--space-md), padding-x-md and so on.

The @include spaceUnit mixin no longer exists. If you're running into issues for using Em units (e.g., compounding effect), use Rem units in your spacing scale.

7. Breakpoints #

If you changed the default CodyFrame breakpoints, pass the $breakpoints map to the config module. More info here.

@use 'config' as * with (
  $breakpoints: (
    'xs': '32rem',
    'sm': '48rem',
    'md': '64rem',
    'lg': '80rem',
    'xl': '90rem'
  )
);

8. Typography #

The text-component has been updated in v4. However, you can copy the text-component style from your v3 project (base/_typography.scss and custom-style/_typography.scss files) and replace the text-component definition in the v4 typography.scss file.

To preserve the type scale of your v3 project, pass the $font-size map to the config module. More info here.

// @all → from min-width: 0
// @md → from breakpoint: md
@use 'config' as * with (
  $font-size: (
    '@all': (
      'xs': '0.6875rem',
      'sm': '0.8125rem',
      'base': '1rem',
      'md': '1.1875rem',
      'lg': '1.4375rem',
      'xl': '1.75rem',
      '2xl': '2.0625rem',
      '3xl': '2.5rem',
      '4xl': '3rem'
    ),
    '@md': (
      'xs': '0.75rem',
      'sm': '0.9375rem',
      'base': '1.125rem',
      'md': '1.375rem',
      'lg': '1.625rem',
      'xl': '2rem',
      '2xl': '2.5rem',
      '3xl': '3rem',
      '4xl': '3.625rem'
    )
  )
);

To define the project font families, pass the $font-family map:

@use 'config' as * with (
  $font-family: (
    'primary': 'system-ui, sans-serif',
    'secondary': 'serif'
  )
);

The @include textUnit mixin no longer exists. Replace it with font-size: 1rem; If you're running into issue caused by Em units (e.g., compounding effect), consider switching to Rem units.

9. Aspect Ratio #

Replace the aspect-ratio-{x/y} classes with media-wrapper-{x/y}. More info here.

10. Max-Width #

The max-width CSS variables have been updated in v4. To preserve the v3 values, pass the $max-width map to the config module:

@use 'config' as * with (
  $max-width: (
    '5xs': '17.5rem',
    '4xs': '20rem',
    '3xs': '26rem',
    '2xs': '32rem',
    'xs': '38rem',
    'sm': '48rem',
    'md': '64rem',
    'lg': '80rem',
    'xl': '90rem',
    '2xl': '100rem',
    '3xl': '120rem',
    '4xl': '150rem'
  )
);

11. Components #

In each component's SCSS, remember to import the config instead of the old base file.

@use '../../../node_modules/codyhouse-framework/main/assets/css/base' as *;
// --- ↓
@use '../../../node_modules/codyframe/main/scss/config' as *;

What's next #

Expect updates to your favorite components and exciting new components!