Skip to content

Auth portal design

How the sign-in portal (auth, served at auth.<platform domain>) is meant to look and behave, and why. One portal serves every shop on the platform, so the same page can sit behind a bakery's storefront, a charity's donation form, the admin and the operator app in the same hour. Clarity and consistency come first. Someone who signs in to two shops should meet the same layout, the same words and the same order of steps on both, with only the shop's identity changed.

This page describes the target design. Not every auth page follows it yet; a change to an auth page moves that page towards it, and a new page starts from it. The general rules in UX guidelines apply here too; this page adds what is particular to signing in.

Who sees the portal

Audience Arrives from Pages Whose look
Shoppers A shop's storefront, its emails, the profile widget Sign in, create an account, email code, emailed-link landing, continue as, link errors, signed out, the sign-in email The shop's (shop skin)
Shop staff The admin, the operator app (POS), an MCP client such as an AI assistant Consent, choose a shop, confirm it's you (step-up), the Badger account home Badger's (Badger skin)
Prospects The marketing site Sign-up: start, summary, building, failed Badger's (Badger skin)

This is the platform rule from Design and UX: whatever a shopper sees belongs to the shop; whatever Badger says to the people who run shops looks like Badger. The portal is the one place where both happen on the same domain, so the split is made per page, explicitly.

Choosing the skin

  • A page's skin is decided by its audience, never by which data happens to be present. The controller decides; the template doesn't test siteName != null to work out who owns it.
  • <body data-skin="shop"> on shopper pages, <body data-skin="badger"> on staff and prospect pages. The skin changes tokens only (accent, page background, brand mark), never markup, so a component looks and behaves the same in both.
  • Sign-in reached from a client that is not bound to a shop (the admin, the operator app before a shop is chosen, the Badger account page) uses the Badger skin with generic wording ("Sign in").
  • A shop record that can't be found falls back to the Badger skin. Never show a half-empty shop frame.
  • The /account page reached directly is Badger's. Reached from a shop (a returnTo on the shop's domain, as the profile widget sends), it takes the shop skin and the shop's voice, and keeps that returnTo on every link and redirect, so the shopper always has a way back.
  • Why: a shopper at a small shop has never heard of Badger and shouldn't be asked to trust it with their account. A shop owner, on the other hand, is granting Badger-level access and should see that it is Badger asking.

What the shop skin shows

Every shopper page carries the shop's identity as visible text. The logo alone, or the <title> alone, is never enough.

Part Rule
Logo If the shop has one: max 48px high, max min(200px, 100%) wide, object-fit: contain, centred in a fixed-height slot. A logo never sets the card's width
Shop name Always shown. As a text wordmark when there is no logo; in the heading ("Sign in to {shop}") or as a caption when there is
Domain Under the name, in muted text ("hedgerow.co.uk"). The domain is the strongest sign that the page is genuine, so it is never hidden
Back to the shop A "Back to {shop}" link to the shop's domain, in the same place on every shopper page (above the footer)
Favicon The shop's icon, falling back to the Badger icon
Colour Neutral ink, not the shop's brand colour (see Tokens). Identity comes from the logo, name, domain and favicon
Footer "Secured by Badger Commerce", small and quiet. This is the only place a shopper meets the name Badger

