Add onboarding modal

frontend/app/src/screens/BorrowScreen/BorrowScreen.tsx

@@ -11,6 +11,8 @@ import { InterestRateField } from "@/src/comps/InterestRateField/InterestRateFie
 import { LinkTextButton } from "@/src/comps/LinkTextButton/LinkTextButton";
 import { RedemptionInfo } from "@/src/comps/RedemptionInfo/RedemptionInfo";
 import { Screen } from "@/src/comps/Screen/Screen";
+import { useStoredState } from "@/src/services/StoredState";
+import { FirstTimeOnboardingModal } from "./FirstTimeOnboardingModal";
 import { WarningBox } from "@/src/comps/WarningBox/WarningBox";
 import { DEBT_SUGGESTIONS, ETH_MAX_RESERVE, MAX_COLLATERAL_DEPOSITS, MIN_DEBT } from "@/src/constants";
 import content from "@/src/content";
@@ -91,6 +93,16 @@ export function BorrowScreen() {
   const [interestRateDelegate, setInterestRateDelegate] = useState<Address | null>(null);
   const [agreeToLiquidationRisk, setAgreeToLiquidationRisk] = useState(false);
 
+  // First-time user onboarding modal
+  const { onboardingDismissed, setState: setStoredState } = useStoredState();
+  const [onboardingClosed, setOnboardingClosed] = useState(false);
+  const showOnboarding = !onboardingDismissed && !onboardingClosed;
+
+  const handleOnboardingClose = () => {
+    setOnboardingClosed(true);
+    setStoredState({ onboardingDismissed: true });
+  };
+
   const agreeCheckboxId = useId();
 
   const setInterestRateRounded = useCallback((averageInterestRate: Dnum, setValue: (value: string) => void) => {
@@ -224,19 +236,24 @@ export function BorrowScreen() {
     && !insufficientColl;
 
   return (
-    <Screen
-      heading={{
-        title: (
-          <div
-            className={css({
-              display: "flex",
-              alignItems: "center",
-              justifyContent: "center",
-              flexFlow: "wrap",
-              gap: "0 8px",
-            })}
-          >
-            {content.borrowScreen.headline(
+    <>
+      <FirstTimeOnboardingModal
+        visible={showOnboarding}
+        onClose={handleOnboardingClose}
+      />
+      <Screen
+        heading={{
+          title: (
+            <div
+              className={css({
+                display: "flex",
+                alignItems: "center",
+                justifyContent: "center",
+                flexFlow: "wrap",
+                gap: "0 8px",
+              })}
+            >
+              {content.borrowScreen.headline(
               <div
                 className={css({
                   display: "flex",
@@ -603,5 +620,6 @@ export function BorrowScreen() {
           : undefined}
       />
     </Screen>
+    </>
   );
 }

frontend/app/src/screens/BorrowScreen/FirstTimeOnboardingModal.tsx

@@ -0,0 +1,141 @@
+import { WHITE_LABEL_CONFIG } from "@/src/white-label.config";
+import { css } from "@/styled-system/css";
+import { Button, Modal } from "@liquity2/uikit";
+
+export function FirstTimeOnboardingModal({
+  onClose,
+  visible,
+}: {
+  onClose: () => void;
+  visible: boolean;
+}) {
+  const { mainToken } = WHITE_LABEL_CONFIG.tokens;
+  const { brandName, links } = WHITE_LABEL_CONFIG.branding;
+
+  return (
+    <Modal
+      onClose={onClose}
+      title={`Welcome to ${brandName}`}
+      visible={visible}
+      maxWidth={560}
+    >
+      <div
+        className={css({
+          display: "flex",
+          flexDirection: "column",
+          gap: 24,
+        })}
+      >
+        <p
+          className={css({
+            fontSize: 16,
+            color: "contentAlt",
+            lineHeight: 1.5,
+          })}
+        >
+          Before opening your first position, here are some important things to know:
+        </p>
+
+        <div
+          className={css({
+            display: "flex",
+            flexDirection: "column",
+            gap: 16,
+          })}
+        >
+          <FaqItem
+            title="What is a Trove?"
+            description={`A Trove is your collateralized debt position. You deposit collateral (like ETH or LSTs) and borrow ${mainToken.symbol} against it.`}
+          />
+
+          <FaqItem
+            title="What are Redemptions?"
+            description={`Redemptions allow ${mainToken.symbol} holders to exchange their ${mainToken.symbol} for collateral at face value. Positions with lower interest rates are redeemed first. Setting a higher interest rate reduces your redemption risk.`}
+          />
+
+          <FaqItem
+            title="How do Interest Rates work?"
+            description="You set your own interest rate. Higher rates mean lower redemption risk but more interest paid. You can adjust your rate anytime, but there's a fee if you change it within 7 days of your last adjustment."
+          />
+
+          <FaqItem
+            title="What about Liquidations?"
+            description="If your collateral value drops and your Loan-to-Value (LTV) exceeds the maximum, your position can be liquidated. Monitor your position and add collateral if needed."
+          />
+        </div>
+
+        <div
+          className={css({
+            display: "flex",
+            flexDirection: "column",
+            gap: 12,
+            paddingTop: 8,
+          })}
+        >
+          <Button
+            label="Got it, let's start"
+            mode="primary"
+            size="large"
+            wide
+            onClick={onClose}
+          />
+          <a
+            href={links.docs.base}
+            target="_blank"
+            rel="noopener noreferrer"
+            className={css({
+              display: "block",
+              textAlign: "center",
+              color: "accent",
+              fontSize: 14,
+              textDecoration: "none",
+              _hover: {
+                textDecoration: "underline",
+              },
+            })}
+          >
+            Read the full documentation
+          </a>
+        </div>
+      </div>
+    </Modal>
+  );
+}
+
+function FaqItem({
+  title,
+  description,
+}: {
+  title: string;
+  description: string;
+}) {
+  return (
+    <div
+      className={css({
+        padding: 16,
+        background: "infoSurface",
+        borderRadius: 8,
+      })}
+    >
+      <h3
+        className={css({
+          fontSize: 14,
+          fontWeight: 600,
+          color: "content",
+          marginBottom: 4,
+        })}
+      >
+        {title}
+      </h3>
+      <p
+        className={css({
+          fontSize: 14,
+          color: "contentAlt",
+          lineHeight: 1.5,
+        })}
+      >
+        {description}
+      </p>
+    </div>
+  );
+}

frontend/app/src/services/StoredState.tsx

@@ -22,13 +22,15 @@ export const StoredStateSchema = v.object({
     v.literal("approve-amount"),
     v.literal("approve-infinite"),
   ]),
+  onboardingDismissed: v.optional(v.boolean()),
 });
 
 type StoredStateType = v.InferOutput<typeof StoredStateSchema>;
 
 const defaultState: StoredStateType = {
   loanModes: {},
   preferredApproveMethod: "permit",
+  onboardingDismissed: false,
 };
 
 type StoredStateContext = StoredStateType & {