feat(breaking): Rename `useUtilities` to `useUtilitiesPreset` by alexgrozav · Pull Request #95 · styleframe-dev/styleframe

alexgrozav · 2026-01-22T07:09:30Z

This pull request updates the documentation and code examples throughout the project to use the new useDefaultUtilitiesPreset function instead of the deprecated useUtilities function from @styleframe/theme. This change ensures consistency across docs and code, and better reflects the recommended way to register all utility factories in Styleframe.

Documentation updates:

All references, code samples, and explanations in the API and utilities documentation now use useDefaultUtilitiesPreset in place of useUtilities, clarifying its purpose and usage for recipe auto-generation. [1] [2] [3] [4] [5] [6] [7] [8]
The documentation for registering utilities has been revised to explain the use of presets and to link to further information, removing outdated details about the old function.

Codebase updates:

All usage of useUtilities in Storybook configuration and example files has been replaced with useDefaultUtilitiesPreset, including imports and function calls. [1] [2] [3] [4] [5] [6]

Rename useUtilities to useDefaultUtilitiesPreset for consistency with useDefaultDesignTokensPreset naming convention. Add comprehensive presets documentation with API reference, examples, and best practices. Update all references across docs, storybook examples, and CHANGELOGs. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

changeset-bot · 2026-01-22T07:09:34Z

🦋 Changeset detected

Latest commit: 7e65d41

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@styleframe/theme	Minor
styleframe	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-01-22T07:09:35Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
app-styleframe-dev-production	Ready	Preview, Comment	Jan 24, 2026 6:09am
styleframe-dev-production	Ready	Preview, Comment	Jan 24, 2026 6:09am
styleframe-storybook	Ready	Preview, Comment	Jan 24, 2026 6:09am

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

codecov · 2026-01-22T07:15:31Z

Codecov Report

❌ Patch coverage is 91.08911% with 9 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ties/transitions-animation/useTransitionUtility.ts	0.00%	4 Missing ⚠️
theme/src/utilities/useUtilitiesPreset.ts	0.00%	2 Missing ⚠️
theme/src/presets/index.ts	0.00%	0 Missing and 1 partial ⚠️
theme/src/utilities/backgrounds/index.ts	0.00%	1 Missing ⚠️
theme/src/utilities/index.ts	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

Copilot

Pull request overview

This PR updates the public API and documentation/examples to use useDefaultUtilitiesPreset instead of the deprecated useUtilities, aiming to align naming with other “preset” composables and keep docs consistent.

Changes:

Renames the exported utilities preset function from useUtilities to useDefaultUtilitiesPreset and updates the utilities barrel export.
Replaces Storybook example imports/calls to use the new function name.
Adds/updates a large set of utilities documentation pages (including a new “Presets” page) to reference the new API.

Reviewed changes

