diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 969a1f9e..39197377 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -97,4 +97,11 @@
         * [Infrared](/reference/sensors/infrared)
             * [on event](/reference/sensors/infrared/on-event),
             * [distance](reference/sensors/infrared/proximity),
-            * [pause until](reference/sensors/infrared/pause-until)
\ No newline at end of file
+            * [pause until](reference/sensors/infrared/pause-until)
+        * [Color](/reference/sensors/color-sensor)
+            * [on color detected](/reference/sensors/color-sensor/on-color-detected)
+            * [pause for color](/reference/sensors/color-sensor/pause-for-color)
+            * [on light changed](/reference/sensors/color-sensor/on-light-changed)
+            * [pause for light](/reference/sensors/color-sensor/pause-for-light)
+            * [color](/reference/sensors/color-sensor/color)
+            * [light](/reference/sensors/color-sensor/ambient-light)
\ No newline at end of file
diff --git a/docs/reference/sensors.md b/docs/reference/sensors.md
index 9ff5e53c..cba0e8d2 100644
--- a/docs/reference/sensors.md
+++ b/docs/reference/sensors.md
@@ -1,5 +1,17 @@
 # Sensors
 
+# Color
+
+```cards
+sensors.color1.onColorDetected(ColorSensorColor.Blue, function () {})
+sensors.color1.onLightChanged(LightIntensityMode.Reflected, LightCondition.Dark, function () {})
+sensors.color1.pauseForLight(LightIntensityMode.Reflected, LightCondition.Dark)
+sensors.color1.pauseForColor(ColorSensorColor.Blue)
+sensors.color1.color();
+sensors.color1.light(LightIntensityMode.Ambient)
+sensors.color(ColorSensorColor.Blue)
+```
+
 ## Touch
 
 ```cards
diff --git a/libs/color-sensor/color.ts b/libs/color-sensor/color.ts
index bf78c58a..ddf85f63 100644
--- a/libs/color-sensor/color.ts
+++ b/libs/color-sensor/color.ts
@@ -192,7 +192,7 @@ namespace sensors {
         }
 
         /**
-         * Waits for the given color to be detected
+         * Wait for the given color to be detected
          * @param color the color to detect
          */
         //% help=sensors/color-sensor/pause-for-light
@@ -210,7 +210,7 @@ namespace sensors {
         }
 
         /**
-         * Measures the ambient or reflected light value from 0 (darkest) to 100 (brightest).
+         * Measure the ambient or reflected light value from 0 (darkest) to 100 (brightest).
          * @param sensor the color sensor port
          */
         //% help=sensors/color-sensor/light
@@ -237,7 +237,7 @@ namespace sensors {
         }
 
         /**
-         * Sets a threshold value
+         * Set a threshold value
          * @param condition the dark or bright light condition
          * @param value the value threshold
          */
@@ -253,7 +253,7 @@ namespace sensors {
         }
 
         /**
-         * Gets the threshold value
+         * Get a threshold value
          * @param condition the light condition
          */
         //% blockId=colorGetThreshold block="%sensor|%condition"
@@ -318,6 +318,7 @@ namespace sensors {
     //% blockId=colorSensorColor block="color %color"
     //% group="Color Sensor"
     //% weight=97
+    //% help=sensors/color
     //% color.fieldEditor="gridpicker"
     //% color.fieldOptions.columns=4 
     //% color.fieldOptions.tooltips=true
diff --git a/libs/color-sensor/docs/reference/sensors/color-sensor.md b/libs/color-sensor/docs/reference/sensors/color-sensor.md
index f8298b50..6f17219a 100644
--- a/libs/color-sensor/docs/reference/sensors/color-sensor.md
+++ b/libs/color-sensor/docs/reference/sensors/color-sensor.md
@@ -1,16 +1,19 @@
-# Color Sensor
+# Color sensor
 
 ```cards
-sensors.color1.onColorDetected(ColorSensorColor.Blue, function () {
-})
+sensors.color1.onColorDetected(ColorSensorColor.Blue, function () {})
+sensors.color1.onLightChanged(LightIntensityMode.Reflected, LightCondition.Dark, function () {})
+sensors.color1.pauseForLight(LightIntensityMode.Reflected, LightCondition.Dark)
+sensors.color1.pauseForColor(ColorSensorColor.Blue)
 sensors.color1.color();
