Skip to content

Commit f0c5210

Browse files
parloughparlough
authored
Update style of GFM alerts for improved accessibility and consistency (#4001)
Based on the styles from docs.flutter.dev and dart.dev with slightly increased contrast, which we'll adopt there as well. Resolves #3995 Light mode: <img width="480" alt="Screenshot of each alert style in light mode" src="https://github.com/user-attachments/assets/4a90d92a-3c88-499e-ab79-855c1b7e4284" /> Dark mode: <img width="480" alt="Screenshot of each alert style in dark mode" src="https://github.com/user-attachments/assets/599def0a-30d0-47c1-aeaf-c614037f0a6a" />
1 parent eb188ad commit f0c5210

File tree

8 files changed

+92
-65
lines changed

8 files changed

+92
-65
lines changed

‎CHANGELOG.md

+2
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
* Require Dart 3.6 or later.
44
* Require analyzer 7.2.0 APIs.
5+
* Update the design of GitHub-flavored Markdown alerts for
6+
improved accessibility and to better match GitHub and other Dart sites.
57

68
## 8.3.2
79

‎lib/resources/styles.css

+1-1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎pubspec.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ dev_dependencies:
2727
dart_style: ^3.0.0
2828
lints: ^5.0.0
2929
matcher: ^0.12.15
30-
sass: ^1.80.4
30+
sass: ^1.85.0
3131
test: ^1.24.2
3232
test_descriptor: ^2.0.1
3333
test_process: ^2.0.3

‎testing/test_package/lib/fake.dart

+17-3
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
// ignore_for_file: unused_element, unused_import
2+
13
/// # WOW FAKE PACKAGE IS __BEST__ [PACKAGE][pkg]
24
/// {@category Real Libraries}
35
/// If you don't have this package yet, get it.
@@ -44,9 +46,21 @@
4446
/// * <http://myfakepackage.com/buthidethisone>
4547
///
4648
/// [pkg]: http://example.org
47-
48-
// ignore_for_file: unused_element, unused_import
49-
49+
///
50+
/// > [!NOTE]
51+
/// > A highlighted note aside/admonition.
52+
///
53+
/// > [!TIP]
54+
/// > A highlighted tip aside/admonition.
55+
///
56+
/// > [!IMPORTANT]
57+
/// > A highlighted important aside/admonition.
58+
///
59+
/// > [!WARNING]
60+
/// > A highlighted warning aside/admonition.
61+
///
62+
/// > [!CAUTION]
63+
/// > A highlighted caution aside/admonition.
5064
library fake;
5165

5266
import 'dart:async';

‎web/sig.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
E8ACF6F50B82736C814C1F0BDE7849EE
1+
8863C34F7B0AA9147CD23809CF67E875

‎web/styles/_gfm.scss

+53-48
Original file line numberDiff line numberDiff line change
@@ -2,70 +2,75 @@
22
// for details. All rights reserved. Use of this source code is governed by a
33
// BSD-style license that can be found in the LICENSE file.
44

5-
/* github alert styles */
6-
5+
/// Alert/admonition styles used by GFM, but styled to match other Dart sites.
76
.markdown-alert {
87
margin-top: 1rem;
98
margin-bottom: 1rem;
10-
padding: 1.25rem;
11-
}
9+
padding: 0.75rem;
1210

13-
.markdown-alert > :last-child {
14-
margin-bottom: 0;
15-
}
11+
--alert-title-color: --main-inset-borderColor;
1612

17-
.markdown-alert-title {
18-
display: flex;
19-
align-items: center;
20-
gap: 0.4rem;
21-
margin-bottom: 0.5rem;
13+
background-color: var(--main-inset-bgColor);
14+
border-left: solid 0.25rem var(--alert-title-color);
2215

23-
font-weight: bold;
24-
-webkit-font-smoothing: antialiased;
25-
}
16+
> :last-child {
17+
margin-bottom: 0;
18+
}
2619

27-
.markdown-alert-title:before {
28-
font: 24px / 1 'Material Symbols Outlined';
29-
}
20+
.markdown-alert-title {
21+
display: flex;
22+
align-items: center;
23+
gap: 0.5rem;
24+
margin-bottom: 0.5rem;
3025

31-
/* note, tip, important, warning, caution */
26+
font-size: 1.125rem;
27+
font-weight: 500;
28+
-webkit-font-smoothing: antialiased;
29+
color: var(--alert-title-color, inherit);
3230

33-
.markdown-alert.markdown-alert-note {
34-
background-color: var(--alert-info);
35-
}
31+
&::before {
32+
font: 22px / 1 'Material Symbols Outlined';
33+
user-select: none;
34+
}
35+
}
3636

37-
.markdown-alert-note .markdown-alert-title:before {
38-
content: 'info';
39-
}
37+
&.markdown-alert-note {
38+
--alert-title-color: var(--alert-info-fgColor);
4039

41-
.markdown-alert.markdown-alert-tip {
42-
background-color: var(--alert-tip);
43-
}
40+
.markdown-alert-title::before {
41+
content: 'info';
42+
}
43+
}
4444

45-
.markdown-alert-tip .markdown-alert-title:before {
46-
content: 'lightbulb';
47-
}
45+
&.markdown-alert-tip {
46+
--alert-title-color: var(--alert-tip-fgColor);
4847

49-
.markdown-alert.markdown-alert-important {
50-
background-color: var(--alert-important);
51-
}
48+
.markdown-alert-title::before {
49+
content: 'lightbulb';
50+
}
51+
}
5252

53-
.markdown-alert-important .markdown-alert-title:before {
54-
content: 'feedback';
55-
}
53+
&.markdown-alert-important {
54+
--alert-title-color: var(--alert-important-fgColor);
5655

57-
.markdown-alert.markdown-alert-warning {
58-
background-color: var(--alert-warning);
59-
}
56+
.markdown-alert-title::before {
57+
content: 'feedback';
58+
}
59+
}
6060

61-
.markdown-alert-warning .markdown-alert-title:before {
62-
content: 'warning';
63-
}
61+
&.markdown-alert-warning {
62+
--alert-title-color: var(--alert-warning-fgColor);
6463

65-
.markdown-alert.markdown-alert-caution {
66-
background-color: var(--alert-error);
67-
}
64+
.markdown-alert-title::before {
65+
content: 'warning';
66+
}
67+
}
68+
69+
&.markdown-alert-caution {
70+
--alert-title-color: var(--alert-error-fgColor);
6871

69-
.markdown-alert-caution .markdown-alert-title:before {
70-
content: 'report';
72+
.markdown-alert-title::before {
73+
content: 'report';
74+
}
75+
}
7176
}

‎web/styles/_theme.scss

+16-10
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,9 @@
2424
/*search background*/
2525
--main-search-background: transparent;
2626

27+
--main-inset-bgColor: #f5f5f7;
28+
--main-inset-borderColor: #dadce0;
29+
2730
/*code snippets*/
2831
--main-code-bg: #f8f8f8;
2932
--main-keyword-color: #333;
@@ -37,11 +40,11 @@
3740
--main-icon-color: black;
3841

3942
/* alerts */
40-
--alert-info: #e7f8ff;
41-
--alert-tip: #ecfaf7;
42-
--alert-important: #e2dbff;
43-
--alert-warning: #fcf8e3;
44-
--alert-error: #fde9ee;
43+
--alert-info-fgColor: #2058b7;
44+
--alert-tip-fgColor: #0c7927;
45+
--alert-important-fgColor: #7953bf;
46+
--alert-warning-fgColor: #955d00;
47+
--alert-error-fgColor: #c43131;
4548
}
4649