Long names. Shop names may wrap anywhere in headings (overflow-wrap: anywhere) and are never truncated there. Truncate with an ellipsis only in one-line chrome (the account page's top bar), with the full name in a title attribute. Check every change with a 60-character name and a long name with no spaces.

Why neutral colour: a phishing page can copy any colour in a minute. Trust comes from the domain and from the portal looking the same on every shop. A shop with a red brand shouldn't get sign-in buttons in a third colour, and an unchecked brand colour can make buttons unreadable.

What the Badger skin shows

  • The Badger mark top-left, from the one Badger logo asset the admin uses. No page draws its own Badger icon.
  • Colours from badger-brand-tokens.json (Badger brand tokens): Badger amber for the primary action with brand-ink text on it, brand-strong for amber text and links.
  • The same "Secured by Badger Commerce" footer as shopper pages.
  • A shop or app named on a staff page (the shop a grant applies to, the app asking for access) is content inside the card, with its logo, never the page's chrome.

The shared stylesheet

  • Every auth page links one stylesheet, /css/auth.css (served from the auth module's static folder; /css/** is already public). No page carries its own <style> block with a :root, a raw hex value or a style="" attribute.
  • Page-specific layouts (sign-up's plan cards and summary table, the code input, the passkey prompt, the account page's sections) live in named sections of auth.css, headed /* --- page: <name> --- */, built only from the shared tokens.
  • Two exceptions keep their own styles. The sign-in email is inline-styled because email clients need it, with colours from a fixed palette and the same contrast rules. The profile widget is rendered inside the shop's own page, so it stays self-contained (system font, the shop's accent where one is passed) and never loads auth.css.
  • A test fails the build when an auth template other than those two has a <style> block, a raw hex value or an inline style attribute.
  • Why: each page used to carry its own copy of the tokens, and within a year there were four focus rings, two error reds, three corner radii and seven primary buttons. One stylesheet is the only way a fix reaches every page.

Tokens

Defined on :root in auth.css, prefixed --auth-. Values follow Badger's brand tokens where a role matches, so the Badger skin and the admin agree. Only the accent group and the page background change with the skin.

Group Tokens Value Use
Surface --auth-page #F4F5F7 (both skins; no gradients) Page background
--auth-surface, --auth-surface-alt #FFFFFF, #F6F7F9 Card, inset rows
--auth-border, --auth-border-strong #E4E7EC, #CDD3DC Hairlines; card dividers
--auth-input-border #6B7280 Field and checkbox outlines (3:1 or more on white)
Text --auth-text #171B22 Body text, headings
--auth-text-muted #525A67 Secondary text, hints, ledes
--auth-text-subtle #646D7A The lightest text allowed (footer, small meta). Passes 4.5:1 on white and on --auth-page
Accent --auth-accent, --auth-accent-hover Shop: #171B22, #000000. Badger: #FF8A00, #E87C00 Primary button fill, selected state
--auth-on-accent Shop: #FFFFFF. Badger: #2B1700 Text and icons on the accent fill
--auth-accent-soft Shop: #F1F2F4. Badger: #FFF3E0 Selected rows, info alert fill
--auth-accent-text Shop: #171B22. Badger: #A85300 Accent-coloured text and links
Status --auth-error, --auth-error-soft #B91C1C, #FEF2F2 Error text, error alert
--auth-success, --auth-success-soft #047857, #ECFDF5 Success text, success alert
--auth-warning, --auth-warning-soft #A85B00, #FFF1DB Warnings
--auth-info, --auth-info-soft #2563EB, #E8F0FE Information
Focus --auth-focus-ring 2px solid outline in --auth-focus-color with 2px offset Every interactive element, on :focus-visible
--auth-focus-color Shop: #171B22. Badger: #A85300 Must reach 3:1 against the page and the card
Space --auth-space-1 … --auth-space-8 4, 8, 12, 16, 20, 24, 32, 40px Padding and gaps on the 4px grid
Radius --auth-radius-sm, -md, -lg, -pill 6, 8, 16px, 999px Inputs; buttons and alerts; the card; badges
Shadow --auth-shadow-card, --auth-shadow-sm The existing card shadow; a hairline lift The card; option rows
Type --auth-font Inter, self-hosted (/fonts/), then the system stack All text
--auth-text-xs, -sm, -base, -md, -input, -lg, -title, -title-wide 12, 13, 14, 15, 16, 18, 24, 28px Footer; small meta; body and labels; ledes; fields and buttons; section headings; page title; title on wide pages
Weights 400, 500, 600, 700 Body, emphasis, labels and buttons, titles
Layout --auth-card-width, --auth-card-width-wide 440px, 760px Most pages; sign-up and account
--auth-card-pad 40px 32px, then 24px 20px below 480px Card padding
--auth-gutter 24px, then 16px below 480px Page side padding

Rules for the tokens:

  • No text lighter than --auth-text-subtle. Grey #9CA3AF is for borders and icons only: it is 2.5:1 on white.
  • Status colours are the strong set above, on their soft fills. The lighter reds and greens (#DC2626, #059669) fail 4.5:1 on a tint and aren't used for text.
  • Text on the accent fill is --auth-on-accent, never a literal white. Badger amber can't carry white text (2.4:1); it carries brand-ink.
  • Accent-coloured text is --auth-accent-text, never --auth-accent.
  • The Badger skin's values must match badger-brand-tokens.json; the brand tokens test checks auth.css as it checks admin-ui.css.
  • Pages declare color-scheme: light until a dark set exists that passes the same contrast rules.
  • The font is served by the portal itself (Inter, variable weight, in the auth app's /fonts/). A sign-in page makes no request to a font service. The only third parties a page calls before sign-in are ones it needs to work: the sign-in providers a person chooses, and Cloudflare Turnstile, the bot check on the first sign-up page.

Breakpoints

One breakpoint: max-width: 479px drops the card padding and gutter. Every page works at 320px wide with the keyboard open and no horizontal scroll. The page uses min-height: 100dvh (with a 100vh fallback), respects env(safe-area-inset-*) with viewport-fit=cover, and aligns the card to the top rather than the centre on short viewports, so the iOS toolbar and keyboard don't push it off screen.

Motion

  • At most one entrance animation (the card fading in), and none on a page reached by submitting a form.
  • A looping animation only while something is genuinely in progress: the spinner, the passkey prompt while the browser waits. No decorative pulses.
  • No hover lift on buttons; hover changes colour only, the same on every page.
  • One @media (prefers-reduced-motion: reduce) block in auth.css removes the entrance animation and the pulses and shows content at once. Content never starts at opacity: 0 without it.

Components

One fragment file, templates/auth/fragment/ui.html, plus the matching sections of auth.css. Classes are auth-<component> with BEM elements and is- states, as on the storefront (Components). Pages compose these; they don't restyle them.

Component Class Use
Shell .auth-shell Wraps every page: <main>, centred column, gutter
Card .auth-card, --wide, --flush The one card a page has. --wide for sign-up and account; --flush for a sectioned card whose rows reach the edge (account)
Brand header .auth-brand Top of the card. Shop skin: logo or name, then domain. Badger skin: the Badger mark. Optional eyebrow for the step ("Step 2 of 3")
Title and lede .auth-title, .auth-lede Exactly one <h1 class="auth-title"> per page, then at most one short paragraph
Field .auth-field > <label>, input, .auth-field__hint, .auth-field__error; --code, --suffix Every input. --code for the one-time code, --suffix for sign-up's shop address
Button .auth-btn + --primary, --secondary, --provider, --danger, --link; size --sm Every action (below)
Divider .auth-divider A rule with centred text ("or") between sign-in methods
Alert .auth-alert + --error, --success, --info, --warning Messages about the page or a submission
Account chip .auth-account Avatar, name and email of the person signing in (confirm sign-in, continue as, step-up)
Option list .auth-options Selectable rows with logo, title, description, badge: register's methods, consent's shops, choose a shop, sign-up's choices. Built from native radios or buttons
Result .auth-result + --neutral, --success, --error A whole-page outcome: icon, h1, one paragraph, one primary action, one way back
Footer .auth-footer "Secured by Badger Commerce", below the card, on every page
Spinner .auth-spinner Sign-up building, step-up redirect
Password toggle .auth-field__reveal Show or hide a password

Buttons

  • One primary button per screen. It is the action the page exists for.
  • All buttons are 48px high, 16px text, weight 600, --auth-radius-md, full width inside the card. --sm (40px) is only for row actions on the account page (Connect, Remove).
  • --secondary: a bordered button for an equal alternative ("Use another account").
  • --provider: Google, Apple, Microsoft. Always with the provider's logo in the logo slot, on every page that offers providers: sign in, create an account, step-up and the account page's Connect.
  • --danger: only for removing something (a passkey, a linked account). On the account page it shows in muted ink and turns red on hover or focus, so a list of passkeys isn't a wall of red.
  • --link: a text button for a lesser action ("Use another way to sign in", "Send a new code"). Still a 44px-high hit area.
  • Inline links in running text are underlined (.auth-link). Standalone links styled as buttons are not.
  • Order: primary first, then secondary, then link-style actions. On consent the refusing action sits beside the primary with equal size ("Don't allow" left, "Allow access" right).

Alerts

  • One alert pattern for every message: 14px text, --auth-radius-md, soft fill with the strong text colour, an icon and words (never colour alone).
  • role="alert" for errors, role="status" otherwise. A server error shown on load also gets tabindex="-1" and receives focus.
  • No plain red text for errors, and no inline-styled warning boxes.

The result pattern

Link expired, signed out, step-up failed, sign-up building, sign-up failed and the error page all use .auth-result: an icon in a circle, an h1 that matches what happened, one paragraph that says what to do, one primary action and one way back. A result page never ends with text only.

Page structure

Every auth page renders through one layout fragment and fills its slots. Pages don't copy the shell.

  1. <html th:lang> with the language the text was actually rendered in.
  2. <head>: charset, viewport (width=device-width, initial-scale=1, viewport-fit=cover), <meta name="robots" content="noindex">, color-scheme, the favicon for the skin, the title, and auth.css.
  3. <body data-skin="…"> > .auth-shell (<main>) > .auth-card.
  4. Inside the card: .auth-brand, the h1, the lede, the alert area, the form or content, the primary action, the secondary actions.
  5. Below the card: "Back to {shop}" (shop skin, when the domain is known), then .auth-footer.

Titles follow one pattern, built once by the branding helper: {Page} · {Owner}, in sentence case, where Owner is the shop name on shopper pages and "Badger Commerce" on staff and sign-up pages. No page is titled without an owner, and no title uses internal words.

Branding data reaches templates through one object put on the model by AuthPageBranding: skin, shop name, logo URL, icon URL, domain, back URL and title owner. Every controller that renders an auth page, error paths included, goes through it.

Forms and signing in

Every form is a real <form method="post"> with named inputs and a type="submit" button, and works with Enter from every field. No forms assembled in script and no clickable divs.

  • The first submit button in a form is the action Enter should run. Secondary actions (send a code, resend, cancel) go in their own form or after the primary button. A password field's Enter signs in with the password: on the email-first sign-in page, where sending a code is the first button, the page script makes Enter in the password field sign in with the password.
  • Consent is the exception: "Don't allow" comes first in the form, so Enter never grants access by accident.
  • Field types and autocomplete:
Field Attributes
Sign-in or sign-up identifier type="email", autocomplete="username" (plus webauthn only where passkey autofill is started), autocapitalize="none", autocorrect="off", spellcheck="false"
Existing password type="password", autocomplete="current-password"
New password type="password", autocomplete="new-password"
Emailed code type="text", inputmode="numeric", autocomplete="one-time-code", pattern, maxlength, autocorrect="off"
Name autocomplete="name"
Email kept only for contact type="email", autocomplete="email"
Shop address, promotion code autocapitalize="none" (or characters for codes), autocorrect="off", spellcheck="false"
  • Fields are 16px or larger (--auth-text-input), so iOS doesn't zoom on focus.
  • Every field has a visible <label>. A placeholder is an example, never the label.
  • Every password field has a username the password manager can read in the same form: the visible email field, or a read-only, visually hidden type="email" autocomplete="username" input. Never type="hidden" and never display: none. This includes confirm sign-in, step-up and change password.
  • Every password field has a show/hide toggle: type="button", aria-pressed, a translated label, a 44px target. It resets to hidden on submit.
  • Passwords: one rule, the same on page and server, explained in text (not a colour bar alone). The policy itself is set in Java, not in the template.
  • Passkeys: where the browser supports passkey autofill, sign-in starts a conditional request on load and keeps an explicit "Sign in with a passkey" button (FIDO's tested wording) that cancels it first. The autofill request is silent until the person picks a passkey: if it can't start, nothing is shown. A passkey failure has its own message and never says "Invalid email or password". The passkey button is the first way in on the sign-in page, above Google, Apple and the email form (and first in confirm mode's list of other ways), because below the email form it fell below the fold on a phone and a passkey is the way we'd most like people to sign in. The intro says only "Sign in or create an account", not "with your email address", since the email isn't the first way in.
  • A provider sign-in that fails never blames the password. Cancel at Google, Apple or Microsoft (access_denied, Microsoft's consent_required, Apple's user_cancelled_authorize) says "You didn't finish signing in with that account"; any other provider failure says it "didn't work". Both offer another way in (UpstreamLoginFailureHandler).
  • The stylesheet and script are linked by content version (/css/auth.css?v=<hash>, AuthAssetVersions). Cloudflare and browsers keep them for hours, and under a fixed URL a release's pages ran on the previous release's CSS until the caches expired.
  • Three providers sit in one row. Google, Apple and Microsoft together would be three full-width rows under the passkey button, pushing the email form down on a phone. With three or more, the sign-in and create-an-account pages (ui :: providers) show one row of equal logo buttons; the "Continue with …" name stays in the button for screen readers and as a tooltip. With one or two, each keeps its full-width named button, as peers do. "Sign in faster next time" and confirm mode always use named buttons.
  • "Last used": the sign-in page marks the button this browser last signed in with (a passkey once it has worked; Google, Apple or Microsoft when chosen) with a small "Last used" tag, and opens the password option if a password was last used. Only the method's name is kept, in the browser's local storage; never who signed in. FIDO found people tap a passkey button without having a passkey, so the mark points returning people to the way that worked for them.
  • A provider's first link to an existing account needs an emailed code. "Verified" from Google or Microsoft only means some organisation verified the address's domain with a DNS TXT record, which can be talked into anyone's DNS. So the first time a provider would join an existing account, the code page asks for a code to that address ("Confirm it's your account ... You only need to do this once"), unless the address is on the provider's own mail service or a trusted domain pinned to its organisation. One wait, once, on the page people already know from code sign-in. Details: central sign-in.
  • We don't send people to a passkey after they type their email (Google and Microsoft do). Only accounts with a passkey would get the prompt, so the page would reveal which addresses have accounts. Passkey autofill on the email field and the button give the same shortcut without that.
  • Create an account offers a code or a password, not a passkey. A passkey can only be created once the email is confirmed, so a "passkey" choice did the same as the code. Instead, after the first code sign-in, "Sign in faster next time" asks for one ("Create a passkey", the wording that tested better for Google), and the code option says a new code is sent "until you create a passkey".
  • The code page names the address with "Not {email}? Change email" beside it, so a typo is put right where it's noticed.
  • Resending a code is a lesser action under the code field, with a visible countdown until a new code can be sent. Without script the button simply works.
  • Pending state: every submit disables its button, sets aria-busy="true" and shows a pending label ("Sending…", "Signing in…") until the next page loads, then re-enables on pageshow (back and forward cache). Endpoints that send codes or start a payment are safe to call twice.
  • Keep what was typed after an error, except passwords and codes.
  • Steps revealed by script (a password section, a method choice) are hidden with the hidden attribute or <details>, so invisible fields are never in the tab order.
  • Choices are native controls: a <fieldset> with a <legend> and radios inside labels, styled as option rows.
  • The WebAuthn and form helpers live in one script, /js/auth.js, not a copy per page.

States and ways back

Every flow designs these states, each with a message key:

State What the page does
Default The form, with the one primary action
Submitting Pending button (above)
Field error Text under the field, aria-invalid="true" and aria-describedby on it, focus on the first bad field
Page error .auth-alert--error at the top, focused on load
Expired (link, code, session, request) .auth-result saying what expired and offering a new one ("Send a new link", "Sign in to {shop}")
Code sent Say plainly where it went: "We've sent a sign-in code to {email}". Every address gets a code (an account is made on first use), so this reveals nothing about who has an account. Show a visible countdown until a new code can be sent
Rate-limited Say that several codes have been asked for, how long to wait, and offer another way to sign in
No access (staff) What is missing, who can grant it, "Signed in as {email}", "Sign in with a different account" and a labelled exit
Loading (sign-up building) Spinner and progress; after a fixed time, "This is taking longer than usual. We'll email you when your shop is ready"
Done Where the person is going next, or a button to go there
  • Every page has a way forward and a way back. "Back to {shop}", "Back to the app" or "Cancel and return to {app}" whenever the origin is known. The browser's Back button doesn't count: in an app's sign-in sheet it often isn't there.
  • Context survives every step. client_id, returnTo, the return path and the sign-up id are kept on every redirect and link, including redirects made in script and "use another way" links. An error page in a shop's journey returns to that shop's sign-in, never to a bare /login. A step that must drop the context says where the person will end up.
  • A page reached from an emailed link carries the same branding as the page that sent the email. The link often opens in another browser, and this is the moment a careful shopper checks the page is real.
  • Nothing falls through to the server's default error page. The portal has its own error page, on the shared shell, used for unknown apps, invalid redirect addresses, 404s and unexpected errors.
  • After payment, failure states never offer "Start again". They give a reference and a way to contact support.
  • Messages travel as codes, not text. A redirect carries ?error=password-mismatch or ?notice=passkey-added, which the server maps to a message key. Unknown codes show nothing. An auth page never prints text taken from the URL or from an exception: on a sign-in domain that would let anyone write an official-looking message.

Staff grant screens

Consent is where a staff member gives an app access to a shop, so it is the screen most worth copying for phishing.

  • Show the app's name as a claim. An app that registered itself (any MCP client) is labelled "(not verified by Badger)" and shows where it will send the person back ("Returns you to claude.ai"). Badger's own apps may show a verified mark. A client record doesn't say who registered it, so the mark is given only to the configured ids of the web admin and operator app clients (badger.auth.web-admin.client-id, badger.auth.pos-app.client-id).
  • Name the shop the grant applies to, with its domain.
  • Describe what the app will be able to do in plain words ("See your products, collections and orders"). Raw scope names are shown only to platform operators, if at all.

Accessibility

The portal meets WCAG 2.2 AA, as the rest of the platform does (UX guidelines).

  • One h1 per page, naming the task. Sections below it use h2. A styled div or an eyebrow pill never stands in for a heading.
  • Contrast: 4.5:1 for text, measured against the surface it actually sits on (the card or the page). 3:1 for field borders, checkbox outlines and the focus indicator.
  • Focus is always visible through --auth-focus-ring on :focus-visible, and stays distinct when the element already has an accent border (a selected row, the current shop). Never outline: none without the replacement.
  • Targets are 44px high for buttons and "use another way" links; nothing smaller than 24 by 24px.
  • Every control is native: <button>, <a href>, radios, checkboxes, <details>. A disclosure that isn't <details> is a button with aria-expanded.
  • Errors are never colour alone (see States). Errors raised by script go into a live region that exists before it's updated.
  • Changes of stage move focus. When script swaps one stage for another (the passkey prompt for the password form), focus moves to the new stage's heading or first field.
  • Results are announced: a polite live region for "Code sent", the shop search's result count and sign-up's progress.
  • Logo alt text is the shop's name when the logo stands alone, and empty when the heading next to it already names the shop. Never "Logo". Decorative icons are aria-hidden.
  • Reduced motion is respected (Motion).
  • The sign-in email has lang, role="presentation" on layout tables, a visible "Your code" label before the digits (no aria-label replacing them) and a footer of at least #646D7A.

Wording

Short sentences in plain British English, sentence case, no full stop on buttons or headings. The reader may have arrived from an email in another browser, so every sentence stands on its own: name the thing ("the sign-in code", "Hedgerow Gifts") rather than "it" or "this", and don't assume they know which page sent them.

  • Every error says what happened and what to do next, in one or two sentences: "That code has expired. Send a new one below." Never "Something went wrong" or "Authentication failed".
  • Each failure has its own message. A heading never contradicts the message under it.
  • Shoppers hear about "your account" or "your account with {shop}", never "your Badger account". Badger appears to shoppers only in the footer.
  • No internal words on any page: OAuth, client, scope, token, tenant, step-up, reauthenticate, MCP role, superadmin, purpose codes, reason codes, ids. If support needs a reference, show it as a small "Reference: …" line.
  • Numbers that are configured (how long a code lasts, how long to wait) are parameters, never typed into the text.

Glossary

Use Not Notes
Sign in (verb), sign-in (noun, adjective) Log in, login, Sign In "Sign in to Hedgerow Gifts", "sign-in code"
Sign out Log out, logout
Create an account Sign up, Register Shoppers
Start your free trial Sign up Prospects starting a shop
sign-in code magic link, login link, verification link, OTP The 6-digit code. "Email me a sign-in code"; resending is "Send a new code"
sign-in link magic link, login link The button or link in the sign-in email
passkey Passkey, WebAuthn "Sign in with a passkey", "Use a passkey" (step-up), "Create a passkey" (after sign-in), "Add a passkey" (account page), "Remove"
password "Sign in with a password", "Set a password", "Change password"
Continue Next, Proceed Only once a choice is already made (continue as, the emailed-link page)
Confirm it's you Verify your identity, authenticate, reauthenticate, step-up Step-up and confirm sign-in
Allow access / Don't allow Authorize / Deny Consent
Use another account Not you?, Switch user Changing who signs in
Use another way to sign in Use a different method Changing how
shop store, site, tenant In anything a shopper or shop owner reads
till POS (on one screen alongside "till") Staff wording for the point of sale; pick one per screen
Secured by Badger Commerce Powered by The footer, one key

Text and languages

  • Every word a person can see or hear comes from a message key: text, aria-label, placeholder, alt, title, button labels, the footer, script strings and template fallbacks. Keys use auth.<page>.*; shared words use auth.action.* and auth.common.*. Static script reads its strings from data-msg-* attributes the template renders, as sign-up does.
  • Controllers put codes on the model, never sentences (errorCode, reason, notice), and templates resolve them: #{'auth.error.' + ${code}}. Java builds no English that a person reads.
  • Behaviour never depends on message text. Branch on the code, not on whether the message contains "already exists".
  • Text is rendered with th:text. th:utext only for a key that wraps an escaped parameter in markup.
  • lang matches the language the text was rendered in. A page that fell back to English says lang="en", even when the browser asked for French.
  • A test fails when an auth template uses a missing key or adds visible text outside #{…}, like the storefront's message-key test.

Adding an auth page

  1. Decide the audience and the skin (shopper, staff or prospect) and say it in the controller.
  2. Render through the layout fragment and AuthPageBranding. Don't write a <head>, a :root or a footer.
  3. Compose the page from the components. If a layout is genuinely new, add a named page section to auth.css using the tokens, not a <style> block.
  4. Give it one h1, a title from a key and every string from a key.
  5. Design its states: submitting, field and page errors, expired, rate-limited, no access. Each has a way forward and a way back, and keeps client_id and returnTo.
  6. Check it at 320px and 375px with the keyboard open, in both skins where it can appear, with a long shop name and with no logo, by keyboard alone and with a screen reader, and with reduced motion on.
  7. Update this page if the page adds a component or a rule.

Decisions

Recorded November 2026, from a review of every auth page against this guideline (branding, forms, accessibility, wording, journeys and visual consistency).

Question Decision Why
Should shopper pages take the shop's brand colour? No: neutral ink, the same on every shop. A per-shop accent may come later, taken from the shop's own settings and passed through a contrast check, for the primary button and focus ring only Identity comes from the logo, name and domain. One look across shops is what makes the page recognisable as genuine, and it never clashes or fails contrast
What do staff and prospect pages look like? Badger's brand, from the brand tokens, matching the admin and back-office emails Someone granting access to a shop, or starting one, is dealing with Badger and should see that
Which font? Inter, served by the portal Matches the admin and the brand tokens, without a third-party request on a sign-in page
Whose voice do shoppers hear? The shop's: "your account with {shop}". Badger appears only in the footer A shopper at a small shop has never heard of Badger
Do shops' Site text overrides apply to auth pages? Not yet. One wording across shops Consistency helps trust and support. Revisit for headings only if shops ask
Which language? The shop's locale when the page belongs to a shop, the browser's otherwise A shop's sign-in should read like its storefront
How are third-party apps shown on consent? Badger's own apps may show a verified mark; any app that registered itself is labelled as not verified by Badger, with the address it returns to Consent is the screen most worth copying for phishing
When do we ask for a passkey? Right after an emailed-code sign-in, when the account has no passkey and no linked Google, Apple or Microsoft: "Sign in faster next time", a passkey first, then those providers, then "Not now" (not asked again for 30 days). Every choice carries on to where the person was going, sign-up included A passkey is safer than a code in an inbox, and each sign-in with one is an email we don't send. Asking at the moment they've just waited for an email is when the benefit is clearest
How does someone with only emailed codes confirm it's them (step-up)? "Email me a code" is offered to everyone, after passkey, password and linked sign-ins, and is the main button when it's the only one Without it, an owner fresh from sign-up had no way through and was stuck