address issues

Signed-off-by: Kawika Avilla <kavilla414@gmail.com>

packages/osd-stylelint-config/README.md

@@ -1,6 +1,11 @@
 # osd-stylelint-config
 
-The Stylelint config used by OpenSearch Dashboards
+The Stylelint config used by OpenSearch Dashboards. This package is created to enable the modification of rules with the JSON files in `config/` and any consumer of the `@osd/stylelint-plugin-stylelint` can just extend this config within its `.stylelintrc`.
+
+The ideal state being that this package is maintained externally from the OpenSearch Dashboards repo so that the configs can be modified with rules without being blocked by processes within OpenSearch Dashboards.
+
+Issue:
+https://github.com/opensearch-project/oui/issues/845
 
 ## Usage
 
@@ -14,3 +19,27 @@ in your `.stylelintrc`:
   ]
 }
 ```
+
+This JSON configs that are sent through the compliance engine are expected to follow the schema:
+
+```json
+{
+  "cssProperty": {
+    "regexOfSelector": [
+      {
+        "approved": "OUICompliantValue1",
+        "rejected": [
+          "OUIViolationValue1",
+          "OUIViolationValue2",
+        ]
+      },
+      {
+        "approved": "OUICompliantValue2",
+        "rejected": [
+          "OUIViolationValue3"
+        ]
+      }
+    ]
+  }
+}
+```

packages/osd-stylelint-config/config/colors.json

@@ -1,18 +1,18 @@
 {
   "background-color": {
-    "button": [
+    "buttonTODOTHISANEXAMPLE": [
       {
         "approved": "$euiColorPrimary",
         "rejected": [
-          "blue"
+          "blueTODOTHISANEXAMPLE"
         ]
       },
       {
         "approved": "$euiColorWarning",
         "rejected": [
-          "red"
+          "redTODOTHISANEXAMPLE"
         ]
       }
     ]
   }
-}
+}

packages/osd-stylelint-plugin-stylelint/README.md

@@ -1,3 +1,18 @@
 # Custom Stylelint rules for OpenSearch Dashboards
 
-This package contains custom Stylelint rules used for OpenSearch Dashboards development.
+This package contains custom Stylelint rules used for OpenSearch Dashboards development. Rules are defined in `src/rules` and are the actual logic of the custom rules which are built around parsing a JSON config file passed in and applying the rules defined within there.
+
+This package can work with `@osd/stylelint-config` which houses the JSON config files to be passed into this plugin. The goal being to seperate out OUI compliance rules which can be modified by anyone versus the actual OUI compliance engine which should be only modified by developers.
+
+## Audit styles that are related to custom rules
+
+Setting: 
+```
+export OUI_AUDIT_ENABLED=true
+```
+
+Enables the ability to capture styling that potentially can be subject to compliance when there is a rule that interacts with the styling.
+
+For example, if a style attempts to set a button to have a `background-color: $incorrectVariable()` and the JSON config passed to the compliance engine does not explicitly reject the `$incorrectVariable()` being applied to a button's background color then the linter will pass. But it will output this if the environment variable is set to `true`.
+
+The goal being that setting this environment variable to output a list that can then be added to the JSON config which we can feed back into the compliance engine.

packages/osd-stylelint-plugin-stylelint/src/utils/is_color_property.ts

@@ -48,6 +48,13 @@ const COLOR_PROPERTIES = [
   'mask-border-source',
 ];
 
+/**
+ * This is intended to check a list of defined properties
+ * within a style and see if it's potentially modifying a property
+ * that can have a color. Stylelint crawls styles and will check
+ * each one, therefore this is to optimize the linter to
+ * skip any property that does not impact colors.
+ */
 export const isColorProperty = (prop: string) => {
   return COLOR_PROPERTIES.includes(prop);
 };