Proposal: allow themes to add a top-level admin-menu

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 block editor sidebar/tools panel. Besides, the Customizer 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 slack 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.