# About The Mod Style Design System Mod Style is a design system package for use on Modernize's S3 microsites. Its purpose is to streamline development by providing flexible, reusable, styled components. Current examples: - a predefined list of sass color variables - media breakpoints - buttons and button groups - input fields - custom icon fonts - fonts and typography styles - logos optimized for both desktop and mobile devices - progress bars - modals The functionality of the Mod Style package is built on top of [bootstrap-sass](https://github.com/twbs/bootstrap-sass), which is a sass-powered version of [Bootstrap 3](https://getbootstrap.com/docs/3.3/getting-started/). (bootstrap-sass will be referenced throughout this guide as simply Bootstrap to avoid confusion). The elements found within Mod Style were developed based on the Mod Style sketch file that is maintained by our designers. The current version can be found here: [Mod Style Guide](https://drive.google.com/drive/folders/0B183MmrG_1B7MUx1YlNEVnJjSWc), alongside a changelog, a list of archived versions, and versions that are currently under construction. If this link is not accessible or has not been shared with you, please let someone on the engineering team know. ## File Structure of Mod Style src/ fonts/ modstyle-icons/ - icon font folder - modicons-basic/ - modicons-fill/ - modicons-stroke/ images/ - modstyle-logos/ - Logo images folder styles/ base/ - minimum core css files used by every page - \_animations - \_breakpoint-mixins - \_colors - \_fonts - \_image-mixins - \_logos - \_reset - index components/ - \_buttons - \_inputs - \_nav - \_progress-bars - index icons/ - \_basics - \_fill - \_stroke - index vendor/ - \_bootstrap-base - for importing minimum core bootstrap modules for all pages - \_custom-variables - for overwriting bootstraps variables with our own styles .editorconfig - rules for code editors based on company's code guidelines .sass-lint.yml - configuration for SASS/SCSS linter package-lock.json - lock file for package.json; makes sure that the same versions of Node modules are installed across env package.json - Node modules used in mod-site ## Installation ### For Projects Using Mod Site: 1. Ensure that the latest version of [Mod Style](https://bitbucket.modernize.com/projects/MS/repos/mod-style/browse) is a dependency of your project and is listed inside your package.json. 2. Ensure that the latest version of [Mod Site](https://bitbucket.modernize.com/projects/MS/repos/mod-site/browse) (currently 4.0.\*) is a dependency of your project and is listed inside your package.json. Mod Site ensures that: - [Bootstrap](https://www.npmjs.com/package/bootstrap-sass) is included as a dependency in your project. - Gulp handles proper compiling of src files from the Mod Style package into your project. 3. Create a folder named `vendor` inside the `src/styles/` folder of your project. 4. Inside the `vendor` folder, create a file called `bootstrap-base.scss`. 5. Inside this file you will import the `bootstrap-base.scss` file from Mod Style. 6. Note: If you need any additional bootstrap components (see below for full list of available components), you will import them from Bootstrap into this file. 7. Add this base file into the head section of your html file using a link tag. 8. Your custom css for your project should be listed as a link tag **AFTER** the bootstrap-base file. 9. Import whatever components you will need from Mod Style into the top of your project's index.scss file. - At the very least you will need to import the base/index.scss file. - If you are using icons you will need to import the correct icon type scss file as well. **Example: Properly Including Link Tags in HTML File** ``` html ``` **Example: Importing Bootstrap Files from Mod Style** ``` css @import '../../../node_modules/mod-style-bootstrap/src/styles/vendor/bootstrap-base'; @import '../../../node_modules/mod-style-bootstrap/src/styles/base/index'; @import '../../../node_modules/mod-style-bootstrap/src/styles/components/buttons'; @import '../../../node_modules/mod-style-bootstrap/src/styles/components/inputs'; ``` **Example: Importing Components from Bootstrap** ``` css @import '../../../node_modules/bootstrap-sass/assets/stylesheets/bootstrap/code'; ``` ### For Projects Not Using Mod Site: - Currently this functionality is not supported. ## How Bootstrap Works for Us For more information on the version of Bootstrap we are currently using please see [Bootstrap 3 - Using Sass](https://getbootstrap.com/docs/3.3/css/#sass) . #### Mod Style Bootstrap Base The Mod Style [bootstrap-base.scss](https://bitbucket.modernize.com/projects/MS/repos/mod-style/browse/src/styles/vendor/_bootstrap-base.scss) file serves to pull in the minimum components necessary from Bootstrap. ##### The components included in this file are: - custom-variables - *Note: see custom variables section below for more info* - variables - mixins - normalize - scaffolding - component-animations - grid - forms - buttons - input-groups - modals - *Note: some javascript files necessary for this to work, see [bootstrap modals](https://getbootstrap.com/docs/3.3/javascript/#modals) for more info* - utilities - responsive-utilities ##### List of all other available Bootstrap components For more about available components within Bootstrap 3 see [Bootstrap 3 Components](https://getbootstrap.com/docs/3.3/components/). Another version of this list can be found inside the [Bootstrap](https://github.com/twbs/bootstrap-sass/tree/master/assets/stylesheets/bootstrap) repo. #### Mod Style Custom Variables {#stylesvendorcustom-variables.scss} Every sass variable in Bootstrap includes the `!default` flag, allowing you to override the variable’s default value in your own sass files without modifying Bootstrap’s source code. For that reason Mod Style contains a copy of Bootstrap's [variable.scss](https://github.com/twbs/bootstrap-sass/blob/master/assets/stylesheets/bootstrap/_variables.scss) file located in `styles/vendor/custom-variables.scss`. In this file the `!default` flag has been removed from all variables so that it won’t be re-assigned by the default values in Bootstrap. All variables that are in use by our pages have been over written with our own custom styles. This file is included at the top of the `bootstrap-base.scss` file because it must come before you import Bootstrap’s Sass variables and other files for the override to work properly. ## Developing and Testing Locally To test and develop locally you will need to work within two separate repositories: **modify.modernize.com** 1. Please ensure that you have cloned the [modify.modernize.com](https://bitbucket.modernize.com/projects/MS/repos/modify.modernize.com/browse) repo and you have pulled the most recent changes from master. 2. Please make sure to branch from master using a branch name that corresponds with a JIRA ticket, for ease of tracking changes. 3. Symlink your local copy of mod-style with the modify project: - Navigate to the root directory of your local copy of mod-style and run `npm link #`. - Navigate to the root directory of the modify project and run `npm link mod-style-bootstrap #` in your terminal. - This link allows you to see changes made within Mod Style. - Note: when you make and save changes within Mod Style you will then have to do `cmnd + s` within a modify scss file for you changes to be picked up. - Note: that the npm package name for the mod-style repo is mod-style-bootstrap, not mod-style. 4. Run gulp serve from the root directory of the modify project. 5. Make necessary changes. If new features or elements are being added (i.e icons, form-elements etc.) please be sure to update the modify project to reflect these changes. 6. Be sure to unlink mod-style before pushing your changes by running `npm unlink mod-style-bootstrap #` in the root directory of the modify project. 7. Create a PR against the master branch of modify.modernize.com. 8. Once your PR is approved merge your feature branch into qa. *Note: any changes made in mod-style will have to be published before deploying this repo to qa.* 9. Once qa approves you can merge your changes to master. **mod-style** 1. Please ensure that you have cloned the [mod-style](https://bitbucket.modernize.com/projects/MS/repos/mod-style/browse) repo and you have pulled the most recent changes from master. 2. Please make sure to branch from master using a branch name that corresponds with the same JIRA ticket you used above, for ease of tracking changes. 3. Make necessary changes. If new features or elements are being added (i.e icons, form-elements etc.) please be sure to update the modify.modernize.com ui to reflect these changes. 4. Update the version number in the package.json. 5. If this update coincides with an update to the design system sketch file, please be sure to update `sketchFileVersion` in the package.json as well, to match the version number named on the sketch file. 6. Create a PR against master branch. 7. Once your PR is approved merge your mod-style feature branch directly to master *(Note: There is no qa branch for mod-style)*. 8. In your terminal, from the root directory of mod-style, on the master branch run `npm publish`. 9. Depending on the version number you are releasing, the change will take effect on pages only once the page has been re-deployed to production by qa. If it's a major version increase, pages will have to manually opt in to the change.