4750
.dark-theme {
@@ -64,6 +67,9 @@
6467
/*search background*/
6568
--main-search-background: black;
6669

70+
--main-inset-bgColor: #242b32;
71+
--main-inset-borderColor: #676f7e;
72+
6773
/*code snippets*/
6874
--main-code-bg: #10161E;
6975
--main-keyword-color: white;
@@ -77,11 +83,11 @@
7783
--main-icon-color: white;
7884

7985
/* alerts */
80-
--alert-info: #043875;
81-
--alert-tip: #065517;
82-
--alert-important: #4a00b4;
83-
--alert-warning: #7b6909;
84-
--alert-error: #7a0c17;
86+
--alert-info-fgColor: #429bff;
87+
--alert-tip-fgColor: #25c04b;
88+
--alert-important-fgColor: #ad81ff;
89+
--alert-warning-fgColor: #cea11f;
90+
--alert-error-fgColor: #ff6666;
8591
}
8692

8793
#theme {

‎web/styles/dartdoc/_members.scss

+1-1
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ sup.muted {
9191
}
9292

9393
.from-extension > span {
94-
background-color: var(--alert-warning);
94+
color: var(--alert-warning-fgColor);
9595
font-style: italic;
9696
padding: 2px;
9797
}

0 commit comments

Comments
 (0)