cru-branding-submodule:Cru的品牌样式的SCSSCSS打算作为子模块引入其他存储库中_git_存储_其他

# Cru Branding Submodule **LATEST VERSION: v0.3** The purpose of this repository is firstly to provide consistent branding for Cru's online properties. It's designed to be included in other git repositories as a submodule. Web projects can utilize the classes found in the CSS files "out of the box" or import the SCSS files into their own project's SCSS files and compile everything together for a custom stylesheet. Secondly, this submodule serves as a development area for the core component styling for [cru.org](https://cru.org) which runs on [Adobe Experience Manager (AEM)](https://www.adobe.com/marketing/experience-manager.html). Those files can be found in `/{version-directory}/cruorg`. Seeing how the designs for the core components were given as the examples of the desired cross-project consistent branding, it made sense to develop both in the same place. ## Disclaimer This submodule is still in its infantcy. Variables, mixins, functions, and classes will continue to change periodically right now. Use at your own risk. Please contact John Plastow with any questions. ## Versioning The criteria for what amount of changes necessitate a bump in version number are still being ironed out as is how to keep all versions available. Currently, we're using a simple directory system with a separate directory for each version. ## How to Incorporate into Your Project There are a couple different ways this submodule can be incorporated into a project. 1. Use one of the CSS files located in `/{version-directory}/css` in a `<link>` element in your HTML file's `<head>` area. Inside those files you'll find lots of pre-defined classes that your web project can utilize. 2. Import the SCSS files located in `/{version-directory}/scss` into your own SCSS project and compile everything together for a custom stylesheet. Here's an example of the files you'll probably need for option #2: ``` @import '{local-path-to-submodule-directory}/{version-directory}/scss/options'; @import '{local-path-to-submodule-directory}/{version-directory}/scss/variables'; @import '{local-path-to-submodule-directory}/{version-directory}/scss/mixins'; ``` *Note - If you're using option #2 and needing to export multiple stylesheets, you'll need to import the branding SCSS files into each of the SCSS files in your project that will be exported. We're doing this for the cru.org styles by importing the SCSS partial `/{version-directory}/cruorg/_branding-imports.scss` which contains all the branding imports necessary. This allows us to maintain the branding imports from a single location and only requires a single import in each SCSS file to be exported. ## Using the SCSS Files This is the more complex, but much more powerful, way to use this submodule. All the compiled CSS was originally written in SCSS (a syntax variation of the CSS preprocessing language [SASS](https://sass-lang.com/)) and have largely been sorted into sub-directories according to the type of data they contain, namely variables, mixins, and classes. The power of the SCSS is found in the variables and mixins. If you use the variables and mixins in this submodule and we need to tweak something for the sake of Cru branding, your website will be automatically updated the next time you update the submodule in your development environment and recompile the stylesheets. **Please use the variables and mixins! They were made for YOU!** ### Two media query strategies Much of the web development world uses a mobile-first responsive web development approach, writing CSS for mobile browser sizes first and then working their way up. AEM, on the other hand, uses a desktop-first-ish strategy, writing CSS for the largest browser size first and then covering the rest with a combination of `min-width` and `max-width` definitions, never overriding any styles except the largest. Here's a comparison of the two responsive strategies using this submodule's default breakpoints: 768px and 1200px. We're going to set three different background colors to `body` - red on mobile, green on tablet, and blue on desktop. ``` Mobile-first AEM body { body { background-color: red; background-color: blue; @media (min-width: 768px) { @media (max-width: 768px) { background-color: green; background-color: red; } } @media (min-width: 1200px) { @media (min-width: 769px) and (max-width: 1200px) { background-color: blue; background-color: green; } } } } ``` ### Setting options, overriding variables, and modifying breakpoints While this submodule is designed to keep branding consistent across various projects, there are some things that need to be customizable. The following options are set to false by default, but set them to `true` as needed. * `$cru-import-google-fonts` imports all official Cru branding fonts. * `$cru-import-google-fonts-sans-serif-only` imports only the official Cru branding sans-serif font. * `$cru-import-google-fonts-serif-only` imports only the official Cru branding serif font. * `$cru-aem-media-queries` changes the output format of the media query mixins to AEM-style rather than mobile-first. *Note - These options, along with the variable overrides discussed next, need to be declared **before** importing the branding SCSS files mentioned earlier. Inside `/{version-directory}/scss` you'll find two non-underscored files: `aem.scss` and `mobile-first.scss`. These two files get compiled into their corresponding CSS files in `/{version-directory}/css`. Both files import the `_styles.scss` file and thus all the other files that `_styles.scss` imports itself, but `aem.scss` also imports `_aem-overrides.scss` which contains new option and variable values which will override those in `_options.scss` and `_variables.scss` respectively. The submodule defaults to a mobile-first responsive strategy, so we have to tell it we want AEM media queries instead. We do that by setting the variable `$cru-aem-media-queries` to `true`. AEM also uses an additional breakpoint to what's in this submodule, 992px, so we need to add it to the [map](https://sass-lang.com/documentation/values/maps) of breakpoint values that's used to create the media queries. Non-AEM projects may also find themselves needing to add or modify the breakpoints used, so this example applies to everyone. ``` Default AEM $cru-breakpoints: ( $cru-breakpoints: ( 1: 0, xs: 0, 2: 768px, md: 768px, 3: 1200px, lg: 992px, ) !default; xl: 1200px, ); $cru-breakpoints-mapping: ( $cru-breakpoints-mapping: ( 1: 1, xs: 1, 2: 2, md: 2, 3: 3, lg: 2, ) !default; xl: 3, ); ``` A few things to note: 1. The `!default` flag is only needed on the default map because that's what indicates it can be overridden. 2. The first breakpoint **must** have a value of 0 for computational purposes. 3. You can label your maps' keys whatever you want as long as they're consistent between `$cru-breakpoints` and `$cru-breakpoints-mapping`. 4. The submodule's default styles are set for three browser sizes, essentially mobile, tablet, and desktop, so if you change the number of breakpoints or change the map keys, you need to tell it which breakpoints you want the default styles to apply to. In this example, we're telling the compiler to map the mobile styles (1) to the smallest breakpoint, the tablet styles (2) to the middle two breakpoints, and the desktop styles (3) to the largest breakpoint in `$cru-breakpoints-mapping`. `_aem-overrides