Start documenting Theme crate

Nate Butler and Antonio Scandurra created 2 years ago

Co-Authored-By: Antonio Scandurra <[e-mail]>

Change summary

Cargo.lock                        | 23 ++++-----------
crates/theme/src/scale.rs         | 49 +++++++++++++-------------------
crates/theme/src/settings.rs      |  2 
crates/theme/src/styles/colors.rs |  1 
crates/theme/src/theme.rs         |  8 +++++
crates/theme/theme.md             | 15 ++++++++++
6 files changed, 51 insertions(+), 47 deletions(-)

Detailed changes

Cargo.lock

@@ -1515,7 +1515,7 @@ dependencies = [
  "tonic",
  "tower",
  "tracing",
- "tracing-log 0.1.3",
+ "tracing-log",
  "tracing-subscriber",
  "unindent",
  "util",
@@ -6930,9 +6930,9 @@ dependencies = [
 
 [[package]]
 name = "sharded-slab"
-version = "0.1.7"
+version = "0.1.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f40ca3c46823713e0d4209592e8d6e826aa57e928f09752619fc696c499637f6"
+checksum = "900fba806f70c630b0a382d0d825e17a0f19fcd059a2ade1ff237bcddf446b31"
 dependencies = [
  "lazy_static",
 ]
@@ -8316,17 +8316,6 @@ dependencies = [
  "tracing-core",
 ]
 
-[[package]]
-name = "tracing-log"
-version = "0.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ee855f1f400bd0e5c02d150ae5de3840039a3f54b025156404e34c23c03f47c3"
-dependencies = [
- "log",
- "once_cell",
- "tracing-core",
-]
-
 [[package]]
 name = "tracing-serde"
 version = "0.1.3"
@@ -8339,9 +8328,9 @@ dependencies = [
 
 [[package]]
 name = "tracing-subscriber"
-version = "0.3.18"
+version = "0.3.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ad0f048c97dbd9faa9b7df56362b8ebcaa52adb06b498c050d2f4e32f90a7a8b"
+checksum = "30a651bc37f915e81f087d86e62a18eec5f79550c7faff886f7090b4ea757c77"
 dependencies = [
  "matchers",
  "nu-ansi-term",
@@ -8354,7 +8343,7 @@ dependencies = [
  "thread_local",
  "tracing",
  "tracing-core",
- "tracing-log 0.2.0",
+ "tracing-log",
  "tracing-serde",
 ]
 

crates/theme/src/scale.rs

@@ -2,41 +2,31 @@ use gpui::{AppContext, Hsla, SharedString};
 
 use crate::{ActiveTheme, Appearance};
 
-/// A one-based step in a [`ColorScale`].
+/// A collection of colors that are used to style the UI.
+///
+/// Each step has a semantic meaning, and is used to style different parts of the UI.
 #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Copy)]
 pub struct ColorScaleStep(usize);
 
 impl ColorScaleStep {
-    pub const ONE: Self = Self(1);
-    pub const TWO: Self = Self(2);
-    pub const THREE: Self = Self(3);
-    pub const FOUR: Self = Self(4);
-    pub const FIVE: Self = Self(5);
-    pub const SIX: Self = Self(6);
-    pub const SEVEN: Self = Self(7);
-    pub const EIGHT: Self = Self(8);
-    pub const NINE: Self = Self(9);
-    pub const TEN: Self = Self(10);
-    pub const ELEVEN: Self = Self(11);
-    pub const TWELVE: Self = Self(12);
-
-    /// All of the steps in a [`ColorScale`].
-    pub const ALL: [ColorScaleStep; 12] = [
-        Self::ONE,
-        Self::TWO,
-        Self::THREE,
-        Self::FOUR,
-        Self::FIVE,
-        Self::SIX,
-        Self::SEVEN,
-        Self::EIGHT,
-        Self::NINE,
-        Self::TEN,
-        Self::ELEVEN,
-        Self::TWELVE,
-    ];
+    const ONE: Self = Self(1);
+    const TWO: Self = Self(2);
+    const THREE: Self = Self(3);
+    const FOUR: Self = Self(4);
+    const FIVE: Self = Self(5);
+    const SIX: Self = Self(6);
+    const SEVEN: Self = Self(7);
+    const EIGHT: Self = Self(8);
+    const NINE: Self = Self(9);
+    const TEN: Self = Self(10);
+    const ELEVEN: Self = Self(11);
+    const TWELVE: Self = Self(12);
 }
 
+/// A scale of colors for a given [ColorScaleSet].
+///
+/// Each [ColorScale] contains exactly 12 colors. Refer to
+/// [ColorScaleStep] for a reference of what each step is used for.
 pub struct ColorScale(Vec<Hsla>);
 
 impl FromIterator<Hsla> for ColorScale {
@@ -229,6 +219,7 @@ impl IntoIterator for ColorScales {
     }
 }
 
+/// Provides groups of [ColorScale]s for light and dark themes, as well as transparent versions of each scale.
 pub struct ColorScaleSet {
     name: SharedString,
     light: ColorScale,

crates/theme/src/settings.rs

@@ -27,7 +27,7 @@ pub struct ThemeSettings {
 }
 
 #[derive(Default)]
-pub struct AdjustedBufferFontSize(Pixels);
+pub(crate) struct AdjustedBufferFontSize(Pixels);
 
 #[derive(Clone, Debug, Default, Serialize, Deserialize, JsonSchema)]
 pub struct ThemeSettingsContent {

crates/theme/src/styles/colors.rs

@@ -7,6 +7,7 @@ use crate::{PlayerColors, StatusColors, StatusColorsRefinement, SyntaxTheme, Sys
 #[derive(Refineable, Clone, Debug)]
 #[refineable(Debug, serde::Deserialize)]
 pub struct ThemeColors {
+    /// Border color. Used for most borders, is usually a high contrast color.
     pub border: Hsla,
     /// Border color. Used for deemphasized borders, like a visual divider between two sections
     pub border_variant: Hsla,

crates/theme/src/theme.rs

@@ -1,3 +1,11 @@
+//! # Theme
+//!
+//! This crate provides the theme system for Zed.
+//!
+//! ## Overview
+//!
+//! A theme is a collection of colors used to build a consistent appearance for UI components across the application.
+
 mod default_colors;
 mod default_theme;
 mod one_themes;

crates/theme/theme.md

@@ -0,0 +1,15 @@
+ # Theme
+
+ This crate provides the theme system for Zed.
+
+ ## Overview
+
+ A theme is a collection of colors used to build a consistent appearance for UI components across the application.
+ To produce a theme in Zed,
+
+ A theme is made of of two parts: A [ThemeFamily] and one or more [Theme]s.
+
+//
+ A [ThemeFamily] contains metadata like theme name, author, and theme-specific [ColorScales] as well as a series of themes.
+
+ - [ThemeColors] - A set of colors that are used to style the UI. Refer to the [ThemeColors] documentation for more information.