Surface glossary terms and related links in expandable cards (#6305)

Introduces a new card-based design for entries on the glossary page. The
short description is shown by default and the long description and
resource links are shown once expanded. When navigating to the page, the
card that corresponds to the current fragment (such as `#variance` in
`dart.dev/resources/glossary#variance`) is expanded.

Additionally you can specify the type of a resource to add an icon in
front of the resource button. Currently the supported types are:

- `term` _(for other glossary entries or word definitions)_
- `article` or `doc` _(general for doc pages)_
- `tutorial` _(for tutorials, codelabs, etc.)_
- `api` _(for API links)_
- `video` _(for videos, such as links to Youtube videos)_
- `code` or `sample` _(for code samples or repository links)_
- `diagnostic` or `lint` _(for links to specific lints, diagnostic docs,
etc.)_

To implement this, I've introduced a new set of shared button styles in
`_buttons.scss` and updated the shared set of card styles in
`_cards.scss`. That way cards across the site _(currently this and the
linter rules page)_ can benefit from a consistent structure and shared
styles.

Author: parlough

src/_data/glossary.yml

@@ -10,6 +10,7 @@
   related_links:
     - text: "Refactor"
       link: "#refactor"
+      type: "term"
   labels:
     - "tools"
     - "analyzer"
@@ -62,8 +63,10 @@
   related_links:
     - text: "Final and const variables"
       link: "/language/variables#final-and-const"
+      type: "doc"
     - text: "Don't use const redundantly"
       link: "/effective-dart/usage#dont-use-const-redundantly"
+      type: "doc"
   labels:
     - "language"
     - "const"
@@ -166,8 +169,10 @@
   related_links:
     - text: "Definite assignment specification"
       link: "https://github.com/dart-lang/language/blob/main/resources/type-system/flow-analysis.md"
+      type: "doc"
     - text: "Understanding definite assignment analysis"
       link: "/null-safety/understanding-null-safety#definite-assignment-analysis"
+      type: "doc"
   labels:
     - "language"
     - "flow analysis"
@@ -180,8 +185,10 @@
   related_links:
     - text: "Functions overview"
       link: "/language/functions"
+      type: "doc"
     - text: "Instance methods"
       link: "/language/methods"
+      type: "doc"
   labels:
     - "language"
     - "umbrella term"
@@ -202,8 +209,10 @@
   related_links:
     - text: "Places patterns can appear"
       link: "/language/patterns#places-patterns-can-appear"
+      type: "doc"
     - text: "Dive into Dart patterns and records"
       link: "https://codelabs.developers.google.com/codelabs/dart-patterns-records"
+      type: "tutorial"
   labels:
     - "language"
     - "patterns"
@@ -249,6 +258,7 @@
   related_links:
     - text: "Mixins in Dart"
       link: "/language/mixins"
+      type: "doc"
   labels:
     - "language"
     - "understanding diagnostics"
@@ -321,6 +331,7 @@
   related_links:
     - text: "Inheritance in Dart"
       link: "/language/extend"
+      type: "doc"
   labels:
     - "language"
     - "type inference"
@@ -335,8 +346,10 @@
   related_links:
     - text: "Guidance on libraries and parts"
       link: "/tools/pub/create-packages#organizing-a-package"
+      type: "doc"
     - text: "Use library URIs in `part of` directives"
       link: "/effective-dart/usage#do-use-strings-in-part-of-directives"
+      type: "doc"
   labels:
     - "language"
     - "libraries"
@@ -365,6 +378,7 @@
   related_links:
     - text: "Nullability and generics"
       link: "/null-safety/understanding-null-safety#nullability-and-generics"
+      type: "doc"
   labels:
     - "language"
     - "type system"
@@ -383,8 +397,10 @@
   related_links:
     - text: "Organizing a package's libraries"
       link: "/tools/pub/create-packages#organizing-a-package"
+      type: "doc"
     - text: "Public package directories"
       link: "/tools/pub/package-layout#public-directories"
+      type: "doc"
   labels:
     - "language"
     - "libraries"
@@ -396,10 +412,13 @@
   related_links:
     - text: "Quick fixes for analysis issues"
       link: "https://medium.com/dartlang/quick-fixes-for-analysis-issues-c10df084971a"
+      type: "article"
     - text: "Diagnostic messages"
       link: "/tools/diagnostic-messages"
+      type: "doc"
     - text: "Linter rules"
       link: "/tools/linter-rules"
+      type: "doc"
   labels:
     - "tools"
     - "understanding diagnostics"
@@ -415,6 +434,7 @@
   related_links:
     - text: "Assist"
       link: "#assist"
+      type: "term"
   labels:
     - "tools"
     - "analysis"
@@ -432,8 +452,10 @@
   related_links:
     - text: "Places patterns can appear"
       link: "/language/patterns#places-patterns-can-appear"
+      type: "doc"
     - text: "Dive into Dart patterns and records"
       link: "https://codelabs.developers.google.com/codelabs/dart-patterns-records"
+      type: "tutorial"
   labels:
     - "language"
     - "patterns"
@@ -472,8 +494,10 @@
   related_links:
     - text: "Inheritance in Dart"
       link: "/language/extend"
+      type: "doc"
     - text: "Subtype relationship"
       link: "#subtype"
+      type: "term"
   labels:
     - "language"
     - "type system"
@@ -519,8 +543,10 @@
   related_links:
     - text: "Subclass"
       link: "#subclass"
+      type: "term"
     - text: "Substituting types"
       link: "/language/type-system#substituting-types"
+      type: "doc"
   labels:
     - "language"
     - "type system"
@@ -611,10 +637,13 @@
   related_links:
     - text: "Subtype relationship"
       link: "#subtype"
+      type: "term"
     - text: "Covariance and contravariance"
       link: "https://en.wikipedia.org/wiki/Covariance_and_contravariance_(computer_science)"
+      type: "article"
     - text: "The covariant keyword"
       link: "/language/type-system#covariant-keyword"
+      type: "doc"
   labels:
     - "language"
     - "type system"

src/_includes/linter-rule-cards.md

@@ -46,8 +46,8 @@
 </div>
 
 <div class="trailing">
-<a href="/tools/linter-rules/{{lint.name}}" title="Learn more about this lint and when to enable it.">Learn more</a>
-<button class="copy-button hidden" title="Copy {{lint.name}} to your clipboard.">Copy</button>
+<a class="outlined-button" href="/tools/linter-rules/{{lint.name}}" title="Learn more about this lint and when to enable it.">Learn more</a>
+<button class="copy-button filled-button hidden" title="Copy {{lint.name}} to your clipboard.">Copy</button>
 </div>
 
 </div>

src/_sass/_site.scss

@@ -12,6 +12,7 @@
 @use 'components/alert';
 @use 'components/banner';
 @use 'components/breadcrumbs';
+@use 'components/buttons';
 @use 'components/card';
 @use 'components/code';
 @use 'components/content';

src/_sass/base/_base.scss

@@ -79,81 +79,14 @@ dt {
   }
 }
 
