admin/linkder
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
582f13fa99005086097fdd9b878c4e7c70f8255e
linkder/DESIGN.md
T
serfowiandClaude Opus 5 582f13fa99 Entry screen is the app: phone frame with a live deck inside 
The homepage was a marketing brochure -- a hero paragraph, a "three
steps" explainer and a tag list. It described the gesture in prose
while the actual Tinder deck sat behind /deck/[jobId], reachable only
after signing in AND posting a job. Nobody opening the app ever saw
the product.

Now / renders a phone illustration with the real app running inside
it: the same <Deck>, the same drag physics, real verified pros. On a
phone the bezel collapses and the deck simply fills the viewport --
drawing a picture of a phone on a phone is absurd, and it would eat
the width the cards need.

- Removed the fixed app bar and bottom tab bar. AppShell now renders
  the screen title as an in-flow h1; the bar owned the only h1 on
  every screen, so dropping it silently would have left every page
  headingless. The /jobs "post" action moved from bar chrome into the
  content, since the tab bar was its only other route there.

- getShowcaseDeck(): a deck with no job behind it. getDeck is
  job-scoped (joins jobs for category and location, anti-joins
  swipes), which an anonymous visitor has none of, so this centres on
  the launch city. Eligibility rules are copied verbatim -- nobody may
  appear in the shop window who could not appear on a real deck.

- deck.showcase: the only public procedure in the router. list and
  swipe stay behind clientProcedure. It reads nothing about the caller
  and writes nothing, so a right swipe on the entry screen is purely
  local. No real tradesperson is contacted until a job is posted.

- <Deck> filled a hardcoded 560px desktop box; it now fills its
  container. The card counter moved out from between the two action
  buttons so the thumb zone holds nothing but the two controls.

Verified against the seeded database: 22 eligible pros returned, and
all three seeded traps excluded for the right reason -- Pau Ribas
(22km out, 5km radius), Unverified Ulla (pending), Away Arnau (not
accepting). 7 new integration tests cover exactly that.

Also corrects a label I had written as "Plumbers near you" -- the
showcase deck is not category-filtered and shows every trade.

Includes concurrent edits to the mobile shell, ui/ primitives and
DESIGN.md made outside this session.

typecheck, lint, build clean; 141 tests pass.

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

360 lines
15 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
0. **Mobile only.** One column, one container, thumb-reachable actions, no desktop layout and
no marketing site. See §4 — this constrains every other decision here.
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
**Linkder is a mobile-only product.** There is no desktop layout, no marketing site and no
responsive breakpoint work. Design for a 360–430px viewport and nothing else. On a wider
screen the app renders as a single 480px column centred on `ink-50` — that is a courtesy for
someone who opened it on a laptop, not a layout to design for.
Concretely, this bans:
- Multi-column grids. Everything is one column. A 2-up grid is allowed only for paired
numeric fields (from/to, rate/years) and stat tiles.
- `md:` / `lg:` variants that change structure. Type already scales with `clamp()`.
- Sticky desktop nav bars with link lists, mega-footers, hero sections, feature grids.
An **8px grid**. The only legal spacing values are `4 8 12 16 24 32 40 56 72`. Anything else
is a bug.
| Token | Width | Used for |
|---|---|---|
| `app` | 480px | Every screen. There is no second container. |
- Page gutter: **20px**. One value, all screens.
- Vertical rhythm between blocks within a screen: **32px**. Between major groups: **40px**.
- Gap between sibling cards in a list: **12px**.
- Label → control: **8px**. Control → helper text: **8px**. Field → field: **24px**.
- Bottom of scroll content clears the tab bar by **88px** (`pb-22`) so nothing hides under it.
### 4.1 Safe areas
The tab bar and any fixed footer pad with `env(safe-area-inset-bottom)`. The app bar pads with
`env(safe-area-inset-top)`. Never assume the viewport edge is reachable.
---
## 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 App bar
Fixed top, **56px** plus top safe-area inset. `page` surface at 88% opacity with
`backdrop-blur(12px)` and a hairline bottom border.
Two layouts only:
- **Root screens** — screen title left in `h4`, at most one icon action right.
- **Pushed screens** — 44px back chevron left, centred title in `h4`, optional icon action right.
No link lists. No CTA button in the bar — the primary action lives in the screen or the tab bar.
### 6.7 Tab bar
Fixed bottom, **56px** plus bottom safe-area inset, `page` surface, hairline top border. Two
to five destinations, each a 44px-minimum target with a 24px icon over a `meta` label. Active
tab is `brand-500` icon + label; inactive is `ink-600`. The active state carries both colour and
weight, never colour alone.
The tab bar is the app's only persistent navigation. There is no footer.
### 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 |
| Multi-column grids, `md:` structure changes | One column, always |
| A marketing hero or feature grid | This is an app, not a website |
| A footer | The tab bar is the only persistent nav |
| An action out of thumb reach | Primary actions sit low, near the tab bar |
---
## 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/` |
| App bar and tab bar | `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