-sensors.color1.ambientLight();
-sensors.color1.reflectedLight();
+sensors.color1.light(LightIntensityMode.Ambient)
 ```
 
-## See Also
+## See slso
 
 [on color detected](/reference/sensors/color-sensor/on-color-detected),
+[pause for color](/reference/sensors/color-sensor/pause-for-color),
+[on light changed](/reference/sensors/color-sensor/on-light-changed),
+[pause for light](/reference/sensors/color-sensor/pause-for-light),
 [color](/reference/sensors/color-sensor/color),
-[ambient light](/reference/sensors/color-sensor/ambient-light),
-[reflected light](/reference/sensors/color-sensor/reflected-light),
+[light](/reference/sensors/color-sensor/ambient-light)
diff --git a/libs/color-sensor/docs/reference/sensors/color-sensor/ambient-light.md b/libs/color-sensor/docs/reference/sensors/color-sensor/ambient-light.md
index f416da4e..e69a4e8b 100644
--- a/libs/color-sensor/docs/reference/sensors/color-sensor/ambient-light.md
+++ b/libs/color-sensor/docs/reference/sensors/color-sensor/ambient-light.md
@@ -1,4 +1,20 @@
-# Ambient Light
+# ambient Light
+
+Get the amount of ambient light dectected.
+
+```sig
+sensors.color1.ambientLight()
+```
+
+The amount of ambient light measured is in the range of `0` (darkest) to `100` (brightest).
+
+## Returns
+
+* a [number](/types/number) that is the amount of ambiernt light measured. No light (darkness) is `0` and the brightest light is `100`.
+
+## Example
+
+Make the status light show ``green`` if the ambient light is greater than `20`.
 
 ```blocks
 forever(function () {
@@ -8,4 +24,8 @@ forever(function () {
         brick.setStatusLight(StatusLight.Orange)
     }
 })
-```
\ No newline at end of file
+```
+
+## See also
+
+[reflected light](/reference/sensors/color-sensor/reflected-light)
\ No newline at end of file
diff --git a/libs/color-sensor/docs/reference/sensors/color-sensor/color.md b/libs/color-sensor/docs/reference/sensors/color-sensor/color.md
index 50fe3960..96b4184c 100644
--- a/libs/color-sensor/docs/reference/sensors/color-sensor/color.md
+++ b/libs/color-sensor/docs/reference/sensors/color-sensor/color.md
@@ -1,5 +1,29 @@
 # color
 
+Get the current color detected by the sensor.
+
+```sig
+sensors.color1.color()
+```
+
+The [color](/reference/sensors/color) value returned is one of the colors that the sensor can detect. If you want to use colors for tracking, it's best to use a color that is the same or very close to the ones the sensor detects.
+
+## Returns
+
+* a color value for the current color detected by the color sensor. The colors detected are:
+
+>* ``none``
+>* ``blue``
+>* ``green``
+>* ``yellow``
+>* ``red``
+>* ``white``
+>* ``brown``
+
+## Example
+
+Turn the status light to ``green`` if the color detected by the ``color 1`` sensor is green.
+
 ```blocks
 forever(function () {
     if (sensors.color1.color() == ColorSensorColor.Green) {
@@ -8,4 +32,8 @@ forever(function () {
         brick.setStatusLight(StatusLight.Orange)
     }
 })
-```
\ No newline at end of file
+```
+
+## See also
+
+[color](/reference/sensors/color-sensor/color)
\ No newline at end of file
diff --git a/libs/color-sensor/docs/reference/sensors/color-sensor/light.md b/libs/color-sensor/docs/reference/sensors/color-sensor/light.md
new file mode 100644
index 00000000..57baa37e
--- /dev/null
+++ b/libs/color-sensor/docs/reference/sensors/color-sensor/light.md
@@ -0,0 +1,35 @@
+# light
+
+Get the amount of ambient or reflected light measured by the sensor.
+
+```sig
+sensors.color1.light(LightIntensityMode.Ambient)
+```
+
+The light sensor adjusts itself to more accurately measure light depending on the source of the light. You decide if you want to measure _ambient_ light (light all around or direct light) or if you want to know how much light is reflected from a surface. The amount of light measured is in the range of `0` (darkest) to `100` (brightest).
+
+## Parameters
+
+* **mode**: the type of measurement for light. This is either ``ambient`` or ``reflected`` light.
+
+## Returns
+
+* a number that is the amount of light measured. No light (darkness) is `0` and the brightest light is `100`.
+
+## Example
+
+Make the status light show ``green`` if the ambient light is greater than `20`.
+
+```blocks
+forever(function () {
+    if (sensors.color1.light(LightIntensityMode.Ambient) > 20) {
+        brick.setStatusLight(StatusLight.Green)
+    } else {
+        brick.setStatusLight(StatusLight.Orange)
+    }
+})
+```
+
+## See also
+
+[reflected light](/reference/sensors/color-sensor/reflected-light)
\ No newline at end of file
diff --git a/libs/color-sensor/docs/reference/sensors/color-sensor/on-color-detected.md b/libs/color-sensor/docs/reference/sensors/color-sensor/on-color-detected.md
index 4ded99f4..397d1307 100644
--- a/libs/color-sensor/docs/reference/sensors/color-sensor/on-color-detected.md
+++ b/libs/color-sensor/docs/reference/sensors/color-sensor/on-color-detected.md
@@ -1,16 +1,27 @@
-# On Color Detected
+# on Color Detected
+
+Run some code when the color you want to watch for is detected.
 
 ```sig
 sensors.color1.onColorDetected(ColorSensorColor.Blue, function () { })
 ```
 
-# Parameters
+The [color](/reference/sensors/color) you choose to look for is one of the colors that the sensor can detect. If you want to use colors for tracking, it's best to use a color that is the same or very close to the ones the sensor detects.
 
-## Examples
+## Parameters
 
+* **color**: the [color](/reference/sensors/color) to watch for.
+* **handler**: the code you want to run when the color is detected.
+
+## Example
+
+Show an expression on the screen when the color sensor ``color 1`` sees ``blue``.
 
 ```blocks
 sensors.color1.onColorDetected(ColorSensorColor.Blue, function () {
     brick.showImage(images.expressionsSick)
 })
 ```
+## See also
+
+[pause for color](/reference/sensors/color-sensor/pause-for-color), [color](/reference/sensors/color)
\ No newline at end of file
diff --git a/libs/color-sensor/docs/reference/sensors/color-sensor/on-light-changed.md b/libs/color-sensor/docs/reference/sensors/color-sensor/on-light-changed.md
new file mode 100644
index 00000000..c144ab49
--- /dev/null
+++ b/libs/color-sensor/docs/reference/sensors/color-sensor/on-light-changed.md
@@ -0,0 +1,33 @@
+# on Light Changed
+
+Run some code when the amount of light dectected changes.
+
+```sig
+sensors.color1.onLightChanged(LightIntensityMode.Reflected, LightCondition.Dark, function () {
+
+})
+```
+
+You can check for a change in either _ambient_ or _reflected_ light and run some code when it happens. This event happens when the sensor detects light going to ``dark`` or to ``bright``. You choose what condition you will run your code for.
+
+## Parameters
+
+* **mode**: lighting mode to use for detection. This is for either ``ambient`` or ``reflected`` light.
+* **condition**: the condition that the light changed to: ``dark`` or ``bright``.
+* **handler**: the code you want to run when the light changes.
+
+## Example
+
+Show a message on the screen when the ambient light goes dark.
+
+```blocks
+sensors.color1.onLightChanged(LightIntensityMode.Ambient, LightCondition.Dark, function() {
+    brick.clearScreen();
+    brick.showString("It just got dark", 1)
+    brick.showString("Can you see me?", 2)
+})
+```
+
+## See also
+
+[light](/reference/sensors/color-sensor/light), [on color detected](/reference/sensors/color-sensor/on-color-detected)
\ No newline at end of file
diff --git a/libs/color-sensor/docs/reference/sensors/color-sensor/pause-for-color.md b/libs/color-sensor/docs/reference/sensors/color-sensor/pause-for-color.md
new file mode 100644
index 00000000..0ccdb2d5
--- /dev/null
+++ b/libs/color-sensor/docs/reference/sensors/color-sensor/pause-for-color.md
@@ -0,0 +1,28 @@
+# pause For Color
+
+Wait for the sensor to see a certain color.
+
+```sig
+sensors.color1.pauseForColor(ColorSensorColor.Blue)
+```
+
+The [color](/reference/sensors/color) you choose to look for is one of the colors that the sensor can detect. If you want to use colors for tracking, it's best to use a color that is the same or very close to the ones the sensor detects.
+
+## Parameters
+
+* **color**: the [color](/reference/sensors/color) to watch for.
+
+## Example
+
+Wait for the sensor to see ``blue``. Then, show an expression on the screen.
+
+```blocks
+brick.showString("Waiting for blue", 1)
+sensors.color1.pauseForColor(ColorSensorColor.Blue)
+brick.clearScreen()
+brick.showImage(images.expressionsSick)
+```
+
+## See also
+
+[on color detected](/reference/sensors/color-sensor/on-color-detected), [color](/reference/sensors/color)
\ No newline at end of file
diff --git a/libs/color-sensor/docs/reference/sensors/color-sensor/pause-for-light.md b/libs/color-sensor/docs/reference/sensors/color-sensor/pause-for-light.md
new file mode 100644
index 00000000..55f51eae
--- /dev/null
+++ b/libs/color-sensor/docs/reference/sensors/color-sensor/pause-for-light.md
@@ -0,0 +1,29 @@
+# pause For Light
+
+Wait for the light condition to change.
+
+```sig
+sensors.color1.pauseForLight(LightIntensityMode.Reflected, LightCondition.Dark)
+```
+
+You can wait for a change in either _ambient_ or _reflected_ light. This event happens when the sensor detects light going to ``dark`` or to ``bright``. You choose what condition you will wait for.
+
+## Parameters
+
+* **mode**: lighting mode to use for detection. This is for either ``ambient`` or ``reflected`` light.
+* **condition**: the condition that the light changed to: ``dark`` or ``bright``.
+
+## Example
+
+Wait for the ambient light to go dark, then show an expression on the screen.
+
+```blocks
+brick.showString("Waiting for dark", 1)
+sensors.color1.pauseForLight(LightIntensityMode.Reflected, LightCondition.Dark)
+brick.clearScreen()
+brick.showImage(images.expressionsSick)
+```
+
+## See also
+
+[on light changed](/reference/sensors/color-sensor/on-light-changed)
\ No newline at end of file
diff --git a/libs/color-sensor/docs/reference/sensors/color-sensor/reflected-light.md b/libs/color-sensor/docs/reference/sensors/color-sensor/reflected-light.md
index 5a7eee36..d93b4595 100644
--- a/libs/color-sensor/docs/reference/sensors/color-sensor/reflected-light.md
+++ b/libs/color-sensor/docs/reference/sensors/color-sensor/reflected-light.md
@@ -1,4 +1,20 @@
-# Reflected Light
+# reflected Light
+
+Get the amount of reflected light dectected.
+
+```sig
+sensors.color1.reflectedLight()
+```
+
+The amount of reflected light measured is in the range of `0` (darkest) to `100` (brightest).
+
+## Returns
+
+* a [number](/types/number) that is the amount of ambiernt light measured. No light (darkness) is `0` and the brightest light is `100`.
+
+## Example
+
+Make the status light show ``green`` if the reflected light is greater than `20`.
 
 ```blocks
 forever(function () {
@@ -8,4 +24,8 @@ forever(function () {
         brick.setStatusLight(StatusLight.Orange)
     }
 })
-```
\ No newline at end of file
+```
+
+## See also
+
+[ambient light](/reference/sensors/color-sensor/ambient-light)
\ No newline at end of file
diff --git a/libs/color-sensor/docs/reference/sensors/color.md b/libs/color-sensor/docs/reference/sensors/color.md
new file mode 100644
index 00000000..576c27dd
--- /dev/null
+++ b/libs/color-sensor/docs/reference/sensors/color.md
@@ -0,0 +1,57 @@
+# color
+
+Get a color that the sensor can detect that is close to the color you asked for.
+
+```sig
+sensors.color(ColorSensorColor.Blue)
+```
+
+Since the color sensor can accurately detect some basic colors, you can't just tell it to look for any color. The sensor may recoginze some color component of the color you ask for. So, you can get a simple color that matches some of your color and tell the sensor to look for that.
+
+## Parameters
+
+* **color**: a color to match with a detectable color. The colors to choose from are:
+
+>* ``none``
+>* ``blue``
+>* ``green``
+>* ``yellow``
+>* ``red``
+>* ``white``
+>* ``brown``
+
+## Returns
+
+* a color value that the color sensor can detect. The detectable colors are:
+
+>* ``none``
+>* ``blue``
+>* ``green``
+>* ``yellow``
+>* ``red``
+>* ``white``
+>* ``brown``
+
+## ~hint
+
+Currently, the colors you can ask for (input colors) and the colors returned are the same.
+
+## ~
+
+## Example
+
+Turn the status light to ``green`` if the color detected by the ``color 1`` sensor is green.
+
+```blocks
+forever(function () {
+    if (sensors.color1.color() == sensors.color(ColorSensorColor.Green)) {
+        brick.setStatusLight(StatusLight.Green)
+    } else {
+        brick.setStatusLight(StatusLight.Orange)
+    }
+})
+```
+
+## See also
+
+[color](/reference/sensors/color-sensor/color)
\ No newline at end of file