Initial structure for shared website styles

.github/workflows/dart.yml

@@ -39,16 +39,16 @@ jobs:
       - name: mono_repo self validate
         run: dart pub global run mono_repo generate --validate
   job_002:
-    name: "analyzer_and_format; Dart 3.5.0; PKGS: pkgs/analysis_defaults, pkgs/excerpter, pkgs/inject_dartpad; `dart format --output=none --set-exit-if-changed .`, `dart analyze --fatal-infos .`"
+    name: "analyzer_and_format; Dart 3.5.0; PKGS: pkgs/analysis_defaults, pkgs/dash_design, pkgs/excerpter, pkgs/inject_dartpad; `dart format --output=none --set-exit-if-changed .`, `dart analyze --fatal-infos .`"
     runs-on: ubuntu-latest
     steps:
       - name: Cache Pub hosted dependencies
         uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9
         with:
           path: "~/.pub-cache/hosted"
-          key: "os:ubuntu-latest;pub-cache-hosted;sdk:3.5.0;packages:pkgs/analysis_defaults-pkgs/excerpter-pkgs/inject_dartpad;commands:format-analyze"
+          key: "os:ubuntu-latest;pub-cache-hosted;sdk:3.5.0;packages:pkgs/analysis_defaults-pkgs/dash_design-pkgs/excerpter-pkgs/inject_dartpad;commands:format-analyze"
           restore-keys: |
-            os:ubuntu-latest;pub-cache-hosted;sdk:3.5.0;packages:pkgs/analysis_defaults-pkgs/excerpter-pkgs/inject_dartpad
+            os:ubuntu-latest;pub-cache-hosted;sdk:3.5.0;packages:pkgs/analysis_defaults-pkgs/dash_design-pkgs/excerpter-pkgs/inject_dartpad
             os:ubuntu-latest;pub-cache-hosted;sdk:3.5.0
             os:ubuntu-latest;pub-cache-hosted
             os:ubuntu-latest
@@ -72,6 +72,19 @@ jobs:
         run: dart analyze --fatal-infos .
         if: "always() && steps.pkgs_analysis_defaults_pub_upgrade.conclusion == 'success'"
         working-directory: pkgs/analysis_defaults
+      - id: pkgs_dash_design_pub_upgrade
+        name: pkgs/dash_design; dart pub upgrade
+        run: dart pub upgrade
+        if: "always() && steps.checkout.conclusion == 'success'"
+        working-directory: pkgs/dash_design
+      - name: "pkgs/dash_design; dart format --output=none --set-exit-if-changed ."
+        run: "dart format --output=none --set-exit-if-changed ."
+        if: "always() && steps.pkgs_dash_design_pub_upgrade.conclusion == 'success'"
+        working-directory: pkgs/dash_design
+      - name: "pkgs/dash_design; dart analyze --fatal-infos ."
+        run: dart analyze --fatal-infos .
+        if: "always() && steps.pkgs_dash_design_pub_upgrade.conclusion == 'success'"
+        working-directory: pkgs/dash_design
       - id: pkgs_excerpter_pub_upgrade
         name: pkgs/excerpter; dart pub upgrade
         run: dart pub upgrade
@@ -99,16 +112,16 @@ jobs:
         if: "always() && steps.pkgs_inject_dartpad_pub_upgrade.conclusion == 'success'"
         working-directory: pkgs/inject_dartpad
   job_003:
-    name: "analyzer_and_format; Dart dev; PKGS: pkgs/analysis_defaults, pkgs/excerpter, pkgs/inject_dartpad; `dart format --output=none --set-exit-if-changed .`, `dart analyze --fatal-infos .`"
+    name: "analyzer_and_format; Dart dev; PKGS: pkgs/analysis_defaults, pkgs/dash_design, pkgs/excerpter, pkgs/inject_dartpad; `dart format --output=none --set-exit-if-changed .`, `dart analyze --fatal-infos .`"
     runs-on: ubuntu-latest
     steps:
       - name: Cache Pub hosted dependencies
         uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9
         with:
           path: "~/.pub-cache/hosted"
