Add new mask-image utilities for Tailwind CSS v4.1

[thecrypticace]

This PR adds a new set of composable mask-image utilities, designed to make it easy to create common masking effects while still offering complete control for very custom masks using arbitrary values.

For a quick demo with practical examples, take a look at this prototype that was built in Tailwind Play:

Live prototype

Note: that this prototype contains some implementation differences. There are extra, unnecessary declarations to make the utilities sort correctly which are not needed in core. Also the @property declarations in the prototype are just properties on * instead of using @property which the actual implementation uses.

API reference

Linear masks

Masking single edges

Utility	Description	Default value
mask-t-from-* (e.g. mask-t-from-80%)	Sets the black stop position for the bottom to top mask	0%
mask-t-to-* (e.g. mask-t-to-90%)	Sets the transparent stop position for bottom to top mask	100%
mask-r-from-* (e.g. mask-r-from-80%)	Sets the black stop position for the left to right mask	0%
mask-r-to-* (e.g. mask-r-to-90%)	Sets the transparent stop position for left to right mask	100%
mask-b-from-* (e.g. mask-b-from-80%)	Sets the black stop position for the top to bottom mask	0%
mask-b-to-* (e.g. mask-b-to-90%)	Sets the transparent stop position for top to bottom mask	100%
mask-l-from-* (e.g. mask-l-from-80%)	Sets the black stop position for the right to left mask	0%
mask-l-to-* (e.g. mask-l-to-90%)	Sets the transparent stop position for right to left mask	100%

Notes:

• These utilities should all accept percentages and spacing values as bare values
• Both from and to are optional as long as the other one is specified

Symmetrical masks

Utility	Description	Default value
mask-x-from-* (e.g. mask-x-from-80%)	Sets the black stop position for both left and right edges	0%
mask-x-to-* (e.g. mask-x-to-90%)	Sets the transparent stop position for both left and right edges	100%
mask-y-from-* (e.g. mask-y-from-80%)	Sets the black stop position for both top and bottom edges	0%
mask-y-to-* (e.g. mask-y-to-90%)	Sets the transparent stop position for both top and bottom edges	100%

Notes:

• These are just a shorthand for setting (for example) both mask-l-from and mask-r-from at the same time — each of these utilities contributes to two separate gradients, they aren't combined into a single linear gradient

Custom linear masks

Utility	Description	Default value
mask-linear-* (e.g. mask-linear-45)	Sets the angle for a custom linear mask	0deg
mask-linear-from-* (e.g. mask-linear-from-50%)	Sets the black stop position for a custom linear mask	0%
mask-linear-to-* (e.g. mask-linear-to-75%)	Sets the transparent stop position for a custom linear mask	100%

Notes:

• mask-linear-* can be both a bare angle that's used with the mask-linear-from-* and mask-linear-to-* utilities, or it can be a complete arbitrary linear gradient like mask-linear-[black_10%,transparent_85%]
• from and to both have defaults so they are both optional

Radial masks

Radial mask size

Utility	Description	Default value
mask-radial-* (e.g. mask-radial-[50%_75%])	Sets the radial gradient size to an arbitrary value	farthest-corner
mask-radial-closest-side	Sets the radial gradient size to closest-side
mask-radial-closest-corner	Sets the radial gradient size to closest-corner
mask-radial-farthest-side	Sets the radial gradient size to fartheset-side
mask-radial-farthest-corner	Sets the radial gradient size to farthest-corner
mask-radial-closest-corner	Sets the radial gradient size to closest-corner

Notes:

• mask-radial-* can be just a size when combined with utilities like mask-radial-from-*, or it can be used to provide a complete arbitrary radial mask like mask-radial-[circle_at_top,black_25%,transparent_80%]

Radial mask shape

Utility	Description	Default value
mask-circle	Sets the radial gradient shape to circle
mask-ellipse	Sets the radial gradient shape to ellipse

Notes:

• mask-ellipse is the default, so it's only really useful to "undo" mask-circle

Radial mask position

Utility	Description	Default value
mask-radial-at-* (e.g. mask-radial-at-[25%_100px])	Sets the radial gradient position to an arbitrary value	center
mask-radial-at-top	Sets the radial gradient position to top
mask-radial-at-top-left	Sets the radial gradient position to top left
mask-radial-at-top-right	Sets the radial gradient position to top right
mask-radial-at-bottom	Sets the radial gradient position to bottom
mask-radial-at-bottom-left	Sets the radial gradient position to bottom left
mask-radial-at-bottom-right	Sets the radial gradient position to bottom right
mask-radial-at-left	Sets the radial gradient position to left
mask-radial-at-right	Sets the radial gradient position to right

Notes:

• These are optional, radial masks will just be centered by default

Radial mask stops

Utility	Description	Default value
mask-radial-from-* (e.g. mask-radial-from-80%)	Sets the black stop position for the radial gradient	0%
mask-radial-to-* (e.g. mask-radial-to-90%)	Sets the transparent stop position for radial gradient	100%

Notes:

• Both of these have defaults so you only need to specify one, but can specify both for more control

Conic masks

Utility	Description	Default value
mask-conic-* (e.g. mask-conic-45)	Sets the angle for the conic gradient	0deg
mask-conic-from-* (e.g. mask-conic-from-50%)	Sets the black stop position for the conic gradient	0%
mask-conic-to-* (e.g. mask-conic-to-75%)	Sets the transparent stop position for the conic gradient	100%

Notes:

• mask-conic-* can be just an angle when combined with utilities like mask-conic-from-*, or it can be used to provide a complete arbitrary conic mask like mask-conic-[from_78deg,black_25%,transparent_80%]
• from and to both have defaults so they are both optional

Arbitrary masks

Utility	Description
mask-* (e.g. mask-[linear-gradient(to_bottom,black_45%,transparent_65%,black_90%)])	Sets mask-image to an arbitrary value

Notes:

• This completely overrides the entire mask-image definition, so it's not composable with other mask utilities

[RobinMalfait]

Nice one!

I did notice that we have a utility duplicated (mask-none), and there are a few cases where we don't have explicit tests for.

[RobinMalfait]

💪