===============================================================================
 BRANDING GUIDE  -  SHRDBMS React backoffice
 How to re-skin the app for a broker without rebuilding it.
===============================================================================

This folder - customize/ - is the ONLY folder you work in. You edit ONE file,
branding-config.json (in this same folder), and you drop in a few image files.
That's the whole job.

branding-config.json does not exist on a fresh install - the app then runs on
its built-in default look. To customise, COPY  branding-config.sample.json  to
branding-config.json and edit the COPY. That file, your logo, your favicon and
your sign-in pictures are YOURS: a new version of the app never contains them,
so upgrading never overwrites them.

IN branding-config.json:
   - theme       the colour palette          (one word, section 1)
   - typography  the font pairing            (one word, section 2)
   - text        re-word the sign-in screen  (section 3 - optional)

IMAGE FILES (section 4 - nothing to type in the JSON):
   - client-logo/logo.svg  (or client-logo/logo.png)   the logo on the sign-in screen
   - login-images/login-1.jpg, login-2.jpg ...         pictures on the sign-in screen
   - favicon.ico  (in THIS same folder)     the browser-tab icon

Advanced / rarely needed, also in the JSON:
   - colors   override individual colours on top of the theme    (section 5)
   - fonts    override individual font roles on top of typography (section 6)

The client's NAME and ADDRESS are NOT set here - the app fetches them from the
backend (GET /api/branding.swc) at start-up, so they live in the database and are
changed centrally. If that call fails the screen shows the neutral "SHRDBMS"
wordmark with no address; that is the expected fallback. (The sign-in wording,
by contrast, IS in this file - section 3.)


-------------------------------------------------------------------------------
 THE WORKFLOW
