admin/linkder
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c617bc96878dd4c74f770dd22a5bf157bf1cfc22
linkder/DESIGN.md
T
serfowiandClaude Opus 5 c617bc9687 M1 security: close the password backdoor, apply re-review, pin E.164 
Acts on an adversarial review of the M1 auth and authorization code.
Five findings fixed; the rest recorded in SECURITY-FINDINGS.md as the
M1 exit criteria rather than left in a tool transcript.

- auth: serve /phone-number/request-password-reset, /phone-number/
  reset-password and /sign-in/phone-number as 404. better-auth's
  phoneNumber() registers all three unconditionally -- they are NOT
  gated on emailAndPassword.enabled:false. Left live they form a
  silent second credential path: request-password-reset stores an OTP
  and sends no SMS (sendPasswordResetOTP was never configured, so the
  owner is never told), reset-password mints a bcrypt credential row,
  and sign-in/phone-number then accepts it forever with no OTP. The
  OTP gate still applies, so this is not remote unauthenticated
  takeover -- it converts one momentary OTP compromise into permanent
  access the victim cannot see or rotate.

- auth: drop bearer(). It accepts the plaintext sessions.token column
  as an Authorization credential, making any single leaked row a
  replayable login. The mobile client it was added for is hypothetical.

- auth: pin E.164 via phoneNumberValidator, and add toE164/isE164 to
  @linkder/shared. phone is UNIQUE and bans are per-account, so
  "+34600111222" and "0034600111222" being separately storable meant
  one handset could hold two accounts and a ban was escapable by
  retyping. 15 tests.

- auth: NEXT_PUBLIC_APP_URL now throws in production instead of
  falling back to localhost, which was silently dropping Secure and
  the __Secure- prefix from the production session cookie.

- pro.upsertProfile: actually apply requiresReReview. It was computed,
  returned to the client and never acted on, so a verified plumber
  could become a verified electrician in another city by ignoring a
  response flag. Now demotes to pending in the same transaction and
  audits it. Trade changes count as material (they did not before) --
  the licence is per-trade. Needed a verified -> pending edge in
  VERIFICATION_GRAPH, which did not exist.

Removed two untracked scratch repro files. The impersonation repro
depended on bearer() for transport and no longer applies as written;
the underlying finding (resolveSession drops impersonatedBy, so admin
actions are audited as the victim) is open and documented.

typecheck, lint, build clean; 127 tests pass.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-21 01:19:32 -04:00

