darkmode start

Author: jderochervlk

DARK_MODE_HANDOFF.md

@@ -0,0 +1,111 @@
+# Dark Mode Handoff (Current Status)
+
+## What We Completed
+
+### 1) Playground dark/light support
+
+- Added a `Playground Theme` toggle in Settings.
+- Added runtime CodeMirror theme switching (dark/light).
+- Added theme persistence for playground via `localStorage` key:
+  - `playgroundTheme`
+- Updated JS output panel highlighting to follow playground theme.
+
+### 2) Playground onboarding toast
+
+- Added “New: Light Mode” toast in Playground.
+- Supports:
+  - `Dismiss`
+  - `Try it now` (switches to light mode + closes toast)
+  - auto-close after 10s
+- Toast “seen” state moved to `sessionStorage` key:
+  - `playgroundLightModeToastSeen`
+
+### 3) Playground visual fixes
+
+- Improved light-mode contrast for:
+  - Auto-run toggle text
+  - Middle panel divider appearance
+- Added Cypress flow to:
+  - click toast `Try it now`
+  - switch back to dark mode from Settings
+
+### 4) Site-wide dark mode foundation (first pass)
+
+- Added global site theme model:
+  - `src/common/SiteTheme.res`
+  - `src/common/SiteTheme.resi`
+- Added early root theme initialization script in `app/root.res`.
+- Added navbar theme toggle in `src/components/NavbarPrimary.res`.
+- Added dark-mode styling hooks for shared chrome in `styles/main.css`:
+  - body
+  - primary navbar
+  - docs subnav
+  - mobile overlay
+  - footer
+- Added footer dark-logo swap and footer dark classes in `src/components/Footer.res`.
+
+## Files Changed (Dark Mode Work)
+
+- `app/root.res`
+- `src/common/SiteTheme.res`
+- `src/common/SiteTheme.resi`
+- `src/components/NavbarPrimary.res`
+- `src/components/Footer.res`
+- `src/components/ToggleButton.res`
+- `src/components/CodeMirror.res`
+- `src/components/CodeMirror.resi`
+- `src/Playground.res`
+- `src/components/LandingPage.res`
+- `styles/main.css`
+- `e2e/Playground.cy.res`
+
+## Current Known Issues
+
+### Homepage (dark mode)
+
+- Contrast is still too low in multiple sections.
+- Some typography is still too dim after first pass.
+- Landing surfaces are not fully harmonized (dark values are inconsistent section-to-section).
+
+### General
+
+- This is a foundational implementation, not a complete “theme polish” pass.
+- Full compile/test verification was not fully completed in this environment due hanging command output for `yarn build:res`.
+
+## Recommended Next Steps
+
+### Phase 1: Homepage contrast pass (high priority)
+
+1. Make primary marketing text brighter:
+   - Hero title/subtitle
+   - USP headings and paragraph text
+   - Trusted-by and Curated Resources headings
+2. Normalize dark backgrounds section-by-section:
+   - ensure no remaining light patches
+   - keep visual hierarchy with 2–3 dark surface levels
+3. Tune card and border contrast:
+   - cards in Curated Resources
+   - hr/dividers and muted labels
+
+### Phase 2: Global component pass
+
+1. Audit and fix dark-mode contrast in shared UI:
+   - navbar links/icons/search
+   - mobile overlays
+   - doc-sidebars
+2. Replace broad selector overrides with cleaner semantic dark classes where needed.
+
+### Phase 3: Accessibility + regression checks
+
+1. Check color contrast (target WCAG AA for body text and controls).
+2. Run:
+   - `yarn build:res`
+   - `yarn test`
+   - `yarn cy:run`
+3. Add/adjust e2e checks for global theme toggle and homepage dark-mode snapshots (if desired).
+
+## Suggested Cleanup (after visual stabilization)
+
+- Consolidate theme constants for shared text/surface levels.
+- Avoid overly broad selectors in `styles/main.css` and scope to specific component wrappers.
+- Decide final UX for theme toggle location (navbar-only vs additional settings entry).

app/root.res

@@ -36,10 +36,27 @@ external utilsCss: string = "default"
 
 open ReactRouter
 
