mirror of
https://github.com/ionic-team/ionic-framework.git
synced 2026-03-13 10:22:08 +08:00
4698d22413
Issue number: resolves #29219 --------- <!-- 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 current behavior? <!-- Please describe the current behavior that you are modifying. --> We got feedback that the current dark theme is a bit jarring when compared with native. In particular, devs are expecting the contrast to be white for many of these colors to match native iOS. Currently, text inside of a primary button is black on dark mode, but devs expect it to be white. Additionally, the dark mode colors appear to be too washed out when compared with their light mode counterparts. The team discussed this and we think we can find a way to make the colors more in line with what devs expect while still allowing for AA color contrast levels. ## What is the new behavior? <!-- Please describe the behavior or changes that are being added by this PR. --> - Adjusted the secondary and danger colors to be slightly more vibrant/inline with what developers expect in mobile apps while still meeting AA color contrast. ## 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/.github/CONTRIBUTING.md#footer for more information. --> ## Other information I intentionally did not change the contrast color, and I intentionally did not significantly change the vibrancy of each color token. I did some research into how the native platforms handle colors. I'll place this information here, because there are some subtle differences between web and native that make a difference. ### Material Design [Source](https://m2.material.io/design/color/dark-theme.html#ui-application) Material Design 2 calls for desaturated color tokens as well as flipping contrast colors. For example, a vibrant purple background with light text on light mode is a washed purple with dark text on dark mode. The colors in Ionic <=7 did not follow these patterns. The tokens in Ionic 8 now follows these patterns, so what we have in `main` means we are aligning closer with native MD than have in the past.  ### iOS [Source](https://developer.apple.com/design/human-interface-guidelines/accessibility#Color-and-effects) iOS is a bit tricky. On the docs, Apple references the WCAG color contrast formula (what Ionic follows). However, the table they present below is slightly different: | Text Size | Text Weight | Minimum Contrast Ratio | | - | - | - | | Up to 17 points | All | 4.5:1 | | 18 points and larger | All | 3:1 | | All | Bold | 3:1 | The last row is the main difference. WCAG states that text that is bold AND >=14pts (~18.66px) needs to meet a minimum contrast ratio of 3:1. Apple's guidelines state that any text that is bold (regardless of size) needs to meet a minimum contrast ratio of 3:1. In other words, **Apple is using different guidelines to choose colors which is why colored dark mode buttons on iOS typically use white text**. However, Apple is inconsistent in implementing its own guidelines. Consider the following red buttons in the Apple Music app. | Screenshot | Meets Web guidelines | Meets Apple guidelines | Notes | | - | - | - | - | | <img src="https://github.com/ionic-team/ionic-framework/assets/2721089/6bb0e0b3-c29e-4b96-9ad5-e45e59bf0415" width="300" /> | ❌ | ❌ | Text is not bold which makes it not meet either guidelines. | | <img src="https://github.com/ionic-team/ionic-framework/assets/2721089/8ce93b45-0b2b-4160-97a4-19852134684c" width="300" /> | ❌ | ✅ | Text is bold which makes it pass the Apple guidelines, but it's still too small to also pass the Web guidelines. | ### Ionic One of the things I tried is adjusting the base color to work well with white and black backgrounds. It's common to have a blue background with white text (such as a button) AND to have a blue link on a black background (such as an `a` element). This approach does not work well for the shade/tint colors used for hover/focus states. These colors also need to meet Web guidelines. Consider the following example: | Screenshot | Notes | Text/Link passes AA guidelines | Tint passes AA guidelines | | - | - | - | - | |  | This uses the same primary color found in the light palette | ❌ | ✅ | |  | This changes the base color such that the Text/Link passes with a 4.5:1 ratio | ✅ | ❌ | |  | This changes the base color such that the Tint passes with a 4:5:1 ratio | ❌ | ✅ | We also considered adjusting the `a` and `ion-text` colors to use the tint color. We decided against that because it a) felt a little odd given that tint is typically used for states (hover, focus, etc) and b) we were concerned that making this change would impose future restrictions on how this color palette can evolve. ### Conclusion While Ionic's colors don't exactly match the iOS colors, the reality is that we are a web-based tool, so we are going to be evaluated using web-based tools/standards. As a result, it's recommended that we align closer with the Web guidelines than Apple's guidelines. ## Testing Testing: Developers can look at the colors by opening http://localhost:3333/src/themes/test/colors In the video below, the first state is the dark theme in `main`. The second state is the proposed changes. | Visual Comparison | | - | | <video src="https://github.com/ionic-team/ionic-framework/assets/2721089/241fb1b6-212b-4f03-83cd-9558b9a53761"></video> |
Ionic
Ionic is an open source app development toolkit for building modern, fast, top-quality cross-platform native and Progressive Web Apps from a single codebase with JavaScript and the Web.
Ionic is based on Web Components, which enables significant performance, usability, and feature improvements alongside support for popular web frameworks like Angular, React, and Vue.
Quickstart
·
Documentation
·
Contribute
·
Blog
Community:
Discord
·
Forums
·
Twitter
Packages
| Project | Package | Version | Downloads | Links |
|---|---|---|---|---|
| Core | @ionic/core |
 |
 |
README.md |
| Angular | @ionic/angular |
 |
 |
README.md |
| Vue | @ionic/vue |
 |
 |
README.md |
| React | @ionic/react |
 |
 |
README.md |
Looking for the ionic-angular package? Ionic 3 has been moved to the ionic-v3 repo. See Earlier Versions.
Getting Started
Start a new project by following our quick Getting Started guide. We would love to hear from you! If you have any feedback or run into issues using our framework, please file an issue on this repository.
Migration Guides
Already have an Ionic app? These guides will help you migrate to the latest versions.
Examples
The Ionic Conference App is a full featured Ionic app. It is the perfect starting point for learning and building your own app.
Contributing
Thanks for your interest in contributing! Read up on our guidelines for contributing and then look through our issues with a help wanted label.
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
Future Goals
As Ionic Framework components migrate to the web component standard, a goal of ours is to have Ionic Framework easily work within all of the popular frameworks.
Earlier Versions
The source code for earlier versions of the Ionic Framework may exist in other repositories. Please open issues and pull requests in their respective repositories.
- Ionic 2/3: Moved to
ionic-team/ionic-v3 - Ionic 1: Moved to
ionic-team/ionic-v1