-          key: "os:ubuntu-latest;pub-cache-hosted;sdk:dev;packages:pkgs/analysis_defaults-pkgs/excerpter-pkgs/inject_dartpad;commands:format-analyze"
+          key: "os:ubuntu-latest;pub-cache-hosted;sdk:dev;packages:pkgs/analysis_defaults-pkgs/dash_design-pkgs/excerpter-pkgs/inject_dartpad;commands:format-analyze"
           restore-keys: |
-            os:ubuntu-latest;pub-cache-hosted;sdk:dev;packages:pkgs/analysis_defaults-pkgs/excerpter-pkgs/inject_dartpad
+            os:ubuntu-latest;pub-cache-hosted;sdk:dev;packages:pkgs/analysis_defaults-pkgs/dash_design-pkgs/excerpter-pkgs/inject_dartpad
             os:ubuntu-latest;pub-cache-hosted;sdk:dev
             os:ubuntu-latest;pub-cache-hosted
             os:ubuntu-latest
@@ -132,6 +145,19 @@ jobs:
         run: dart analyze --fatal-infos .
         if: "always() && steps.pkgs_analysis_defaults_pub_upgrade.conclusion == 'success'"
         working-directory: pkgs/analysis_defaults
+      - id: pkgs_dash_design_pub_upgrade
+        name: pkgs/dash_design; dart pub upgrade
+        run: dart pub upgrade
+        if: "always() && steps.checkout.conclusion == 'success'"
+        working-directory: pkgs/dash_design
+      - name: "pkgs/dash_design; dart format --output=none --set-exit-if-changed ."
+        run: "dart format --output=none --set-exit-if-changed ."
+        if: "always() && steps.pkgs_dash_design_pub_upgrade.conclusion == 'success'"
+        working-directory: pkgs/dash_design
+      - name: "pkgs/dash_design; dart analyze --fatal-infos ."
+        run: dart analyze --fatal-infos .
+        if: "always() && steps.pkgs_dash_design_pub_upgrade.conclusion == 'success'"
+        working-directory: pkgs/dash_design
       - id: pkgs_excerpter_pub_upgrade
         name: pkgs/excerpter; dart pub upgrade
         run: dart pub upgrade

pkgs/dash_design/LICENSE

@@ -0,0 +1,27 @@
+Copyright 2024, the Dart project authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of Google LLC nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pkgs/dash_design/README.md

@@ -0,0 +1,21 @@
+## Shared styles for Dart and Flutter websites
+
+> [!CAUTION]
+> This package and the styles it contains are in progress,
+> and are subject to breakages or removal at any point.
+
+### Usage
+
+To be determined.
+
+### Contributing
+
+Contribution information and guidelines to be added.
+
+### Intended clients
+
+- dart.dev
+- docs.flutter.dev
+- pub.dev
+- api.dart.dev
+- api.flutter.dev

pkgs/dash_design/analysis_options.yaml

@@ -0,0 +1 @@
+include: package:analysis_defaults/analysis.yaml

pkgs/dash_design/lib/styles.scss

@@ -0,0 +1,33 @@
+// Copyright (c) 2024, the Dart project authors. Please see the AUTHORS file
+// 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.
+
+/// styles.scss:
+///
+/// Incorporates all styles and CSS custom properties (variables)
+/// from the dash_design package.
+///
+/// Most variables are added at the `:root` (the `html` element),
+/// but dark mode variable overrides are added to the `body` element if
+/// the class `dark-theme` is added to it.
+
+@use 'styles/variables';
+
+$google-site: false !default;
+
+:root {
+  @include variables.typography;
+  @include variables.shared-colors;
+
+  @include variables.light-theme;
+
+  @if $google-site {
+    @include variables.google-overrides;
+  }
+}
+
+body {
+  &.dark-theme {
+    @include variables.dark-theme;
+  }
+}

pkgs/dash_design/lib/styles/variables.scss

