# Kardy — Design System

> Canonical: https://getkardy.com/design.md

## Brand idea

**Make it sticky.** Kardy brings people back to the places they love.
The purpose in the approved Kardy brand book is **“To bring back every customer.”**
This is an ambition, not a guarantee of repeat purchases.

The identity is warm, playful and tactile: an expressive wordmark, a little card
mascot, generous space and confident colour. Functional screens stay clear and calm.
This system applies to the consumer site, PWA, merchant workspace and documentation.

## Logo and mascot

- Use the exact outlined wordmark from the approved Kardy.pdf, not typed “kardy”.
- The shared `KardyWordmark` component uses vector artwork from `brand-artwork.ts`.
  Standalone assets live in `consumers/public/brand/`.
- The default logo is horizontal: wordmark on the left, mascot on the right,
  vertically centred. The mascot is slightly enlarged (1.35× source scale in the
  shared lockup). Use this arrangement in headers, dashboards, documentation,
  social images and bento previews; do not stack the mascot above the wordmark.
- Use burgundy on light backgrounds; soft white or pink on burgundy.
- The tilted card with two eyes is Kardy's compact mark. Use it for the app icon,
  favicon, Wallet icon and occasional brand-led illustrations. Do not use the old K icon.
- Keep the mark's proportions and eye shapes. Do not stretch, redraw or add a face.
- Leave clear space of at least half the wordmark height.
- Preserve the existing divider and right-hand label typography for MERCHANT,
  MERCHANTS, NETWORK and DOCUMENTATION: small, tracked, monospaced and vertically centred.
  Only the wordmark to the left changes; do not turn these labels into display lettering.
- Merchant logos remain merchant-owned. Never replace them with Kardy artwork.

## Approved palette

| Colour      | Hex       | Role                                                        |
| ----------- | --------- | ----------------------------------------------------------- |
| Light pink  | `#FF90C1` | Primary brand fills, selection and positive calls to action |
| Soft violet | `#AF79F3` | Secondary brand panels and supporting artwork               |
| Burgundy    | `#42001C` | Wordmark, text, outlines, readable links and dark actions   |
| White       | `#FFFFFF` | Main light site canvas                                      |
| Soft white  | `#FFF0EE` | Optional brand artwork and reversed text                    |

These four colours replace the previous rich-pink / yellow / purple brand system.
Yellow is no longer a Kardy brand colour. It can still appear in merchant-owned
artwork or semantic warnings.

### Theme implementation

The shared source of truth is `consumers/src/app/globals.css`; the merchant app
imports it and extends the consumer Tailwind configuration.

- `signal`: light pink, with burgundy `signal-foreground`.
- `signal-hover`: a lighter opaque pink; retain burgundy text.
- `signal-ink`: burgundy in light mode, pink in dark mode. Use this for links
  and focus indicators, not the pale fill token.
- `secondary`: soft violet, with burgundy `secondary-foreground`.
- `ink` / `paper`: burgundy / pure white in light mode. Keep the site background white, not pink-tinted. Dark mode uses soft
  white on a deeper burgundy canvas.
- `fog`, `line`, muted text and field tokens are quiet supporting neutrals.
- `sun`, `coral` and `sky` are legacy illustration / semantic helpers, not
  additional core brand colours. Do not use them to theme new Kardy chrome.

Pink and violet are **fills, not small text on white**. Never use white text on
the light pink or soft violet. A dark burgundy action with soft-white text is
also valid. Keep error and destructive actions red and success indicators green.

Mintlify uses burgundy for accessible light-theme navigation and pink for its
light accent value. Documentation previews use the same fixed four-colour palette.

## Typography

The brand book specifies **Lazy Dog** for expressive display lettering and **Inter**
for headings, subheadings and body text.

- The supplied wordmark is outlined, so it renders faithfully without a font download.
- Use Inter for all functional UI, navigation, forms and documentation.
- Use bold, tightly spaced Inter for product headlines; normal tracking for body copy.
- Do not extract the PDF's subset font as a webfont. Additional Lazy Dog headlines
  require a licensed webfont with a complete character set.
- Do not copy presentation font sizes literally onto the web. Use responsive sizes.
- Preserve monospaced, widely tracked lockup suffixes and small utility labels.

## Imagery and illustration

- Lead with the real card mascot, wallet cards, local places and familiar faces.
- Stage pink and violet against soft white; use burgundy for definition.
- Product illustrations must show real, understandable flows and clear sample data.
- Keep merchant-owned passes visually independent of the Kardy interface.
- Use depth only when it helps: soft shadows, layered wallet cards, tactile print.
  Optional 3D artwork should build on the card mascot, not generic floating shapes.
- Never reuse third-party moodboard images or watermarked stock graphics as assets.
- Keep typography and QR codes crisp vectors, not generated raster lettering.
- Avoid decorative animation that competes with the task.

## Branding controls and ownership

The merchant Branding page lets merchants customise their storefront and wallet card.
Saved colours and logos are not migrated when Kardy's own branding changes.

Printed QR signs keep fixed Kardy colours and the approved wordmark. Merchants can
edit copy, choose an outlet and paper size, but cannot change Kardy's sign palette.
QR codes remain dark on white with an unobstructed quiet zone.

## Layout and components

- Keep operational dashboards restrained; use the expressive identity in selected
  brand moments rather than colouring every panel.
- Give public pages generous margins, bold headlines and one clear action.
- Match button heights to adjacent inputs; keep tap targets comfortable.
- Use the shared `KardyWordmark` and `KardyMascot` components.
- Keep cards rounded, borders subtle and shadows soft.
- Member surfaces are mobile-first; merchant surfaces can use denser desktop layouts.

## Voice

Warm, direct and specific. Prefer Join, Save, Scan, Reward and Customise.
Talk about members and merchants, not abstract users. Explain what is available
without promising guaranteed returns or implying planned features are live.

## Accessibility and motion

- Normal text needs at least 4.5:1 contrast; controls and focus indicators need 3:1.
- Pair `bg-signal` with `text-signal-foreground`; use `text-signal-ink` for links.
- Test the actual composited background, including hover states and dark mode.
- Custom merchant colours use luminance-based contrasting text, not a fixed colour.
- Keep persistent labels, visible keyboard focus and status text alongside colour.
- Run `pnpm --filter @kardy/consumer test:contrast` after changing theme tokens.
- Use namespaced `t-*` motion classes and respect reduced-motion preferences.
- Animate meaningful changes, not every element.

## Machine-readable resources

- Sitemap: https://getkardy.com/sitemap.xml
- Short product context: https://getkardy.com/llms.txt
- Full product context: https://getkardy.com/llms-full.txt