diff --git a/CHANGELOG.md b/CHANGELOG.md
index f347ba1a..19623018 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,12 @@
- [breaking] Rebuild Assembly's CSS pipeline on [UnoCSS](https://unocss.dev/). Class names and `buildUserAssets` stay compatible; the generated stylesheet's formatting, comments, and source maps may differ. Node.js 24+ is required.
- [add] Export `presetAssembly()` for on-demand UnoCSS builds that keep Assembly class names. Pass `{ safelist: true }` only when you want the full prebuilt utility set.
-- [add] `examples/jit` — a sample app that generates only the utilities used in its markup (no reset or component preflight).
+- [add] `gap{size}`, `gapx{size}`, and `gapy{size}` on the padding scale, with `*-mm` / `*-ml` / `*-mxl` variants. Use with `flex` or `grid`.
+- [breaking] `grid` is a 12-column CSS Grid. A `col` without a width class spans the full row, `w-1/12` to `w-11/12` set how many columns it spans, `ml-1/12` to `ml-11/12` set where it starts, and `grid--gut{size}` sets `column-gap`. `col--auto` is removed, and other left and right margins on a grid `col` are ignored.
+- [add] `examples/jit` — a sample app that generates only the utilities used in its markup (no reset or component preflight). On-demand builds can also emit off-scale transforms (`rotate*`, `scale*`); pixel utilities stay on the documented scale.
+- [add] `aspect-{ratio}` / `aspect-auto`, `object-{contain,cover,fill,none,scale-down}`, `flex--space-around-main` / `flex--space-evenly-main`, and transform utilities (`rotate{deg}`, `scale{percent}`).
+- [breaking] `txt-break-word` uses `overflow-wrap: anywhere`, so words break only when they would overflow, instead of `word-break: break-all`.
+- [add] `animation-shimmer`, `visible-on-parent-hover`, `bg-canvas`, and `bg-canvas--dark`.
- [internal] Assembly utilities are UnoCSS rules in `src/preset/`. Reset and component CSS live in `src/preset/base.css`. The package build is `src/build-*.js`. The documentation site is VitePress under `docs/`.
## 1.16.0
diff --git a/MIGRATION_GUIDES.md b/MIGRATION_GUIDES.md
index 48403458..96926d96 100644
--- a/MIGRATION_GUIDES.md
+++ b/MIGRATION_GUIDES.md
@@ -4,11 +4,11 @@
Version 2.0.0 rebuilds Assembly with [UnoCSS](https://unocss.dev/) while keeping the existing class names and `buildUserAssets` API.
-You do not need to change class names in markup. Continue to use `assembly.css` / `assembly.js`, or keep calling `Assembly.buildUserAssets`.
+Most markup works unchanged. Continue to use `assembly.css` / `assembly.js`, or keep calling `Assembly.buildUserAssets`. Check grids and `txt-break-word` for the changes below.
What can change:
-- The contents of `assembly.css` are generated by UnoCSS, so whitespace, comments, rule order, and source maps may differ from 1.x. Selectors and declarations for public classes stay the same.
+- The contents of `assembly.css` are generated by UnoCSS, so whitespace, comments, rule order, and source maps may differ from 1.x. Selectors and declarations for public classes stay the same, except for the grid and `txt-break-word`.
- Layout-scale media variants (`px12-mm`, `w-1/2-ml`, and so on) now use the same custom media queries you pass to `buildUserAssets`, instead of the hardcoded default breakpoints.
- `@mapbox/assembly` now depends on `@unocss/core` (used when creating custom builds) and requires Node.js 24+.
@@ -27,6 +27,29 @@ export default defineConfig({
The generated CSS still uses Assembly's CSS variables and custom media queries, so it needs a PostCSS step with `postcss-custom-properties` and `postcss-custom-media`. See [`presetAssembly` in the README](README.md#presetassemblyoptions) for the config.
+### `grid` is CSS Grid
+
+`grid` is now a 12-column CSS Grid instead of a flexbox row. `grid`, `col`, `w-1/12` to `w-11/12`, and `grid--gut{size}` keep their names. Check grids that rely on flexbox behavior:
+
+- `col--auto` is removed. For columns that share the remaining space, use `flex` with `flex-child-grow` on the children.
+- A `col` without a width class spans the full row instead of sizing to its content. For content-sized columns, use `flex`.
+- `flex-child-*` classes have no effect on a `col`.
+- Left and right margin classes on a `col` are ignored. `ml-1/12` to `ml-11/12` still offset a `col`, and need a `w-*` fraction class next to them. `mr-1/12` to `mr-11/12` have no grid equivalent.
+- Give every direct child of `grid` the `col` class, including children that only have a `w-*` fraction class.
+- `grid--gut{size}` sets `column-gap` instead of a negative margin on `grid` and padding on `col`. Add `gapy{size}` for space between rows.
+
+### `txt-break-word`
+
+`txt-break-word` uses `overflow-wrap: anywhere` instead of `word-break: break-all`, so words break only when they would overflow their container.
+
+### New utilities
+
+These are additive with 1.x class names:
+
+- `gap12` / `gapx12` / `gapy12` (padding scale) for `flex` and `grid` spacing.
+- `aspect-16/9`, `object-cover`, `flex--space-evenly-main`, `rotate90`, `scale50`.
+- `animation-shimmer`, `visible-on-parent-hover`, `bg-canvas`, `bg-canvas--dark`.
+
## 1.0.0+
Version 1.0.0 of Assembly introduces breaking changes – learn how to resolve them with this handy guide.
diff --git a/docs/.vitepress/theme/IconGrid.vue b/docs/.vitepress/theme/IconGrid.vue
index 8a6a9115..ea056e31 100644
--- a/docs/.vitepress/theme/IconGrid.vue
+++ b/docs/.vitepress/theme/IconGrid.vue
@@ -7,7 +7,7 @@ import { data as icons } from './icons.data.js';
diff --git a/docs/.vitepress/theme/site-nav.js b/docs/.vitepress/theme/site-nav.js
index 5fa8504c..a92da6c0 100644
--- a/docs/.vitepress/theme/site-nav.js
+++ b/docs/.vitepress/theme/site-nav.js
@@ -70,8 +70,12 @@ const nav = [
'Positioning',
'Margins',
'Padding',
+ 'Gap',
'Sizing',
'Flexbox',
+ 'Aspect ratio',
+ 'Object fit',
+ 'Transforms',
'Layout utils'
]),
docSection('Theming', [
diff --git a/docs/documentation/animations.md b/docs/documentation/animations.md
index 45567baa..4b36bc08 100644
--- a/docs/documentation/animations.md
+++ b/docs/documentation/animations.md
@@ -22,6 +22,20 @@ Transition and reaction animations. By default, these run once for 1.5 seconds.
```
+```selectors
+.animation-shimmer
+```
+
+Sweep a highlight across an element to show it is loading or updating. Works on any background color except white. Runs infinitely for 1.5 seconds per sweep; use the speed and delay modifiers below to change it.
+
+```example
+
+
+
+
+
+```
+
```selectors
.animation--speed-025
.animation--speed-05
diff --git a/docs/documentation/layout.md b/docs/documentation/layout.md
index 7631d642..36d83902 100644
--- a/docs/documentation/layout.md
+++ b/docs/documentation/layout.md
@@ -4,16 +4,16 @@ Define the size, shape, and content flow of your markup.
## Grid
-Assembly uses a 12-column flexible grid with optional gutters.
+Assembly uses a 12-column CSS Grid with optional gutters.
```selectors
.grid
.col
```
-Grids require at minimum two elements: A parent with the class `grid` and a child with the class `col`. To define the width of `col` in a grid, add a width class, `col--auto`, or both. The `grid` class includes `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes.
+Grids require at minimum two elements: A parent with the class `grid` and a child with the class `col`. A `col` spans the full row unless you add a `w-1/12` to `w-11/12` fraction class, which sets how many of the 12 columns it spans. Offset a `col` that has a width class with an [`ml-1/12` to `ml-11/12`](#margins) fraction class; other left and right margins on `col` are ignored inside a grid. The `grid` class includes `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes.
-To avoid unexpected side-effects, do not add margin left or right to `grid` and do not add padding left or right to `col`.
+Align columns with the `flex--*-cross` [flexbox](#flexbox) classes.
```example
@@ -23,18 +23,10 @@ To avoid unexpected side-effects, do not add margin left or right to `grid` and
```
-```selectors
-.col--auto
-```
-
-Apply to a `col` element to override a `col--{size}` rule and take on default `col`, occupying equal space with other `col` siblings.
-This class is designed to be used with `*-mm`, `*-ml`, and `*-mxl` variations
-to target screen sizes.
-
```example
-
w-1/4 col--auto-ml
-
w-3/4 col--auto-ml
+
w-1/4-ml
+
w-3/4-ml
```
@@ -51,19 +43,14 @@ to target screen sizes.
.grid--gut120
```
-Apply column gutters to all columns in a grid by adding a `grid--gut{size}` modifier to the `grid` element. Class set includes `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes.
+Apply column gutters to all columns in a grid by adding a `grid--gut{size}` modifier to the `grid` element. For space between rows, add a [`gapy{size}`](#gap) class. Class set includes `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes.
```example
-
-
-
w-1/6
-
-
-
w-1/3
-
-
-
w-1/2
-
+
+
w-1/6
+
w-1/3
+
w-1/2
+
col
```
@@ -223,11 +210,12 @@ Apply margin on the right.
.mr-11/12
```
-Apply percentage-based margin on the right. When using with `col`, add a width class, `col--auto`, or both to define the size of the element.
+Apply percentage-based margin on the right.
```example
-
-
mr-1/2
+
+
mr-1/2
+
w-1/4
```
@@ -267,7 +255,7 @@ Apply margin on the left.
.ml-11/12
```
-Apply percentage-based margin on the left. When using with `col`, add a width class, `col--auto`, or both to define the size of the element.
+Apply percentage-based margin on the left. Inside a `grid`, these offset a `col` by the same fraction of the 12 columns; pair them with a `w-*` fraction class.
```example
@@ -340,6 +328,52 @@ Apply padding on the left.
pl24
```
+## Gap
+
+Gap utilities fit `gap{size}`, `gapx{size}`, and `gapy{size}` on the padding scale.
+Class sets include `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes.
+Use with `flex`, `inline-flex`, or `grid`.
+
+```selectors
+.gap{gap}
+```
+
+Apply `gap` on both axes.
+
+```example
+
+```
+
## Sizing
All sizing classes fit the following pattern: `` or `-full` for `100%`.
@@ -674,6 +708,32 @@ and last child is at the end.
```
+```selectors
+.flex--space-around-main
+```
+
+Distribute children with equal space around each item on the main axis.
+
+```example
+
+
child
+
child
+
+```
+
+```selectors
+.flex--space-evenly-main
+```
+
+Distribute children with equal space between and around items on the main axis.
+
+```example
+
+
child
+
child
+
+```
+
```selectors
.flex-child-grow
```
@@ -708,6 +768,69 @@ This class prevents that default shrinkage, forcing siblings to accommodate the
```
+## Aspect ratio
+
+Class set includes `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes.
+
+```selectors
+.aspect-auto
+.aspect-1/1
+.aspect-4/3
+.aspect-3/2
+.aspect-16/9
+.aspect-21/9
+.aspect-3/4
+.aspect-9/16
+```
+
+Set `aspect-ratio`. `aspect-auto` resets it.
+
+```example
+
aspect-16/9
+```
+
+## Object fit
+
+```selectors
+.object-contain
+.object-cover
+.object-fill
+.object-none
+.object-scale-down
+```
+
+Set `object-fit` on replaced elements such as `img` and `video`.
+Class set includes `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes.
+
+```example
+
object-cover
+```
+
+## Transforms
+
+Transform utilities use the individual `rotate` and `scale` properties so they compose.
+Class sets include `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes.
+
+```selectors
+.rotate{rotate}
+```
+
+Rotate an element. Combines with `scale*`.
+
+```example
+
+```
+
+```selectors
+.scale{scale}
+```
+
+Scale an element. `scale100` is `1`. Combines with `rotate*`.
+
+```example
+
+```
+
## Layout utils
Extra layout utilities.
diff --git a/docs/documentation/miscellaneous.md b/docs/documentation/miscellaneous.md
index 5289be2e..ccd0bdf7 100644
--- a/docs/documentation/miscellaneous.md
+++ b/docs/documentation/miscellaneous.md
@@ -38,6 +38,32 @@ Use `color-*` classes to apply a custom color to the spinner handle.
```
+```selectors
+.visible-on-parent-hover
+```
+
+Hide an element until its parent is hovered or contains keyboard focus.
+
+```example
+
+ Hover this row
+
+
+```
+
+```selectors
+.bg-canvas
+.bg-canvas--dark
+```
+
+Fill an element with a checkerboard, for previewing transparent images and colors.
+On dark backgrounds, add the `bg-canvas--dark` modifier.
+
+```example
+
+
+```
+
```selectors
.events-none
```
diff --git a/docs/documentation/typography.md b/docs/documentation/typography.md
index cbd6a9b3..27cb3d52 100644
--- a/docs/documentation/typography.md
+++ b/docs/documentation/typography.md
@@ -302,7 +302,7 @@ Prevent text from wrapping.
.txt-break-word
```
-Allow words to break across lines.
+Break a word across lines only when it would overflow its container.
```example
-This effect is easy, of course, if you can fix the height of the columns. Often, though, that's not what you want. If you want columns to have equal heights *based on the column with the tallest content*, you need some flexbox powers.
+This effect is easy, of course, if you can fix the height of the columns. Often, though, that's not what you want. If you want columns to have equal heights *based on the column with the tallest content*, use a `grid`.
-The key here is to add `flex--stretch-cross` to the `grid`, and add `h-full` to the *child* of the `col` element, which is the one with the background color.
+Columns in a `grid` stretch to the height of the tallest column in their row, so add `h-full` to the *child* of the `col` element, which is the one with the background color.
Assembly comes with icons covering most UI design needs. The icons are designed to be used as embedded SVGs. For usage instructions, see the [`icon` class documentation](/documentation/#icons).
+
These are the numbers, corresponding to pixel values, available for each set of layout classes. All of these class sets include `*-mm`, `*-ml`, and `*-mxl` variations to target screen sizes.
+