Skip to content

Improve design guide defaults and schema descriptions - #193

Merged
MaggieCabrera merged 7 commits into
WordPress:trunkfrom
shail-mehta:fix/191-design-guide-defaults-schema
Nov 10, 2026
Merged

MaggieCabrera merged 7 commits into
WordPress:trunkfrom
shail-mehta:fix/191-design-guide-defaults-schema

Conversation

@shail-mehta

@shail-mehta shail-mehta commented Nov 4, 2026 •

Copy link
Copy Markdown
Member

Description

Fixes #191

Follow-up to the ipsum/get-design-guide ability after #182 and the review of wordpress-develop#15113.

  • Return only the basic design sections by default (theme, colorScheme, colors, gradients, duotone, typography, spacing, layout, guidelines). Larger lists (patterns, templates, templateParts, templatePartAreas, blockStyles, styleVariations) are available through fields.
  • Document omitted, empty, and explicit fields behavior in the ability and input schema.
  • Add clearer translated titles and descriptions, including hidden, pattern blockTypes/postTypes, template customized/pattern, font value shapes and heading fallback, and that font sizes and spacing are not sorted.
  • Mark guaranteed nested fields as required and use additionalProperties: false on fixed objects, while keeping top-level sections optional.
  • Do not require name on font family, font size, or spacing presets. A template part area may be null, and an empty blockFonts map is an object.

wordpress-develop PHPUnit coverage called out in the issue is left for a separate core PR.

Screenshots

N/A

Testing Instructions

  1. Activate Ipsum and log in as a user with edit_theme_options.
  2. Run the ability with no input. It is read-only, so this is a GET: await wp.apiFetch( { path: '/wp-abilities/v1/abilities/ipsum/get-design-guide/run' } ).
  3. Confirm the response includes the basic sections and omits patterns, templates, templateParts, templatePartAreas, blockStyles, and styleVariations.
  4. Request a heavy section explicitly: await wp.apiFetch( { path: '/wp-abilities/v1/abilities/ipsum/get-design-guide/run?input=' + encodeURIComponent( JSON.stringify( { fields: [ 'patterns' ] } ) ) } ). Confirm only that section is returned.
  5. Request a few basic sections the same way, for example fields: [ 'colors', 'typography' ], and confirm the response is limited to those keys.
  6. Check one non-default color variation is active, then re-run the default ability call and confirm palette roles still read correctly.
  7. Spot-check the ability schema in the abilities REST index for the updated fields description and property titles.

Use of AI Tools

  • Cursor

@shail-mehta
shail-mehta marked this pull request as ready for review November 4, 2026 09:17
@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: shail-mehta <shailu25@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: MaggieCabrera <onemaggie@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.


Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

  • @propsbot add <username> to give props to a GitHub user. Requires write access.
  • @propsbot remove <username> to leave a user out of the props. Requires write access.
  • @propsbot refresh to refresh this list. Adding the props-bot label works too.

@MaggieCabrera

Copy link
Copy Markdown
Contributor

Thanks for this. The new defaults and descriptions read well. A few things to fix before merging:

  • name shouldn't be required for font sizes, font families or spacing presets. theme.json doesn't require it there, and the presets helper drops missing keys. A single preset without a name, say from a child theme, fails output validation, and then the default call returns an error.
  • The template part area can be null when a part has no area term, so it shouldn't be required as a string.
  • An empty blockFonts is sent as [], but the schema says it's an object. Casting it to (object) fixes that.
  • The testing steps need GET instead of POST. The ability is read-only, so POST gets rejected.

A preset without a name, a template part with no area, or an empty block font map was failing output validation on the default call.
@shail-mehta

shail-mehta commented Nov 10, 2026 •

Copy link
Copy Markdown
Member Author

Thanks @MaggieCabrera - addressed in b6cf477 / 50a163d:

  • name is no longer required for font family, font size, or spacing presets.
  • Template part area can be null when the part has no area term.
  • An empty blockFonts map is cast to (object).
  • Testing steps now use GET, since the ability is read-only.

@gziolo gziolo left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for contributing! This is looking good overall and addresses the feedback, apart from the test coverage requested in the original issue. I left a few suggestions to simplify the schema helpers and remove the redundant cast.

Comment thread inc/abilities.php Outdated
return $object_list(
$description,

$titled = static function ( $title, $description = '' ) use ( $string ) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we use explicit schema arrays here? This helper also sets the type to string, which its name does not make clear. The translations work correctly.

Comment thread inc/abilities.php Outdated
return $schema;
};

$preset_list = static function ( $title, $description, $value_key, $value_schema, $extra_properties = array(), $require_name = true ) use ( $object_list, $titled ) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we simplify the arguments? Calls ending in array(), false are hard to follow. Listing the required fields at the call site would make them clearer.

Comment thread inc/abilities.php Outdated
Comment on lines +631 to +632
// An empty array JSON-encodes as [], which fails the object schema.
'blockFonts' => (object) $block_fonts,

@gziolo gziolo Nov 10, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This cast and comment are no longer needed in WordPress 7.2. Core already converts empty arrays to JSON objects based on the output schema.

An empty blockFonts is sent as [], but the schema says it's an object. Casting it to (object) fixes that.

@MaggieCabrera, see WordPress/wordpress-develop@ba4c6de.

@shail-mehta

Copy link
Copy Markdown
Member Author

Thanks for the review! Addressed all three points in 083e968

@MaggieCabrera
MaggieCabrera merged commit fdfda0a into WordPress:trunk Nov 10, 2026
6 checks passed
@shail-mehta
shail-mehta deleted the fix/191-design-guide-defaults-schema branch November 10, 2026 15:33
MaggieCabrera added a commit to MaggieCabrera/wordpress-develop that referenced this pull request Nov 12, 2026
The `ipsum/get-design-guide` ability now returns only the basic design sections by default, and the larger lists, such as patterns and templates, are available through `fields`. Its schema gets clearer translated titles and descriptions, and marks the nested fields that are always there.

The tests live in core, since Ipsum's repository has no PHPUnit setup. They cover the ability's registration and schema, the default and requested sections, invalid input, permissions, the REST endpoint, and how the guide follows the saved global styles and customized templates.

Synced from WordPress/ipsum#193.

See #66678.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
wporg-sync pushed a commit to WordPress/wordpress-develop that referenced this pull request Nov 17, 2026
This updates Ipsum from `bc2e5af700e28980f251d97f58cf80c72ee50a13` to `d26734ecc1ba178d9c120178ce9d2c48825fc108` on its `trunk` branch.

A full list of changes included in this commit can be found on GitHub: WordPress/ipsum@bc2e5af...d26734e

