diff --git a/schemas/color-theme/v1.json b/schemas/color-theme/v1.json
index c9b8109..c01942f 100644
--- a/schemas/color-theme/v1.json
+++ b/schemas/color-theme/v1.json
@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema",
-  "$id": "https://gitea.jbrumond.me/minimal/docs/raw/branch/master/schemas/color-theme.json",
+  "$id": "https://gitea.jbrumond.me/minimal/docs/raw/branch/master/schemas/color-theme/v1.json",
   "type": "object",
   "properties": {
     "name": {
@@ -13,21 +13,23 @@
       "properties": {
         "sun": {
           "$ref": "#/definitions/css_color",
-          "description": "The color of the sun icon used to indicate that the light color theme is active"
+          "description": "The color of the sun icon used to indicate that the light color theme is active. Must have\ngood contrast against bg_main\n"
         },
         "moon": {
           "$ref": "#/definitions/css_color",
-          "description": "The color of the moon icon used to indicate that the dark color theme is active"
+          "description": "The color of the moon icon used to indicate that the dark color theme is active. Must have\ngood contrast against bg_main\n"
         },
         "bg_main": {
           "$ref": "#/definitions/css_color",
-          "description": "The primary background color applied to the page as a whole"
+          "description": "The primary background color applied to the page as a whole. Must have good contrast against\nthe main copy text colors text_heading, text_body, text_light, text_link, text_link_active,\nand text_link_visited\n"
         },
         "bg_light": {
-          "$ref": "#/definitions/css_color"
+          "$ref": "#/definitions/css_color",
+          "description": "A lighter background color applied to content panels; Should have a relatively low contrast against\nthe bg_main color, providing only a light accent. Must have good contrast against the main copy text\ncolors text_heading, text_body, text_light, text_link, text_link_active, and text_link_visited\n"
         },
         "bg_heavy": {
-          "$ref": "#/definitions/css_color"
+          "$ref": "#/definitions/css_color",
+          "description": "A heavier background color applied to content panels; Should have a relatively higher contrast against\nthe bg_main color, directing attention to what is \"important\" or \"primary\" content inside of it. Must\nhave good contrast against the main copy text colors text_heading, text_body, text_light, text_link,\ntext_link_active, and text_link_visited\n"
         },
         "bg_popup_mask": {
           "$ref": "#/definitions/css_color"
@@ -59,34 +61,44 @@
           "description": "The color of hyperlinks that have been previously visited"
         },
         "text_highlight": {
-          "$ref": "#/definitions/css_color"
+          "$ref": "#/definitions/css_color",
+          "description": "The color of text highlighted using the <mark>text</mark> tag (or by using ==text==\nin markdown)\n"
         },
         "bg_text_highlight": {
-          "$ref": "#/definitions/css_color"
+          "$ref": "#/definitions/css_color",
+          "description": "The background color of text highlighted using the <mark>text</mark> tag (or by using\n==text== in markdown)\n"
         },
         "text_selection": {
-          "$ref": "#/definitions/css_color"
+          "$ref": "#/definitions/css_color",
+          "description": "The color of text that has been selected by the user"
         },
         "bg_text_selection": {
-          "$ref": "#/definitions/css_color"
+          "$ref": "#/definitions/css_color",
+          "description": "The background color of text that has been selected by the user"
         },
         "bg_button_primary": {
-          "$ref": "#/definitions/css_color"
+          "$ref": "#/definitions/css_color",
+          "description": "The background color of \"primary\" buttons (typically major, positive actions, like \"save\"\nor \"publish\")\n"
         },
         "bg_button_primary_hover": {
-          "$ref": "#/definitions/css_color"
+          "$ref": "#/definitions/css_color",
+          "description": "The background color of \"primary\" buttons (typically major, positive actions, like \"save\"\nor \"publish\") while the user is hovering over them\n"
         },
         "text_button_primary": {
-          "$ref": "#/definitions/css_color"
+          "$ref": "#/definitions/css_color",
+          "description": "The text color of \"primary\" buttons (typically major, positive actions, like \"save\" or \"publish\")\n"
         },
         "bg_button_secondary": {
-          "$ref": "#/definitions/css_color"
+          "$ref": "#/definitions/css_color",
+          "description": "The background color of \"secondary\" buttons (typically safe, unimpactful, or backward moving\nactions, like \"cancel\" or \"preview\")\n"
         },
         "bg_button_secondary_hover": {
-          "$ref": "#/definitions/css_color"
+          "$ref": "#/definitions/css_color",
+          "description": "The background color of \"secondary\" buttons (typically safe, unimpactful, or backward moving\nactions, like \"cancel\" or \"preview\") while the user is hovering over them\n"
         },
         "text_button_secondary": {
-          "$ref": "#/definitions/css_color"
+          "$ref": "#/definitions/css_color",
+          "description": "The text color of \"secondary\" buttons (typically safe, unimpactful, or backward moving actions,\nlike \"cancel\" or \"preview\")\n"
         },
         "bg_error_box": {
           "$ref": "#/definitions/css_color"
diff --git a/schemas/color-theme/v1.yaml b/schemas/color-theme/v1.yaml
index 171323e..8f25df7 100644
--- a/schemas/color-theme/v1.yaml
+++ b/schemas/color-theme/v1.yaml
@@ -1,5 +1,5 @@
 $schema: http://json-schema.org/draft-07/schema
-$id: https://gitea.jbrumond.me/minimal/docs/raw/branch/master/schemas/color-theme.json
+$id: https://gitea.jbrumond.me/minimal/docs/raw/branch/master/schemas/color-theme/v1.json
 type: object
 properties:
   name:
@@ -16,25 +16,43 @@ properties:
       # Theme Picker Icon Colors
       sun:
         $ref: "#/definitions/css_color"
-        description: The color of the sun icon used to indicate that the light color theme is active
+        description: |
+          The color of the sun icon used to indicate that the light color theme is active. Must have
+          good contrast against bg_main
       moon:
         $ref: "#/definitions/css_color"
-        description: The color of the moon icon used to indicate that the dark color theme is active
+        description: |
+          The color of the moon icon used to indicate that the dark color theme is active. Must have
+          good contrast against bg_main
 
       # Content Background Colors
       bg_main:
         $ref: "#/definitions/css_color"
-        description: The primary background color applied to the page as a whole
+        description: |
+          The primary background color applied to the page as a whole. Must have good contrast against
+          the main copy text colors text_heading, text_body, text_light, text_link, text_link_active,
+          and text_link_visited
       bg_light:
         $ref: "#/definitions/css_color"
+        description: |
+          A lighter background color applied to content panels; Should have a relatively low contrast against
+          the bg_main color, providing only a light accent. Must have good contrast against the main copy text
+          colors text_heading, text_body, text_light, text_link, text_link_active, and text_link_visited
       bg_heavy:
         $ref: "#/definitions/css_color"
+        description: |
+          A heavier background color applied to content panels; Should have a relatively higher contrast against
+          the bg_main color, directing attention to what is "important" or "primary" content inside of it. Must
+          have good contrast against the main copy text colors text_heading, text_body, text_light, text_link,
+          text_link_active, and text_link_visited
       bg_popup_mask:
         $ref: "#/definitions/css_color"
+        # todo: description
 
       # 
       line:
         $ref: "#/definitions/css_color"
+        # todo: description
 
       # Main Content Text Colors
       text_heading:
@@ -45,6 +63,7 @@ properties:
         description: The color of main / normal body copy text
       text_light:
         $ref: "#/definitions/css_color"
+        # todo: description
       text_link:
         $ref: "#/definitions/css_color"
         description: The default color of hyperlinks
@@ -58,128 +77,198 @@ properties:
       # Text Highlighted with <mark>
       text_highlight:
         $ref: "#/definitions/css_color"
+        description: |
+          The color of text highlighted using the <mark>text</mark> tag (or by using ==text==
+          in markdown)
       bg_text_highlight:
         $ref: "#/definitions/css_color"
+        description: |
+          The background color of text highlighted using the <mark>text</mark> tag (or by using
+          ==text== in markdown)
 
       # User-Selected Text
       text_selection:
         $ref: "#/definitions/css_color"
+        description: The color of text that has been selected by the user
       bg_text_selection:
         $ref: "#/definitions/css_color"
+        description: The background color of text that has been selected by the user
 
       # Buttons
       bg_button_primary:
         $ref: "#/definitions/css_color"
+        description: |
+          The background color of "primary" buttons (typically major, positive actions, like "save"
+          or "publish")
       bg_button_primary_hover:
         $ref: "#/definitions/css_color"
+        description: |
+          The background color of "primary" buttons (typically major, positive actions, like "save"
+          or "publish") while the user is hovering over them
       text_button_primary:
         $ref: "#/definitions/css_color"
+        description: |
+          The text color of "primary" buttons (typically major, positive actions, like "save" or "publish")
       bg_button_secondary:
         $ref: "#/definitions/css_color"
+        description: |
+          The background color of "secondary" buttons (typically safe, unimpactful, or backward moving
+          actions, like "cancel" or "preview")
       bg_button_secondary_hover:
         $ref: "#/definitions/css_color"
+        description: |
+          The background color of "secondary" buttons (typically safe, unimpactful, or backward moving
+          actions, like "cancel" or "preview") while the user is hovering over them
       text_button_secondary:
         $ref: "#/definitions/css_color"
+        description: |
+          The text color of "secondary" buttons (typically safe, unimpactful, or backward moving actions,
+          like "cancel" or "preview")
 
       # Error Boxes / Alerts
       bg_error_box:
         $ref: "#/definitions/css_color"
+        # todo: description
       border_error_box:
         $ref: "#/definitions/css_color"
+        # todo: description
       text_error_box:
         $ref: "#/definitions/css_color"
+        # todo: description
 
       # Inputs / Forms
       bg_input:
         $ref: "#/definitions/css_color"
+        # todo: description
       border_input:
         $ref: "#/definitions/css_color"
+        # todo: description
       border_input_invalid:
         $ref: "#/definitions/css_color"
+        # todo: description
 
       # Activity / Result Indicators
       icon_active_indicator:
         $ref: "#/definitions/css_color"
+        # todo: description
       icon_success_indicator:
         $ref: "#/definitions/css_color"
+        # todo: description
       icon_failure_indicator:
         $ref: "#/definitions/css_color"
+        # todo: description
       icon_warning_indicator:
         $ref: "#/definitions/css_color"
+        # todo: description
 
       # Charts
       chart_axis:
         $ref: "#/definitions/css_color"
+        # todo: description
       chart_text:
         $ref: "#/definitions/css_color"
+        # todo: description
       chart_guideline:
         $ref: "#/definitions/css_color"
+        # todo: description
       chart_data_0:
         $ref: "#/definitions/css_color"
+        # todo: description
       chart_data_1:
         $ref: "#/definitions/css_color"
+        # todo: description
       chart_data_2:
         $ref: "#/definitions/css_color"
+        # todo: description
       chart_data_3:
         $ref: "#/definitions/css_color"
+        # todo: description
       chart_data_4:
         $ref: "#/definitions/css_color"
+        # todo: description
       chart_data_5:
         $ref: "#/definitions/css_color"
+        # todo: description
       chart_data_6:
         $ref: "#/definitions/css_color"
+        # todo: description
       chart_data_7:
         $ref: "#/definitions/css_color"
+        # todo: description
       chart_data_8:
         $ref: "#/definitions/css_color"
+        # todo: description
       chart_data_9:
         $ref: "#/definitions/css_color"
+        # todo: description
 
       # Pre-Formatted / Syntax Highlighted Code Blocks
       code_normal:
         $ref: "#/definitions/css_color"
+        # todo: description
       code_shadow:
         $ref: "#/definitions/css_color"
+        # todo: description
       code_background:
         $ref: "#/definitions/css_color"
+        # todo: description
       code_selection:
         $ref: "#/definitions/css_color"
+        # todo: description
       code_comment:
         $ref: "#/definitions/css_color"
+        # todo: description
       code_punc:
         $ref: "#/definitions/css_color"
+        # todo: description
       code_operator:
         $ref: "#/definitions/css_color"
+        # todo: description
       code_const_literal:
         $ref: "#/definitions/css_color"
+        # todo: description
       code_number_literal:
         $ref: "#/definitions/css_color"
+        # todo: description
       code_boolean_literal:
         $ref: "#/definitions/css_color"
+        # todo: description
       code_tag:
         $ref: "#/definitions/css_color"
+        # todo: description
       code_string:
         $ref: "#/definitions/css_color"
+        # todo: description
       code_keyword:
         $ref: "#/definitions/css_color"
+        # todo: description
       code_func_name:
         $ref: "#/definitions/css_color"
+        # todo: description
       code_class_name:
         $ref: "#/definitions/css_color"
+        # todo: description
       code_regex_important:
         $ref: "#/definitions/css_color"
+        # todo: description
       code_variable:
         $ref: "#/definitions/css_color"
+        # todo: description
       code_builtin:
         $ref: "#/definitions/css_color"
+        # todo: description
       code_attr_name:
         $ref: "#/definitions/css_color"
+        # todo: description
       code_gutter_divider:
         $ref: "#/definitions/css_color"
+        # todo: description
       code_line_number:
         $ref: "#/definitions/css_color"
+        # todo: description
       code_line_highlight:
         $ref: "#/definitions/css_color"
+        # todo: description
 definitions:
   css_color:
     oneOf:
@@ -203,6 +292,7 @@ definitions:
         pattern: ^(rgba\(\s*([0-9]{1,3})\s*,\s*([0-9]{1,3})\s*,\s*([0-9]{1,3})\s*,\s*([01]|[01]?\.[0-9]{1,3})\s*\))$
         examples:
           - rgba(10, 70, 130, 0.5)
+      # todo: other color function formats, like hsl
       # transparent
       - type: string
         const: transparent