refactor(readablecolor): update docs and function signature

Updated readableColor docs and function signature to be clearer on the purpose of each param and
when to use them.

re #555

Author: bhough

package.json

@@ -1,6 +1,6 @@
 {
   "name": "polished",
-  "version": "4.0.4",
+  "version": "4.0.5",
   "description": "A lightweight toolset for writing styles in Javascript.",
   "license": "MIT",
   "author": "Brian Hough <[email protected]> (https://polished.js.org)",

src/color/readableColor.js

@@ -2,11 +2,11 @@
 import getContrast from './getContrast'
 import getLuminance from './getLuminance'
 
-const defaultLightReturnColor = '#000'
-const defaultDarkReturnColor = '#fff'
+const defaultReturnIfLightColor = '#000'
+const defaultReturnIfDarkColor = '#fff'
 
 /**
- * Returns black or white (or optional light and dark return colors) for best
+ * Returns black or white (or optional passed colors) for best
  * contrast depending on the luminosity of the given color.
  * When passing custom return colors, strict mode ensures that the
  * return color always meets or exceeds WCAG level AA or greater. If this test
@@ -42,15 +42,15 @@ const defaultDarkReturnColor = '#fff'
  */
 export default function readableColor(
   color: string,
-  lightReturnColor?: string = defaultLightReturnColor,
-  darkReturnColor?: string = defaultDarkReturnColor,
+  returnIfLightColor?: string = defaultReturnIfLightColor,
+  returnIfDarkColor?: string = defaultReturnIfDarkColor,
   strict?: boolean = true,
 ): string {
-  const isLightColor = getLuminance(color) > 0.179
-  const preferredReturnColor = isLightColor ? lightReturnColor : darkReturnColor
+  const isColorLight = getLuminance(color) > 0.179
+  const preferredReturnColor = isColorLight ? returnIfLightColor : returnIfDarkColor
 
   if (!strict || getContrast(color, preferredReturnColor) >= 4.5) {
     return preferredReturnColor
   }
-  return isLightColor ? defaultLightReturnColor : defaultDarkReturnColor
+  return isColorLight ? defaultReturnIfLightColor : defaultReturnIfDarkColor
 }

src/color/test/readableColor.test.js

@@ -10,11 +10,11 @@ describe('readableColor', () => {
     expect(readableColor('#000')).toEqual('#fff')
   })
 
-  it('should return custom light background when passed dark color', () => {
+  it('should return custom light color when passed a dark color', () => {
     expect(readableColor('black', '#001', '#ff8')).toEqual('#ff8')
   })
 
-  it('should return custom dark background when passed light color', () => {
+  it('should return custom dark color when passed a light color', () => {
     expect(readableColor('white', '#001', '#ff8')).toEqual('#001')
   })