version 1.3 optimized for subtheming

README.md

@@ -1,31 +1,36 @@
 Afterlight Tribute
---------
+------------------
 
 Afterlight Tribute is a monochromatic blog theme with an option for a full-screen background image.  It is a simple blank canvas theme.
 
 - this theme is based on the popular, open-source Wordpress theme Afterlight.
 
-- novices can edit the css/style.css file to alter the appearence of your website.
+- novices can edit just the css/your-custom.css file to alter the appearence of your website.
 
-- or front end developers can use the libSASS, liveReload, NPM and Grunt built-in tools for a styling workflow
+- or developers can use the libSASS, liveReload, NPM and Grunt built-in tools for a styling workflow
 
-- novices can use the Responsive Menus or Mobile Navigation modules (downloaded separately) for dropdown or mobile-friendly main menu.
+- novices can install, edit, and deploy the theme as is (deleting the subtheme folder)
 
-- or front end developers can theme their own menus without needing to un-theme existing menu CSS
+- or developers can use the easy, out-of-the-box subtheming folder options for easier future updates to the theme
 
-- sliders, custom fonts and other theme features do not come with this theme and you are encouraged to incorporate separate modules for each page feature that you wish to have.
+- novices can use the Responsive Menus or Mobile Navigation modules (downloaded separately) for dropdown or mobile-friendly main menu.
 
-- a blog or organization that wishes to be seen as stylish is a good example of how to use this theme.
+- or developers can theme their own menus without needing to un-theme existing menu CSS
 
-- a traditional/blue-chip type business is probably not a good fit for this theme.
+- sliders, custom fonts and other theme features do not come with this theme and you are encouraged to incorporate separate modules for each page feature that you wish to have.
 
 - this theme contains checkboxes to serve base style/script files from your site or from Cloudflare CDN
 
 - this theme contains checkboxes to serve modernizr script for browser feature detection, jquery-validate for form validation, fastclick for mobile tapping, and hammer for touch based events.  You must provide the custom integration for each.
 
 - this theme contains easy UI background-image settings for Juiced layouts.
 
-- You can change your website colours from this theme's settings page using the Color module.  (Though it is actually faster/more accurate just to edit the style.css or Sass files).  To use this functionality, enable the Color module on your website. Edit your theme .info file to remove the semi-colons from the stylesheets[all][] lines.  Finally, visit your theme settings page, select your colours, and hit save.  Because this is not a priority for all sites and we only have so much time, if you see an error while using this feature please raise an issue on https://github.com/backdrop-contrib or @biolithic and we will get to fixing it.
+- You can change your website colours from this theme's settings page using the Color module.  (Though it is actually faster/more accurate just to edit the css/your-custom.css or Sass files).  To use this functionality, enable the Color module on your website. Edit your theme .info file to remove the semi-colon from the ;stylesheets[all][] = css/colors.css.  Finally, visit your theme settings page, select your colours, and hit save.  Because this is not a priority for all sites and we only have so much time, if you see an error while using this feature please raise an issue on https://github.com/backdrop-contrib or @biolithic and we will get to fixing it.
+
+- a blog or organization that wishes to be seen as stylish is a good example of how to use this theme.
+
+- a traditional/blue-chip type business is probably not a good fit for this theme.
+
 
 CONTENTS OF THIS FILE
 ---------------------
@@ -36,6 +41,9 @@ CONTENTS OF THIS FILE
  - Special Thanks
  - Coming From Drupal?
  - Javascript Usage
+ - Novice Theming
+ - Intermediate Theming
+ - Advanced Theming
  - Advanced Usage
  - File Structure
  - SASS
@@ -47,8 +55,7 @@ CONTENTS OF THIS FILE
 TESTED
 -----
 
-This theme is under heavy reconstruction and production usage is not recommended at this time.  Estimated production release is 2/2016.
-A former version of this theme has been manually tested successfully creating and viewing nodes and style guide in Backdrop with the Mobile Navigation, Webform and Responsive Menus modules.
+This theme has been manually tested successfully creating and viewing nodes and style guide in Backdrop with the Mobile Navigation, Webform and Responsive Menus modules.
 
 http://dev-backdropthemes.pantheon.io/afterlight-tribute
 
@@ -61,12 +68,11 @@ KNOWN ISSUES
 
 NOTE -- this theme is somewhat stable but being developed state.  If you have spare time and shared ideas on how to propel it forward coding cleanly and under the appropriate licenses, you are welcome to join in and offer advice or build it together.
 
+Color module support is tested working but not promised 100% coverage.
+
 SPECIAL THANKS
 --------------
 
-This theme is based on of Xtheme for Drupal. <https://www.drupal.org/project/xtheme>
-Special thanks to <https://www.drupal.org/u/frankbaele> for this great work!
-
 This theme is based on Afterlight by Automattic. <https://wordpress.com/themes/afterlight>
 Special thanks to them for this great work!
 
