[RFC] Set Recommended Sizes for extension store visual assets

[cdowdy]

This would be the recommended sizes for assets used in the extension store.

Currently on the main extension store page: https://extensions.bolt.cm/ icons for extensions are scaled by the browser to ~200x200px and themes to ~400px. This can make the site slow on slower connections and is wasted browser processing.

What I'm proposing is to have in the docs under Themes and Extensions Publishing to the marketplace a set of recommended sizes for Icons. These aren't set in stone or checked server side. It's just what is already being done by the CSS on the extension store and will make things more efficient and not waste bandwidth and make things a little easier for the developer knowing what the the store prefers .

Icons

For Extensions:

• Icon of at least 200x200 pixels
• publish the psd (if available) of the "fallback" extension icon https://extensions.bolt.cm/files/bolt-extension.png
• publish an SVG version as well if available

For Themes: Currently the first listed screenshot in composer.json is used on the main page:

• recommend a screenshot of at least 400px wide (currently is scales it to about 400px wide and about 250/270px tall) this would be used for the main page for "recently added" and "most downloaded" that is shown.
• ask that they crop out a section for this screen shot. An example of this (bolt's sizes of course are different) can be seen in Drupal's theme submission guidelines:

Cut out a piece about ~420x252 (5:3 ratio) resized to exactly 150x90 (~35% of the original size). Try to show only useful page elements (menu, tabs, title, links). Don't include browser chrome (toolbar, status bar, scrollbar, etc).

Those above are strictly used for "icons" on the main page.

Screenshots

For the theme and extensions "details" page .. examples: File Browser and a theme Bootstrap theme

The icon used in the upper left hand corner would be the 200x200px icon. This is scaled down to ~60x60px. Using the 200px image is a lot better than scaling down 800+px images

Screenshots could be recommended for at least 1000px wide (to account for HIDPI screens) or to a specific aspect ratio.

Examples:

• drupal 7+

The screenshot should show the entire page and be about ~900x675 (4:3 ratio) resized to exactly 600x450. The image is displayed at 300x225 but for retina displays, you need to provide an image that doubles the regular resolution. Try to show many useful page elements (menu, tabs, title, links). Don't include browser chrome (toolbar, status bar, scrollbar, etc).

• Wordpress themes

he screenshot should accurately show the theme design and saved in PNG format. The recommended image size is 1200x900. The screenshot will only be shown as 387x290, but the over double-sized image allows for high-resolution viewing on HiDPI displays.

• October CMS

Plugin screenshots aspect ratio should be 1.33, for example 800x600px. Theme screenshots aspect ratio should be 1.5, for example 990x660px. Screenshots shouldn't be wider than 1200 px. Theme screenshots should have width of at least 850px. Plugin screenshots should have width of at least 838px. The ideal plugin screnshot size is 838x630px. Screenshots shouldn't contain Windows task bar or MacOS dock. Screenshots shouldn't contain the browser window frame or its elements (scrollbars, Chrome footer address panel, etc.). Screenshots shouldn't contain the windows shadows. Screenshot images shouldn't be resized (squeezed) with image editors to accommodate to the size requirements. Screenshots should use the 100% browser zoom (fonts shouldn't be reduced or enlarged). Use the standard, non-customized theme for the back-end screenshots. Screenshots should be displayed in the English language. Maximum number of plugin screenshots is 5.

How This Would All Look on Bolt.cm/docs

The below copy could possibly go in one of two places.

• Publishing Your Extension on the Marketplace
• Phase 3 - Moving to the Bolt Marketplace

  Market Place Assets Best Practices:

When you are ready to submit your Extension or Theme to the Bolt Marketplace it is recommended you have the following:

Icons

• Extensions:
  • an icon of at least 200x200px in a PNG or SVG format.
• Themes:
  • an icon of at least 200x200px in a PNG or SVG format.
  • a screen shot of your theme cropped to 400x270px (or 1.48 aspect ratio). Please try to show at minimum the navigation and useful theme elements. Please Do Not include any of the browser "chrome" ie: toolbars, scrollbars, statusbar or extensions you may have installed in your browser.

If you don't provide an Icon Bolt's default marketplace icon will be used

Icon Production Assets:

• link to bolts default icon psd if its available
• link to bolts default icon svg, ai, sketch files if they exist

Screenshots

You should provide at least one screen shot for your Theme and Extensions.

• be at least 1000px wide ( or a specific aspect ratio for extensions )
• please use no more or no less then 100% zoom when you are taking the screenshot
• if text is in the screenshot please use a PNG image.
• Try to show the entirety of the page being screenshot - headers, generic body copy, footer and menus
• If the theme has unique elements or pages please include those too.

Before Submission

After you have created your marketplace assets we ask that you optimize your images.

If it's a PNG or JPG image you can use tinypng.org
If its an SVG image you can use svgomg online

How the composer file would look:

• icon section: no change
• screenshots: no change but the user should add the cropped image for the extension front page

"extra": {
        "bolt-screenshots": [  
            "screenshots/screenshot-cropped.png",
            "screenshots/screenshot1.png"
        ]
    }  

Other considerations.

I left the screenshot at 1000px wide in the copy above because Its hard to determine what an appropriate screenshot width for a theme or extension should be. If its a theme or extension with text in the screenshot then anything below say 500px could become hard to see on small screens or blurry if scaled up for HIDPI screens. Then again these aren't hard numbers just recommendations so whatever is thought to fit best within the marketplace theme would suffice.

• Icon considerations.
  If SVG is used then scaling shouldn't be an issue. If a PNG is used then HIDPI screens may get a muddled image. We could implement <img srcset="" and use the screen density descriptor ie:

<!-- icon image --> 
<img srcset="bolt-icon.png-200px.png 1x, bolt-icon.png-400px.png 2x, bolt-icon.png-800px.png 3x"  
  src="200px-icon.png" <!-- this is the fallback for browser w/no srcset support -->  />   

this would also require a change to the composer.json for the extension or theme and possibly the twig markup

 "extra": {
        "bolt-icon": [
            "bolt-icon.png-200px.png",
            "bolt-icon.png-400px.png",
            "bolt-icon.png-800px.png"
        ]
    }  

If a developer doesn't submit all of the icons then it'll fallback to the normal bolt-icon.png image and whatever size it is. I don't know if this is a breaking change though moving this too an array.

 "extra": {
        "bolt-icon": [ "bolt-icon.png.png" ]
    }  

• Screenshot Considerations:

As Phillip mentioned in slack potential theme users would want to see a large picture. So recommending a screenshot size is nice but if a user submits a small image for the screenshot it may be hard to see since we aren't going to impose any server side checks. As the marketplace is right now a user would have to right click and open the image in a new tab.
So we could either wrap the image in an anchor and link to the full size image or use a lightbox. This though would require extra markup by the theme developer. They'd have to

• create small versions for each screenshot and provide the full res image... not ideal.

also the screenshots section in composer would become massive and messy with a lightbox/anchor open to new page with image pattern

"extra": {
        "bolt-icon": "bolt-icon.png",
        "bolt-screenshots": [
           "screenshots/screenshot-thumb-1.png",
           "screenshots/screenshot1.png" ,
           "screenshots/screenshot-thumb-2.png",
           "screenshots/screenshot2.png"
        ]
    } 

Alternatively we could just wrap the image in an anchor/lightbox and use just the provided screenshot for both the "thumb" and for the "fullres" image like

<div class="gallery" id="scroll_gallery">  
  <a href="/screenshots/screenshot-1.png">
    <img class="image_gallery" src="/screenshots/screenshot-1.png">    
  </a>
  <a href="/screenshots/screenshot-2.png" >
    <img class="image_gallery" src="/screenshots/screenshot-2.png">    
  </a> 
</div>  

Usually I would also recommend responsive images (similar to the icons above under "icon considerations") and use screen density as the descriptor but this too has the same issues as the lightbox/anchor method above and it makes the developer create a crap ton of images. Again not ideal. It could also create a mess in the composer.json file and you don't want to go adding stuff there all willy nilly

"extra": {
        "bolt-screenshots": [
            "screenshots/screenshot-one-1x.png",
            "screenshots/screenshot-one-2x.png",  
            "screenshots/screenshot-one-3x.png"

            "screenshots/screenshot-two-1x.png",
            "screenshots/screenshot-two-2x.png",  
            "screenshots/screenshot-two-3x.png"
            and so on and so on 
        ]
    }  

[GwendolenLynch]

I have to take my hat off to you, @cdowdy … this is one awesomely written RFC. :+1:

I'm banned by myself, and potentially others, from weighing in on UI debates… But from the point of view of the PHP to handle the keys changing to arrays, that's an easy type check so all good. and you've all but written the docs already. Also :+1:

[SvanteRichter]

Just plain awesome. This is a more exhaustive and complete RFC than I've seen in basically any bolt repo. :+1: One quick thing, if we could add a link/reminder for this at https://extensions.bolt.cm/submit (after it's in the docs) that'd be awesome too.

[cdowdy]

Thanks @GawainLynch and @SahAssar I'm ready to write the docs up after a good recommended screenshot size is determined. I'd rather err on the side of caution/too big then have a too small recomended image.

The UI doesn't need to change.. I threw in the anchor/lightbox pattern as supplementary to the whole RFC. It's more of a "nice to have" thing because whats currently there works™ haha.

What page do you all thing this would be more appropriate? Moving to the marketplace page or Publishing to the marketplace?

[cdowdy]

O and here is how the "icons" for themes would look. I took "ion" from the recently added themes section and cropped the header/nav out. Instead of linking to this: https://raw.githubusercontent.com/nestordedios/bolt-theme-ion/master/screenshots/screenshot1.png

and the actual repo link

The new style im proposing would use this image as the main/front page theme "icon"

[PhillippOhlandt]

Hey,

thanks for the awesome RFC.

Most of it looks good, but I am not in favor of changing the composer.json structure because it will be a hell to maintain that on the store if we want the old structure still working. It means also much much much more work for the extension/theme author because he/she has to make all the different icon and screenshots sizes. It will also increase the repo size too much. So, if we want to have them in different sizes, we should scale them on the extension store server like I did on boltthem.es.

Except that, I like the recommendations on the RFC. I would also like to see a hint on avoiding the following type of screenshot: https://github.com/JustSteveKing/Bolt-Medium/blob/master/screenshots/homepage.png If you don't know what I mean: Showing 8 blog items which makes the screenshot too high and stupid big in file size.

[cdowdy]

@PhillippOhlandt yeah I agree with the the multiple thumbs for the screenshots. That is: having every screen shot have a thumbnail version creates a mess.

As for the 3 icon sizes that was just an extra and not part of the entire RFC. It was a more "nice to have" feature. I don't want to introduce a breaking change or something that becomes maintenance hell. You all have enough on your plates! The creation of the Icons could be automated because yeah saying hey make these three (even though a small number) could become tedious and annoying to devs who push a lot of themes or extensions. I think it was you Phillip who created a nut like command feature for creating extensions? I just thought of building an extension that could add a back-end page and/or a nut command that does a extension/theme pre-publish check. It would check the "extras" part of composer.json and if it found a bolt-icon entry make two more at the sizes we want and save them to the icon save path. It could also look for screenshots and if they aren't there spawn a headless browser like phantomjs (one for php here ) and snag one. I've never seen the boltthem.es site before that's pretty neat.

anyways there goes me rambling again and offf topic... back on topic!

What would we call that long repeated screenshot Phillip linked too? Don't show repeated content? If you're fetching a list of items only show the first?

I'll update the RFC copy and post it here in a bit that way you all can read it and add changes/suggestions before deciding and making a pullrequest.

[cdowdy]

Market Place Visual Assets Best Practices:

When you are ready to submit your Extension or Theme to the Bolt Marketplace it is recommended you have the following:

Icons

• Extensions:
  • an icon of at least 200x200px in a PNG or SVG format.
• Themes:
  • an icon of at least 200x200px in a PNG or SVG format.
  • a screen shot of your theme cropped to 400x270px (or 1.48 aspect ratio). Please try to show at minimum the navigation and useful theme elements. Please Do Not include any of the browser "chrome" ie: toolbars, scrollbars, statusbar or extensions you may have installed in your browser.

If you don't provide an Icon Bolt's default marketplace icon will be used

Icon Production Assets:

• link to bolts default icon psd if its available
• link to bolts default icon svg, ai, sketch files if they exist

Screenshots

You should provide at least one screen shot for your Theme(s) and Extension(s).

General recomendations for both an extension and theme screenshots are:

• Use no more or no less than 100% browser zoom.
• If there is text in the screenshot please use a PNG image.
• Screenshots shouldn't contain any browser "chrome" or features. Those include:
  • any extensions you've installed
  • any scroll bars
  • toolbars
  • status bars

Themes

Recomendations for your theme screenshots:

• be no larger than 1200px wide - ( or an agreed aspect ratio )
• show the entirety of the page ( full page screenshot ) and include:
  • Navigation and menus
  • Headers and Footers
  • Generic body copy