-a, button {
-  text-decoration: none;
-  color: $brand-primary;
-  font-family: $site-font-family-base;
-  font-weight: 400;
-  cursor: pointer;
-  background: none;
-
-  &:visited {
+a {
+  &, &:visited {
     color: $brand-primary;
   }
-
-  &.filled-button, &.text-button {
-    display: flex;
-    align-items: center;
-    padding: 0.5rem 1rem;
-    gap: 0.5rem;
-    width: fit-content;
-    cursor: pointer;
-    font-size: 1.25rem;
-    white-space: nowrap;
-
-    font-family: $site-font-family-alt;
-
-    &:focus-visible {
-      outline: 2px solid var(--focus-outline-color);
-    }
-  }
-
-  &.filled-button {
-    background-color: $site-color-primary;
-    border-radius: 0.25rem;
-    outline-offset: 2px;
-
-    &, &:hover, &:focus, &:active {
-      color: $site-color-white;
-      text-decoration: none;
-    }
-
-    &:hover {
-      @include interaction-style(4%);
-    }
-
-    &:active {
-      @include interaction-style(8%);
-    }
-  }
-
-  &.text-button {
-    border-radius: 1.5rem;
-
-    &, &:hover, &:focus, &:active {
-      color: $site-color-primary;
-      background: none;
-      text-decoration: none;
-    }
-
-    &:hover {
-      @include interaction-style(4%);
-    }
-
-    &:active {
-      @include interaction-style(7%);
-    }
-  }
-}
-
-.button-group {
-  display: flex;
-  flex-direction: row;
-  gap: 0.75rem;
 }
 
 button {
-  &:hover, &:focus, &:active {
+  &:hover, &:active {
     color: $flutter-color-blue-700;
     outline: none;
     text-decoration: none;

src/_sass/base/_layout.scss

@@ -19,11 +19,11 @@
 
   > article {
     min-width: 8rem;
+    width: 60rem;
+    max-width: 100%;
 
     > .content {
-      max-width: 58rem;
-      margin-left: auto;
-      margin-right: auto;
+      min-width: 8rem;
       padding: $site-content-top-padding;
     }
   }

src/_sass/base/_variables.scss

@@ -15,7 +15,7 @@ $flutter-color-grey-500: #E8EAED;
 $site-color-dark-background: #1C2834;
 $site-color-black: #000;
 $site-color-white: #FFF;
-$site-color-codeblock-bg: #F8F9FA;
+$site-color-codeblock-bg: rgba(248, 249, 250, 0.9);
 $site-color-light-grey: #DADCE0;
 $site-color-nav-links: #6E7274;
 $site-color-body: #212121;

src/_sass/components/_buttons.scss

@@ -0,0 +1,97 @@
+@use '../base/mixins' as mixins;
+@use '../base/variables' as *;
+
+a, button {
+  // Reset style of buttons and anchors.
+  text-decoration: none;
+  cursor: pointer;
+  background: none;
+  border: none;
+  font-weight: 400;
+
+  &.filled-button, &.icon-button, &.text-button, &.outlined-button {
+    // Reset style of buttons.
+    user-select: none;
+    padding: 0;
+
+    // Shared layout styles.
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    justify-content: center;
+    border-radius: 20px;
+    width: fit-content;
+    white-space: nowrap;
+    font-family: $site-font-family-alt;
+    font-size: 1rem;
+    outline-offset: 2px;
+
+    &.hidden {
+      display: none;
+    }
+
+    &:hover {
+      @include mixins.interaction-style(6%);
+      text-decoration: none;
+    }
+
+    &:active {
+      @include mixins.interaction-style(10%);
+      text-decoration: none;
+    }
+
+    &:focus-visible {
+      outline: 2px solid var(--focus-outline-color);
+    }
+  }
+
+  &.filled-button, &.outlined-button, &.text-button {
+    padding: 0.25rem 0.75rem;
+    gap: 0.4rem;
+
+    // A larger call-to-action button.
+    &.large-button {
+      padding: 0.6rem 1.2rem;
+      font-size: 1.5rem;
+      gap: 0.75rem;
+    }
+  }
+
+  &.filled-button {
+    background-color: #06599C;
+    outline-offset: 2px;
+
+    // Ensure color takes precedence over other anchor styling.
+    &, &:hover, &:focus, &:active {
+      color: $site-color-white;
+    }
+
+    span.material-symbols {
+      font-variation-settings: 'FILL' 1;
+      font-size: 20px;
+    }
+  }
+
+  &.icon-button {
+    height: 2rem;
+    width: 2rem;
+
+    padding: 0.2rem;
+    color: #3a3a3a;
+
+    span {
+      font-size: 22px;
+    }
+  }
+
+  &.text-button, &.outlined-button {
+    // Ensure color takes precedence over other anchor styling.
+    &, &:hover, &:active, &:focus {
+      color: #3a3a3a;
+    }
+  }
+
+  &.outlined-button {
+    border: 1px solid rgba(0, 0, 0, .125);
+  }
+}