1e757513ce
Issue number: None --------- <!-- Please do not submit updates to dependencies unless it fixes an issue. --> <!-- Please try to limit your pull request to one type (bugfix, feature, etc). Submit multiple pull requests if needed. --> ## What is the new behavior? <!-- Please describe the behavior or changes that are being added by this PR. --> This PR follows the architectural changes defined on the _SCSS Architecture Design Doc_. Due to some of the developments done in the meantime, not everything that was defined on that document was followed and some sections were simplified. Overall, there were two guidelines that supported the work on this PR: - Have no impact on the current scss partials & CSS architecture for the `md/iOS` themes. - Make everything related to the new `Ionic` Theme separated. Based on these, here're the changes made: **On Themes folder (private):** - Renamed current internal scss partials on src/themes, related to md/iOS, to `native.*.scss` and move them to a new folder, called `native`. Updated imports on all framework. - Removed the ionic prefix from the name of the mixins and function partials on src/themes. Updated imports on all framework. - Created new folder, named ionic, inside src/themes. This holds the `ionic.globals.scss`, with all the mixins and functions forwarded, to be used on other scopes. - Replaced on already created Ionic theme files, the usage of tokens and mixins with @use, to instead _@use "../../themes/ionic/ionic.globals.scss" as globals;_. This ensures an equal approach is followed everywhere and also makes it easier to change the files imported or paths, in the future, as its all in the same global file. - Updated the foundations `readMe` file, with the new process for using globals.  **On css folder (public):** - Created new folder, named `ionic`, inside src/css. This holds all the files related exclusively to Ionic Theme, following the same structure as exists now for md/iOS, with a core, a bundle, utils, etc. Some files were a bit duplicated, to eliminate imports from ios or md theme partials. The only file common to both Themes is the `normalize.scss`. - No folder structure or renamings were done on the existing output, to prevent breaking-changes for developers already making imports from this folder. - Updated typography and link partials to use globals instead of tokens. - Changed `font-size` styles on typography to be on `body`, instead of `html`, to enable correct support of accessibility features on browsers and devices, related to `font-size`.  **Other changes related to global styles new architecture:** - Updated margin & padding utility-classed generated by token, to include css variables and padding/margin mixins. - Updated link test to use new global Ionic bundle, correct utility-class on ion-content and updated snapshots. The font-size changed to 16, as its now the default on the body. - Updated typography snapshots. - Updated prettier format on all scss files. Later on we should make sure this is equal for all team members. ## Does this introduce a breaking change? - [ ] Yes - [x] No <!-- If this introduces a breaking change: 1. Describe the impact and migration path for existing applications below. 2. Update the BREAKING.md file with the breaking change. 3. Add "BREAKING CHANGE: [...]" to the commit description when merging. See https://github.com/ionic-team/ionic-framework/blob/main/docs/CONTRIBUTING.md#footer for more information. --> --------- Co-authored-by: Sean Perkins <sean@ionic.io>
18 KiB
Sass Guidelines
Definitions
Sass: An extension to CSS that reduces the repetition in CSS and allows developers to use shared functions, mixins and variables. 1
Members: Refers to variables, functions and mixins in Sass.
Scope
Sass provides members that make it easier to reuse code throughout the Ionic Framework repository. Variables hold values that can be used by other stylesheets. Mixins define reusable blocks of styles that can be included in other selectors. Functions allow the manipulation of values and can perform calculations.
The purpose of this document is to identify the scenarios in which Sass variables should be used.
Historical Usage
In Ionic Framework v1 through v3, the project was built with Sass variables that developers could change at runtime. While the default values were provided by Ionic Framework, anyone developing with it could override these values to rebuild the Ionic Framework CSS with their own values. 2
Due to this, Ionic Framework documented the Sass variables as part of the public API using @prop comments as early as v2.0.0:
// alert.ios.scss
/// @prop - Max width of the alert
$alert-ios-max-width: 270px !default;
/// @prop - Border radius of the alert
$alert-ios-border-radius: 13px !default;
If a Sass variable was deprecated or hidden from the public API, the @prop comment would be removed, or it would never be added, as seen in v3.9.2:
// alert.ios.scss
// deprecated
$alert-ios-head-padding: null !default;
To ensure proper documentation of variables for customizing Ionic Framework, Sass variables were added for components even if they were not used multiple times within the same component or elsewhere:
// alert.ios.scss
/// @prop - Text color of the label for the checked radio alert
$alert-ios-radio-label-text-color-checked: $alert-ios-button-text-color !default;
.alert-ios [aria-checked="true"] .alert-radio-label {
color: $alert-ios-radio-label-text-color-checked;
}
Current Usage
The abundance of Sass variables currently in Ionic Framework is a result of their historical usage, being used to rebuild the CSS and customize Ionic Framework components.
The comments for Sass variables are also still visible today in v7.7.0, even though they are no longer used by any documentation generators:
// alert.ios.vars.scss
/// @prop - Max width of the alert
$alert-ios-max-width: dynamic-font-clamp(1, 270px, 1.2) !default;
/// @prop - Border radius of the alert
$alert-ios-border-radius: 13px !default;
These comments aren't necessary when the naming describes its use thoroughly. The comments for the variables above do not need to be there, as it is fairly obvious what they are used for.
However, the comment for the following variable might be helpful in explaining where it is used because on first glance it reads like it could be used for a sub title inside of a title:
// action-sheet.ios.vars.scss
/// @prop - Font weight of the action sheet title when it has a sub title
$action-sheet-ios-title-with-sub-title-font-weight: 600 !default;
It could be argued though that the comment doesn't really help, as seeing the variable in use will explain its purpose the best. Additionally, this is an example of a variable that isn't necessary, given it is only used in one place, which is why it is so specific in the first place.
Recommended Usage
There are two things that need to be outlined here: when we should use comments and when we should use variables. The sections below detail the recommended usage for each of these.
Comments
We should update the comments for Sass variables in one of the following ways:
-
If we don't intend to ever publicly document the Sass variables again, we should update the comments to remove the syntax that was added for documentation generation:
// alert.ios.vars.scss -/// @prop - Border radius of the alert +// Border radius of the alert $alert-ios-border-radius: 13px !default; -
If we don't find the comments to be helpful, and want to stick with keeping the variable names specific, we should remove the comments entirely:
// alert.ios.vars.scss -/// @prop - Border radius of the alert $alert-ios-border-radius: 13px !default; -
If we find the comments to be helpful for certain variables or situations, like when there are math calculations involved, we should keep only the comments that are necessary to explain what is going on:
-/// @prop - Height of the alert button /** * We want the height of the button to * scale with the text so the next never runs * into the edge of the button. We change the height * instead of adding padding because we would need to offset * the height the padding and the border. Since the border uses * a hairline (<1px) width, this will cause subpixel rendering * differences across browsers. */ $alert-ios-button-height: dynamic-font-min(1, 44px) !default;
Variables
The table below outlines the recommended approach for when to use Sass variables. Each scenario links to a section that explains it in more detail.
| Scenario | |
|---|---|
| ✅ | Global |
| ✅ | Theming |
| ✅ | Reusable values |
| ✅ | Media queries |
| ✅ | Dynamic calculations |
| 🚫 | Consistency |
| 🚫 | Text Alignment |
| 🚫 | Structural Changes |
| 🚫 | Font Properties |
✅ Global
Global variables that are used in multiple places include font-family, z-index, and opacity. These should continue to be set in variables as they affect multiple components that use them.
Example of global variables:
// ionic.globals.scss
$font-family-base: var(--ion-font-family, inherit) !default;
$hairlines-width: 0.55px !default;
$placeholder-opacity: 0.6 !default;
✅ Theming
Storing colors and other design-related values makes it easy to update an entire theme by modifying a few variables.
Example of theme variables:
// ionic.theme.default.scss
$background-color-value: #fff !default;
$background-color-rgb-value: 255, 255, 255 !default;
$text-color-value: #000 !default;
$text-color-rgb-value: 0, 0, 0 !default;
$background-color: var(
--ion-background-color,
$background-color-value
) !default;
$background-color-rgb: var(
--ion-background-color-rgb,
$background-color-rgb-value
) !default;
$text-color: var(--ion-text-color, $text-color-value) !default;
$text-color-rgb: var(--ion-text-color-rgb, $text-color-rgb-value) !default;
// ionic.theme.default.ios.scss
$backdrop-ios-color: var(--ion-backdrop-color, #000) !default;
$overlay-ios-background-color: var(
--ion-overlay-background-color,
var(--ion-color-step-100, #f9f9f9)
) !default;
✅ Reusable values
Use variables for values that are repeated throughout stylesheets, such as spacing, border-radius, font-size, or any other value used in multiple places. A value should only be considered reusable if it is used more than once and related among the elements it is being applied to in some way. For instance, a value is not considered related if it changes a common property, such as border style. While many components use border-style: solid, it does not need to be stored unless these components will require updates with design changes. Currently, the border styles have consistently been set to solid, with the exception of none for a CSS reset.
Example of reusable values:
| Do ✅ |
|---|
|
| Don't ❌ |
|
If a value is shared among multiple components, it should be made into a global variable instead of importing the variable from a specific component. For example, variables that are shared between list components (item, item divider, list header) should be defined in a global theme file:
| Do ✅ |
|---|
|
| Don't ❌ |
|
Tip
The names of the global variables are just an example. We do not currently have a naming convention for global variables.
✅ Media queries
Define breakpoints for responsive design to allow easy adjustments as needed.
Example of breakpoints used by media queries:
// ionic.globals.scss
// The minimum dimensions at which your layout will change,
// adapting to different screen sizes, for use in media queries
$screen-breakpoints: (
xs: 0,
sm: 576px,
md: 768px,
lg: 992px,
xl: 1200px,
) !default;
✅ Dynamic calculations
Variables can be useful for dynamic calculations, such as storing a base font size in a variable and then using it in calculations for other font sizes or spacing values. Variables should not be used for storing a function call, even if the function itself has dynamic calculations.
| Do ✅ |
|---|
|
| Don't ❌ |
|
🚫 Consistency
While we usually aim for consistency across different modes, this isn't always necessary when dealing with Sass variables. If certain styles are present in one mode but absent in another, there's no need to include a Sass variable for the mode lacking those styles.
For example, the color of the label changes when focused in md mode. However, in ios, the label does not receive different styling when focused, therefore it does not require the same styles or a Sass variable defined:
| Do ✅ |
|---|
|
| Don't ❌ |
|
🚫 Text Alignment
A text alignment property should not be stored in a Sass variable, even if it is used in multiple places. This is because the alignment may be tied to a specific design, and the design may change, causing them to become disconnected.
| Do ✅ | Don't ❌ |
|---|---|
|
|
🚫 Structural Changes
Variables should not be used when they are structural changes of an element. This includes display properties, flex properties, grid properties, and more.
| Do ✅ |
|---|
|
| Don't ❌ |
|
🚫 Font Properties
We shouldn't use variables for changing things such as font-size or font-weight, as these are not changed based on a theme and do not need to be updated globally. When updating the font-size and font-weight for these elements, it will always be done on a case-by-case basis:
| Do ✅ |
|---|
|
| Don't ❌ |
|
-
Sass Documentation, https://sass-lang.com/documentation/ ↩︎
-
Ionic Framework v3 Documentation - Theming - Overriding Ionic Variables, https://ionicframework.com/docs/v3/theming/overriding-ionic-variables/ ↩︎