The Themes Team would like to add the following requirements and we would also like to hear your opinions on this matter.

Themes should add a page under the Appearance menu using add_theme_page. If they need to have sub-pages (like for example documentation, FAQs, donation link etc), then they are allowed to use add_menu_page and add_submenu_page, provided they follow these requirements:
 * You are allowed to create only one (1) main page using `add_menu_page`. The recommended maximum number of sub-menu pages (`add_submenu_page`) is three (3).
 * The `$position` (priority) parameter must be `null` or only occupy the spot above the Appearance page (59). Check the code example on how to set the correct priority.
 * `add_submenu_page` must be used only on the page created using `add_menu_page`.
 * If you recommend plugins via TGMPA, you are required to use the `parent_slug` configuration option (this should be the top-level page's slug).
 * Core UI patterns must be used. You are not allowed to style the menu & submenu page links in any way. The admin color scheme must remain the same.
 * Use only monochromatic icons. It must account for the admin color scheme.
 * The title must be kept short and not include spam.
 * Child themes are allowed to add one extra sub-page or remove the parent's pages and add its own.

Before you start mentioning that this will be abused and it’s an open door for spam, please consider these:

• You can only have one theme active, which means there can only be one top-level link and it will not occupy that much screen real estate.
• Themes are not allowed to add a panel with information to the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor sidebarSidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme./tools panel. Besides, the CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. will be used less and less and theme authors need to have a visible way to list their theme’s documentation & information.

If you need more info, please check add_menu_page and add_submenu_page.

Added 15th July by @williampatton

For additional context about this idea we had a conversation in slackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. about this that started from this message and continued for quite some time – partially async.

https://wordpress.slack.com/archives/C02RP4Y3K/p1594225597110800 (slack account required)

Added July 18th by @acosmin

After a few discussions and taking @greenshady ‘s ideas into consideration, we’ve decided to:

• remove the sub-pages limit, we recommend using a maximum of three (3)
• the menu page priority can either be null or only occupy the position above the Appearance page. That’s 60 – 1, 59. This will also help users know where to look for this page. You can use this code to make sure your page will always be after Appearance:

function prefix_admin_menu() {
	$menus = $GLOBALS[ 'menu' ];
	$priority = array_filter( $menus, function( $item ) { 
		return 'themes.php' === $item[2];
	} );
	$priority = ! empty( $priority ) && 1 === count( $priority ) ? key( $priority ) - 1 : null;

	add_menu_page(
		__( 'Theme Name Title', 'textdomain' ),
		__( 'Theme Name', 'textdomain' ),

		'edit_theme_options',
		'theme-options.php',
		'',
		'dashicons-admin-customizer',
		$priority
	);
}
add_action( 'admin_menu', 'prefix_admin_menu' );

If you have suggestions on how to improve this code snippet, please do it in the comments.