Copilot reviewed 24 out of 39 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
theme/src/utilities/useDefaultUtilitiesPreset.ts	Renames the exported preset function and updates its in-file usage example.
theme/src/utilities/index.ts	Switches barrel export from `useUtilities` to `useDefaultUtilitiesPreset`.
theme/CHANGELOG.md	Updates changelog text to describe the rename as breaking.
engine/styleframe/CHANGELOG.md	Updates changelog text to describe the rename as breaking.
apps/storybook/src/useSpacing.styleframe.ts	Updates import/call sites to `useDefaultUtilitiesPreset`.
apps/storybook/src/useScale.styleframe.ts	Updates import/call sites to `useDefaultUtilitiesPreset`.
apps/storybook/src/useLineHeight.styleframe.ts	Updates import/call sites to `useDefaultUtilitiesPreset`.
apps/storybook/src/useLetterSpacing.styleframe.ts	Updates import/call sites to `useDefaultUtilitiesPreset`.
apps/storybook/src/useFontWeight.styleframe.ts	Updates import/call sites to `useDefaultUtilitiesPreset`.
apps/storybook/src/useFontSize.styleframe.ts	Updates import/call sites to `useDefaultUtilitiesPreset`.
apps/storybook/src/useFontFamily.styleframe.ts	Updates import/call sites to `useDefaultUtilitiesPreset`.
apps/storybook/src/useColorTint.styleframe.ts	Updates import/call sites to `useDefaultUtilitiesPreset`.
apps/storybook/src/useColorShade.styleframe.ts	Updates import/call sites to `useDefaultUtilitiesPreset`.
apps/storybook/src/useColorLightness.styleframe.ts	Updates import/call sites to `useDefaultUtilitiesPreset`.
apps/storybook/src/useBreakpoint.styleframe.ts	Updates import/call sites to `useDefaultUtilitiesPreset`.
apps/storybook/src/useBoxShadow.styleframe.ts	Updates import/call sites to `useDefaultUtilitiesPreset`.
apps/storybook/src/useBorderWidth.styleframe.ts	Updates import/call sites to `useDefaultUtilitiesPreset`.
apps/storybook/src/useBorderStyle.styleframe.ts	Updates import/call sites to `useDefaultUtilitiesPreset`.
apps/storybook/src/useBorderRadius.styleframe.ts	Updates import/call sites to `useDefaultUtilitiesPreset`.
apps/storybook/src/global.styleframe.ts	Updates import/call sites to `useDefaultUtilitiesPreset`.
apps/docs/content/docs/05.utilities/00.index.md	Updates the utilities index page to point users to presets and the new function name.
apps/docs/content/docs/05.utilities/01.presets.md	Adds a dedicated presets page describing `useDefaultUtilitiesPreset` usage and listing available utilities.
apps/docs/content/docs/05.utilities/02.accessibility.md	Adds/updates accessibility utilities documentation.
apps/docs/content/docs/05.utilities/03.backgrounds.md	Adds/updates backgrounds utilities documentation.
apps/docs/content/docs/05.utilities/04.borders.md	Adds/updates borders utilities documentation.
apps/docs/content/docs/05.utilities/05.effects.md	Adds/updates effects utilities documentation.
apps/docs/content/docs/05.utilities/06.filters.md	Adds/updates filters utilities documentation.
apps/docs/content/docs/05.utilities/07.flexbox-grid.md	Adds/updates flexbox & grid utilities documentation.
apps/docs/content/docs/05.utilities/08.interactivity.md	Adds/updates interactivity utilities documentation.
apps/docs/content/docs/05.utilities/09.layout.md	Adds/updates layout utilities documentation.
apps/docs/content/docs/05.utilities/10.sizing.md	Adds/updates sizing utilities documentation.
apps/docs/content/docs/05.utilities/11.spacing.md	Adds/updates spacing utilities documentation.
apps/docs/content/docs/05.utilities/12.svg.md	Adds/updates SVG utilities documentation.
apps/docs/content/docs/05.utilities/13.tables.md	Adds/updates tables utilities documentation.
apps/docs/content/docs/05.utilities/14.transforms.md	Adds/updates transforms utilities documentation.
apps/docs/content/docs/05.utilities/15.transitions-animation.md	Adds/updates transitions & animation utilities documentation.
apps/docs/content/docs/05.utilities/16.typography.md	Adds/updates typography utilities documentation.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-22T07:16:05Z

apps/docs/content/docs/05.utilities/01.presets.md

