# qID Connect design

The widget ships styled and themed. Integrators should not need a designer to
look right, and users should recognize the flow across every BTX app the way
they recognize WalletConnect across EVM apps. This file is the design
contract.

## The mark

`assets/qid-mark.svg`. A geometric q with an electron dot: the q is the brand,
the dot is the quantum hint, and at small sizes it still reads. It is drawn
with `currentColor`, so it takes the color of the text next to it. On brand
surfaces use emerald `#34d399` on near-black green `#050c08`.

Rules: do not redraw it, stretch it, add gradients to it, or put it on a busy
background. Minimum size 16 px.

## The button

The widget renders it; these rules exist for anyone recreating it natively.

- Label is exactly "Sign in with qID". Not "Login", not "Connect wallet",
  not "qID". The phrase is the brand, like "Sign in with Google".
- Mark on the left, label on the right, 0.55em gap.
- Default look: emerald `#34d399` fill, near-black text `#04120c`, radius
  12 px, weight 700, subtle glow shadow, small lift on hover.
- Never place an email or password field next to it. It replaces them.

## The dialog

- Max width 400 px, radius 20 px, one dialog, three tabs: "Scan with phone"
  (default active, QR-first), "Desktop wallet" (copy-paste), and "Open in
  wallet" (the `btxqid://` deep link). Further transports arrive as new tabs.
- Above the tabs sits the supported-wallet list ("Works with"), the
  WalletConnect pattern: each row is a wallet name plus an "Available now" or
  "Coming soon" chip. Default list: PQ Wallet for BTX available now, bonuz Wallet
  available now. Integrators override with the `wallets` option; `wallets: []`
  hides the list. Names render as text, never markup.
- After a proof is accepted the dialog plays a brief signing animation, a
  small character rain in the brand accent, about 0.8 seconds, then the check
  mark. Self contained, a few hundred bytes, skipped when the user prefers
  reduced motion or the integrator passes `signingFx: false`.
- The QR card is always white with 14 px padding and the mark centered in a
  white badge. QR modules stay dark on white in both themes; scanners need
  the contrast. Error correction level Q, so the center badge never breaks
  scanning.
- The safety line is part of the design, not legal noise. Every surface ends
  with: a sign-in proof can never move funds.

## The signed-in state (the account chip)

- After sign-in, the account chip (`mountQidAccount`) carries the signed-in
  state everywhere the same way the dialog carries sign-in: a pill with a
  green dot and the short address, opening a dropdown with the full address
  (click to copy), any integrator menu items, and a two-step **Log out**. The
  chip's dot is a settled state — it does not pulse like the "waiting" spinner.
- Log out is never a one-click accident: it lives inside the dropdown, styled
  as the one destructive action. The chip renders nothing when signed out, so
  it can be mounted unconditionally next to the button.

## Theming

Everything reads CSS variables with dark defaults, light theme applies
automatically via `prefers-color-scheme`. Integrators override on the mount
element or any ancestor:

```css
#signin {
  --qidc-accent: #34d399;   /* brand accent: button, tabs, highlights */
  --qidc-bg: #101613;       /* dialog background */
  --qidc-fg: #e9f3ed;       /* dialog text */
  --qidc-border: #25352c;   /* hairlines */
  --qidc-muted: #8fae9d;    /* secondary text */
  --qidc-code-bg: #0a0f0c;  /* code and input background */
  --qidc-btn-bg: #34d399;   /* button fill (defaults to accent) */
  --qidc-btn-fg: #04120c;   /* button label */
}
```

Change the accent to match your app; keep the white QR card and the label
text as they are.

## Motion

Overlay fades in 180 ms, dialog pops 96 to 100 percent scale. The waiting
dot pulses at 1.2 s. Success is a scale-in check circle, then the dialog
closes itself after about a second. Nothing else moves. No spinners over the
QR, no shimmer.

## Assets in this folder

- `qid-mark.svg` the mark
- `qid-connect-hero.png` the hero banner for docs, OG images, and launch
  posts (Higgsfield render, dark green with the emerald QR monument and the
  ring-and-electron center that echoes the mark)


**Theming and the portaled dialog.** The button renders inside your mount
element, but the dialog is portaled to `document.body` so it can overlay the
page — it is not a DOM descendant of the mount, so CSS custom properties set
on the mount do not cascade to it automatically. The widget handles this for
you: on open it copies the `--qidc-*` values computed on your mount element
onto the dialog. So setting `#signin { --qidc-accent: … }` themes both the
button and the dialog. Setting them on `:root` also works and themes
everything unconditionally.