@@ -78,11 +84,19 @@ You may extend this theme with the documentation/classes from http://purecss.io
 
 "Pure plays well with other libraries, including Bootstrap and jQuery. As a developer, you can pull in Pure as a foundational CSS framework, and then include specific Bootstrap or jQuery modules that your application may require."
 
-This theme can use the Bourbon/Neat SASS extensions from thoughtbot (disabled by default).
+This theme can use the Bourbon/Neat SASS extensions from thoughtbot.  Uncomment those lines in your gruntfile.js to get started!
 Bourbon is maintained and funded by thoughtbot, inc. Tweet your questions or suggestions to @bourbonsass and while you’re at it follow us too.
 
 Copyright © 2011–2015 thoughtbot, inc. Bourbon is free software, and may be redistributed under the terms specified in the license.
 
+node-bourbon is Copyright © 2013-2014 Michael LaCroix. It is free software, and may be redistributed under the terms specified in the LICENSE file.
+
+node-neat is Copyright © 2013-2014 Michael LaCroix. It is free software, and may be redistributed under the terms specified in the LICENSE file.
+
+This theme can use the Susy SASS extensions. Uncomment those lines in your gruntfile.js to get started! © Copyright 2015 | Miriam Eric Suzanne. <http://susydocs.oddbird.net>
+
+Special thanks to Michael LaCroix @iamlacroix <http://www.lacroixdesign.net> Frank Baele <https://www.drupal.org/u/frankbaele> and Danny Englander @Danny_Englander <http://dannyenglander.com> for their workflow documentation and help!!!  Also to Wicker Park, Chicago, IL for fostering the creative life to the world.
+
 COMING FROM DRUPAL?
 -------------------
 
@@ -93,7 +107,69 @@ This theme does not use the PureCSS grid or any grid by default -- it relies on
 JAVASCRIPT USAGE
 ------------------
 
-If you would like to add custom Javascript to your site, edit the js/scripts.js file.
+If you would like to add custom Javascript to your site, edit the js/scripts.js file (in the subtheme if you are using that setup).
+
+Novice Theming
+------------------
+
+If you just want to start using this theme right now and don't feel that you will need to support this very much in the future, you can!
+-- delete the subtheme folder...it's just dead weight.
+-- if you would like to add custom Javascript to your site, edit the js/scripts.js file.
+-- if you would like to add custom CSS to your site, edit the css/your-custom.css file.
+-- if you would like to use the Admin UI to customize your site, enable the Color module and visit /admin/appearance/settings/afterlight_tribute
+
+Intermediate Theming
+----------------------
+
+If you use a bit of wisdom on theming, you will know that there are base styles, and then there are your own custom styles.  There is the theme as of this moment, but in the future, updates may be made to the core theme and you may want to incorporate those back down easily to your custom theme.  You may even hate the base styles of this theme and just wish to incorporate your own only using this theme as a starting point.
+
+This is called "sub-theming".
+
+To accomplish sub-theming easily with this theme:
+
+Copy the folder afterlight_tribute_subtheme and paste it in your site's root THEMES directory.  After doing this, you will have at least two folders in that same level: afterlight_tribute and afterlight_tribute_subtheme.  Delete the afterlight_tribute_subtheme folder that's inside of the parent theme afterlight_tribute.  Inside of your top-level afterlight_tribute_subtheme, rename afterlight_tribute_subtheme.info.starterkit to afterlight_tribute_subtheme.info
+
+After clearing your site cache, visit /admin/appearance/list .  Enable Afterlight Tribute Subtheme, and make it your default theme.  Now, you can edit custom styles in this theme while it inherits styles from its parent theme afterlight_tribute.  When updates come out for the afterlight_tribute theme, you can just copy and paste or update the parent theme any time and it won't erase your custom theming work (which is done now in the child theme afterlight_tribute_subtheme).
+
+You work in the top-level afterlight_tribute_subtheme theme.
+
+-- if you would like to add custom Javascript to your site, edit the js/scripts.js file.
+-- if you would like to add custom CSS to your site, edit the css/your-custom.css file.
+-- if you would like to use the Admin UI to customize your site, visit /admin/appearance/settings/afterlight_tribute_subtheme
+
+It will import the parent theme CSS and Javascript.  By editing the subtheme files, you will add on top of those.
+It won't import the parent theme theme settings and template files.
+
+If you like, you can rename every instance of afterlight_tribute_subtheme to your own theme name, and by copying and pasting your subtheme folder, you can create more than one subtheme.
+
+For more on this topic, here is an article that might help you <http://singlebrook.com/blog/drupal-sub-themes-using-sass>
+
+Advanced Theming
+------------------
+
+Create a subtheme as stated above.
+
+Use the built-in tools which will increase your productivity to produce leaner, faster downloading styles.
+
+Visit /admin/appearance/settings/afterlight_tribute_subtheme and:
+
+-- Uncheck "use Cloudflare CDN"
+
+-- Check "Only load the your-custom.css sub-theme file and remove the parent theme styles."
+
+-- Open up your gruntfile.js and comment out or uncomment the lines of the tools that you wish to use.
+
+-- Open up your sass/style.scss file in your subtheme and uncomment/comment the lines of the tools/partials that you wish to use.
+
+-- Edit the sass/your-custom Sass files to add your custom styles.  Edit the sass/core at your own risk.
+
+-- If you need to alter template.php, theme-settings.php, .tpl files, Javascript files, etc... make sure to do that in your subtheme.
+
+-- If you want to update the theme (from a newer version), copy the sass/core files from the new version over the sass/core files in your current subtheme.
+
+Sass will always over-ride and save over your /css/your-custom.css file.  If you are writing CSS by hand in addition to Sass, make a new CSS file, include it in your .info file, and the write custom CSS to that file.  This way, if you "Grunt watch" without thinking about it, any custom CSS will be safe and won't be over-ridden.
+
+
 
 ADVANCED USAGE
 ------------------
