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 != nullto 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
/accountpage reached directly is Badger's. Reached from a shop (areturnToon the shop's domain, as the profile widget sends), it takes the shop skin and the shop's voice, and keeps thatreturnToon 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 withbrand-inktext on it,brand-strongfor 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 astyle=""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 inlinestyleattribute. - 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#9CA3AFis 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 carriesbrand-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 checksauth.cssas it checksadmin-ui.css. - Pages declare
color-scheme: lightuntil 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 inauth.cssremoves the entrance animation and the pulses and shows content at once. Content never starts atopacity: 0without 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 getstabindex="-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.
<html th:lang>with the language the text was actually rendered in.<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, andauth.css.<body data-skin="…">>.auth-shell(<main>) >.auth-card.- Inside the card:
.auth-brand, theh1, the lede, the alert area, the form or content, the primary action, the secondary actions. - 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. Nevertype="hidden"and neverdisplay: 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'sconsent_required, Apple'suser_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 onpageshow(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
hiddenattribute 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-mismatchor?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
h1per page, naming the task. Sections below it useh2. A styleddivor 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-ringon:focus-visible, and stays distinct when the element already has an accent border (a selected row, the current shop). Neveroutline: nonewithout 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 witharia-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 (noaria-labelreplacing 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 useauth.<page>.*; shared words useauth.action.*andauth.common.*. Static script reads its strings fromdata-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:utextonly for a key that wraps an escaped parameter in markup. langmatches the language the text was rendered in. A page that fell back to English sayslang="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¶
- Decide the audience and the skin (shopper, staff or prospect) and say it in the controller.
- Render through the layout fragment and
AuthPageBranding. Don't write a<head>, a:rootor a footer. - Compose the page from the components. If a layout is genuinely new, add a named page section
to
auth.cssusing the tokens, not a<style>block. - Give it one
h1, a title from a key and every string from a key. - 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_idandreturnTo. - 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.
- 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 |