+let initializeThemeScript = `
+(() => {
+  try {
+    const key = "siteTheme";
+    const darkClass = "site-dark";
+    const lightClass = "site-light";
+    const stored = localStorage.getItem(key);
+    const preferred = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+    const theme = stored === "dark" || stored === "light" ? stored : preferred;
+    const root = document.documentElement;
+    root.classList.remove(darkClass, lightClass);
+    root.classList.add(theme === "dark" ? darkClass : lightClass);
+  } catch (_err) {}
+})();
+`
+
 @react.component
 let default = () => {
   <html lang="en">
     <head>
+      <script> {React.string(initializeThemeScript)} </script>
       <style> {React.string("html {opacity:0;}")} </style>
       <link rel="preload" href={mainCss} as_="style" />
       <link rel="stylesheet" href={mainCss} />

src/common/SiteTheme.res

@@ -0,0 +1,56 @@
+let storageKey = "siteTheme"
+let darkClassName = "site-dark"
+let lightClassName = "site-light"
+
+type t = Light | Dark
+
+let toString = (theme: t): string =>
+  switch theme {
+  | Light => "light"
+  | Dark => "dark"
+  }
+
+let fromString = (value: string): t =>
+  switch value {
+  | "dark" => Dark
+  | _ => Light
+  }
+
+let toggle = (theme: t): t =>
+  switch theme {
+  | Light => Dark
+  | Dark => Light
+  }
+
+let applyToDom = (theme: t): unit => {
+  let classList = document.documentElement.classList
+  switch theme {
+  | Dark =>
+    WebAPI.DOMTokenList.add(classList, darkClassName)
+    WebAPI.DOMTokenList.remove(classList, lightClassName)
+  | Light =>
+    WebAPI.DOMTokenList.add(classList, lightClassName)
+    WebAPI.DOMTokenList.remove(classList, darkClassName)
+  }
+}
+
+let getPreferred = (): t => {
+  let mediaQuery = window->WebAPI.Window.matchMedia("(prefers-color-scheme: dark)")
+  mediaQuery.matches ? Dark : Light
+}
+
+let getInitial = (): t => {
+  let stored = WebAPI.Storage.getItem(window.localStorage, storageKey)->Null.toOption
+  switch stored {
+  | Some(value) => fromString(value)
+  | None => getPreferred()
+  }
+}
+
+let persist = (theme: t): unit =>
+  WebAPI.Storage.setItem(window.localStorage, ~key=storageKey, ~value=theme->toString)
+
+let set = (theme: t): unit => {
+  applyToDom(theme)
+  persist(theme)
+}

src/common/SiteTheme.resi

@@ -0,0 +1,11 @@
+let storageKey: string
+
+type t = Light | Dark
+
+let toString: t => string
+let fromString: string => t
+let toggle: t => t
+let getInitial: unit => t
+let applyToDom: t => unit
+let persist: t => unit
+let set: t => unit

src/components/Footer.res

@@ -18,12 +18,13 @@ let make = () => {
   let iconLink = "hover:pointer hover:text-gray-60-tr"
   let copyrightYear = Date.make()->Date.getFullYear->Int.toString
 
-  <footer className="flex justify-center border-t border-gray-10">
+  <footer id="site-footer" className="flex justify-center border-t border-gray-10">
     <div
-      className="flex flex-col md:flex-row justify-between max-w-1280 w-full px-8 py-16 text-gray-80 "
+      className="site-footer-content flex flex-col md:flex-row justify-between max-w-1280 w-full px-8 py-16 text-gray-80 "
     >
       <div>
-        <img className="w-40 mb-5" src="/rescript_logo_black.svg" />
+        <img className="site-logo-light w-40 mb-5" src="/rescript_logo_black.svg" />
+        <img className="site-logo-dark hidden w-40 mb-5" src="/brand/rescript-logo-white.svg" />
         <div className="text-16">
           <p> {React.string(`© ${copyrightYear} The ReScript Project`)} </p>
         </div>
@@ -32,7 +33,7 @@ let make = () => {
         className="flex flex-col space-y-16 md:flex-row mt-16 md:mt-0 md:ml-16 md:space-y-0 md:space-x-16"
       >
         <Section title="About">
-          <ul className="text-16 text-gray-80-tr space-y-2">
+          <ul className="site-footer-muted text-16 text-gray-80-tr space-y-2">
             <li>
               <Link to=#"/community/overview" className={linkClass}>
                 {React.string("Community")}
@@ -47,7 +48,7 @@ let make = () => {
           </ul>
         </Section>
         <Section title="Find us on">
-          <div className="flex space-x-3 text-gray-100">
+          <div className="site-footer-icons flex space-x-3 text-gray-100">
             <a className=iconLink rel="noopener noreferrer" href=Constants.githubHref>
               <Icon.GitHub className="w-6 h-6" />
             </a>

src/components/LandingPage.res

@@ -70,7 +70,7 @@ export {
     let (example, _setExample) = React.useState(_ => examples->Array.getUnsafe(0))
 
     //Playground Section & Background
-    <section className="relative mt-20 bg-gray-10">
+    <section className="lp-playground-hero relative mt-20 bg-gray-10">
       <div className="relative flex justify-center w-full">
         <div className="relative w-full pt-6 pb-8 sm:px-8 md:px-16 max-w-[1400px]">
           // Playground widget
@@ -686,7 +686,7 @@ let make = (~components=MarkdownComponents.default) => {
       description="Fast, Simple, Fully Typed JavaScript from the Future"
       keywords=["ReScript", "rescriptlang", "JavaScript", "JS", "TypeScript"]
     />
-    <div className="mt-4 xs:mt-16">
+    <div id="landing-page" className="mt-4 xs:mt-16">
       <div className="text-gray-80 text-18 z">
         <div className="absolute w-full top-16">
           <Banner>

src/components/NavbarPrimary.res

@@ -7,6 +7,29 @@ let isActive = (~url, ~pathname: Path.t) => {
     : "hover:text-fire-30"
 }
 
+module ThemeToggle = {
+  @react.component
+  let make = (~theme: SiteTheme.t, ~onToggle: unit => unit) => {
+    let (label, title) = switch theme {
+    | SiteTheme.Light => ("Light", "Switch to dark mode")
+    | SiteTheme.Dark => ("Dark", "Switch to light mode")
+    }
+
+    <button
+      className="rounded border border-gray-60 px-2 py-1 text-12 hover:cursor-pointer hover:text-white"
+      onClick={evt => {
+        ReactEvent.Mouse.preventDefault(evt)
+        onToggle()
+      }}
+      title
+      ariaLabel={title}
+      dataTestId="theme-toggle"
+    >
+      {React.string(label)}
+    </button>
+  }
+}
+
 module LeftContent = {
   @react.component
   let make = () => {
@@ -44,14 +67,15 @@ module LeftContent = {
 
 module RightContent = {
   @react.component
-  let make = () => {
+  let make = (~theme, ~onToggleTheme) => {
     let iconClasses = "w-6 h-6 opacity-50 hover:opacity-100"
     let linkClasses = "hidden md:block"
     <div
       dataTestId="navbar-primary-right-content"
       className="row-start-1 justify-self-end col-[content] grid grid-flow-col items-center space-x-5 text-gray-40"
     >
       <Search />
+      <ThemeToggle theme onToggle=onToggleTheme />
       <button
         className={"h-1 w-auto block md:hidden opacity-50 hover:opacity-100 m-0"}
         onClick={toggleMobileOverlay}
@@ -95,8 +119,23 @@ module RightContent = {
 
 @react.component
 let make = () => {
+  let (theme, setTheme) = React.useState(_ => SiteTheme.Light)
   let scrollDirection = Hooks.useScrollDirection(~topMargin=64, ~threshold=32)
 
+  React.useEffect(() => {
+    let initialTheme = SiteTheme.getInitial()
+    setTheme(_ => initialTheme)
+    SiteTheme.applyToDom(initialTheme)
+    None
+  }, [])
+
+  let onToggleTheme = () =>
+    setTheme(prev => {
+      let next = SiteTheme.toggle(prev)
+      SiteTheme.set(next)
+      next
+    })
+
   let navbarClasses = switch scrollDirection {
   | Up(_) => "translate-y-0"
   | Down(_) => "-translate-y-full md:translate-y-0"
@@ -112,7 +151,7 @@ let make = () => {
     `}
     >
       <LeftContent />
-      <RightContent />
+      <RightContent theme onToggleTheme />
     </nav>
     <NavbarMobileOverlay />
   </>