docs: add website app surveys custom css guide

Co-authored-by: Johannes <jobenjada@users.noreply.github.com>

docs/docs.json

@@ -118,6 +118,7 @@
                   "xm-and-surveys/surveys/website-app-surveys/workspace-id-migration",
                   "xm-and-surveys/surveys/website-app-surveys/framework-guides",
                   "xm-and-surveys/surveys/website-app-surveys/google-tag-manager",
+                  "xm-and-surveys/surveys/website-app-surveys/custom-css",
                   {
                     "group": "Features",
                     "icon": "wrench",

docs/xm-and-surveys/surveys/website-app-surveys/custom-css.mdx

@@ -0,0 +1,103 @@
+---
+title: "Custom CSS"
+description: "Use scoped global CSS to customize Website & App Surveys without breaking your app styles."
+icon: "palette"
+---
+
+Yes, custom CSS for Website & App Surveys is supported.
+
+Use this when the Styling UI is not enough and you need tighter brand control.
+
+<Note>
+  Start with the built-in [Styling Theme](/xm-and-surveys/core-features/styling-theme) first. Use custom CSS only for advanced overrides.
+</Note>
+
+## Problem
+
+Website & App Surveys are rendered inside your product, so your app's global CSS can compete with survey styles.
+
+Common examples:
+
+- A global rule like `button { ... !important; }` changes survey buttons.
+- Typography resets change survey text spacing and sizing.
+- Utility-heavy global styles create unexpected visual differences between pages.
+
+## Solution
+
+Scope your overrides to the survey root (`#fbjs`) and use `!important` for the exact targets you want to control.
+
+This gives you two important guarantees:
+
+1. Your custom rules apply only to the survey.
+2. Your rules reliably win against conflicting global styles.
+
+## Add Scoped Overrides In Global CSS
+
+<Steps>
+  <Step title="Open your global stylesheet">
+    Use the stylesheet that is loaded on pages where surveys are shown (for example `globals.css`).
+  </Step>
+  <Step title="Add scoped rules under #fbjs">
+    Keep all custom rules prefixed with `#fbjs`.
+  </Step>
+  <Step title="Use !important only where needed">
+    Add `!important` to properties that are still being overridden by your app-wide CSS.
+  </Step>
+</Steps>
+
+```css globals.css
+/* 1) Theme-level variables */
+#fbjs {
+  --fb-brand-color: #0ea5e9 !important;
+  --fb-brand-text-color: #ffffff !important;
+  --fb-heading-color: #0f172a !important;
+  --fb-subheading-color: #334155 !important;
+  --fb-survey-background-color: #ffffff !important;
+  --fb-border-radius: 12px !important;
+}
+
+/* 2) Targeted component overrides */
+#fbjs .button-custom,
+#fbjs button.button-custom {
+  border: 1px solid #0284c7 !important;
+  box-shadow: none !important;
+}
+
+#fbjs .label-headline,
+#fbjs .label-headline * {
+  font-size: 1.125rem !important;
+  font-weight: 700 !important;
+}
+
+#fbjs .bg-input-bg,
+#fbjs .border-input-border,
+#fbjs .text-input-text {
+  background: #f8fafc !important;
+  border-color: #cbd5e1 !important;
+  color: #0f172a !important;
+}
+```
+
+<Info>
+  Internal Tailwind utility classes are implementation details and may change over time. Prefer CSS variables and stable survey selectors scoped under `#fbjs`.
+</Info>
+
+## Best Practices
+
+- Keep all survey overrides in one section or file for easier maintenance.
+- Avoid global selectors without `#fbjs` (for example `button`, `input`, `p`) when styling surveys.
+- Document why each `!important` exists so future cleanup is easy.
+- After changes, hard refresh your page to clear cached SDK assets.
+
+## Troubleshooting
+
+**My app styles still win over survey styles**
+
+- Increase selector specificity under `#fbjs`.
+- Add `!important` only on the conflicting property.
+- Check the browser inspector to confirm which rule is winning.
+
+**Survey styles are affecting the rest of my app**
+
+- This usually means a selector is missing `#fbjs`.
+- Prefix every rule with `#fbjs` to keep styles isolated.