Design and UX¶

How Badger's screens and emails are meant to look and behave, and why. This section is for people building Badger, not for shop owners: it records the design decisions behind a surface so the next change keeps them, and says where the mock-ups that led to them live.

Start here¶

Read Foundations for the two systems, the token tiers and the scales, then Components for how a storefront component is shared and which ones are, then UX guidelines for states, forms, feedback, accessibility and wording. To see the components rendered, use the Pattern library (/system/patterns); for the admin, /admin/styleguide.

Surfaces¶

The rule that splits them: whatever a shopper sees belongs to the shop and takes its theme. Whatever Badger says to the people who run the shop looks like Badger.

Mock-ups and this section¶

New designs usually start as a Claude artifact, a mock-up page on claude.ai, reviewed before any template is written. That is working material: it shows the options and gets the decisions made. Once a design ships, the decisions belong here, in the repo, next to the code they describe.

• Write the decisions into a page here in the same change that ships the design, as for any other doc. Say what was decided and why, then the rules a later change must keep. Describe what shipped, not what the mock-up showed: the two drift (the back-office email mock-up still shows the old sender, for example).
• Link the mock-up under a Mock-ups heading, with its date and what it covers, if it's worth looking at later (it shows options that were turned down, or a layout easier to see than to describe). Artifacts are private until shared: share it as "anyone with the link" first, otherwise nobody else can open it.
• Don't depend on the link. A page here must make sense if the artifact is gone. Anything only the mock-up says, and that still matters, gets written down here.
• No customer data in a mock-up you share. Use example figures or a demo site's. Real shop totals and references are fine for review, but swap them for example figures before sharing the link.

Design systems¶

The two looks are also published as Claude Design System artifacts, so a mock-up starts from the real tokens and components rather than a guess:

They are generated, never edited by hand: dev-scripts/design-system/build.py reads the stylesheets, badger-brand-tokens.json, the pattern library export and the admin styleguide, and writes the files; --check validates them and prints the contrast of every text colour in every theme. Rerun it and publish again when a token, a shared component or one of these pages changes (dev-scripts/design-system/README.md).

Pages¶

• Foundations: Badger's look and the shop's look, the storefront token tiers, scales, breakpoints and motion.
• Components: the shared storefront component contract, how to add one, and the catalogue of what is shared, planned or theme-owned.
• UX guidelines: rules for empty, loading and error states, confirmations, forms, feedback, accessibility, wording and performance.
• Pattern library: shared storefront fragments rendered from fixtures in every Nova-family theme, and the before/after screenshots that prove a refactor changed nothing.
• Shop emails: the layout every email to a shop's customers shares.
• Back-office emails: the Gift Aid claim and payout emails Badger sends to shop staff, and the layout every later one uses.
• Admin Payouts page: Finance › Payouts, a shop's Stripe payouts and what each one is made of.
• Account area: the customer's account pages, their header band and tabs, the overview and the list pages.
• Finish setting up card: the admin home card and Settings badges that list what a shop's features still need.
• Admin location page: a location's settings, showing only what that location does.
• Storefront inventory: which components the Nova-family themes share and which they have copied, with token, inline-style and message-key counts.