docs: updated the styling ADR to give more MXUI details and added a pr review claude skill

Author: wesrisenmay-mx

.claude/skills/adr-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: adr-review
-description: Review a pull/merge request's new code against the connect-widget Architecture Decision Records (ADRs). Use when asked to "ADR review", "review this PR against the ADRs", "check ADR compliance", or before approving a PR/MR in the connect-widget (GitHub) or the sibling GitLab repo that follows the same standards. Reviews styling (CSS Modules / MUI), testing (Vitest/MSW/Cypress), folder structure (screaming architecture), PR size, and undocumented architecture choices.
+description: Review a pull/merge request's new code against the connect-widget Architecture Decision Records (ADRs). Use when asked to "ADR review", "review this PR against the ADRs", "check ADR compliance", or before approving a PR/MR in the connect-widget (GitHub) or the sibling GitLab repo that follows the same standards. Reviews styling (prefer raw MXUI/MUI, theme variables, CSS Modules), testing (Vitest/MSW/Cypress), folder structure (screaming architecture), PR size, and undocumented architecture choices.
 ---
 
 # ADR Review

.claude/skills/adr-review/reference/adr-checklist.md

@@ -11,10 +11,27 @@ Cite the ADR number in every finding (e.g. `[ADR 0001 Styling]`).
 
 ## ADR 0001 — Styling our HTML
 
-Decision: style with **CSS Modules**; use **MUI `Stack`** for spacing/layout.
+Decision: prefer **raw MXUI/MUI components**; custom styling is rare and must be
+designer-validated; when custom styling is warranted, style with **CSS Modules** and
+use **MUI `Stack`** for spacing/layout.
 
 Check added/changed `.tsx`/`.jsx`/`.css` code:
 
+- **Prefer raw MXUI/MUI components.** Reach for the design system's components as-is
+  before writing any custom styling — they carry the design system's styling by
+  default. Flag new custom-styled elements (CSS Modules, wrappers, overrides) that
+  reimplement something an existing MXUI/MUI component already provides.
+- **Custom styling should be rare and designer-validated.** Custom styling should be
+  the exception, not the norm, and should be validated with a designer before being
+  implemented. If a design doesn't fit the design system, that deviation should be
+  confirmed as intentional with a designer. When a PR adds non-trivial custom styling,
+  flag it (usually "Consider"/"Should fix") with a note to confirm designer sign-off —
+  especially when it visibly deviates from the design system.
+- **Prefer MUI theme variables over hard-coded values.** When a raw component can't be
+  used, prefer MUI theme variables (e.g. `--mui-palette-*` CSS variables, visible in
+  Chrome dev tools' Styles panel on a rendered MXUI component) over hard-coded colors,
+  spacing, and other magic values. Flag hard-coded hex/rgb colors or pixel values that
+  a theme variable would cover.
 - **CSS Modules required.** New stylesheets must be `*.module.css` and imported as a
   module (`import styles from './Foo.module.css'`). Flag new plain `.css`/global CSS
   files, or Tailwind / other global CSS-framework classes, or styled-components.

architectureDecisionRecords/0001Styling.md

@@ -18,7 +18,13 @@ We also need to work with both CSS modules and MXUI. MXUI uses [MUI](https://mui
 
 ## Decision
 
-We will use CSS modules to style our html.
+We should use the raw MXUI and MUI components as much as possible. These components come with the design system's styling baked in, so leaning on them keeps us consistent by default.
+
+Custom styling should be rare. Before implementing custom styling, validate it with a designer. If a design doesn't fit within the confines of the design system, confirm with the designer that the deviation from the design system was intentional.
+
+If we can't use the raw MUI component, then we should use a MUI theme variable when possible. These theme variables can be viewed by looking in Chrome dev tools under the Styles panel where an MXUI component is being rendered.
+
+When custom styling is warranted, we will use CSS modules to style our html.
 
 When we need to add spacing between two elements, we should use a MUI [Stack](https://mui.com/material-ui/react-stack/) with a `spacing` prop.