New requirements for settings pages & onboarding in themes

As discussed in our last meeting, we’d like to hear your thoughts on what should or shouldn’t be allowed when developing settings pages or onboarding processes in WordPress themes.

We’ve brainstormed a list of requirements, but we’d really value your input on this:

Admin notice / Theme activation

Themes must use the admin_notices hook to provide any custom messages to the user. These admin notices must either be a one-time message or permanently dismissible. This notice can be used to link to a settings page or start an onboarding process, for example. Popups are not allowed upon theme activation.

Admin page

Themes may optionally add custom sub-pages under Appearance in the WordPress admin. 

They should only contain coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. WordPress UIUI UI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing. elements and generally match the WordPress admin design.

If necessary, themes can include custom styles or scripts for their admin pages, but they cannot leak/spill out to other WordPress admin pages. Enqueue styles/scripts on the admin_enqueue_scripts hook and use $hook_suffix parameter to determine the page.

For ReactReact React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. admin pages, make use of Core components for features if they are available.

Additionally, themes must reference the correct user role capabilities when performing any action inside of the WordPress admin. They must also use an appropriate capability selector or function, such as canUser or current_user_can().

Inserting posts/pages via wp_insert|update_post() can be used if the action is done with user consent.


Themes must use the Settings and Options APIs when storing custom settings in the database. 

Themes must also only add a single database option, which should be an array when storing multiple settings. This option must also be prefixed with the theme slug.

Themes may optionally custom core WordPress options that only affect the front-end and how the website displays (e.g., site logo, front page settings), as long as the user is notified that their saved options will be modified. User consent is required.

All data passed to add_option(), update_option(), or other functions for saving to the database must be validated and/or sanitized with the correct function or method for the data type.

Not allowed

The following features are not allowed as part of an admin menu or onboarding process:

  • Demo imports
  • External calls
  • Tracking/Affiliate links

As an example, you can check the Ollie Dash plugin. Based on a first review, we would not allow the child themeChild theme A Child Theme is a customized theme based upon a Parent Theme. It’s considered best practice to create a child theme if you want to modify the CSS of your theme. and updater functionality.

Our goal is to put these requirements into action starting from the first month of next year, immediately following our upcoming meeting on January 9, 2024. Meanwhile, we’d appreciate it if you could share your opinions.

Wishing you a Happy Holiday and a joyful New Year! 🙂