Skip to content

Let AI agents ask Ipsum how it's designed using the abilities API - #182

Merged
MaggieCabrera merged 7 commits into
trunkfrom
add/design-guide-ability
Oct 30, 2026
Merged

MaggieCabrera merged 7 commits into
trunkfrom
add/design-guide-ability

Conversation

@MaggieCabrera

@MaggieCabrera MaggieCabrera commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Description

Part of #75. It builds on #179, so it merges after it.

AI agents that build pages on a site usually can't see the theme's files, so they guess how it's meant to look. Now they can ask Ipsum directly and get its colors and what each one is for, its fonts, sizes and spacing, its style variations, and its patterns and templates.

Most of that is read from the theme as it is. The part worth a design review is the wording Ipsum adds itself. First, what each color is for:

Color What agents are told
Base The page background.
Contrast Body text, links and buttons.
Accent The accent color. Use it sparingly.
Strong Contrast The strongest contrast with the background: hover states, and the background of inverted sections such as the navigation overlay.
Surface A subtle wash behind quotes, tags and table headers.
Border Faint lines, such as borders, list markers and table rules.

Then three short guidelines:

  • Style with the presets in this guide, by slug, rather than with literal values. Every style variation redefines the colors, so a literal color keeps the look of one variation under all the others.
  • Each template and template part holds a single Pattern block, and that pattern holds the markup. To change one on this site, save new markup to the template or template part itself.
  • Hidden patterns are there to fill templates and template parts, not to be inserted on their own.

Testing Instructions

  1. Log in as an admin and open the Site Editor.
  2. Open the browser console and run await wp.apiFetch( { path: '/wp-abilities/v1/abilities/ipsum/get-design-guide/run' } ).
  3. You get the whole guide. Under colors, each color has the description above.

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5.5
Used for: The code, testing it, and this description.

🤖 Generated with Claude Code

@github-actions github-actions Bot added documentation Improvements or additions to documentation [Area] Theme Functions Issues or PRs that touch functions.php. labels Oct 28, 2026
@MaggieCabrera
MaggieCabrera requested a review from juanfra October 28, 2026 11:50

@mikachan mikachan 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.

Nice, these colour descriptions read well. All of the roles describe how a colour relates to the rest of the palette rather than whether it's light or dark.

I've left some other inline comments. Most of them are about giving agents a bit more detail in the role descriptions, as some of the colours behave differently from what their slugs suggest. I've mostly looked at the design side of this rather than the PHP.

Comment thread inc/abilities.php Resolved
Comment thread inc/abilities.php Resolved
Comment thread inc/abilities.php Resolved
Comment thread inc/abilities.php Resolved
Comment thread inc/abilities.php Resolved
Comment thread inc/abilities.php Resolved
Base automatically changed from update/palette-role-names to trunk October 29, 2026 10:28
Register a read-only ipsum/get-design-guide ability with the Abilities
API. It reads the active palette with each color's role, the type and
spacing scales, style variations, block styles, patterns, templates and
template parts live from the site, so an agent working through the API
learns how Ipsum is meant to be used.

Part of #75.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@MaggieCabrera
MaggieCabrera force-pushed the add/design-guide-ability branch from 3ccca2f to f25903c Compare October 29, 2026 10:56
@MaggieCabrera MaggieCabrera changed the title Pilot an ability that returns the theme's design guide Let AI agents ask Ipsum how it's designed (pilot) Oct 29, 2026
@MaggieCabrera

Copy link
Copy Markdown
Contributor Author

@mikachan do you think the name of the colors should change to reflect more what they actually are for?

@MaggieCabrera
MaggieCabrera marked this pull request as ready for review October 29, 2026 16:28
@github-actions

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: MaggieCabrera <onemaggie@git.wordpress.org>
Co-authored-by: mikachan <mikachan@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 MaggieCabrera changed the title Let AI agents ask Ipsum how it's designed (pilot) Let AI agents ask Ipsum how it's designed Oct 29, 2026
@mikachan

Copy link
Copy Markdown
Member

do you think the name of the colors should change to reflect more what they actually are for?

You mean Base, Contrast, Accent, etc? I don't think so, as if we keep the names like this, it makes carrying over colours easier when switching themes. I'm also personally a fan of this naming structure, but that's just my opinion. Were you thinking we should update the names too?

Co-authored-by: Sarah Norris <1645628+mikachan@users.noreply.github.com>
@MaggieCabrera

Copy link
Copy Markdown
Contributor Author

I've left some other inline comments. Most of them are about giving agents a bit more detail in the role descriptions, as some of the colours behave differently from what their slugs suggest.

no, it's because you said

I've left some other inline comments. Most of them are about giving agents a bit more detail in the role descriptions, as some of the colours behave differently from what their slugs suggest.

Co-authored-by: Sarah Norris <1645628+mikachan@users.noreply.github.com>
@mikachan

Copy link
Copy Markdown
Member

Ah sorry, no I think it's fine to keep the slugs and names as they are.

MaggieCabrera and others added 4 commits October 30, 2026 15:52
Co-authored-by: Sarah Norris <1645628+mikachan@users.noreply.github.com>
Co-authored-by: Sarah Norris <1645628+mikachan@users.noreply.github.com>
Co-authored-by: Sarah Norris <1645628+mikachan@users.noreply.github.com>
Co-authored-by: Sarah Norris <1645628+mikachan@users.noreply.github.com>
@MaggieCabrera
MaggieCabrera merged commit 92aa4fb into trunk Oct 30, 2026
5 checks passed
@MaggieCabrera
MaggieCabrera deleted the add/design-guide-ability branch October 30, 2026 15:03
MaggieCabrera added a commit to MaggieCabrera/wordpress-develop that referenced this pull request Nov 2, 2026
Ipsum registers a read-only `ipsum/get-design-guide` ability with the Abilities API. It returns the theme's colors and what each one is for, its fonts, sizes and spacing, its style variations, and its patterns and templates, so agents building pages can follow the design without seeing the theme's files.

Synced from WordPress/ipsum#182.

See #66352.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@MaggieCabrera MaggieCabrera changed the title Let AI agents ask Ipsum how it's designed Let AI agents ask Ipsum how it's designed using the abilities API Nov 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Area] Theme Functions Issues or PRs that touch functions.php. documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants