After reviewing 100's of themes, the most common reasons why themes are rejected and require updates are:
- Weak SCSS. This comes in lots of flavors, but typically the downfall is either...
- Styling one component in the context of another in a way that will break if it's used other than exactly the way the theme uses it. For example .card .btn { margin-right: 5px; } might work for your theme, but it means it unexpected behavior for any other button in a card.
- Being too dependent on a markup chain that makes the component terribly fragile. An example of a brittle selector is .list-group > li > a > span. Avoid selectors like these.
- Inconsistent naming of classes/variables. Ideally, we want these classes to be named in same way Bootstrap does.
- Poor/confusing organization of directories. Most themes should be close to the structure we suggest. It's okay to move all the assets into a single "assets" or "src" directory, but generally, this is right structure.
- Poor/confusing organization of SCSS files. File names and content shouldn't be vague catch-alls (“elements.scss”) or cross-component ("responsive.scss"). Instead each file should be tied to a specific component whenever possible, with a few exceptions for things like type, grid, etc.
- Lacking documentation. Any extended/new components should be documented within the context of the theme. If it relies on a 3rd party plugin, link to the plugin's documentation as well.
- Including too many plugins. This is case by base, but we've found sometimes themes have plugins that feel really forced for the sake of having a long list of plugins. Each plugin should be well integrated into the theme and have a specific purpose.
- Responsive issues. Often times we'll find unconsidered responsive elements. They are most common among navigation, plugin elements, or fly-out/modal elements.
- Complicating the build system. Don't try to get too fancy. The majority of themes use Gulp. A few use Webpack or npm scripts. Those are the only things we allow, so stick to 'em and keep it simple.
- Super “one-off” JS. Instead of styling a plugin as a component, sometimes we'll find 500 lines of JS for one plugin that are attached and specific to a single page’s use case rather than a component.
- Making “getting started” not super obvious. There should be a README.md and/or a like “get-started.html” that explains the basics of how to get started and to compile SCSS. For most themes, this is basically "npm install -g gulp-cli", "npm install", "gulp". Also not defining the default "gulp" command to compile + watch + create a server is common.