Pro 8902 add styles #518

BoDonkey · 2026-01-19T14:06:46Z

Summary

Summarize the changes briefly, including which issue/ticket this resolves. If it closes an existing Github issue, include "Closes #[issue number]"
This PR adds new documentation for global and per-widget styles. It also adds reference documentation for the styles module. Closes PRO-8902, PRO-8403, and PRO-8992.

What are the specific steps to test this change?

For example:

Run the website and log in as an admin

Open a piece manager modal and select several pieces

Click the "Archive" button on the top left of the manager and confirm that it should proceed

Check that all pieces have been archived properly

What kind of change does this PR introduce?

(Check at least one)

Make sure the PR fulfills these requirements:

It includes a) the existing issue ID being resolved, b) a convincing reason for adding this feature, or c) a clear description of the bug it resolves
The changelog is updated
Related documentation has been updated
Related tests have been updated

If adding a new feature without an already open issue, it's best to open a feature request issue first and wait for approval before working on it.

Other information:

linear · 2026-01-19T14:06:49Z

PRO-8902 Add palette documentation to docs

PRO-8403 As a developer, I need documentation with examples for configuring Widget Styles.

PRO-8992 Document Palette to Styles migration task

boutell

Great stuff, some notes but nothing huge I think

boutell · 2026-01-20T12:12:51Z

docs/.vitepress/sidebarGuide.js