@@ -105,7 +181,7 @@ Overall file structure
 
 - The .info file is for the listing of files to incorporate into your theme.
 - The color folder is for the Color module UI.  Probably not important to alter.
-- The CSS folder contains the style.css file you should use, which is the file that gets loaded on every page.  It gets overriden by SASS if you use SASS.
+- The CSS folder contains the your-custom.css file which is the CSS file that gets loaded on every page.  It gets overriden by SASS if you use SASS.
 - The JS folder contains the scripts.js file you should use, which is the file that gets loaded on every page.
 - The images folder is for your images and icons.
 - The SASS folder is for your SASS CSS partials.
@@ -114,6 +190,7 @@ Overall file structure
 - Gruntfile.js and package.json contain settings if you are using libSASS
 - If you are not aware, the sass and node_modules folders do not need to be on the live server.  They are for local development only.
 
+
 SASS file structure
 
 This theme is in the process of retro-fitting its CSS into SASS.
@@ -123,18 +200,23 @@ We are in the process of converting from random code from different places into
 
 This file organization is described as such:
 
+core folder is for Sass partials downloaded from Backdropcms.org
+
+your-custom folder loads on top of those core files and are blank, ready for you to add your custom styles to
+
 - style partial is where you can choose/add/remove which partials get added to the final overall CSS file
 - print partial is not used by default but would contain styles for viewing printed copies of your website
 - wysiwyg partial is not used by default but would contain styles for the rich text editors of your website
 
-BASE FOLDER
-- normalize and typography partials for people to work on the typography of the website
+VENDOR FOLDER
+- keep all your third-party library partials in one place in this folder
 
 HELPERS FOLDER
 - variables partial for people to work on the overall settings/defaults of the website
 - extendables, functions, and mixins partials for people to work on the theming functions of the website
 
 DESIGN FOLDER
+- typography partials for people to work on the typography of the website
 - layout partial for people to work on the big picture and layout aspects of the website
 - components partial for people to work on the atomic design, buttons, and small aspects of the website
 - navigation partial for people to work on the header and footer of the website
@@ -172,24 +254,18 @@ npm install
 
 to install the SASS tools for this theme.
 
-To enable livereload for development purposes, uncomment a line starting with this in the middle of your template.php file:
-// backdrop_add_js("document.write('<script src=\"http://' + (location.host
-
 After this has installed, use these commands on the command line in the root of your theme to make the theme do its thing:
 
 Grunt tasks
 ---------------------
-- grunt sass
-
-compile the sass files
 
 - grunt watch
 
 start watching for changes you make to your files and on save automatically reload the page in your localhost.
 
 - grunt prod
 
-compile the theme for production
+compile/minify the theme files for production
 
 Compass compile
 ---------------------

afterlight_tribute.info

@@ -2,14 +2,15 @@ name = Afterlight Tribute
 description = A stylish theme for Backdrop CMS based on https://wordpress.com/themes/afterlight
 backdrop = 1.x
 type = theme
-version = 1.x-1.1
+version = 1.x-1.3
 
-; stylesheets[all][] = css/pure.min.css
-; stylesheets[all][] = css/style.css
+stylesheets[all][] = css/pure.min.css
+stylesheets[all][] = css/style.css
 ; stylesheets[all][] = css/colors.css
-; stylesheets[print][] = css/print.css
+stylesheets[all][] = css/your-custom.css
+stylesheets[print][] = css/print.css
 
-; scripts[] = js/scripts.js
+scripts[] = js/scripts.js
 breakpoints[all] = (min-width: 0em)
 breakpoints[small] = (min-width: 35em)
 breakpoints[large] = (min-width: 55em)