@@ -0,0 +1,52 @@
+// Copyright (c) 2024, the Dart project authors. Please see the AUTHORS file
+// 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.
+
+/// styles/variables.scss:
+///
+/// Mixins that can be included to load CSS custom properties (variables)
+/// into any desired scope.
+
+/// Shared typography CSS variables.
+@mixin typography {
+  /// Used for body text and smaller UI elements, like labels.
+  --dash-default-fontFamily: 'Roboto', sans-serif;
+
+  /// Used for headlines, titles, and larger UI elements.
+  --dash-display-fontFamily: 'Roboto', sans-serif;
+
+  /// Used for monospace text, such as code blocks.
+  --dash-mono-fontFamily: 'Roboto Mono', 'Source Code Pro', 'Cascadia Mono', 'JetBrains Mono', monospace;
+
+  /// Used for icons, such as the magnifying glass for search.
+  --dash-symbol-fontFamily: 'Material Symbols', 'Material Symbols Outlined';
+}
+
+/// Color-related, theme-agnostic CSS variables.
+@mixin shared-colors {
+
+}
+
+/// Light-theme specific CSS variables.
+@mixin light-theme {
+  /// The default text color, used for body text.
+  --dash-surface-fgColor: #4a4a4a;
+}
+
+/// Dark-theme specific CSS variables.
+@mixin dark-theme {
+  --dash-surface-fgColor: #dcdcdc;
+}
+
+/// CSS variables that specify values that can only be used by Google sites,
+/// such as enabling the Google Sans font families.
+///
+/// These overrides should be included after all other variables are defined.
+@mixin google-overrides {
+  // Non-Google sites, such as self-hosted API docs,
+  // can't use Google Sans or Google Symbols.
+  --dash-default-fontFamily: 'Google Sans Text', 'Google Sans', 'Roboto', sans-serif;
+  --dash-display-fontFamily: 'Google Sans', 'Google Sans Text', 'Roboto', sans-serif;
+  --dash-mono-fontFamily: 'Google Sans Mono', 'Roboto Mono', 'Source Code Pro', 'Cascadia Mono', 'JetBrains Mono', monospace;
+  --dash-symbol-fontFamily: 'Google Symbols', 'Material Symbols', 'Material Symbols Outlined';
+}

pkgs/dash_design/mono_pkg.yaml

@@ -0,0 +1,9 @@
+sdk:
+- pubspec
+- dev
+
+stages:
+- analyzer_and_format:
+  - group:
+    - format
+    - analyze: --fatal-infos .

pkgs/dash_design/pubspec.yaml

@@ -0,0 +1,15 @@
+name: dash_design
+description: Shared styles for Dart and Flutter websites.
+version: 0.0.1-wip
+publish_to: none
+repository: https://github.com/dart-lang/site-shared/tree/main/pkgs/dash_design
+
+environment:
+  sdk: ^3.5.0
+
+dev_dependencies:
+  analysis_defaults:
+    path: ../analysis_defaults
+  path: ^1.9.0
+  sass: ^1.79.4
+  test: ^1.25.8

pkgs/dash_design/test/style_test.dart

@@ -0,0 +1,25 @@
+// Copyright (c) 2024, the Dart project authors. Please see the AUTHORS file
+// 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.
+
+import 'dart:isolate';
+
+import 'package:path/path.dart' as path;
+import 'package:sass/sass.dart' as sass;
+import 'package:test/test.dart';
+
+void main() {
+  test('Can build styles.scss file', () {
+    final compileResult = sass.compileToResult(_stylesPath!,
+        fatalDeprecations: sass.Deprecation.values.where((d) => !d.isFuture));
+    expect(compileResult.css, contains('--dash-default-font-family'));
+  });
+}
+
+String? get _stylesPath {
+  final packageUri = Uri.parse('package:dash_design/styles.scss');
+  final resolvedUri = Isolate.resolvePackageUriSync(packageUri);
+  if (resolvedUri == null) return null;
+  if (!resolvedUri.isScheme('file')) return null;
+  return path.fromUri(resolvedUri);
+}