328 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Linkder Design System
**Version 1.0** · derived from the wix.com design language, adapted for Linkder.
This document is the single source of truth for how Linkder looks. Every screen must be
buildable from the tokens and components below. If a screen needs something that is not in
here, add it here first, then build it.
## Provenance and scope
The visual language is adapted from **wix.com** (sampled 2026-08-21): the Madefor typeface
pair, the signature action blue, the navy-black ink, the pill geometry and the generous
whitespace rhythm. Values below were read off the live stylesheet, not eyeballed.
Adopted: typefaces (Wix Madefor Display / Text, published under the SIL Open Font License via
Google Fonts), colour ramps, radius and spacing conventions, component geometry.
**Not** adopted: Wix's logo, wordmark, product names, illustrations or photography. Linkder is
not affiliated with Wix and must never present itself as such.
---
## 1. Principles
1. **Blue means action.** `brand-500` is reserved for things the user can do. It is never
decoration, never a background wash for a whole section, never body text.
2. **Ink is near-black, not grey.** Headings sit at `ink-950` (`#000624`) — black with a blue
cast. Grey text is a deliberate demotion, not a default.
3. **Type carries the design.** Big, tight display type over ornament. Negative tracking on
anything above 24px; zero tracking on body.
4. **Pills for actions, soft rectangles for containers.** A pill is clickable. A rounded
rectangle holds content. Never the reverse.
5. **Whitespace over borders.** Separate with space first, a hairline second, a shadow last.
---
## 2. Colour
All values are sampled from wix.com. Hex is normative.
### 2.1 Brand — action blue
| Token | Hex | Use |
|---|---|---|
| `brand-50` | `#EDF3FF` | Hover fill on ghost / outline controls |
| `brand-100` | `#DCE8FF` | Selected-chip fill, info banner background |
| `brand-200` | `#95B9FF` | Focus ring halo, disabled primary |
| `brand-400` | `#5E97FF` | **Dark-mode** link and accent text |
| `brand-500` | `#116DFF` | **Primary action.** Buttons, links, active states |
| `brand-600` | `#094BCC` | Primary hover / pressed |
| `brand-700` | `#082F7B` | Primary active on dark surfaces |
`brand-500` on white is **4.5:1** — it clears AA for normal text, but only just. Do not tint it
lighter for text. On dark surfaces use `brand-400` (7.0:1 on `ink-950`) instead.
### 2.2 Ink — text and surfaces
| Token | Hex | Use |
|---|---|---|
| `ink-0` | `#FFFFFF` | Card surface, page background (light) |
| `ink-50` | `#F7F8F8` | Alternating section background |
| `ink-100` | `#F0F0F0` | Inset fills, skeletons, track backgrounds |
| `ink-200` | `#E2E2E2` | **Hairline borders** |
| `ink-300` | `#C2C2C2` | Border on dark, disabled border |
| `ink-400` | `#B0B0B0` | **Dark-mode** secondary text |
| `ink-500` | `#8F8F8F` | Placeholder and disabled text **only** (3.2:1 — never body copy) |
| `ink-600` | `#6E6E6E` | **Secondary body text** (5.1:1 on white) |
| `ink-800` | `#212121` | Body text on tinted surfaces |
| `ink-950` | `#000624` | **Headings, primary text, dark surfaces** |
### 2.3 Semantic
| Token | Hex | Meaning |
|---|---|---|
| `go-50` | `#F3F8F0` | Success banner background |
| `go-100` | `#D2E4C7` | Success border |
| `go-400` | `#92B079` | Success on dark |
| `go-600` | `#618741` | **Success** — verified, accepted, right-swipe |
| `go-700` | `#39641D` | Success pressed |
| `sun-50` | `#FFE9DF` | Warning / pending banner background |
| `sun-100` | `#FFBFA1` | Warning border |
| `sun-400` | `#FA854F` | Warning on dark |
| `sun-500` | `#EA6020` | **Warning** — pending review, expiring soon |
| `sun-600` | `#C94001` | Warning pressed |
| `stop-50` | `#FFECEC` | Error banner background |
| `stop-100` | `#FFC9CB` | Error border |
| `stop-400` | `#FF6A70` | Error on dark |
| `stop-500` | `#ED1C24` | **Error / destructive** — rejected, left-swipe |
| `stop-600` | `#C4141B` | Error pressed |
Never use green/red as the *only* signal. Pair with an icon and a word.
### 2.4 Dark mode
Dark mode inverts the ink ramp and lightens the accent. It is not a separate palette.
| Role | Light | Dark |
|---|---|---|
| Page background | `ink-0` | `ink-950` |
| Raised surface (card) | `ink-0` | `#0C1230` |
| Sunken surface | `ink-50` | `#070C22` |
| Primary text | `ink-950` | `ink-0` |
| Secondary text | `ink-600` | `ink-400` |
| Hairline | `ink-200` | `rgb(255 255 255 / .14)` |
| Accent text / link | `brand-500` | `brand-400` |
| Filled primary button | `brand-500` bg, white text | unchanged |
---
## 3. Typography
### 3.1 Families
| Role | Family | Weights |
|---|---|---|
| Display — h1–h3, big numbers, buttons | **Wix Madefor Display** | 400–800 variable |
| Text — body, labels, inputs, meta | **Wix Madefor Text** | 400–800 variable |
Fallback stack: `'Segoe UI', system-ui, -apple-system, sans-serif`.
Load via `next/font/google` with `display: 'swap'`, exposed as CSS variables. Never link a
stylesheet in `<head>` — it costs a render-blocking round trip.
### 3.2 Scale
Display sizes use `clamp()` so one token works from 360px to desktop.
| Token | Size | Line | Tracking | Weight | Family |
|---|---|---|---|---|---|
| `display-xl` | `clamp(2.75rem, 6vw, 4.5rem)` | 1.04 | `-0.03em` | 700 | Display |
| `display-lg` | `clamp(2.25rem, 4.5vw, 3.25rem)` | 1.08 | `-0.025em` | 700 | Display |
| `h1` | `clamp(1.875rem, 3.5vw, 2.5rem)` | 1.12 | `-0.02em` | 700 | Display |
| `h2` | `clamp(1.5rem, 2.5vw, 2rem)` | 1.18 | `-0.02em` | 700 | Display |
| `h3` | `1.375rem` | 1.25 | `-0.015em` | 600 | Display |
| `h4` | `1.125rem` | 1.35 | `-0.01em` | 600 | Display |
| `body-lg` | `1.125rem` | 1.55 | `0` | 400 | Text |
| `body` | `1rem` | 1.6 | `0` | 400 | Text |
| `body-sm` | `0.875rem` | 1.5 | `0` | 400 | Text |
| `meta` | `0.75rem` | 1.45 | `0` | 500 | Text |
| `overline` | `0.75rem` | 1.4 | `0.08em` | 700 | Text, uppercase |
### 3.3 Rules
- **One display element per view.** A page has one `h1`. A card has none.
- Tracking is negative above 24px and exactly zero below it. Never positive except `overline`.
- Body copy maxes at **68 characters** (`max-w-[68ch]`).
- Headlines use `text-balance`; paragraphs use `text-pretty`.
- Prices, counters and table figures use `tabular-nums`.
---
## 4. Space and layout
An **8px grid**. The only legal spacing values are `4 8 12 16 24 32 40 56 72 96 128`. Anything
else is a bug.
| Container | Width | Used for |
|---|---|---|
| `prose` | 680px | Reading, forms, single-column flows |
| `app` | 1080px | Dashboards, lists |
| `wide` | 1280px | Marketing sections |
- Page gutter: **24px** mobile, **32px** ≥768px.
- Vertical rhythm between page sections: **72px** mobile, **96px** desktop.
- Gap between sibling cards in a list: **12px**.
- Label → control: **8px**. Control → helper text: **8px**. Field → field: **24px**.
---
## 5. Radius and elevation
| Token | Value | Applies to |
|---|---|---|
| `radius-pill` | `999px` | **All buttons**, chips, avatars, badges |
| `radius-card` | `18px` | Cards, banners, modals |
| `radius-lg` | `12px` | Inputs, list rows, small containers |
| `radius-md` | `8px` | Tags, thumbnails, inline code |
| `radius-deck` | `28px` | The swipe card only |
Elevation is restrained. Four steps, no more:
| Token | Shadow | Use |
|---|---|---|
| `shadow-none` | — | Default. Most surfaces are flat with a hairline. |
| `shadow-sm` | `0 1px 2px rgb(0 6 36 / .06), 0 1px 3px rgb(0 6 36 / .04)` | Hover on a list row |
| `shadow-md` | `0 4px 12px rgb(0 6 36 / .08), 0 2px 4px rgb(0 6 36 / .04)` | Sticky header, popovers |
| `shadow-lg` | `0 12px 32px rgb(0 6 36 / .12), 0 4px 8px rgb(0 6 36 / .06)` | Deck card, modal |
Shadows are tinted with `#000624`, never pure black.
---
## 6. Components
### 6.1 Button
Always a pill. Always Display family, weight 600. Label is sentence case, never ALL CAPS.
| Variant | Fill | Text | Border | Hover |
|---|---|---|---|---|
| `primary` | `brand-500` | white | none | `brand-600` |
| `dark` | `ink-950` | white | none | `#1A2145` |
| `outline` | transparent | `ink-950` | `1.5px ink-950` | `ink-50` fill |
| `ghost` | transparent | `brand-500` | none | `brand-50` fill |
| `danger` | `stop-500` | white | none | `stop-600` |
| Size | Height | Padding-x | Font |
|---|---|---|---|
| `sm` | 36px | 16px | `body-sm` |
| `md` | 44px | 24px | `body` |
| `lg` | 56px | 32px | `body-lg` |
Control heights are their own scale — **36 / 44 / 56** for buttons, **48** for inputs. They are
exempt from the 8px spacing grid in §4, which governs margins, padding and gaps.
- Minimum touch target is **44px**. `sm` is desktop-only or must sit inside a 44px row.
- Disabled: `opacity: .45`, `cursor: not-allowed`. Never grey out by swapping colour.
- Busy: leading 16px spinner, label unchanged, control disabled. Never replace the label.
- Icon-only buttons are circles and require `aria-label`.
### 6.2 Input, textarea, select
- `radius-lg` (12px), `1.5px ink-200` border, `ink-0` fill, **16px** text (never smaller — iOS
zooms below 16px), padding `12px 16px`, height 48px.
- Focus: border `brand-500` + `0 0 0 3px brand-200`. Never remove the outline without
replacing it.
- Error: border `stop-500`, message below in `body-sm` `stop-500` with `role="alert"`.
- Placeholder is `ink-500` and never carries meaning the label doesn't.
- Every control has a visible `<label>`. Placeholder-as-label is forbidden.
### 6.3 Card
`ink-0` surface, `radius-card`, `1px ink-200` hairline, `shadow-none`. Padding 24px (20px below
640px). Interactive cards raise to `shadow-sm` and shift the border to `brand-500` on hover;
they do not lift or scale.
### 6.4 Chip / selectable tag
Pill, `1.5px` border, `12px 16px` padding, `body-sm`. Unselected: `ink-200` border on
transparent. Selected: `brand-500` border, `brand-100` fill, weight 600, leading check icon.
Selection must never rely on fill alone.
### 6.5 Banner / status card
`radius-card`, 20px padding, 12px icon-to-text gap, tinted surface + matching border:
| Tone | Fill | Border | Icon |
|---|---|---|---|
| `info` | `brand-100` | `brand-200` | `brand-500` |
| `success` | `go-50` | `go-100` | `go-600` |
| `warning` | `sun-50` | `sun-100` | `sun-500` |
| `error` | `stop-50` | `stop-100` | `stop-500` |
Title in `h4`, body in `body-sm` `ink-600`.
### 6.6 Navigation
Sticky top bar, 72px tall, `ink-0` at 88% opacity with `backdrop-blur(12px)`, hairline bottom
border. Wordmark left in Display 700 `-0.02em`. Primary CTA right as a pill. Mobile collapses
links; the CTA stays visible in the bar.
### 6.7 Footer
`ink-950` surface, white text, secondary links `ink-400`, 72px top padding, 40px bottom,
4-up column grid collapsing to 1-up under 640px.
### 6.8 Deck card
The one place that breaks the flat rule. `radius-deck` (28px), `shadow-lg`, full-bleed photo,
bottom scrim `linear-gradient(to top, rgb(0 6 36 / .92), rgb(0 6 36 / .35) 45%, transparent)`.
Overlay stamps: `SEND JOB` in `go-600`, `PASS` in `stop-500`, 4px border, ±12° rotation. Action
buttons are 64px circles, 2px border, `ink-0` fill.
---
## 7. Motion
| Token | Duration | Easing | Use |
|---|---|---|---|
| `motion-fast` | 120ms | `cubic-bezier(.4,0,.2,1)` | Hover, focus, colour |
| `motion-base` | 200ms | `cubic-bezier(.4,0,.2,1)` | Enter / exit, expand |
| `motion-slow` | 320ms | `cubic-bezier(.22,1,.36,1)` | Page and card transitions |
Transition `color`, `background-color`, `border-color`, `opacity`, `transform` — never `all`.
Non-essential animation is wrapped in `@media (prefers-reduced-motion: no-preference)`. The
deck's drag is essential and stays; its spring flattens under reduced motion.
---
## 8. Accessibility floor
- Body text ≥ 4.5:1, large text and UI borders ≥ 3:1. `ink-500` fails body text — placeholder only.
- Visible focus on every interactive element: `0 0 0 3px brand-200` plus a `brand-500` border.
- Touch targets ≥ 44×44px.
- Colour is never the sole carrier of meaning.
- One `h1` per page, headings in order, no level skipped for size.
- Decorative images `alt=""`; icons inside labelled controls `aria-hidden`.
---
## 9. Do / Don't
| Don't | Do |
|---|---|
| Square-cornered buttons | `radius-pill`, always |
| `brand-500` as a section background | White or `ink-50`; blue for the CTA inside it |
| Grey `#8F8F8F` body copy | `ink-600` for secondary text |
| Positive letter-spacing on headings | `-0.02em` and tighter |
| Three shadows on one screen | One raised element per view |
| `transition: all` | Name the properties |
| Placeholder standing in for a label | Visible `<label>` every time |
| Arbitrary values like `py-[13px]` | The 8px scale |
| A second accent colour | Blue is the only accent |
---
## 10. Where this lives in code
| Concern | File |
|---|---|
| Token definitions (`@theme`), base layer, dark mode | `apps/web/src/styles/globals.css` |
| Font loading, chrome wiring | `apps/web/src/app/layout.tsx` |
| Button, Input, Card, Chip, Banner, Field primitives | `apps/web/src/components/ui/` |
| Site header and footer | `apps/web/src/components/chrome/` |
Screens compose primitives. A screen that writes its own `rounded-xl bg-[#...]` has bypassed the
system — fix the primitive instead.
Reference in New Issue View Git Blame Copy Permalink