Migrating from version 3

Migrating from version 3 to a more recent version is a big change. We recommend that you stage the website somewhere becasue the update can be disruptive until it's done.

Number System

The number system used throughout most of v3 is copied over to v4 and higher. For example: mt-1 is equivalent to margin-top: 10px;.

Breakpoints

Breakpoints have been updated to be mobile-first. Additionally, the actual breakpoint values have been changed to be more in line with other frameworks.

These breakpoints are inspired by:

• Pure
• Bootstrap
• Open Props
• Worldwide mobile stats
• Common screen resolutions
• And our own usage in building websites

Key	Screen width
3xs	>= 240px
2xs	>= 360px
xs	>= 420px
sm	>= 576px
md	>= 768px
lg	>= 1024px
xl	>= 1280px
2xl	>= 1440px
3xl	>= 1600px
4xl	>= 1920px
5xl	>= 2560px

Updated Classes

v3	v4
.u-cf	.clearfix
.u-cleanContent	.last-child-sb-0
.u-hiddenVisually	.visually-hidden
.u-hidden	.hidden
.u-block	.block
.u-inline	.inline
.u-flex	.flex
.u-flexInline	.inline-flex
.u-flexRowReverse	.flex-reverse
.u-flexCol	.flex-col
.u-flexColReverse	.flex-col-reverse
.u-flexJustifyStart	.justify-start
.u-flexJustifyEnd	.justify-end
.u-flexJustifyCenter	.justify-center
.u-flexJustifyBetween	.justify-between
.u-flexJustifyAround	.justify-around
.u-flexAlignItemsStart	.align-start
.u-flexAlignItemsEnd	.align-end
.u-flexAlignItemsCenter	.align-center
.u-gutters*	.px-*
.u-heightFull	.h-1-1 or h-100
.u-linkSubtle	.link-subtle
.u-margTop*	.mt-*
.u-margRight*	.me-*
.u-margBottom*	.mb-*
.u-margLeft*	.ms-*
.u-padTop*	.pt-*
.u-padRight*	.pe-*
.u-padBottom*	.pb-*
.u-padLeft*	.ps-*
.u-posAbsolute	.absolute
.u-posRelative	.relative
.u-posStatic	.static
.u-printHide	.print-hide
.u-printShow	.print-show
.u-heightFull	.h-100
.u-rowGap*	.gy-*
.u-size*of*	.col-*-* or .w-*-*
.u-styleEm	.style-italic
.u-textBreak	.break-word
.u-textBreakAll	.break-all
.u-textLeft	.text-start
.u-textLower	.text-lower
.u-textNoWrap	.no-wrap
.u-textUpper	.text-upper
.u-textCenter	.text-center
.u-textRight	.text-end
.u-weightNormal	.weight-normal
.u-weightBold	.weight-bold
.u-widthFull	.w-1-1 or .w-100

Removed Classes

• .u-align*
• .u-inlineBlock
• .u-table*
• .u-flexRow
• .u-flexWrap
• .u-flexAlignItemsStretch
• .u-flexAlignItemsBaseline
• .u-flexAlignContent*
• .u-flexAlignSelf*
• .u-flexOrder*
• .u-flexGrow
• .u-flexExpand
• .u-img*
• .u-float*
• .u-nbfc
• .u-nbfcAlt
• .u-linkClean
• .u-linkObvious
• .u-linkNatural
• .u-linkComplex
• .u-guttersMarg*
• .u-spacedMarg*
• .u-gutters*
• .u-spaced* replaced with vertical padding .py-*
• .u-pull* , spiritually succeeded by .order-*. But, there are also .pull- classes if you just need to move something to the left.
• .u-push* , spiritually succeeded by .order-*. But, there are also .push- classes if you just need to move something to the right.
• .u-radius*
• .u-text* , exceptions for .u-textUpper and .u-textCenter.
• .u-style*
• .u-weight* , exceptions for .u-weightNormal and .u-weightBold.
• .u-fontSize*

Components

All components have been removed from Cacao. The purpose of Cacao has pivoted to being only a reset/base and core utilities.

Changed to a Utility

• .Constrain → .aspect. Many options removed.
• .FlexEmbed → .embed. Use .aspect for an aspect ratio.
• .Grid → .grid. Alignment and gutters can be handled using the new Flex utilities.
• .Image--* → .image-*. Only ported options for left and right.

Removed

• .Arrange
• .Breadcrumb
• .Button
• .Container
• .Content
• .FormError
• .FormLabel
• .FormRequired
• .SelectInput
• .FormSuccess
• .TextInput
• .ImageCaption
• .ImageWrapper
• .ColumnList
• .List
• .Media
• .Message
• .NavBar
• .Dropdown
• .FooterNav
• .MainNav
• .SidebarNav
• .SmScBtn
• .Pagination
• .Triangle

Grid styles

Equal height grids

Remove Grid--equalHeight from the grid div.

Add flex class to the grid column divs.

Aligning cells

Change these classes on the grid div.

• Grid--alignBottom → align-end
• Grid--alignMiddle → align-center
• Grid-alignCenter → justify-center
• Grid--alignRight → justify-right

Grid gutters

• Grid--withGutterSm → g-1
• Grid--withGutter → g-2
• Grid--withGutterLg → g-4
• Grid--withGutterXlg → g-5 (although a g-6 would be nice since the margin is about 60px)

Grid column sizes

When changing the classes for grid columns remember that the new Cacao is mobile-first. Start with the smallest column size and go up from there.

You'll typically see u-sm-, u-md-, and u-lg- styles. The smallest one is the base column size. After that we use the breakpoint styles, but one size smaller than the old class names.

For example, if the grid column had these styles: Grid-cell u-size1of5 u-lg-size1of4 u-md-size1of3 u-sm-sizeFull then you would do this:

1. Remove the Grid-cell class.
2. Change u-sm-sizeFull to col-1-1.
3. Change u-md-size1of3 to col-sm-1-3.
4. Change u-lg-size1of4 to col-md-1-4.
5. Change u-size1of5 to col-lg-1-5.

The end result will be

col-1-1 col-sm-1-3 col-md-1-4 col-lg-1-5

By convention, we start with the smallest screen size and progress from there.