- Address the review notes from the 7.2 Beta 5 core commit (WordPress/ipsum#216)
- Fix Pullquote custom line height not applying on the front end (WordPress/ipsum#203)
- Fix horizontal scroll caused by long unbroken words in comments (WordPress/ipsum#200)
- Improve design guide defaults and schema descriptions (WordPress/ipsum#193)
- Make the short post date format translatable (WordPress/ipsum#224)
- Fix Details block markers being announced by screen readers (WordPress/ipsum#230)
- Remove the physical left alignment from the page patterns (WordPress/ipsum#226)
- Indent the navigation submenus on the inline start (WordPress/ipsum#225)
- Fix accessible names for overlay navigation (WordPress/ipsum#228)
- Split AGENTS.md so it holds for any copy of the theme (WordPress/ipsum#214)
- Use a logical margin for the comment form checkbox (WordPress/ipsum#231)
- Keep keyboard focus visible and clear of the sticky header (WordPress/ipsum#145)
- Fix accessible name of overlay search form (WordPress/ipsum#239)
- Show a message when the blog and Archive Full have no posts (WordPress/ipsum#238)
- Keep the post date on one line when categories wrap (WordPress/ipsum#205)
- Remove repeated button styles from theme.json (WordPress/ipsum#235)
- Remove unused values from theme.json (WordPress/ipsum#237)
- Make the credit line URL translatable (WordPress/ipsum#240)
- Use single border radius values in theme.json (WordPress/ipsum#236)
- Escape the short post date format instead of ignoring PHPCS (WordPress/ipsum#245)
- Use the Site Title in Footer Centered (WordPress/ipsum#244)
- Keep AGENTS.md about the theme, not the GitHub repository (WordPress/ipsum#247)
- Treat "Written by" as a label before the author name (WordPress/ipsum#246)
- Use Quote blocks for statement patterns and remove text quote mark styles (WordPress/ipsum#232)
  

This commit also includes changes that only exist in core:

- Tests for the `ipsum/get-design-guide` ability are added in `tests/phpunit/tests/theme/ipsumGetDesignGuideAbility.php`, because Ipsum's repository has no PHPUnit setup. On multisite, the tests save global styles as a super admin, since only super admins can save unfiltered global styles.
- `contributing.txt` says Ipsum is developed on GitHub until its 1.0 release, with contributions going through Trac after that. It also drops the note about `style.css` being used when it is newer than `style.min.css`.
- A test message in `ipsumDesignGuide.php` says "do not match" instead of "to not match".

Developed in: #15948

Follow-up to r65366.

Props onemaggie, juanfra, shailu25, iamarinoh, 369work, gziolo, wildworks, suryakantupadhyay, khushalsains, ravipatel, meahadi.
Fixes #66678. See #66352.

git-svn-id: https://develop.svn.wordpress.org/trunk@65549 602fd350-edb4-49c9-b593-d223f7449a82
wporg-sync pushed a commit to WordPress/WordPress that referenced this pull request Nov 17, 2026
This updates Ipsum from `bc2e5af700e28980f251d97f58cf80c72ee50a13` to `d26734ecc1ba178d9c120178ce9d2c48825fc108` on its `trunk` branch.

A full list of changes included in this commit can be found on GitHub: WordPress/ipsum@bc2e5af...d26734e

- Address the review notes from the 7.2 Beta 5 core commit (WordPress/ipsum#216)
- Fix Pullquote custom line height not applying on the front end (WordPress/ipsum#203)
- Fix horizontal scroll caused by long unbroken words in comments (WordPress/ipsum#200)
- Improve design guide defaults and schema descriptions (WordPress/ipsum#193)
- Make the short post date format translatable (WordPress/ipsum#224)
- Fix Details block markers being announced by screen readers (WordPress/ipsum#230)
- Remove the physical left alignment from the page patterns (WordPress/ipsum#226)
- Indent the navigation submenus on the inline start (WordPress/ipsum#225)
- Fix accessible names for overlay navigation (WordPress/ipsum#228)
- Split AGENTS.md so it holds for any copy of the theme (WordPress/ipsum#214)
- Use a logical margin for the comment form checkbox (WordPress/ipsum#231)
- Keep keyboard focus visible and clear of the sticky header (WordPress/ipsum#145)
- Fix accessible name of overlay search form (WordPress/ipsum#239)
- Show a message when the blog and Archive Full have no posts (WordPress/ipsum#238)
- Keep the post date on one line when categories wrap (WordPress/ipsum#205)
- Remove repeated button styles from theme.json (WordPress/ipsum#235)
- Remove unused values from theme.json (WordPress/ipsum#237)
- Make the credit line URL translatable (WordPress/ipsum#240)
- Use single border radius values in theme.json (WordPress/ipsum#236)
- Escape the short post date format instead of ignoring PHPCS (WordPress/ipsum#245)
- Use the Site Title in Footer Centered (WordPress/ipsum#244)
- Keep AGENTS.md about the theme, not the GitHub repository (WordPress/ipsum#247)
- Treat "Written by" as a label before the author name (WordPress/ipsum#246)
- Use Quote blocks for statement patterns and remove text quote mark styles (WordPress/ipsum#232)
  

This commit also includes changes that only exist in core:

- Tests for the `ipsum/get-design-guide` ability are added in `tests/phpunit/tests/theme/ipsumGetDesignGuideAbility.php`, because Ipsum's repository has no PHPUnit setup. On multisite, the tests save global styles as a super admin, since only super admins can save unfiltered global styles.
- `contributing.txt` says Ipsum is developed on GitHub until its 1.0 release, with contributions going through Trac after that. It also drops the note about `style.css` being used when it is newer than `style.min.css`.
- A test message in `ipsumDesignGuide.php` says "do not match" instead of "to not match".

Developed in: WordPress/wordpress-develop#15948

Follow-up to r65366.

Props onemaggie, juanfra, shailu25, iamarinoh, 369work, gziolo, wildworks, suryakantupadhyay, khushalsains, ravipatel, meahadi.
Fixes #66678. See #66352.
Built from https://develop.svn.wordpress.org/trunk@65549


git-svn-id: http://core.svn.wordpress.org/trunk@64622 1a063a9b-81f0-0310-95a4-ce76da25c4cd
arshidkv12 pushed a commit to arshidkv12/wordpress-develop that referenced this pull request Nov 21, 2026
This updates Ipsum from `bc2e5af700e28980f251d97f58cf80c72ee50a13` to `d26734ecc1ba178d9c120178ce9d2c48825fc108` on its `trunk` branch.

A full list of changes included in this commit can be found on GitHub: WordPress/ipsum@bc2e5af...d26734e

- Address the review notes from the 7.2 Beta 5 core commit (WordPress/ipsum#216)
- Fix Pullquote custom line height not applying on the front end (WordPress/ipsum#203)
- Fix horizontal scroll caused by long unbroken words in comments (WordPress/ipsum#200)
- Improve design guide defaults and schema descriptions (WordPress/ipsum#193)
- Make the short post date format translatable (WordPress/ipsum#224)
- Fix Details block markers being announced by screen readers (WordPress/ipsum#230)
- Remove the physical left alignment from the page patterns (WordPress/ipsum#226)
- Indent the navigation submenus on the inline start (WordPress/ipsum#225)
- Fix accessible names for overlay navigation (WordPress/ipsum#228)
- Split AGENTS.md so it holds for any copy of the theme (WordPress/ipsum#214)
- Use a logical margin for the comment form checkbox (WordPress/ipsum#231)
- Keep keyboard focus visible and clear of the sticky header (WordPress/ipsum#145)
- Fix accessible name of overlay search form (WordPress/ipsum#239)
- Show a message when the blog and Archive Full have no posts (WordPress/ipsum#238)
- Keep the post date on one line when categories wrap (WordPress/ipsum#205)
- Remove repeated button styles from theme.json (WordPress/ipsum#235)
- Remove unused values from theme.json (WordPress/ipsum#237)
- Make the credit line URL translatable (WordPress/ipsum#240)
- Use single border radius values in theme.json (WordPress/ipsum#236)
- Escape the short post date format instead of ignoring PHPCS (WordPress/ipsum#245)
- Use the Site Title in Footer Centered (WordPress/ipsum#244)
- Keep AGENTS.md about the theme, not the GitHub repository (WordPress/ipsum#247)
- Treat "Written by" as a label before the author name (WordPress/ipsum#246)
- Use Quote blocks for statement patterns and remove text quote mark styles (WordPress/ipsum#232)
  

This commit also includes changes that only exist in core:

- Tests for the `ipsum/get-design-guide` ability are added in `tests/phpunit/tests/theme/ipsumGetDesignGuideAbility.php`, because Ipsum's repository has no PHPUnit setup. On multisite, the tests save global styles as a super admin, since only super admins can save unfiltered global styles.
- `contributing.txt` says Ipsum is developed on GitHub until its 1.0 release, with contributions going through Trac after that. It also drops the note about `style.css` being used when it is newer than `style.min.css`.
- A test message in `ipsumDesignGuide.php` says "do not match" instead of "to not match".

Developed in: WordPress#15948

Follow-up to r65366.

Props onemaggie, juanfra, shailu25, iamarinoh, 369work, gziolo, wildworks, suryakantupadhyay, khushalsains, ravipatel, meahadi.
Fixes #66678. See #66352.

git-svn-id: https://develop.svn.wordpress.org/trunk@65549 602fd350-edb4-49c9-b593-d223f7449a82
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improve design guide defaults and schema descriptions

3 participants