-------------------------------------------------------------------------------
 1. First time only: copy  branding-config.sample.json  to  branding-config.json
    (same folder). Then open  branding-config.json  in any text editor
    (Notepad is fine).
 2. Change the values you want (see below). You only need to keep the keys you
    change - anything you leave out uses the built-in default.
 3. Save.
 4. In the browser, hard-refresh:  Ctrl + Shift + R.
 5. The new look loads immediately - no rebuild, no Windows service restart.
    (IIS is set to never cache this file, so the change is picked up at once.)

 If something you set did NOT take effect:
   - Press F12 in the browser, open the "Console" tab, reload.
   - A line starting with  [branding]  tells you what was ignored and why
     (usually a typo, a missing quote, or a colour in a format the app
     doesn't accept).
   - A broken file never breaks the app - it just falls back to the built-in
     "SHRDBMS" house style.


-------------------------------------------------------------------------------
 FILE FORMAT RULES
-------------------------------------------------------------------------------
 - It is a JSON file. Keep the { } braces and the commas between items.
 - Text values go in "double quotes":   "theme": "theme-07"
 - No comma after the LAST item in a { } block.
 - You MAY add notes with  //  ... the app ignores them. Example:
       "theme": "theme-07",   // ABC brand blue
   (Your editor might underline the // in yellow - that is only the editor
    being strict; the app is fine with it.)


-------------------------------------------------------------------------------
 1. theme      - the base colour palette
-------------------------------------------------------------------------------
 Pick ONE. This sets every accent colour in the app in one go.

   "theme": "theme-07"

   VALUE      NAME       PRIMARY    FEEL
   theme-01   Indigo     #1d4ed8    all-purpose blue
   theme-02   Emerald    #047857    growth / positive
   theme-03   Graphite   #334155    minimal, understated
   theme-04   Crimson    #9f1239    bold, high-energy
   theme-05   Violet     #6d28d9    premium, modern
   theme-06   Teal       #0f766e    calm fintech
   theme-07   Azure      #0369a1    clean corporate blue (DEFAULT)
   theme-08   Sapphire   #3730a3    deep formal blue
   theme-09   Forest     #15803d    solid, traditional
   theme-10   Amber      #92400e    warm, distinctive
   theme-11   Rose       #be123c    approachable, retail
   theme-12   Cyan       #0e7490    bright, tech-forward
   theme-13   Plum       #86198f    rich, boutique
   theme-14   Navy       #1e3a8a    conservative, institutional
   theme-15   Olive      #4d7c0f    earthy, muted
   theme-16   Burgundy   #991b1b    heritage, private-client
   theme-17   Ocean      #155e75    deep teal-blue
   theme-18   Zinc       #52525b    true-neutral grey
   theme-19   Magenta    #a21caf    vivid, challenger brand
   theme-20   Copper     #9a3412    warm bronze, premium
   theme-21   Pewter     #45454c    white + grey monochrome

 The neutral background/surface/text colours and the red/green figures stay
 the same on every theme, on purpose - so ledgers and reports always read the
 same way for every broker. The whole sign-in screen (both panels, the
 buttons, the field icons, the dashed seam) follows the theme automatically.


-------------------------------------------------------------------------------
 2. typography  - the font pairing (one word swaps every font)
-------------------------------------------------------------------------------
 Like "theme" for colours: one value changes headings, body text, figures AND
 the sign-in heading together.

   "typography": "serif"

   VALUE         HEADINGS       BODY     SIGN-IN HEADING   NEEDS INTERNET?
   ""  (blank)   Space Grotesk  Archivo  Spectral (serif)  no  - house default
   "sans"        Space Grotesk  Inter    Space Grotesk     no  - no serif anywhere
   "serif"       Spectral       Inter    Spectral          no  - serif headings
   "minimal"     Inter          Inter    Inter             no  - one face, quietest
   "editorial"   Fraunces       Inter    Fraunces          YES - loads Fraunces

 - Figures / codes stay "IBM Plex Mono" in every preset.
 - An unknown value behaves like ""  (house default).
 - "editorial" pulls the Fraunces face from Google Fonts at run time; on a
   network with no internet it falls back to a system serif - not broken, just
   plainer. The other presets use only the faces that ship with the app (the
   "fonts" folder) and always work offline.
 - Need a pairing that isn't here? Use section 6 ("fonts") to name the exact
   families yourself.


-------------------------------------------------------------------------------
 3. text       - re-word the sign-in screen   (OPTIONAL)
-------------------------------------------------------------------------------
 The sign-in screen ships with neutral wording. To put the broker's own words
 there, fill in the "text" block. Every line is optional - leave it "" and the
 built-in wording is used (and the description line simply stays hidden).

   "text": {
     "loginWelcome":     "One console for clients, DP, ledgers and KYC.",
     "loginDescription": "Ledgers and holdings, trade register and net position, fund transfers and KYC - opened in your role, scoped to one year.",
     "authHeading":      "Sign in to your backoffice"
   }

   KEY               WHERE IT SHOWS                             DEFAULT
   loginWelcome      big line on the left sign-in panel         "One console for clients, DP,
                                                                 ledgers, positions and KYC."
   loginDescription  one grey sentence under that big line      (empty - line hidden until
                                                                 you write one)
   authHeading       heading above the ID / password fields     "Sign in to your backoffice"

 - Plain text only. One line each - line breaks and repeated spaces are pulled
   back to single spaces so the panel can't be knocked out of shape.
 - Length caps: loginWelcome ~160 chars, loginDescription ~240, authHeading ~80.
   Anything longer is trimmed.
 - This is the WORDING only. The FONT of the "authHeading" line is a separate
   knob - "fonts": { "authDisplay": ... } in section 6.
 - The client's NAME and ADDRESS are still NOT here (see the top of this file) -
   only the wording above.


-------------------------------------------------------------------------------
 4. logo + sign-in pictures + favicon  - just drop the files in
-------------------------------------------------------------------------------
 There is NOTHING to type in branding-config.json for these. Copy the files
 in using these EXACT names and locations:

     client-logo/logo.svg    your logo for the sign-in screen   (or  client-logo/logo.png )
     login-images/login-1.jpg  your sign-in pictures (login-2.jpg, login-3.jpg ...)
     favicon.ico             the browser-tab icon  (goes directly in THIS folder,
                             NOT inside client-logo/)

 The app looks for them on start-up and uses whatever it finds.

 LOGO
 - Inside THIS folder there is a subfolder named  client-logo . Put your file
   there, named exactly  logo.svg  (preferred) or  logo.png . SVG or a
   transparent PNG; it is shown about 30 px tall, width scales to fit.
 - (An older install that already keeps its logo in a  logos/  folder next to
   index.html still works - it is picked up when client-logo/ has none.)
 - This subfolder is for YOUR logo only - do not touch any other folder here
   (a separate one holds the app's own "Powered by" mark and is not yours to
   edit).
 - No logo.svg / logo.png in  client-logo/  ->  the sign-in screen shows a text
   monogram from the client name instead ("ABC Securities Ltd." -> "AB").

 FAVICON
 - Name it exactly  favicon.ico , placed directly in THIS folder (same level
   as branding-config.json, not inside client-logo/). A 32x32 / 48x48 .ico is
   safest across browsers.
 - No favicon.ico  ->  the bundled default icon (favicon-default.ico) is kept.
   Leave favicon-default.ico alone; your own icon is a separate file named
   favicon.ico.

 SIGN-IN PICTURES
 - Put them in the  login-images  subfolder, named  login-1.jpg , login-2.jpg ,
   login-3.jpg ... (.jpg, .png or .webp), up to 6, numbered from 1 with no gaps
   (the app stops at the first missing number). They are shown as a slideshow
   beside the sign-in form. None there -> no slideshow, the page still works.

 A new version of the app never contains your logo, pictures or favicon.ico, so
 installing it does NOT remove them.


-------------------------------------------------------------------------------
 5. colors     - fine-tune individual colours   (OPTIONAL - advanced)
-------------------------------------------------------------------------------
 Most installs never need this - just pick a "theme" (section 1).
 Use "colors" only to override specific colours on top of the chosen theme.

   "colors": {
     "primary":         "#1e6f5c",
     "primaryHover":    "#17594a",
     "primaryContrast": "#ffffff"
   }

 - Keep  "colors": {}  to change nothing.
 - Add only the keys you want to change; the rest come from the theme.
 - Accepted value formats:
       "#1d4ed8"              (3, 4, 6 or 8 hex digits)
       "rgb(29,78,216)"       "rgba(29,78,216,0.9)"
       "hsl(221,83%,48%)"     "hsla(221,83%,48%,0.9)"
   Anything else is ignored (a typo cannot break the page).

   KEY                WHAT IT COLOURS
   primary            main buttons, links, active menu item, focus ring, KPI
                      accents, the avatar, the dark sidebar + the dark sign-in
                      panel, sign-in field icons
   primaryHover       those same things while the mouse is over them
   primaryContrast    the TEXT / ICON that sits on top of a primary button
                      (set this if you choose a light "primary")
   secondary          a secondary accent (used sparingly)
   info               neutral information banners            (default blue)

   (The page background, cards/panels, text and hairlines - "bg" / "surface" /
   "border" / "text" / "textMuted" - are NOT overridable here: they belong to
   the light/dark switch every user controls themselves (the sun/moon toggle),
   not to the broker's colour scheme. An override here would fight that
   switch and could leave dark mode permanently broken for this install.)

   (Gain / loss / caution colours - green, red, amber - are fixed by the app and
   cannot be changed here: they carry meaning, so they must look the same on
   every install. Any "success" / "danger" / "warning" key is ignored.)

 NOTE ON CONTRAST: if you set a light "primary" and do NOT set
 "primaryContrast", the app auto-picks whichever of near-black / near-white
 text reads better on it, so the button label stays readable.

 NOTE ON DARK MODE: "primaryHover" and "primaryContrast" are used in the normal
 (light) look only. In dark mode the app lightens "primary" itself so it reads
 on the dark background, and chooses its own hover and button-text colours to
 match - a colour picked for the light look would not be readable on it.


-------------------------------------------------------------------------------
 6. fonts      - override individual font roles   (OPTIONAL - advanced)
-------------------------------------------------------------------------------
 Only needed if no "typography" preset (section 2) fits. Each role you fill in
 overrides that one role; the rest still come from the chosen "typography".

   "fonts": {
     "heading": "Poppins",
     "body": "",
     "mono": "",
     "authDisplay": "",
     "googleFonts": ["Poppins:wght@500;600;700"]
   }

   KEY          AFFECTS                              DEFAULT
   heading      page titles and headings             "Space Grotesk"
   body         ALL body text, tables, form fields   "Archivo"
   mono         codes, references, figures           "IBM Plex Mono"
   authDisplay  the sign-in heading line only        "Spectral" (a serif)

 - Leave a value ""  to keep whatever "typography" set for that role.
 - CARE with "body": a narrow or low-legibility font makes dense data tables
   hard to read. Test a full ledger screen before shipping it to a broker.

 WHICH FONT NAMES WORK
 - These five are always available, no extra step - they ship WITH the app (the
   "fonts" folder next to index.html), so they work even with no internet:
       "Archivo"   "Inter"   "Space Grotesk"   "Spectral"   "IBM Plex Mono"
 - To use ANY other font, you must also list it under "googleFonts" so the
   app can load it. Each entry is a Google Fonts "family" spec:

       "googleFonts": [
         "Poppins:wght@400;600;700",
         "Roboto Mono:wght@400;500"
       ]

   Then you can use  "heading": "Poppins"  and  "mono": "Roboto Mono".

 - Loading Google Fonts needs the browser to reach fonts.googleapis.com.
   On a locked-down broker network where that is blocked, the app simply
   falls back to a standard system font - it does not break.
 - If a broker network has no internet at all, stick to the five built-in
   fonts. (Hosting your own font file on the server is possible - see
   fonts/README.txt - but the "fonts" folder is part of the application and is
   replaced by every new version, so ask your provider to add a font
   permanently.)


-------------------------------------------------------------------------------
 WORKED EXAMPLES
-------------------------------------------------------------------------------
 Typical install - two words in the JSON:
 {
   "theme": "theme-06",
   "typography": "serif"
 }
 ...plus  client-logo/logo.svg  and  favicon.ico  dropped into this folder.

 Same, with the broker's own sign-in wording:
 {
   "theme": "theme-06",
   "typography": "serif",
   "text": {
     "loginWelcome": "Your ABC Securities backoffice, in one place.",
     "loginDescription": "Clients and DP, ledgers and holdings, trade register and net position - opened in your role, scoped to one year."
   }
 }

 With advanced tweaks - a custom heading font + one recoloured token:
 {
   "theme": "theme-06",
   "typography": "sans",
   "colors": { "primary": "#0e7c66", "primaryHover": "#0b6353" },
   "fonts": { "heading": "Manrope", "googleFonts": ["Manrope:wght@500;700"] }
 }

 The client's NAME and ADDRESS are NOT in this file - the backend's
 /api/branding.swc returns them for that install.


-------------------------------------------------------------------------------
 AFTER A NEW BUILD IS DEPLOYED
-------------------------------------------------------------------------------
 Copy the new build OVER the installed folder (do not empty the folder first).
 A build never contains anything of yours: everything you created in this
 customize/ folder (branding-config.json, app-config.js, favicon.ico, your logo,
 your sign-in pictures) is left exactly as it is, so the look, the backend path,
 the logo and the icon all stay as you set them.
   - Still keep a copy of this customize/ folder somewhere safe (an installer
     that clears the folder first would remove it).
   - If a build adds a new setting, the built-in default applies until you add
     it: compare your file with the new branding-config.sample.json.
   - Older installs that keep these files next to index.html (branding-config.json,
     app-config.js, favicon.ico, logos/, images/login/) keep working too. A copy
     inside customize/ takes priority; to tidy up, move them in here
     (logos/ -> client-logo/, images/login/ -> login-images/).
===============================================================================
