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"
/>

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 * Require Dart 3.6 or later.
 * Require analyzer 7.2.0 APIs.
+* Update the design of GitHub-flavored Markdown alerts for
+  improved accessibility and to better match GitHub and other Dart sites.
 
 ## 8.3.2
 

pubspec.yaml

@@ -27,7 +27,7 @@ dev_dependencies:
   dart_style: ^3.0.0
   lints: ^5.0.0
   matcher: ^0.12.15
-  sass: ^1.80.4
+  sass: ^1.85.0
   test: ^1.24.2
   test_descriptor: ^2.0.1
   test_process: ^2.0.3

testing/test_package/lib/fake.dart

@@ -1,3 +1,5 @@
+// ignore_for_file: unused_element, unused_import
+
 /// # WOW FAKE PACKAGE IS __BEST__ [PACKAGE][pkg]
 /// {@category Real Libraries}
 /// If you don't have this package yet, get it.
@@ -44,9 +46,21 @@
 /// * <http://myfakepackage.com/buthidethisone>
 ///
 /// [pkg]: http://example.org
-
-// ignore_for_file: unused_element, unused_import
-
+///
+/// > [!NOTE]
+/// > A highlighted note aside/admonition.
+///
+/// > [!TIP]
+/// > A highlighted tip aside/admonition.
+///
+/// > [!IMPORTANT]
+/// > A highlighted important aside/admonition.
+///
+/// > [!WARNING]
+/// > A highlighted warning aside/admonition.
+///
+/// > [!CAUTION]
+/// > A highlighted caution aside/admonition.
 library fake;
 
 import 'dart:async';

web/sig.txt

@@ -1 +1 @@
-E8ACF6F50B82736C814C1F0BDE7849EE
+8863C34F7B0AA9147CD23809CF67E875

web/styles/_gfm.scss

@@ -2,70 +2,75 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-/* github alert styles */
-
+/// Alert/admonition styles used by GFM, but styled to match other Dart sites.
 .markdown-alert {
   margin-top: 1rem;
   margin-bottom: 1rem;
-  padding: 1.25rem;
-}
+  padding: 0.75rem;
 
-.markdown-alert > :last-child {
-  margin-bottom: 0;
-}
+  --alert-title-color: --main-inset-borderColor;
 
-.markdown-alert-title {
-  display: flex;
-  align-items: center;
-  gap: 0.4rem;
-  margin-bottom: 0.5rem;
+  background-color: var(--main-inset-bgColor);
+  border-left: solid 0.25rem var(--alert-title-color);
 
-  font-weight: bold;
-  -webkit-font-smoothing: antialiased;
-}
+  > :last-child {
+    margin-bottom: 0;
+  }
 
-.markdown-alert-title:before {
-  font: 24px / 1 'Material Symbols Outlined';
-}
+  .markdown-alert-title {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    margin-bottom: 0.5rem;
 
-/* note, tip, important, warning, caution */
+    font-size: 1.125rem;
+    font-weight: 500;
+    -webkit-font-smoothing: antialiased;
+    color: var(--alert-title-color, inherit);
 
-.markdown-alert.markdown-alert-note {
-  background-color: var(--alert-info);
-}
+    &::before {
+      font: 22px / 1 'Material Symbols Outlined';
+      user-select: none;
+    }
+  }
 
-.markdown-alert-note .markdown-alert-title:before {
-  content: 'info';
-}
+  &.markdown-alert-note {
+    --alert-title-color: var(--alert-info-fgColor);
 
-.markdown-alert.markdown-alert-tip {
-  background-color: var(--alert-tip);
-}
+    .markdown-alert-title::before {
+      content: 'info';
+    }
+  }
 
-.markdown-alert-tip .markdown-alert-title:before {
-  content: 'lightbulb';
-}
+  &.markdown-alert-tip {
+    --alert-title-color: var(--alert-tip-fgColor);
 
-.markdown-alert.markdown-alert-important {
-  background-color: var(--alert-important);
-}
+    .markdown-alert-title::before {
+      content: 'lightbulb';
+    }
+  }
 
-.markdown-alert-important .markdown-alert-title:before {
-  content: 'feedback';
-}
+  &.markdown-alert-important {
+    --alert-title-color: var(--alert-important-fgColor);
 
-.markdown-alert.markdown-alert-warning {
-  background-color: var(--alert-warning);
-}
+    .markdown-alert-title::before {
+      content: 'feedback';
+    }
+  }
 
-.markdown-alert-warning .markdown-alert-title:before {
-  content: 'warning';
-}
+  &.markdown-alert-warning {
+    --alert-title-color: var(--alert-warning-fgColor);
 
-.markdown-alert.markdown-alert-caution {
-  background-color: var(--alert-error);
-}
+    .markdown-alert-title::before {
+      content: 'warning';
+    }
+  }
+
+  &.markdown-alert-caution {
+    --alert-title-color: var(--alert-error-fgColor);
 
-.markdown-alert-caution .markdown-alert-title:before {
-  content: 'report';
+    .markdown-alert-title::before {
+      content: 'report';
+    }
+  }
 }

web/styles/_theme.scss

@@ -24,6 +24,9 @@
   /*search background*/
   --main-search-background: transparent;
 
+  --main-inset-bgColor: #f5f5f7;
+  --main-inset-borderColor: #dadce0;
+
   /*code snippets*/
   --main-code-bg: #f8f8f8;
   --main-keyword-color: #333;
@@ -37,11 +40,11 @@
   --main-icon-color: black;
 
   /* alerts */
-  --alert-info: #e7f8ff;
-  --alert-tip: #ecfaf7;
-  --alert-important: #e2dbff;
-  --alert-warning: #fcf8e3;
-  --alert-error: #fde9ee;
+  --alert-info-fgColor: #2058b7;
+  --alert-tip-fgColor: #0c7927;
+  --alert-important-fgColor: #7953bf;
+  --alert-warning-fgColor: #955d00;
+  --alert-error-fgColor: #c43131;
 }
 
 .dark-theme {
@@ -64,6 +67,9 @@
   /*search background*/
   --main-search-background: black;
 
+  --main-inset-bgColor: #242b32;
+  --main-inset-borderColor: #676f7e;
+
   /*code snippets*/
   --main-code-bg: #10161E;
   --main-keyword-color: white;
@@ -77,11 +83,11 @@
   --main-icon-color: white;
 
   /* alerts */
-  --alert-info: #043875;
-  --alert-tip: #065517;
-  --alert-important: #4a00b4;
-  --alert-warning: #7b6909;
-  --alert-error: #7a0c17;
+  --alert-info-fgColor: #429bff;
+  --alert-tip-fgColor: #25c04b;
+  --alert-important-fgColor: #ad81ff;
+  --alert-warning-fgColor: #cea11f;
+  --alert-error-fgColor: #ff6666;
 }
 
 #theme {

web/styles/dartdoc/_members.scss

@@ -91,7 +91,7 @@ sup.muted {
 }
 
 .from-extension > span {
-  background-color: var(--alert-warning);
+  color: var(--alert-warning-fgColor);
   font-style: italic;
   padding: 2px;
 }