feat(ui): add Mosaic hover, motionSafe, and alpha CSS utilities

.changeset/real-chicken-build.md

@@ -0,0 +1,2 @@
+---
+---

eslint.config.mjs

@@ -536,6 +536,29 @@ export default tseslint.config([
  'custom-rules/no-physical-css-properties': 'error',
  },
  },
+ {
+ name: 'packages/ui/mosaic',
+ files: ['packages/ui/src/mosaic/**/*'],
+ ignores: ['packages/ui/src/mosaic/utils.ts', 'packages/ui/src/mosaic/__tests__/**'],
+ rules: {
+ 'no-restricted-syntax': [
+ 'error',
+ {
+ selector: "Property > Literal.key[value='&:hover']",
+ message: "Use hover() from mosaic/utils instead of bare '&:hover'.",
+ },
+ {
+ selector: "Property > Literal.key[value='@media (hover: hover)']",
+ message: "Use hover() from mosaic/utils instead of raw '@media (hover: hover)'.",
+ },
+ {
+ selector: "Property > Literal.key[value='@media (prefers-reduced-motion: no-preference)']",
+ message:
+ "Use motionSafe() from mosaic/utils instead of raw '@media (prefers-reduced-motion: no-preference)'.",
+ },
+ ],
+ },
+ },
  {
  name: 'packages - vitest',
  files: ['packages/*/src/**/*.test.{ts,tsx}'],

packages/ui/src/mosaic/__tests__/utils.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+
+import { defaultMosaicVariables, resolveVariables } from '../variables';
+import { alpha, hover, motionSafe } from '../utils';
+
+describe('hover', () => {
+ it('wraps styles in @media (hover: hover) and &:hover', () => {
+ expect(hover({ color: 'red' })).toEqual({
+ '@media (hover: hover)': {
+ '&:hover': { color: 'red' },
+ },
+ });
+ });
+
+ it('passes complex style objects through unchanged', () => {
+ const styles = { backgroundColor: 'blue', opacity: 0.8, transform: 'scale(1.05)' };
+ expect(hover(styles)).toEqual({
+ '@media (hover: hover)': {
+ '&:hover': styles,
+ },
+ });
+ });
+});
+
+describe('motionSafe', () => {
+ it('wraps styles in @media (prefers-reduced-motion: no-preference)', () => {
+ expect(motionSafe({ transition: 'transform 200ms ease' })).toEqual({
+ '@media (prefers-reduced-motion: no-preference)': { transition: 'transform 200ms ease' },
+ });
+ });
+});
+
+describe('alpha', () => {
+ it('produces a color-mix expression', () => {
+ expect(alpha('#000', 50)).toBe('color-mix(in oklab, #000 50%, transparent)');
+ });
+
+ it('accepts any CSS color string', () => {
+ expect(alpha('oklch(58.5% .233 277.117)', 80)).toBe(
+ 'color-mix(in oklab, oklch(58.5% .233 277.117) 80%, transparent)',
+ );
+ });
+
+ it('matches theme.alpha output for the same resolved color', () => {
+ const theme = resolveVariables(defaultMosaicVariables);
+ const resolvedColor = defaultMosaicVariables.color.primary;
+ expect(theme.alpha('primary', 60)).toBe(alpha(resolvedColor, 60));
+ });
+});

packages/ui/src/mosaic/components/button.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 
 import { cva, type VariantProps } from '../cva';
 import { useMosaicTheme } from '../MosaicProvider';
+import { hover } from '../utils';
 
 export const buttonStyles = cva(theme => ({
  base: {
@@ -27,7 +28,7 @@ export const buttonStyles = cva(theme => ({
  primary: {
  backgroundColor: theme.color.primary,
  color: theme.color.primaryForeground,
-'&:hover': { backgroundColor: theme.mix('primary', 'primaryForeground', 12) },
+...hover({ backgroundColor: theme.mix('primary', 'primaryForeground', 12) }),
  '&:active': { backgroundColor: theme.mix('primary', 'primaryForeground', 24) },
  },
  },

packages/ui/src/mosaic/utils.ts

@@ -0,0 +1,22 @@
+import type { StyleRule } from './cva';
+
+/** Wraps styles in `@media (hover: hover)` so they only apply on hover-capable devices. */
+export function hover(styles: StyleRule): StyleRule {
+ return {
+ '@media (hover: hover)': {
+ '&:hover': styles,
+ },
+ };
+}
+
+/** Wraps styles in `@media (prefers-reduced-motion: no-preference)` so animations only run when the user has not requested reduced motion. */
+export function motionSafe(styles: StyleRule): StyleRule {
+ return {
+ '@media (prefers-reduced-motion: no-preference)': styles,
+ };
+}
+
+/** Applies opacity to any CSS color via `color-mix`. */
+export function alpha(color: string, opacity: number): string {
+ return `color-mix(in oklab, ${color} ${opacity}%, transparent)`;
+}

packages/ui/src/mosaic/variables.ts

@@ -1,3 +1,5 @@
+import { alpha } from './utils';
+
 // ─── Token Defaults ──────────────────────────────────────────────────────────
 
 /** Baseline design token values. Every Mosaic theme starts from this object. */
@@ -99,7 +101,7 @@ export function resolveVariables(defaults: MosaicTokens, variables?: MosaicVaria
  ...tokens,
  spacing: (<N extends number>(n: N) => `calc(${tokens.spacing} * ${n})`) as MosaicTheme['spacing'],
  alpha: (<K extends keyof MosaicTokens['color'], O extends number>(color: K, opacity: O) =>
-`color-mix(in oklab, ${tokens.color[color]} ${opacity}%, transparent)`) as MosaicTheme['alpha'],
+alpha(tokens.color[color], opacity)) as MosaicTheme['alpha'],
  mix: (<A extends keyof MosaicTokens['color'], B extends keyof MosaicTokens['color'], P extends number>(
  a: A,
  b: B,

.changeset/real-chicken-build.md

@@ -0,0 +1,2 @@
+---
+---

eslint.config.mjs

@@ -536,6 +536,29 @@ export default tseslint.config([
  'custom-rules/no-physical-css-properties': 'error',
  },
  },
+ {
+ name: 'packages/ui/mosaic',
+ files: ['packages/ui/src/mosaic/**/*'],
+ ignores: ['packages/ui/src/mosaic/utils.ts', 'packages/ui/src/mosaic/__tests__/**'],
+ rules: {
+ 'no-restricted-syntax': [
+ 'error',
+ {
+ selector: "Property > Literal.key[value='&:hover']",
+ message: "Use hover() from mosaic/utils instead of bare '&:hover'.",
+ },
+ {
+ selector: "Property > Literal.key[value='@media (hover: hover)']",
+ message: "Use hover() from mosaic/utils instead of raw '@media (hover: hover)'.",
+ },
+ {
+ selector: "Property > Literal.key[value='@media (prefers-reduced-motion: no-preference)']",
+ message:
+ "Use motionSafe() from mosaic/utils instead of raw '@media (prefers-reduced-motion: no-preference)'.",
+ },
+ ],
+ },
+ },
  {
  name: 'packages - vitest',
  files: ['packages/*/src/**/*.test.{ts,tsx}'],

packages/ui/src/mosaic/__tests__/utils.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+
+import { defaultMosaicVariables, resolveVariables } from '../variables';
+import { alpha, hover, motionSafe } from '../utils';
+
+describe('hover', () => {
+ it('wraps styles in @media (hover: hover) and &:hover', () => {
+ expect(hover({ color: 'red' })).toEqual({
+ '@media (hover: hover)': {
+ '&:hover': { color: 'red' },
+ },
+ });
+ });
+
+ it('passes complex style objects through unchanged', () => {
+ const styles = { backgroundColor: 'blue', opacity: 0.8, transform: 'scale(1.05)' };
+ expect(hover(styles)).toEqual({
+ '@media (hover: hover)': {
+ '&:hover': styles,
+ },
+ });
+ });
+});
+
+describe('motionSafe', () => {
+ it('wraps styles in @media (prefers-reduced-motion: no-preference)', () => {
+ expect(motionSafe({ transition: 'transform 200ms ease' })).toEqual({
+ '@media (prefers-reduced-motion: no-preference)': { transition: 'transform 200ms ease' },
+ });
+ });
+});
+
+describe('alpha', () => {
+ it('produces a color-mix expression', () => {
+ expect(alpha('#000', 50)).toBe('color-mix(in oklab, #000 50%, transparent)');
+ });
+
+ it('accepts any CSS color string', () => {
+ expect(alpha('oklch(58.5% .233 277.117)', 80)).toBe(
+ 'color-mix(in oklab, oklch(58.5% .233 277.117) 80%, transparent)',
+ );
+ });
+
+ it('matches theme.alpha output for the same resolved color', () => {
+ const theme = resolveVariables(defaultMosaicVariables);
+ const resolvedColor = defaultMosaicVariables.color.primary;
+ expect(theme.alpha('primary', 60)).toBe(alpha(resolvedColor, 60));
+ });
+});

packages/ui/src/mosaic/components/button.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 
 import { cva, type VariantProps } from '../cva';
 import { useMosaicTheme } from '../MosaicProvider';
+import { hover } from '../utils';
 
 export const buttonStyles = cva(theme => ({
  base: {
@@ -27,7 +28,7 @@ export const buttonStyles = cva(theme => ({
  primary: {
  backgroundColor: theme.color.primary,
  color: theme.color.primaryForeground,
-'&:hover': { backgroundColor: theme.mix('primary', 'primaryForeground', 12) },
+...hover({ backgroundColor: theme.mix('primary', 'primaryForeground', 12) }),
  '&:active': { backgroundColor: theme.mix('primary', 'primaryForeground', 24) },
  },
  },

packages/ui/src/mosaic/utils.ts

@@ -0,0 +1,22 @@
+import type { StyleRule } from './cva';
+
+/** Wraps styles in `@media (hover: hover)` so they only apply on hover-capable devices. */
+export function hover(styles: StyleRule): StyleRule {
+ return {
+ '@media (hover: hover)': {
+ '&:hover': styles,
+ },
+ };
+}
+
+/** Wraps styles in `@media (prefers-reduced-motion: no-preference)` so animations only run when the user has not requested reduced motion. */
+export function motionSafe(styles: StyleRule): StyleRule {
+ return {
+ '@media (prefers-reduced-motion: no-preference)': styles,
+ };
+}
+
+/** Applies opacity to any CSS color via `color-mix`. */
+export function alpha(color: string, opacity: number): string {
+ return `color-mix(in oklab, ${color} ${opacity}%, transparent)`;
+}

packages/ui/src/mosaic/variables.ts

@@ -1,3 +1,5 @@
+import { alpha } from './utils';
+
 // ─── Token Defaults ──────────────────────────────────────────────────────────
 
 /** Baseline design token values. Every Mosaic theme starts from this object. */
@@ -99,7 +101,7 @@ export function resolveVariables(defaults: MosaicTokens, variables?: MosaicVaria
  ...tokens,
  spacing: (<N extends number>(n: N) => `calc(${tokens.spacing} * ${n})`) as MosaicTheme['spacing'],
  alpha: (<K extends keyof MosaicTokens['color'], O extends number>(color: K, opacity: O) =>
-`color-mix(in oklab, ${tokens.color[color]} ${opacity}%, transparent)`) as MosaicTheme['alpha'],
+alpha(tokens.color[color], opacity)) as MosaicTheme['alpha'],
  mix: (<A extends keyof MosaicTokens['color'], B extends keyof MosaicTokens['color'], P extends number>(
  a: A,
  b: B,

.changeset/real-chicken-build.md

@@ -0,0 +1,2 @@
+---
+---

eslint.config.mjs

@@ -536,6 +536,29 @@ export default tseslint.config([
  'custom-rules/no-physical-css-properties': 'error',
  },
  },
+ {
+ name: 'packages/ui/mosaic',
+ files: ['packages/ui/src/mosaic/**/*'],
+ ignores: ['packages/ui/src/mosaic/utils.ts', 'packages/ui/src/mosaic/__tests__/**'],
+ rules: {
+ 'no-restricted-syntax': [
+ 'error',
+ {
+ selector: "Property > Literal.key[value='&:hover']",
+ message: "Use hover() from mosaic/utils instead of bare '&:hover'.",
+ },
+ {
+ selector: "Property > Literal.key[value='@media (hover: hover)']",
+ message: "Use hover() from mosaic/utils instead of raw '@media (hover: hover)'.",
+ },
+ {
+ selector: "Property > Literal.key[value='@media (prefers-reduced-motion: no-preference)']",
+ message:
+ "Use motionSafe() from mosaic/utils instead of raw '@media (prefers-reduced-motion: no-preference)'.",
+ },
+ ],
+ },
+ },
  {
  name: 'packages - vitest',
  files: ['packages/*/src/**/*.test.{ts,tsx}'],

packages/ui/src/mosaic/__tests__/utils.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+
+import { defaultMosaicVariables, resolveVariables } from '../variables';
+import { alpha, hover, motionSafe } from '../utils';
+
+describe('hover', () => {
+ it('wraps styles in @media (hover: hover) and &:hover', () => {
+ expect(hover({ color: 'red' })).toEqual({
+ '@media (hover: hover)': {
+ '&:hover': { color: 'red' },
+ },
+ });
+ });
+
+ it('passes complex style objects through unchanged', () => {
+ const styles = { backgroundColor: 'blue', opacity: 0.8, transform: 'scale(1.05)' };
+ expect(hover(styles)).toEqual({
+ '@media (hover: hover)': {
+ '&:hover': styles,
+ },
+ });
+ });
+});
+
+describe('motionSafe', () => {
+ it('wraps styles in @media (prefers-reduced-motion: no-preference)', () => {
+ expect(motionSafe({ transition: 'transform 200ms ease' })).toEqual({
+ '@media (prefers-reduced-motion: no-preference)': { transition: 'transform 200ms ease' },
+ });
+ });
+});
+
+describe('alpha', () => {
+ it('produces a color-mix expression', () => {
+ expect(alpha('#000', 50)).toBe('color-mix(in oklab, #000 50%, transparent)');
+ });
+
+ it('accepts any CSS color string', () => {
+ expect(alpha('oklch(58.5% .233 277.117)', 80)).toBe(
+ 'color-mix(in oklab, oklch(58.5% .233 277.117) 80%, transparent)',
+ );
+ });
+
+ it('matches theme.alpha output for the same resolved color', () => {
+ const theme = resolveVariables(defaultMosaicVariables);
+ const resolvedColor = defaultMosaicVariables.color.primary;
+ expect(theme.alpha('primary', 60)).toBe(alpha(resolvedColor, 60));
+ });
+});

packages/ui/src/mosaic/components/button.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 
 import { cva, type VariantProps } from '../cva';
 import { useMosaicTheme } from '../MosaicProvider';
+import { hover } from '../utils';
 
 export const buttonStyles = cva(theme => ({
  base: {
@@ -27,7 +28,7 @@ export const buttonStyles = cva(theme => ({
  primary: {
  backgroundColor: theme.color.primary,
  color: theme.color.primaryForeground,
-'&:hover': { backgroundColor: theme.mix('primary', 'primaryForeground', 12) },
+...hover({ backgroundColor: theme.mix('primary', 'primaryForeground', 12) }),
  '&:active': { backgroundColor: theme.mix('primary', 'primaryForeground', 24) },
  },
  },

packages/ui/src/mosaic/utils.ts

@@ -0,0 +1,22 @@
+import type { StyleRule } from './cva';
+
+/** Wraps styles in `@media (hover: hover)` so they only apply on hover-capable devices. */
+export function hover(styles: StyleRule): StyleRule {
+ return {
+ '@media (hover: hover)': {
+ '&:hover': styles,
+ },
+ };
+}
+
+/** Wraps styles in `@media (prefers-reduced-motion: no-preference)` so animations only run when the user has not requested reduced motion. */
+export function motionSafe(styles: StyleRule): StyleRule {
+ return {
+ '@media (prefers-reduced-motion: no-preference)': styles,
+ };
+}
+
+/** Applies opacity to any CSS color via `color-mix`. */
+export function alpha(color: string, opacity: number): string {
+ return `color-mix(in oklab, ${color} ${opacity}%, transparent)`;
+}

packages/ui/src/mosaic/variables.ts

@@ -1,3 +1,5 @@
+import { alpha } from './utils';
+
 // ─── Token Defaults ──────────────────────────────────────────────────────────
 
 /** Baseline design token values. Every Mosaic theme starts from this object. */
@@ -99,7 +101,7 @@ export function resolveVariables(defaults: MosaicTokens, variables?: MosaicVaria
  ...tokens,
  spacing: (<N extends number>(n: N) => `calc(${tokens.spacing} * ${n})`) as MosaicTheme['spacing'],
  alpha: (<K extends keyof MosaicTokens['color'], O extends number>(color: K, opacity: O) =>
-`color-mix(in oklab, ${tokens.color[color]} ${opacity}%, transparent)`) as MosaicTheme['alpha'],
+alpha(tokens.color[color], opacity)) as MosaicTheme['alpha'],
  mix: (<A extends keyof MosaicTokens['color'], B extends keyof MosaicTokens['color'], P extends number>(
  a: A,
  b: B,

.changeset/real-chicken-build.md

@@ -0,0 +1,2 @@
+---
+---

eslint.config.mjs

@@ -536,6 +536,29 @@ export default tseslint.config([
  'custom-rules/no-physical-css-properties': 'error',
  },
  },
+ {
+ name: 'packages/ui/mosaic',
+ files: ['packages/ui/src/mosaic/**/*'],
+ ignores: ['packages/ui/src/mosaic/utils.ts', 'packages/ui/src/mosaic/__tests__/**'],
+ rules: {
+ 'no-restricted-syntax': [
+ 'error',
+ {
+ selector: "Property > Literal.key[value='&:hover']",
+ message: "Use hover() from mosaic/utils instead of bare '&:hover'.",
+ },
+ {
+ selector: "Property > Literal.key[value='@media (hover: hover)']",
+ message: "Use hover() from mosaic/utils instead of raw '@media (hover: hover)'.",
+ },
+ {
+ selector: "Property > Literal.key[value='@media (prefers-reduced-motion: no-preference)']",
+ message:
+ "Use motionSafe() from mosaic/utils instead of raw '@media (prefers-reduced-motion: no-preference)'.",
+ },
+ ],
+ },
+ },
  {
  name: 'packages - vitest',
  files: ['packages/*/src/**/*.test.{ts,tsx}'],

packages/ui/src/mosaic/__tests__/utils.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+
+import { defaultMosaicVariables, resolveVariables } from '../variables';
+import { alpha, hover, motionSafe } from '../utils';
+
+describe('hover', () => {
+ it('wraps styles in @media (hover: hover) and &:hover', () => {
+ expect(hover({ color: 'red' })).toEqual({
+ '@media (hover: hover)': {
+ '&:hover': { color: 'red' },
+ },
+ });
+ });
+
+ it('passes complex style objects through unchanged', () => {
+ const styles = { backgroundColor: 'blue', opacity: 0.8, transform: 'scale(1.05)' };
+ expect(hover(styles)).toEqual({
+ '@media (hover: hover)': {
+ '&:hover': styles,
+ },
+ });
+ });
+});
+
+describe('motionSafe', () => {
+ it('wraps styles in @media (prefers-reduced-motion: no-preference)', () => {
+ expect(motionSafe({ transition: 'transform 200ms ease' })).toEqual({
+ '@media (prefers-reduced-motion: no-preference)': { transition: 'transform 200ms ease' },
+ });
+ });
+});
+
+describe('alpha', () => {
+ it('produces a color-mix expression', () => {
+ expect(alpha('#000', 50)).toBe('color-mix(in oklab, #000 50%, transparent)');
+ });
+
+ it('accepts any CSS color string', () => {
+ expect(alpha('oklch(58.5% .233 277.117)', 80)).toBe(
+ 'color-mix(in oklab, oklch(58.5% .233 277.117) 80%, transparent)',
+ );
+ });
+
+ it('matches theme.alpha output for the same resolved color', () => {
+ const theme = resolveVariables(defaultMosaicVariables);
+ const resolvedColor = defaultMosaicVariables.color.primary;
+ expect(theme.alpha('primary', 60)).toBe(alpha(resolvedColor, 60));
+ });
+});

packages/ui/src/mosaic/components/button.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 
 import { cva, type VariantProps } from '../cva';
 import { useMosaicTheme } from '../MosaicProvider';
+import { hover } from '../utils';
 
 export const buttonStyles = cva(theme => ({
  base: {
@@ -27,7 +28,7 @@ export const buttonStyles = cva(theme => ({
  primary: {
  backgroundColor: theme.color.primary,
  color: theme.color.primaryForeground,
-'&:hover': { backgroundColor: theme.mix('primary', 'primaryForeground', 12) },
+...hover({ backgroundColor: theme.mix('primary', 'primaryForeground', 12) }),
  '&:active': { backgroundColor: theme.mix('primary', 'primaryForeground', 24) },
  },
  },

packages/ui/src/mosaic/utils.ts

@@ -0,0 +1,22 @@
+import type { StyleRule } from './cva';
+
+/** Wraps styles in `@media (hover: hover)` so they only apply on hover-capable devices. */
+export function hover(styles: StyleRule): StyleRule {
+ return {
+ '@media (hover: hover)': {
+ '&:hover': styles,
+ },
+ };
+}
+
+/** Wraps styles in `@media (prefers-reduced-motion: no-preference)` so animations only run when the user has not requested reduced motion. */
+export function motionSafe(styles: StyleRule): StyleRule {
+ return {
+ '@media (prefers-reduced-motion: no-preference)': styles,
+ };
+}
+
+/** Applies opacity to any CSS color via `color-mix`. */
+export function alpha(color: string, opacity: number): string {
+ return `color-mix(in oklab, ${color} ${opacity}%, transparent)`;
+}

packages/ui/src/mosaic/variables.ts

@@ -1,3 +1,5 @@
+import { alpha } from './utils';
+
 // ─── Token Defaults ──────────────────────────────────────────────────────────
 
 /** Baseline design token values. Every Mosaic theme starts from this object. */
@@ -99,7 +101,7 @@ export function resolveVariables(defaults: MosaicTokens, variables?: MosaicVaria
  ...tokens,
  spacing: (<N extends number>(n: N) => `calc(${tokens.spacing} * ${n})`) as MosaicTheme['spacing'],
  alpha: (<K extends keyof MosaicTokens['color'], O extends number>(color: K, opacity: O) =>
-`color-mix(in oklab, ${tokens.color[color]} ${opacity}%, transparent)`) as MosaicTheme['alpha'],
+alpha(tokens.color[color], opacity)) as MosaicTheme['alpha'],
  mix: (<A extends keyof MosaicTokens['color'], B extends keyof MosaicTokens['color'], P extends number>(
  a: A,
  b: B,

.changeset/real-chicken-build.md

@@ -0,0 +1,2 @@
+---
+---

eslint.config.mjs

@@ -536,6 +536,29 @@ export default tseslint.config([
  'custom-rules/no-physical-css-properties': 'error',
  },
  },
+ {
+ name: 'packages/ui/mosaic',
+ files: ['packages/ui/src/mosaic/**/*'],
+ ignores: ['packages/ui/src/mosaic/utils.ts', 'packages/ui/src/mosaic/__tests__/**'],
+ rules: {
+ 'no-restricted-syntax': [
+ 'error',
+ {
+ selector: "Property > Literal.key[value='&:hover']",
+ message: "Use hover() from mosaic/utils instead of bare '&:hover'.",
+ },
+ {
+ selector: "Property > Literal.key[value='@media (hover: hover)']",
+ message: "Use hover() from mosaic/utils instead of raw '@media (hover: hover)'.",
+ },
+ {
+ selector: "Property > Literal.key[value='@media (prefers-reduced-motion: no-preference)']",
+ message:
+ "Use motionSafe() from mosaic/utils instead of raw '@media (prefers-reduced-motion: no-preference)'.",
+ },
+ ],
+ },
+ },
  {
  name: 'packages - vitest',
  files: ['packages/*/src/**/*.test.{ts,tsx}'],

packages/ui/src/mosaic/__tests__/utils.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+
+import { defaultMosaicVariables, resolveVariables } from '../variables';
+import { alpha, hover, motionSafe } from '../utils';
+
+describe('hover', () => {
+ it('wraps styles in @media (hover: hover) and &:hover', () => {
+ expect(hover({ color: 'red' })).toEqual({
+ '@media (hover: hover)': {
+ '&:hover': { color: 'red' },
+ },
+ });
+ });
+
+ it('passes complex style objects through unchanged', () => {
+ const styles = { backgroundColor: 'blue', opacity: 0.8, transform: 'scale(1.05)' };
+ expect(hover(styles)).toEqual({
+ '@media (hover: hover)': {
+ '&:hover': styles,
+ },
+ });
+ });
+});
+
+describe('motionSafe', () => {
+ it('wraps styles in @media (prefers-reduced-motion: no-preference)', () => {
+ expect(motionSafe({ transition: 'transform 200ms ease' })).toEqual({
+ '@media (prefers-reduced-motion: no-preference)': { transition: 'transform 200ms ease' },
+ });
+ });
+});
+
+describe('alpha', () => {
+ it('produces a color-mix expression', () => {
+ expect(alpha('#000', 50)).toBe('color-mix(in oklab, #000 50%, transparent)');
+ });
+
+ it('accepts any CSS color string', () => {
+ expect(alpha('oklch(58.5% .233 277.117)', 80)).toBe(
+ 'color-mix(in oklab, oklch(58.5% .233 277.117) 80%, transparent)',
+ );
+ });
+
+ it('matches theme.alpha output for the same resolved color', () => {
+ const theme = resolveVariables(defaultMosaicVariables);
+ const resolvedColor = defaultMosaicVariables.color.primary;
+ expect(theme.alpha('primary', 60)).toBe(alpha(resolvedColor, 60));
+ });
+});

packages/ui/src/mosaic/components/button.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 
 import { cva, type VariantProps } from '../cva';
 import { useMosaicTheme } from '../MosaicProvider';
+import { hover } from '../utils';
 
 export const buttonStyles = cva(theme => ({
  base: {
@@ -27,7 +28,7 @@ export const buttonStyles = cva(theme => ({
  primary: {
  backgroundColor: theme.color.primary,
  color: theme.color.primaryForeground,
-'&:hover': { backgroundColor: theme.mix('primary', 'primaryForeground', 12) },
+...hover({ backgroundColor: theme.mix('primary', 'primaryForeground', 12) }),
  '&:active': { backgroundColor: theme.mix('primary', 'primaryForeground', 24) },
  },
  },

packages/ui/src/mosaic/utils.ts

@@ -0,0 +1,22 @@
+import type { StyleRule } from './cva';
+
+/** Wraps styles in `@media (hover: hover)` so they only apply on hover-capable devices. */
+export function hover(styles: StyleRule): StyleRule {
+ return {
+ '@media (hover: hover)': {
+ '&:hover': styles,
+ },
+ };
+}
+
+/** Wraps styles in `@media (prefers-reduced-motion: no-preference)` so animations only run when the user has not requested reduced motion. */
+export function motionSafe(styles: StyleRule): StyleRule {
+ return {
+ '@media (prefers-reduced-motion: no-preference)': styles,
+ };
+}
+
+/** Applies opacity to any CSS color via `color-mix`. */
+export function alpha(color: string, opacity: number): string {
+ return `color-mix(in oklab, ${color} ${opacity}%, transparent)`;
+}

packages/ui/src/mosaic/variables.ts

@@ -1,3 +1,5 @@
+import { alpha } from './utils';
+
 // ─── Token Defaults ──────────────────────────────────────────────────────────
 
 /** Baseline design token values. Every Mosaic theme starts from this object. */
@@ -99,7 +101,7 @@ export function resolveVariables(defaults: MosaicTokens, variables?: MosaicVaria
  ...tokens,
  spacing: (<N extends number>(n: N) => `calc(${tokens.spacing} * ${n})`) as MosaicTheme['spacing'],
  alpha: (<K extends keyof MosaicTokens['color'], O extends number>(color: K, opacity: O) =>
-`color-mix(in oklab, ${tokens.color[color]} ${opacity}%, transparent)`) as MosaicTheme['alpha'],
+alpha(tokens.color[color], opacity)) as MosaicTheme['alpha'],
  mix: (<A extends keyof MosaicTokens['color'], B extends keyof MosaicTokens['color'], P extends number>(
  a: A,
  b: B,

.changeset/real-chicken-build.md

@@ -0,0 +1,2 @@
+---
+---

eslint.config.mjs

@@ -536,6 +536,29 @@ export default tseslint.config([
  'custom-rules/no-physical-css-properties': 'error',
  },
  },
+ {
+ name: 'packages/ui/mosaic',
+ files: ['packages/ui/src/mosaic/**/*'],
+ ignores: ['packages/ui/src/mosaic/utils.ts', 'packages/ui/src/mosaic/__tests__/**'],
+ rules: {
+ 'no-restricted-syntax': [
+ 'error',
+ {
+ selector: "Property > Literal.key[value='&:hover']",
+ message: "Use hover() from mosaic/utils instead of bare '&:hover'.",
+ },
+ {
+ selector: "Property > Literal.key[value='@media (hover: hover)']",
+ message: "Use hover() from mosaic/utils instead of raw '@media (hover: hover)'.",
+ },
+ {
+ selector: "Property > Literal.key[value='@media (prefers-reduced-motion: no-preference)']",
+ message:
+ "Use motionSafe() from mosaic/utils instead of raw '@media (prefers-reduced-motion: no-preference)'.",
+ },
+ ],
+ },
+ },
  {
  name: 'packages - vitest',
  files: ['packages/*/src/**/*.test.{ts,tsx}'],

packages/ui/src/mosaic/__tests__/utils.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+
+import { defaultMosaicVariables, resolveVariables } from '../variables';
+import { alpha, hover, motionSafe } from '../utils';
+
+describe('hover', () => {
+ it('wraps styles in @media (hover: hover) and &:hover', () => {
+ expect(hover({ color: 'red' })).toEqual({
+ '@media (hover: hover)': {
+ '&:hover': { color: 'red' },
+ },
+ });
+ });
+
+ it('passes complex style objects through unchanged', () => {
+ const styles = { backgroundColor: 'blue', opacity: 0.8, transform: 'scale(1.05)' };
+ expect(hover(styles)).toEqual({
+ '@media (hover: hover)': {
+ '&:hover': styles,
+ },
+ });
+ });
+});
+
+describe('motionSafe', () => {
+ it('wraps styles in @media (prefers-reduced-motion: no-preference)', () => {
+ expect(motionSafe({ transition: 'transform 200ms ease' })).toEqual({
+ '@media (prefers-reduced-motion: no-preference)': { transition: 'transform 200ms ease' },
+ });
+ });
+});
+
+describe('alpha', () => {
+ it('produces a color-mix expression', () => {
+ expect(alpha('#000', 50)).toBe('color-mix(in oklab, #000 50%, transparent)');
+ });
+
+ it('accepts any CSS color string', () => {
+ expect(alpha('oklch(58.5% .233 277.117)', 80)).toBe(
+ 'color-mix(in oklab, oklch(58.5% .233 277.117) 80%, transparent)',
+ );
+ });
+
+ it('matches theme.alpha output for the same resolved color', () => {
+ const theme = resolveVariables(defaultMosaicVariables);
+ const resolvedColor = defaultMosaicVariables.color.primary;
+ expect(theme.alpha('primary', 60)).toBe(alpha(resolvedColor, 60));
+ });
+});

packages/ui/src/mosaic/components/button.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 
 import { cva, type VariantProps } from '../cva';
 import { useMosaicTheme } from '../MosaicProvider';
+import { hover } from '../utils';
 
 export const buttonStyles = cva(theme => ({
  base: {
@@ -27,7 +28,7 @@ export const buttonStyles = cva(theme => ({
  primary: {
  backgroundColor: theme.color.primary,
  color: theme.color.primaryForeground,
-'&:hover': { backgroundColor: theme.mix('primary', 'primaryForeground', 12) },
+...hover({ backgroundColor: theme.mix('primary', 'primaryForeground', 12) }),
  '&:active': { backgroundColor: theme.mix('primary', 'primaryForeground', 24) },
  },
  },

packages/ui/src/mosaic/utils.ts

@@ -0,0 +1,22 @@
+import type { StyleRule } from './cva';
+
+/** Wraps styles in `@media (hover: hover)` so they only apply on hover-capable devices. */
+export function hover(styles: StyleRule): StyleRule {
+ return {
+ '@media (hover: hover)': {
+ '&:hover': styles,
+ },
+ };
+}
+
+/** Wraps styles in `@media (prefers-reduced-motion: no-preference)` so animations only run when the user has not requested reduced motion. */
+export function motionSafe(styles: StyleRule): StyleRule {
+ return {
+ '@media (prefers-reduced-motion: no-preference)': styles,
+ };
+}
+
+/** Applies opacity to any CSS color via `color-mix`. */
+export function alpha(color: string, opacity: number): string {
+ return `color-mix(in oklab, ${color} ${opacity}%, transparent)`;
+}

packages/ui/src/mosaic/variables.ts

@@ -1,3 +1,5 @@
+import { alpha } from './utils';
+
 // ─── Token Defaults ──────────────────────────────────────────────────────────
 
 /** Baseline design token values. Every Mosaic theme starts from this object. */
@@ -99,7 +101,7 @@ export function resolveVariables(defaults: MosaicTokens, variables?: MosaicVaria
  ...tokens,
  spacing: (<N extends number>(n: N) => `calc(${tokens.spacing} * ${n})`) as MosaicTheme['spacing'],
  alpha: (<K extends keyof MosaicTokens['color'], O extends number>(color: K, opacity: O) =>
-`color-mix(in oklab, ${tokens.color[color]} ${opacity}%, transparent)`) as MosaicTheme['alpha'],
+alpha(tokens.color[color], opacity)) as MosaicTheme['alpha'],
  mix: (<A extends keyof MosaicTokens['color'], B extends keyof MosaicTokens['color'], P extends number>(
  a: A,
  b: B,

.changeset/real-chicken-build.md

@@ -0,0 +1,2 @@
+---
+---

eslint.config.mjs

@@ -536,6 +536,29 @@ export default tseslint.config([
  'custom-rules/no-physical-css-properties': 'error',
  },
  },
+ {
+ name: 'packages/ui/mosaic',
+ files: ['packages/ui/src/mosaic/**/*'],
+ ignores: ['packages/ui/src/mosaic/utils.ts', 'packages/ui/src/mosaic/__tests__/**'],
+ rules: {
+ 'no-restricted-syntax': [
+ 'error',
+ {
+ selector: "Property > Literal.key[value='&:hover']",
+ message: "Use hover() from mosaic/utils instead of bare '&:hover'.",
+ },
+ {
+ selector: "Property > Literal.key[value='@media (hover: hover)']",
+ message: "Use hover() from mosaic/utils instead of raw '@media (hover: hover)'.",
+ },
+ {
+ selector: "Property > Literal.key[value='@media (prefers-reduced-motion: no-preference)']",
+ message:
+ "Use motionSafe() from mosaic/utils instead of raw '@media (prefers-reduced-motion: no-preference)'.",
+ },
+ ],
+ },
+ },
  {
  name: 'packages - vitest',
  files: ['packages/*/src/**/*.test.{ts,tsx}'],

packages/ui/src/mosaic/__tests__/utils.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+
+import { defaultMosaicVariables, resolveVariables } from '../variables';
+import { alpha, hover, motionSafe } from '../utils';
+
+describe('hover', () => {
+ it('wraps styles in @media (hover: hover) and &:hover', () => {
+ expect(hover({ color: 'red' })).toEqual({
+ '@media (hover: hover)': {
+ '&:hover': { color: 'red' },
+ },
+ });
+ });
+
+ it('passes complex style objects through unchanged', () => {
+ const styles = { backgroundColor: 'blue', opacity: 0.8, transform: 'scale(1.05)' };
+ expect(hover(styles)).toEqual({
+ '@media (hover: hover)': {
+ '&:hover': styles,
+ },
+ });
+ });
+});
+
+describe('motionSafe', () => {
+ it('wraps styles in @media (prefers-reduced-motion: no-preference)', () => {
+ expect(motionSafe({ transition: 'transform 200ms ease' })).toEqual({
+ '@media (prefers-reduced-motion: no-preference)': { transition: 'transform 200ms ease' },
+ });
+ });
+});
+
+describe('alpha', () => {
+ it('produces a color-mix expression', () => {
+ expect(alpha('#000', 50)).toBe('color-mix(in oklab, #000 50%, transparent)');
+ });
+
+ it('accepts any CSS color string', () => {
+ expect(alpha('oklch(58.5% .233 277.117)', 80)).toBe(
+ 'color-mix(in oklab, oklch(58.5% .233 277.117) 80%, transparent)',
+ );
+ });
+
+ it('matches theme.alpha output for the same resolved color', () => {
+ const theme = resolveVariables(defaultMosaicVariables);
+ const resolvedColor = defaultMosaicVariables.color.primary;
+ expect(theme.alpha('primary', 60)).toBe(alpha(resolvedColor, 60));
+ });
+});

packages/ui/src/mosaic/components/button.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 
 import { cva, type VariantProps } from '../cva';
 import { useMosaicTheme } from '../MosaicProvider';
+import { hover } from '../utils';
 
 export const buttonStyles = cva(theme => ({
  base: {
@@ -27,7 +28,7 @@ export const buttonStyles = cva(theme => ({
  primary: {
  backgroundColor: theme.color.primary,
  color: theme.color.primaryForeground,
-'&:hover': { backgroundColor: theme.mix('primary', 'primaryForeground', 12) },
+...hover({ backgroundColor: theme.mix('primary', 'primaryForeground', 12) }),
  '&:active': { backgroundColor: theme.mix('primary', 'primaryForeground', 24) },
  },
  },

packages/ui/src/mosaic/utils.ts

@@ -0,0 +1,22 @@
+import type { StyleRule } from './cva';
+
+/** Wraps styles in `@media (hover: hover)` so they only apply on hover-capable devices. */
+export function hover(styles: StyleRule): StyleRule {
+ return {
+ '@media (hover: hover)': {
+ '&:hover': styles,
+ },
+ };
+}
+
+/** Wraps styles in `@media (prefers-reduced-motion: no-preference)` so animations only run when the user has not requested reduced motion. */
+export function motionSafe(styles: StyleRule): StyleRule {
+ return {
+ '@media (prefers-reduced-motion: no-preference)': styles,
+ };
+}
+
+/** Applies opacity to any CSS color via `color-mix`. */
+export function alpha(color: string, opacity: number): string {
+ return `color-mix(in oklab, ${color} ${opacity}%, transparent)`;
+}

packages/ui/src/mosaic/variables.ts

@@ -1,3 +1,5 @@
+import { alpha } from './utils';
+
 // ─── Token Defaults ──────────────────────────────────────────────────────────
 
 /** Baseline design token values. Every Mosaic theme starts from this object. */
@@ -99,7 +101,7 @@ export function resolveVariables(defaults: MosaicTokens, variables?: MosaicVaria
  ...tokens,
  spacing: (<N extends number>(n: N) => `calc(${tokens.spacing} * ${n})`) as MosaicTheme['spacing'],
  alpha: (<K extends keyof MosaicTokens['color'], O extends number>(color: K, opacity: O) =>
-`color-mix(in oklab, ${tokens.color[color]} ${opacity}%, transparent)`) as MosaicTheme['alpha'],
+alpha(tokens.color[color], opacity)) as MosaicTheme['alpha'],
  mix: (<A extends keyof MosaicTokens['color'], B extends keyof MosaicTokens['color'], P extends number>(
  a: A,
  b: B,

.changeset/real-chicken-build.md

@@ -0,0 +1,2 @@
+---
+---

eslint.config.mjs

@@ -536,6 +536,29 @@ export default tseslint.config([
  'custom-rules/no-physical-css-properties': 'error',
  },
  },
+ {
+ name: 'packages/ui/mosaic',
+ files: ['packages/ui/src/mosaic/**/*'],
+ ignores: ['packages/ui/src/mosaic/utils.ts', 'packages/ui/src/mosaic/__tests__/**'],
+ rules: {
+ 'no-restricted-syntax': [
+ 'error',
+ {
+ selector: "Property > Literal.key[value='&:hover']",
+ message: "Use hover() from mosaic/utils instead of bare '&:hover'.",
+ },
+ {
+ selector: "Property > Literal.key[value='@media (hover: hover)']",
+ message: "Use hover() from mosaic/utils instead of raw '@media (hover: hover)'.",
+ },
+ {
+ selector: "Property > Literal.key[value='@media (prefers-reduced-motion: no-preference)']",
+ message:
+ "Use motionSafe() from mosaic/utils instead of raw '@media (prefers-reduced-motion: no-preference)'.",
+ },
+ ],
+ },
+ },
  {
  name: 'packages - vitest',
  files: ['packages/*/src/**/*.test.{ts,tsx}'],

packages/ui/src/mosaic/__tests__/utils.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+
+import { defaultMosaicVariables, resolveVariables } from '../variables';
+import { alpha, hover, motionSafe } from '../utils';
+
+describe('hover', () => {
+ it('wraps styles in @media (hover: hover) and &:hover', () => {
+ expect(hover({ color: 'red' })).toEqual({
+ '@media (hover: hover)': {
+ '&:hover': { color: 'red' },
+ },
+ });
+ });
+
+ it('passes complex style objects through unchanged', () => {
+ const styles = { backgroundColor: 'blue', opacity: 0.8, transform: 'scale(1.05)' };
+ expect(hover(styles)).toEqual({
+ '@media (hover: hover)': {
+ '&:hover': styles,
+ },
+ });
+ });
+});
+
+describe('motionSafe', () => {
+ it('wraps styles in @media (prefers-reduced-motion: no-preference)', () => {
+ expect(motionSafe({ transition: 'transform 200ms ease' })).toEqual({
+ '@media (prefers-reduced-motion: no-preference)': { transition: 'transform 200ms ease' },
+ });
+ });
+});
+
+describe('alpha', () => {
+ it('produces a color-mix expression', () => {
+ expect(alpha('#000', 50)).toBe('color-mix(in oklab, #000 50%, transparent)');
+ });
+
+ it('accepts any CSS color string', () => {
+ expect(alpha('oklch(58.5% .233 277.117)', 80)).toBe(
+ 'color-mix(in oklab, oklch(58.5% .233 277.117) 80%, transparent)',
+ );
+ });
+
+ it('matches theme.alpha output for the same resolved color', () => {
+ const theme = resolveVariables(defaultMosaicVariables);
+ const resolvedColor = defaultMosaicVariables.color.primary;
+ expect(theme.alpha('primary', 60)).toBe(alpha(resolvedColor, 60));
+ });
+});

packages/ui/src/mosaic/components/button.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 
 import { cva, type VariantProps } from '../cva';
 import { useMosaicTheme } from '../MosaicProvider';
+import { hover } from '../utils';
 
 export const buttonStyles = cva(theme => ({
  base: {
@@ -27,7 +28,7 @@ export const buttonStyles = cva(theme => ({
  primary: {
  backgroundColor: theme.color.primary,
  color: theme.color.primaryForeground,
-'&:hover': { backgroundColor: theme.mix('primary', 'primaryForeground', 12) },
+...hover({ backgroundColor: theme.mix('primary', 'primaryForeground', 12) }),
  '&:active': { backgroundColor: theme.mix('primary', 'primaryForeground', 24) },
  },
  },

packages/ui/src/mosaic/utils.ts

@@ -0,0 +1,22 @@
+import type { StyleRule } from './cva';
+
+/** Wraps styles in `@media (hover: hover)` so they only apply on hover-capable devices. */
+export function hover(styles: StyleRule): StyleRule {
+ return {
+ '@media (hover: hover)': {
+ '&:hover': styles,
+ },
+ };
+}
+
+/** Wraps styles in `@media (prefers-reduced-motion: no-preference)` so animations only run when the user has not requested reduced motion. */
+export function motionSafe(styles: StyleRule): StyleRule {
+ return {
+ '@media (prefers-reduced-motion: no-preference)': styles,
+ };
+}
+
+/** Applies opacity to any CSS color via `color-mix`. */
+export function alpha(color: string, opacity: number): string {
+ return `color-mix(in oklab, ${color} ${opacity}%, transparent)`;
+}

packages/ui/src/mosaic/variables.ts

@@ -1,3 +1,5 @@
+import { alpha } from './utils';
+
 // ─── Token Defaults ──────────────────────────────────────────────────────────
 
 /** Baseline design token values. Every Mosaic theme starts from this object. */
@@ -99,7 +101,7 @@ export function resolveVariables(defaults: MosaicTokens, variables?: MosaicVaria
  ...tokens,
  spacing: (<N extends number>(n: N) => `calc(${tokens.spacing} * ${n})`) as MosaicTheme['spacing'],
  alpha: (<K extends keyof MosaicTokens['color'], O extends number>(color: K, opacity: O) =>
-`color-mix(in oklab, ${tokens.color[color]} ${opacity}%, transparent)`) as MosaicTheme['alpha'],
+alpha(tokens.color[color], opacity)) as MosaicTheme['alpha'],
  mix: (<A extends keyof MosaicTokens['color'], B extends keyof MosaicTokens['color'], P extends number>(
  a: A,
  b: B,