• If the theme has unique elements please include those.
• A Large (desktop) and small screen (mobile) screenshot (show responsiveness)
• DO NOT show repeated content - ie: if you are showing a list of Blog Posts show the first post not all the posts.

Extensions

• be no larger than 1200px wide - ( or an agreed aspect ratio )
• If your extension does something unique try to show the expected result in Bolt's default theme

this section below could probably not be included
How To Take A Screenshot

Google Chrome can take responsive image shots (not fullscreen without an extension) through their dev tools:

• Here is How and click the top right 3 dotted overflow menu button and select capture screenshot.
• FireFox Through its command line feature
  • screenshot your-screenshot-name.png --fullpage

Before Submission

After you have created your marketplace assets we ask that you optimize your images.

If it's a PNG or JPG image you can use tinypng.org
If its an SVG image you can use svgomg online

[cdowdy]

Ok I just tested out an svg as an icon. Currently you can't use an SVG for an icon because its sent / delivered with the wrong mime type

Here is the response headers:

HTTP/1.1 200 OK
Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'
Strict-Transport-Security: max-age=31536000
X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-XSS-Protection: 1; mode=block
ETag: "87c583ae11e69ed44256ae74b2f5e0cfc04499ac"
Content-Type: text/plain; charset=utf-8
Cache-Control: max-age=300
X-Geo-Block-List: 
X-GitHub-Request-Id: ************
Content-Encoding: gzip
Content-Length: 6854
Accept-Ranges: bytes
Date: Thu, 28 Jul 2016 17:39:04 GMT
Via: 1.1 varnish
Connection: keep-alive
X-Served-By: cache-atl6235-ATL
X-Cache: HIT
X-Cache-Hits: 1
Vary: Authorization,Accept-Encoding
Access-Control-Allow-Origin: *
X-Fastly-Request-ID: 71d175e35a74a3dbfca12ef7a745544408b26ff4
Expires: Thu, 28 Jul 2016 17:44:04 GMT
Source-Age: 29  

So that stinks... I'll have to remove all the references to SVG.

Edit: if you use https://rawgit.com/ for icons then the appropriate headers are sent. There's a long standing bug on githubs issue tracker referencing SVG and wrong content type header

[PhillippOhlandt]

Ok, I reviewed the text. I like the recommended widths and heights, especially for the first screenshot of a theme.

Could you move the text for the first screenshot of a theme to the screenshots section? It sounds a bit confusing in the Icons section and I don't want people to set that first screenshot as bolt-icon. Then you can also put the two Icon sections (extensions and themes) together.

For the links to production assets. We only have this: https://bolt.cm/distribution/logo

For the screenshot section: 1200px wide is good for themes, we shouldn't limit on the length, because we already define the size of the first screenshot (for performance in the store listviews). For extensions I would recommend the same ratio than for the first theme screenshot.

Personally I like the "How To Take A Screenshot" section, I would let it in there.

Soo, if you adjust the little things above and remove the SVG references I would give it a go. I think the text is long enough to have it's own page in the docs. We could put it in "Extending Bolt > Basics" and link to it from the following page/section: https://docs.bolt.cm/3.0/extensions/basics/creating#publishing-your-extension-on-the-marketplace

[cdowdy]

You're referencing this part right?

Themes: an icon of at least 200x200px in a PNG or SVG format. a screen shot of your theme cropped to 400x270px (or 1.48 aspect ratio). Please try to show at minimum the navigation and useful theme elements. Please Do Not include any of the browser "chrome" ie: toolbars, scrollbars, statusbar or extensions you may have installed in your browser.

If so yeah I can see how that could be confusing. I'll remove the references to the SVG files unless you all think moving to the cdn rawgit offers is worthwhile (example url here referencing the most recent tag/release: https://cdn.rawgit.com/cdowdy/bolt-html5-video/v1.0.1/screenshots/html5-videos-icon-2.svg )

Also have to make sure to offer an example "extras" portion of composer.json that says the cropped image needs to be first in the screenshots section. Since this image is used as the "icon" on the main extension page and the actual icon is used as the icon on the details page: ie: https://extensions.bolt.cm/view/dsduit/helios-html5up and possibly change the template logic to excluded the first image in the array or ones with "-cropped" in it but that is easier said then done.

Thanks @PhillippOhlandt for the pointers and I'll get on to the updates.

[PhillippOhlandt]

@cdowdy important change. Set the icon size to 400x400px, because the store homepage shows them as 3XX x 3XX px at some viewports.

[PhillippOhlandt]

its in for some time now 👍