Expose CSS variables for button and link colors (#177)

## Description

This is an ask from some embed clients. This change is narrowly scoped
to just specific UI elements; I think it's best to keep customization
points limited to concrete use cases, to avoid complexity.

I made new CSS variables for the specific UI elements, to allow
customizing them separately. (There are plausible colors for the
button that look bad when used as the link text color.) Another reason
not to make `color-action-primary` (and other color aliases) into
customization points is to give us the freedom to use them on other
components (or _stop_ using them on existing components) without
worrying about breaking a supposedly-stable public interface.

The submit button and links are the most obvious purple-500
components, but note that there are still some others: the triangle in
the dropdown button, and the icon in the project selector. If needed,
we can allow customizing those (or maybe just make them
non-customizable and go back to grayscale); we'll see what embed
clients say.

### Followup

Once this is landed, document the customizable variables in the readme
and in the embed docs on Zuplo.

## Test Plan

Without overriding any variables, look at the form and results in all
widths; make sure it looks exactly the same as before.

Add some CSS in index.html:

```css
rewiring-america-state-calculator {
  --color-background-button: 0 255 0;
  --color-text-button: 255 255 0;
  --color-text-link: 255 0 255;
}
```

Make sure the submit button is green with yellow text, and the links
(the two in the form, plus the "learn more" links in the incentive
cards, on narrow and wide layouts) are magenta.

README.md

@@ -62,6 +62,30 @@ When the event is dispatched, the form submission or reset has already happened,
 | `calculator-submitted` | The key `formData` contains an object with the form data that was submitted. Possible keys are `zip`, `owner_status`, `household_income`, `household_size`, `tax_filing`, and `projects`. |
 | `calculator-reset`     | None                                                                                                                                                                                      |
 
+### Customizing Colors
+
+The colors of some UI elements can be customized by overriding CSS variables.
+
+Overriding values must be defined on the calculator element. The values must be a color in absolute or relative [CSS `rgb()` syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/rgb), and must not include an alpha value. For example:
+
+```css
+rewiring-america-state-calculator {
+  /* Absolute value syntax */
+  --ra-color-background-button: 195 0 74;
+
+  /* Relative color syntax */
+  --ra-color-text-link: from blue r g b;
+}
+```
+
+| Variable name                  | Usage                                                             |
+| ------------------------------ | ----------------------------------------------------------------- |
+| `--ra-color-background-button` | The background color of the submit button in the calculator form. |
+| `--ra-color-text-button`       | The text color of the submit button in the calculator form.       |
+| `--ra-color-text-link`         | The text color of links throughout the calculator UI.             |
+
+The calculator defines and uses many other CSS variables, but **their existence and behavior are not guaranteed to be stable**; override them at your own risk. Only variables prefixed with `--ra-` are supported customization points.
+
 ## Running / building
 
 ### Run a development server

src/buttons.tsx

@@ -2,18 +2,19 @@ import clsx from 'clsx';
 import { FC, PropsWithChildren } from 'react';
 
 /** A button that looks like a real button; white text on purple. */
-export const PrimaryButton: FC<
-  PropsWithChildren<{ id?: string; onClick?: (e: React.MouseEvent) => void }>
-> = ({ id, children, onClick }) => (
+export const PrimaryButton: FC<PropsWithChildren<{ id?: string }>> = ({
+  id,
+  children,
+}) => (
   <button
     id={id}
     className={clsx(
       'w-full',
       'text-base',
       'leading-7',
       'p-2',
-      'bg-color-action-primary',
-      'text-color-text-primary-on-dark',
+      'bg-ra-color-background-button',
+      'text-ra-color-text-button',
       'rounded',
       'font-semibold',
       'hover:bg-gradient-to-r',
@@ -28,7 +29,6 @@ export const PrimaryButton: FC<
       'focus-visible:from-color-shadow-primary/25 focus-visible:from-0%',
       'focus-visible:via-color-shadow-primary/25 focus-visible:via-100%',
     )}
-    onClick={onClick}
   >
     {children}
   </button>
@@ -39,7 +39,7 @@ export const TextButton: FC<
   PropsWithChildren<{ onClick?: (e: React.MouseEvent) => void }>
 > = ({ children, onClick }) => (
   <button
-    className="text-purple-500 text-base font-medium leading-tight hover:underline"
+    className="text-ra-color-text-link text-base font-medium leading-tight hover:underline"
     onClick={onClick}
   >
     {children}

src/icons.tsx

@@ -135,14 +135,14 @@ export const UpRightArrow: FC<IconProps> = ({ w, h }) => (
   >
     <path
       d="M5.83325 14.1667L14.1666 5.83337"
-      stroke="#4A00C3"
+      stroke="currentColor"
       strokeWidth="1.5"
       strokeLinecap="round"
       strokeLinejoin="round"
     />
     <path
       d="M5.83325 5.83337H14.1666V14.1667"
-      stroke="#4A00C3"
+      stroke="currentColor"
       strokeWidth="1.5"
       strokeLinecap="round"
       strokeLinejoin="round"
@@ -190,21 +190,21 @@ export const ExternalLink: FC<IconProps> = ({ w, h }) => (
   >
     <path
       d="M15 10.8333V15.8333C15 16.2754 14.8244 16.6993 14.5118 17.0118C14.1993 17.3244 13.7754 17.5 13.3333 17.5H4.16667C3.72464 17.5 3.30072 17.3244 2.98816 17.0118C2.67559 16.6993 2.5 16.2754 2.5 15.8333V6.66667C2.5 6.22464 2.67559 5.80072 2.98816 5.48816C3.30072 5.17559 3.72464 5 4.16667 5H9.16667"
-      stroke="#4A00C3"
+      stroke="currentColor"
       strokeWidth="1.5"
       strokeLinecap="round"
       strokeLinejoin="round"
     />
     <path
       d="M12.5 2.5H17.5V7.5"
-      stroke="#4A00C3"
+      stroke="currentColor"
       strokeWidth="1.5"
       strokeLinecap="round"
       strokeLinejoin="round"
     />
     <path
       d="M8.33398 11.6667L17.5007 2.5"
-      stroke="#4A00C3"
+      stroke="currentColor"
       strokeWidth="1.5"
       strokeLinecap="round"
       strokeLinejoin="round"

src/state-calculator.tsx

@@ -238,7 +238,7 @@ const StateCalculator: FC<{
         <div className="text-color-text-secondary text-[0.75rem] leading-tight pb-[0.1875rem]">
           {msg('We’re dedicated to safeguarding your privacy.')}{' '}
           <a
-            className="text-color-action-primary font-medium"
+            className="text-ra-color-text-link font-medium hover:underline"
             target="_blank"
             href="https://content.rewiringamerica.org/view/privacy-policy.pdf"
           >

src/state-incentive-details.tsx

@@ -155,7 +155,7 @@ const BorderedLinkButton: FC<PropsWithChildren<{ href: string }>> = ({
       'border',
       'rounded',
       'border-grey-300',
-      'text-purple-500',
+      'text-ra-color-text-link',
       'text-base',
       'font-medium',
       'leading-tight',
@@ -178,7 +178,7 @@ const BorderlessLinkButton: FC<PropsWithChildren<{ href: string }>> = ({
       'sm:flex',
       'gap-2',
       'items-center',
-      'text-purple-500',
+      'text-ra-color-text-link',
       'text-base',
       'font-medium',
       'leading-tight',

src/tailwind.css

@@ -55,6 +55,12 @@
   --color-text-primary: var(--grey-700);
   --color-text-secondary: var(--grey-400);
   --color-text-tertiary: var(--yellow-800);
+
+  /* SPECIFIC UI ELEMENTS */
+  /* These are documented customization points for embedders */
+  --ra-color-background-button: var(--color-action-primary);
+  --ra-color-text-button: var(--color-text-primary-on-dark);
+  --ra-color-text-link: var(--color-action-primary);
 }
 
 :host {

styleConstants.ts

@@ -49,6 +49,11 @@ export const SUPPORTED_COLORS = [
   'color-text-primary',
   'color-text-secondary',
   'color-text-tertiary',
+  // SPECIFIC UI ELEMENTS
+  // These are documented customization points for embedders
+  'ra-color-background-button',
+  'ra-color-text-button',
+  'ra-color-text-link',
 ];
 
 export type SupportedColorsType = (typeof SUPPORTED_COLORS)[number];