+import { useModifier } from '@styleframe/theme';
+
+const hover = useModifier(s, 'hover', ({ declarations }) => ({


The docs example imports and uses useModifier from @styleframe/theme, but there is no useModifier export in the codebase. Update the example to use s.modifier(...) (from the Styleframe instance) or the correct public API for creating modifiers.

Suggested change

import { useModifier } from '@styleframe/theme';

const hover = useModifier(s, 'hover', ({ declarations }) => ({

const hover = s.modifier('hover', ({ declarations }) => ({

Copilot · 2026-01-22T07:16:06Z

apps/docs/content/docs/05.utilities/01.presets.md

+|-----------------|--------------|---------------|
+| `createBackgroundAttachmentUtility` | `background-attachment` | `_background-attachment:*` |
+| `createBackgroundClipUtility` | `background-clip` | `_background-clip:*` |
+| `createBackgroundColorUtility` | `background-color` | `_background-color:*` |


These class patterns don't match the actual utility names produced by the implementation. For example, useBackgroundColorUtility registers the utility name as background (emits ._background\:<key>), not _background-color:* (see theme/src/utilities/backgrounds/useBackgroundColorUtility.ts and its tests). Please align the documented class patterns with the real emitted selectors.

Suggested change

| `createBackgroundColorUtility` | `background-color` | `_background-color:*` |

| `createBackgroundColorUtility` | `background-color` | `_background:*` |

Copilot · 2026-01-22T07:16:06Z

apps/docs/content/docs/05.utilities/01.presets.md

+| `createBorderColorTopUtility` | `border-top-color` | `_border-color-top:*` |
+| `createBorderColorRightUtility` | `border-right-color` | `_border-color-right:*` |
+| `createBorderColorBottomUtility` | `border-bottom-color` | `_border-color-bottom:*` |
+| `createBorderColorLeftUtility` | `border-left-color` | `_border-color-left:*` |
+| `createBorderColorXUtility` | `border-left/right-color` | `_border-color-x:*` |
+| `createBorderColorYUtility` | `border-top/bottom-color` | `_border-color-y:*` |
+| `createBorderColorStartUtility` | `border-inline-start-color` | `_border-color-start:*` |
+| `createBorderColorEndUtility` | `border-inline-end-color` | `_border-color-end:*` |


Copilot · 2026-01-22T07:16:06Z

apps/docs/content/docs/05.utilities/01.presets.md

+| `createRingInsetUtility` | `--ring-inset` | `_ring-inset:*` |
+| `createRingOffsetColorUtility` | `--ring-offset-color` | `_ring-offset-color:*` |
+| `createRingOffsetWidthUtility` | `--ring-offset-width` | `_ring-offset-width:*` |
+| `createRingWidthUtility` | `box-shadow` (ring) | `_ring-width:*` |


Copilot · 2026-01-22T07:16:07Z

theme/CHANGELOG.md

 ### Patch Changes

- [#76](https://github.com/styleframe-dev/styleframe/pull/76) [`06afe2a`](https://github.com/styleframe-dev/styleframe/commit/06afe2af66c3ecd8c6a516336e594c1e8cb56de1) Thanks [@alexgrozav](https://github.com/alexgrozav)! - feat: add useUtilities function for registering all utility factories
+- [#76](https://github.com/styleframe-dev/styleframe/pull/76) [`06afe2a`](https://github.com/styleframe-dev/styleframe/commit/06afe2af66c3ecd8c6a516336e594c1e8cb56de1) Thanks [@alexgrozav](https://github.com/alexgrozav)! - **BREAKING**: rename `useUtilities` to `useDefaultUtilitiesPreset` for consistency with design tokens preset naming

-  Introduces `useUtilities()` that registers all ~180 utility composables with a Styleframe instance and returns their creator functions. This enables automatic utility class generation for recipe declarations.
+  Renamed `useUtilities()` to `useDefaultUtilitiesPreset()` to align with the naming convention established by `useDefaultDesignTokensPreset()`. The function registers all ~180 utility composables with a Styleframe instance and returns their creator functions, enabling automatic utility class generation for recipe declarations.

-  Updated recipe documentation examples to use `useUtilities()` with destructured functions and demonstrate both `ref()` and `@variable.name` syntax for referencing design tokens.
+  Updated recipe documentation examples to use `useDefaultUtilitiesPreset()` with destructured functions and demonstrate both `ref()` and `@variable.name` syntax for referencing design tokens.


This entry describes a breaking API rename under the "### Patch Changes" section for v2.3.0, which conflicts with semver expectations and also rewrites an old PR/commit reference (#76 / 06afe2a). Consider adding a new release entry (and appropriate major/minor section) for the current change instead of editing historical notes, and avoid marking breaking changes as patch-level.

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Simplify the function name from useDefaultUtilitiesPreset to useUtilitiesPreset for a cleaner API. Update all imports, documentation, and CHANGELOGs accordingly. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

… syntax Update all utility class names to use CSS-standard property names instead of abbreviated Tailwind-style names. This affects generated CSS classes. Changes include: - Border color: border-t-color → border-top-color, etc. - Scroll: scroll-mt → scroll-margin-top, etc. - Grid: grid-cols → grid-template-columns, col → grid-column, etc. - Flex: grow → flex-grow, shrink → flex-shrink, basis → flex-basis - Align: content → align-content, items → align-items, self → align-self - Justify: justify → justify-content - Transition: duration → transition-duration, ease → transition-timing-function - Transform: backface → backface-visibility, origin → transform-origin - Inset: start → inset-inline-start, end → inset-inline-end - Typography: underline-offset → text-underline-offset - Box: box-decoration → box-decoration-break - Outline: outline → outline-width Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

alexgrozav requested a review from Copilot January 22, 2026 07:09

alexgrozav self-assigned this Jan 22, 2026

alexgrozav changed the title ~~feat(breaking): rename useUtilities to useDefaultUtilitiesPreset~~ feat(breaking): Rename useUtilities to useDefaultUtilitiesPreset Jan 22, 2026

Copilot started reviewing on behalf of alexgrozav January 22, 2026 07:09 View session

chore: add changeset for useDefaultUtilitiesPreset rename

af029f9

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

vercel bot deployed to Preview – styleframe-storybook January 22, 2026 07:11 View deployment

vercel bot deployed to Preview – app-styleframe-dev-production January 22, 2026 07:12 View deployment

vercel bot deployed to Preview – styleframe-dev-production January 22, 2026 07:12 View deployment

Copilot AI reviewed Jan 22, 2026

View reviewed changes

refactor: rename useDefaultUtilitiesPreset to useUtilitiesPreset

a60e31b

Simplify the function name from useDefaultUtilitiesPreset to useUtilitiesPreset for a cleaner API. Update all imports, documentation, and CHANGELOGs accordingly. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

vercel bot deployed to Preview – styleframe-storybook January 23, 2026 09:07 View deployment

vercel bot deployed to Preview – app-styleframe-dev-production January 23, 2026 09:07 View deployment

vercel bot deployed to Preview – styleframe-dev-production January 23, 2026 09:08 View deployment

alexgrozav changed the title ~~feat(breaking): Rename useUtilities to useDefaultUtilitiesPreset~~ feat(breaking): Rename useUtilities to useUtilitiesPreset Jan 23, 2026

vercel bot deployed to Preview – styleframe-storybook January 24, 2026 06:03 View deployment

vercel bot deployed to Preview – app-styleframe-dev-production January 24, 2026 06:03 View deployment

vercel bot deployed to Preview – styleframe-dev-production January 24, 2026 06:04 View deployment

chore: update changeset version to minor

7e65d41

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

vercel bot deployed to Preview – styleframe-storybook January 24, 2026 06:08 View deployment

vercel bot deployed to Preview – app-styleframe-dev-production January 24, 2026 06:09 View deployment

vercel bot deployed to Preview – styleframe-dev-production January 24, 2026 06:09 View deployment

alexgrozav merged commit 75fd781 into main Jan 24, 2026
12 checks passed

alexgrozav deleted the alexgrozav/rename-use-utilities branch January 24, 2026 06:19

github-actions bot mentioned this pull request Jan 24, 2026

chore: update versions #94

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(breaking): Rename `useUtilities` to `useUtilitiesPreset`#95

feat(breaking): Rename `useUtilities` to `useUtilitiesPreset`#95
alexgrozav merged 5 commits intomainfrom
alexgrozav/rename-use-utilities

alexgrozav commented Jan 22, 2026

Uh oh!

changeset-bot bot commented Jan 22, 2026 •

edited

Loading

Uh oh!

vercel bot commented Jan 22, 2026 •

edited

Loading

Uh oh!

codecov bot commented Jan 22, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 22, 2026

Uh oh!

Copilot AI Jan 22, 2026

Uh oh!

Copilot AI Jan 22, 2026

Uh oh!

Copilot AI Jan 22, 2026

Uh oh!

Copilot AI Jan 22, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		import { useModifier } from '@styleframe/theme';

		const hover = useModifier(s, 'hover', ({ declarations }) => ({

	\| `createBackgroundColorUtility` \| `background-color` \| `_background-color:*` \|
	\| `createBackgroundColorUtility` \| `background-color` \| `_background:*` \|

Uh oh!

Conversation

alexgrozav commented Jan 22, 2026

Uh oh!

changeset-bot bot commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

changeset-bot bot commented Jan 22, 2026 •

edited

Loading

vercel bot commented Jan 22, 2026 •

edited

Loading

codecov bot commented Jan 22, 2026 •

edited

Loading