+        text: 'Styling',
+        collapsed: true,
+        items: [
+          { text: 'Global Styling', link: 'guide/global-styling.md' },


Global Styles / Widget Styles seems better, I don't think it makes sense to have two variations on the word, just makes it harder to find later

boutell · 2026-01-20T12:13:17Z

docs/guide/global-styles.md

@@ -0,0 +1,1098 @@
+# Global Styles


"Styles" here (which I think is correct), file should be renamed to match

boutell · 2026-01-20T12:13:49Z

docs/guide/global-styling.md

+
+## Configuration
+
+Global styles are configured in a project-level `modules/@apostrophecms/styles/index.js` using a styles cascade that works much like the schema fields cascade. You define fields with types, labels, and properties—but instead of creating form inputs for content, these fields create controls for CSS properties.


Use emdash, spaces around the emdash

boutell · 2026-01-20T12:15:49Z

docs/guide/global-styling.md

+
+#### `unit`
+
+Append units to numeric values from `range` or `box` fields.


Is it not supported for integer or float fields? If it's not then it's not...

~~Since we are only recommending range, I'm not going to change this.~~

I tested the integer and float fields. They are working so I updated this and added those fields in.

boutell · 2026-01-20T12:17:05Z

docs/guide/global-styling.md

+
+// URL function
+valueTemplate: 'url(%VALUE%)'
+// Result: url(image.jpg)


I'm trying to picture a scenario where this second example would actually work out, but offhand I can't think of one. Maybe a select field with /modules image URLs? Or just skip it, not asking you to add more work here.

I removed that example, but also updated the section for named object fields.

boutell · 2026-01-20T12:36:28Z

docs/guide/widget-styles.md

+### Performance considerations
+
+- Widget styles are generated for each instance, so they add to page size
+- For styles that should apply to all instances of a widget type, use regular CSS


use global styles or regular CSS

boutell · 2026-01-20T12:37:01Z

docs/guide/widget-styles.md

+- For styles that should apply to all instances of a widget type, use regular CSS
+- Reserve widget styles for per-instance customization that content creators need
+
+## When to use widget styles vs. global styles


This whole section is great 🔥

boutell · 2026-01-20T12:38:28Z

docs/reference/modules/styles.md

+```
+
+::: warning
+Widget modules do not support the `group` property in their `styles` configuration. Attempting to use grouping with widget styles will cause an error.


boutell · 2026-01-20T12:38:57Z

docs/reference/modules/styles.md

+
+### `serverRendered`
+
+When set to `true`, all CSS rendering (including preview during editing) goes through your custom `getStylesheet` method. This is required when implementing custom CSS generation logic.


This is available for global styles only. For performance reasons it is not available for widget-specific styles.

boutell · 2026-01-20T12:40:36Z

docs/reference/modules/styles.md

+
+The module automatically injects styles into every page:
+
+- **For guests:** `<link>` tag pointing to cached stylesheet endpoint


Guests are logged-in users with a specific role. I suggest "for the public" or "for logged-out visitors."

boutell · 2026-01-22T20:07:41Z

docs/.vitepress/sidebarGuide.js

        collapsed: true,
        items: [
-          { text: 'Global Styling', link: 'guide/global-styling.md' },
+          { text: 'Global Styling', link: 'guide/global-styles.md' },


Global Styles should be the title too, I don't see any reason to potentially confuse a developer on this point.

Dumb oversight. Thanks.

boutell · 2026-01-22T20:08:40Z

docs/guide/global-styles.md


 **Every field needs:**
- `type` (or `preset`) - The control type: `color`, `range`, `string`, `select`, `box`, or a preset name
+- `type` (or `preset`) - The control type: `color`, `range`, `integr`, `float`, `string`, `select`, `box`, or a preset name


integr -> integer

docs/guide/widget-styles.md

boutell · 2026-01-22T20:13:01Z

docs/guide/widget-styles.md

+- **Design Editors**: Grant both `edit` and `editStyles` permissions (can edit everything)
+
+::: warning
+You must add `editPermission` to **every style field individually**. This includes fields within presets. The property cannot be set at the parent level and cascade down.


Per Miro we need to update this, how about:

You must add editPermission to every style field individually. In the case of presets, you may set editPermission once for each use of the preset and it will be applied to every field generated by that use of the preset.

boutell · 2026-01-22T20:14:59Z

docs/guide/widget-styles.md

+| **Delivery** | Cached stylesheet + inline | Inline per widget |
+| **Interface** | Dedicated admin UI | Widget editor modal |
+| **Selectors** | Required | Optional (for nested elements) |
+| **Grouping** | Supports nested groups | Not supported |


This additional note is still needed:

| **Overrides** | Supports custom render method | Not supported |

boutell · 2026-01-22T20:16:18Z

docs/reference/modules/styles.md

 ### `serverRendered`

 When set to `true`, all CSS rendering (including preview during editing) goes through your custom `getStylesheet` method. This is required when implementing custom CSS generation logic.
+**This option is only available for global styles.** Widget styles are always rendered server-side for performance reasons.


Not really, we render them on the front end when editing, which is one of the reasons for this policy.

This would be better language:

"Widget styles are always rendered by our standardized logic for performance reasons."

BoDonkey added 2 commits January 15, 2026 13:58

First stab

4b02752

Update new styles documentation, including migration task

fe92ef1

BoDonkey requested a review from boutell January 19, 2026 14:06

boutell requested changes Jan 20, 2026

View reviewed changes

response to first comments

b352e0b

BoDonkey requested a review from boutell January 20, 2026 18:58

boutell requested changes Jan 22, 2026

View reviewed changes

BoDonkey requested a review from boutell January 23, 2026 11:08

Response to second comments

31a0f45

boutell approved these changes Jan 23, 2026

View reviewed changes

BoDonkey merged commit 41d6c36 into main Jan 23, 2026

BoDonkey deleted the pro-8902-add-styles branch January 23, 2026 14:16


		## Configuration

		Global styles are configured in a project-level `modules/@apostrophecms/styles/index.js` using a styles cascade that works much like the schema fields cascade. You define fields with types, labels, and properties—but instead of creating form inputs for content, these fields create controls for CSS properties.


		#### `unit`

		Append units to numeric values from `range` or `box` fields.


		### `serverRendered`

		When set to `true`, all CSS rendering (including preview during editing) goes through your custom `getStylesheet` method. This is required when implementing custom CSS generation logic.


		The module automatically injects styles into every page:

		- For guests: `<link>` tag pointing to cached stylesheet endpoint

Pro 8902 add styles #518

Pro 8902 add styles #518

Conversation

BoDonkey commented Jan 19, 2026

Summary

What are the specific steps to test this change?

What kind of change does this PR introduce?

Make sure the PR fulfills these requirements:

Uh oh!

linear bot commented Jan 19, 2026

Uh oh!

boutell left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BoDonkey Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

BoDonkey Jan 20, 2026 •

edited

Loading