# THE FLAKK DESIGN BIBLE 1.0

Single source of truth for everything Flakk shows: the staff app **Flakk** (phone, every role), the desktop console, **Flakk Guest**, the flakk.app site and the desktop EXEs.
Owner: the design director (task dcv2, 19.11.2026). Newest decision wins; this bible overrides earlier builder choices. Changes go through the director, not through builders.

Files in this folder

| File | What |
|---|---|
| `FLAKK-DESIGN-BIBLE.md` | this: principles, tokens, type, colour, iconography, layout per surface, components, states, copy tone |
| `flakk-bible.css` | tokens 1.3.0 additions + the reference component CSS the mockups are built from |
| `tokens-1.3.0.json` | the same tokens as data (generated, do not hand-edit values; edit the bible, then the json) |
| `MOTION.md` | the motion spec for every detail |
| `HAPTICS.md` | the haptics spec and the native mapping |
| `REVIEW-GATE.md` | how a builder screen passes review before gwvf ships it |
| `mockups/` | the hi-fi reference screens at 390 and 1440 |
| `reviews/` | dated review results per builder task |
| `board/` | the published direction board (source) |

---

## 1. The direction: Quiet Ledger

Flakk is a hotel's quiet, expensive notebook. Paper, ink, one gold rule. It never looks like a dashboard, a SaaS admin, or an AI tool. It looks like the inside of a well-run house: calm, exact, generous with space, with the one thing that matters today set in large serif numerals.

What Gummi asked for, in his words, and how this answers it:

- "luxurious, straightforward, complex, but minimalistic" → complexity lives in the data density of rules and lists, not in chrome. One screen can carry 30 facts and still feel empty.
- "the design of a luxury ad, its simplification and minimalism" → a luxury ad has one image, one line, one brand mark. Each Flakk screen has one hero (a number or a date), one lede sentence, and one amber action.
- "more colours, use the Flakk yellow" (11:43) → amber is used with intent, not spread: the orb, the one primary action, the selected tab, the progress rule, the amber-ink action lines. Navy carries the dock and the big numerals. Green, clay and blue appear only as 6 px status dots. That is more colour *meaning*, with less colour *area*. The rejected 15:03 layout spread amber over hero cards, tiles and count discs; that is what reads as "AI and basic".
- "motion graphics for every specific detail" → MOTION.md names every transition on every surface; nothing moves by default browser behaviour.
- "correct haptics for confirmation messages" → HAPTICS.md: one tick per intention, success felt once, never noisy.

### 1.1 Ten principles (the review gate checks each one)

1. **Paper and ink, one theme.** Page is warm paper `#FBF8F2`, text is ink `#16181D`, headings and numerals are navy `#0F2A47`. There is no dark mode and no light/dark mixing in any Flakk app. The only dark objects are the dock, the desktop sidebar, the Flakk Key card and the toast.
2. **Rules, not boxes.** Content is separated by 1 px hairlines (`--fk-rule`). Cards exist only for physical objects: a key, a stay, a room, a sheet. Never nested cards, never coloured tiles, never a card around a list.
3. **Numbers are the hero.** Every screen opens with a context line, then one Fraunces line (a date, a number, a room, a name), then one lede sentence that says what matters. Ledger numbers are Fraunces 40 px light with a small Geist unit.
4. **One amber per region.** A region (a screen on phone, a column on desktop) has at most one amber-filled control. Amber is otherwise a 3 px rule, a progress fill, the selected tab disc or the orb. Amber text never sits on paper; action lines use amber-ink `#8F5710`.
5. **Status is a dot and a word.** 6 px dot in ok/warn/bad/info/amber + a word in ink-soft. No pills, chips, badges, count discs or outlined tags anywhere.
6. **Space is the luxury.** 24 px phone gutter, 40 px desktop gutter, 32 px between sections, 64 px min list rows. If a screen feels empty, that is correct; fill it with nothing.
7. **Symmetry around the orb.** Phone: 2 or 4 icon-only, equal-width tabs, split evenly left and right of the dead-centre orb buckle. No labels, no top bar on the selected tab. Desktop: a left sidebar with the orb on top. Never a top tab row, never a horizontal pill row, never a sub-tab row.
8. **Everything the AI shows comes out of the orb.** Sheets, answers, confirmations and toasts scale and fade from the orb's centre and go back into it. The orb is one particle system, amber and navy only, idle ↔ active morph.
9. **Motion is short, springy and only transform + opacity.** Two main durations (400 snappy, 550 smooth), one stagger (24 ms), press squash 0.96 (0.94 on big controls). Reduced motion keeps 120 ms fades and stops decorative loops only.
10. **Haptics are rare and exact.** Light for selection, medium for the primary action, success once when the app's own success path runs, error once when it fails. Never on scroll, never on navigation back, never twice within 45 ms.

### 1.2 Never (hard fails at the gate)

- a header bar on phone; a horizontal pill, chip, segment or sub-tab row; labelled dock tabs; unequal tab widths; asymmetric bars
- a second theme or `prefers-color-scheme: dark` rules inside the apps; `<meta name="color-scheme" content="light dark">`
- coloured count discs, KPI tiles, gradient hero cards, amber or coloured text on paper (except amber-ink action lines), red banners
- text under 16 px at 100 % text size (units, captions, times included), icons under 20 px, tap targets under 48 px
- more than one shadow level on a screen besides the dock; blur over moving content; borders thicker than 1 px except the 3 px amber rule and the 1.6 px icon stroke
- transforms on containers with fixed children; layout or paint properties animated; a decorative loop that keeps running under reduced motion
- emoji as icons; filled icon glyphs; stock illustrations; the generic AI-tool look (glassy cards, purple gradients, rounded-everything, centred everything)

---

## 2. Tokens

Base tokens 1.2.0 (`flakk-tokens.css`) stay exactly as they are. The bible adds 1.3.0 tokens (in `flakk-bible.css` §1 and `tokens-1.3.0.json`). Nothing is renamed; builders add, they do not edit.

### 2.1 Colour

| Token | Value | Use |
|---|---|---|
| `--fk-paper` | `#FBF8F2` | the page, the sheet |
| `--fk-linen` | `#FFFDF9` | an object on the page (key card, stay card, side panel, desktop rail) |
| `--fk-cream` | `#F3EDE2` | avatar fill, inactive switch |
| `--fk-cream-2` | `#EEE6D8` | progress track, skeleton bars |
| `--fk-ink` | `#16181D` | body text |
| `--fk-ink-soft` | `#4A4E58` | secondary text, status words, labels |
| `--fk-ink-faint` | `#6A6E77` | context lines, units, times (5.3:1 on paper) |
| `--fk-navy` | `#0F2A47` | headings, numerals, icons, the final "ink" button |
| `--fk-navy-deep` | `#0A1D33` | dock, sidebar, toast, Flakk Key card base |
| `--fk-navy-2` | `#1D3B5E` | a navy hover / second surface inside navy |
| `--fk-amber` | `#F2A741` | the orb, the primary button fill, selected tab icon (on navy) |
| `--fk-amber-rule` | `#E9A33F` | 3 px rules and progress fills on paper |
| `--fk-amber-ink` | `#8F5710` | action lines on paper (6.4:1) |
| `--fk-amber-wash` | `rgba(242,167,65,.12)` | selected row, desktop hover, today column |
| `--fk-rule` | `rgba(15,42,71,.12)` | hairlines |
| `--fk-rule-strong` | `rgba(15,42,71,.22)` | section-title rule, outline button, sheet grabber |
| `--fk-ok` `--fk-warn` `--fk-bad` `--fk-info` | `#1F8A5B` `#C98612` `#C2402F` `#2F6FB3` | status dots only, never fills, never text |
| `--fk-scrim` | `rgba(10,29,51,.42)` | behind sheets |
| dock | `--fk-tabbar-bg rgba(10,29,51,.92)` with 14 px backdrop blur, `--fk-tabbar-fg-muted #B7C1CF` idle icon, `--fk-tabbar-active-fg #F2A741` selected icon on the `--fk-tabbar-active-fill` disc | |

Contrast: every text pair in the bible is at least 4.5:1 (ink-faint on paper 5.3, amber-ink on paper 6.4, amber on navy-deep 7.1, tabbar-fg-muted on navy-deep 8.9). Amber `#F2A741` as text on paper is 1.9:1 and therefore forbidden.

### 2.2 Type

Geist (UI), Fraunces (display, `opsz` 144 for ≥ 30 px, `opsz` 24 for row values), Geist Mono (ids, versions, logs). Minimum 16 px at scale 1; everything multiplies by `--fk-scale` (Setup › Text size).

| Role | Face | Size / line | Weight | Tracking | Where |
|---|---|---|---|---|---|
| context | Geist | 16 / 1.3 | 400 | 0 | first line of a screen, ink-faint |
| hero | Fraunces | 56 / 1.0 | 300 | −0.02em | the one date / number / room of a screen |
| display-2 | Fraunces | 30 / 1.12 | 400 | −0.02em | sheet titles, guest questions, empty states |
| large (ledger number) | Fraunces | 40 / 1.05 | 300 | −0.02em | stat numbers; unit in Geist 16/500 ink-faint |
| row value | Fraunces | 21 / 1 | 400 | 0 | amounts and room numbers at the end of a row |
| title | Geist | 19 / 1.25 | 600 | −0.01em | section titles, lede |
| lede | Geist | 19 / 1.35 | 400, bold span 600 | 0 | the sentence under the hero |
| body / row title | Geist | 16 / 1.45 | 400 / 500 | 0 | everything else |
| label (button) | Geist | 16 / 1 | 500 | −0.01em | buttons, nav items |
| mono | Geist Mono | 16 / 1.45 | 400 | 0 | versions, ids, logs |

Numerals: lining, proportional in Fraunces; tabular (`tnum`) only in mono columns and tape charts. Icelandic and English use the same scale; Icelandic words are longer, so titles wrap, they never shrink.

### 2.3 Spacing, radius, elevation

- 8-pt grid: 4 8 12 16 24 32 40 48 64. Phone gutter 24, desktop 40. Section gap 32 (phone) / 40 (desktop). Row min height 64. Control height 56 (primary/secondary/input), 44 (text action, switch row). Tap target ≥ 48.
- Radius: 8 small (skeleton), 12 row highlight, 16 object + control, 24 sheet top, 26 dock, 999 switch + toast. Never different radii on sibling elements.
- Elevation (exactly four): 0 none (rules), 1 object `0 0 0 1px rule, 0 1px 2px rgba(15,42,71,.05)`, 2 sheet `0 -8px 32px rgba(10,29,51,.16)`, 3 dock/orb `0 6px 14px rgba(4,12,24,.26)`. A screen shows at most one level-1 object group plus the dock.

### 2.4 Iconography

One custom stroke set: 24 px grid, 1.6 px stroke, round caps and joins, 2 px inner padding, no fills, no two-tone, optical centring. Icons are navy on paper, `--fk-tabbar-fg-muted` idle / amber selected in the dock and sidebar. 24 px in the dock, 22 px in the sidebar, 20 px inline.
Set 1.0: today (sun over horizon), bookings (calendar), money (banknote), team (two people), inbox (speech bubble), rooms (door), key, stay (bed), menu (three lines), person, developer (code chevrons), check (tick), chevron, plus, close, search, phone, mail, clock, pin, spa (leaf), breakfast (cup), taxi (car), sparkle (orb hint, used once in onboarding). Export as inline `<symbol>` sprites; never emoji, never filled glyphs, never icon fonts.

---

## 3. Layout per surface

### 3.1 Flakk staff app on phone (390 × 844 reference, 360 min)

- No header bar. The page starts (under the system status bar) with: context line → hero → lede. Then sections separated by rules. Bottom padding clears the dock (69.2 + 10 + safe area + 32).
- Dock: 4 icon-only, equal-width tabs, 2 left and 2 right of the orb buckle; 2 tabs for roles with fewer surfaces (1 left, 1 right). Selected tab = amber icon + 44 px soft disc. Fourth tab is always Menu. Tab sets per role are owned by `flakk-roles.mjs`; the bible fixes only the shape.
- Sub-navigation never appears as a row. A screen with several views (Money: today / week / payouts) uses the hero as a disclosure (tap "515,300 kr ⌄" → sheet with the choices) or a list in Menu.
- Role first screens (what the lede and ledger say): owner/manager = occupancy, revenue, collected, rooms ready + Needs you; front desk = arrivals, departures with check-in status + the three actions (New booking, Check in, Message a guest) as rows, not tiles; housekeeping = rooms ready count + the room list with status dots; maintenance = open / urgent / in progress as a ledger + the ticket list; developer = lanes, errors, deploys + the review list.
- Primary action on phone: one amber button pinned above the dock only on "doing" screens (checklist, check-in, payment). Overview screens have none; their actions are amber-ink action lines inside Needs you.

### 3.2 Desktop console (≥ 900, 1440 × 900 reference)

- Grid: sidebar 248 | content (max 1120, gutter 40) | optional rail 360 (linen, hairline left). Inbox uses sidebar | list 380 | thread | rail.
- Sidebar: navy-deep, orb 56 px centred at top (40 px below it), a hairline, nav items 48 px (icon 22 + word, muted → selected amber on the active fill), spacer, Menu, hotel block (hotel name + role). No logo other than the orb. No collapse.
- Content starts with `.fk-top`: hero block left, the one primary button right (min 200 px wide, never full width). Then the 4-column ledger, then two columns 64 px apart. Sheets become right side panels (36 rem, slide in from the right edge, see MOTION §4).
- Hover: rows get `--fk-amber-wash` background with 12 px radius; no underline, no colour change on text. Focus: 2 px amber outline, 2 px offset.

### 3.3 Flakk Guest (phone product; desktop = centred 560 column)

- Orb-first, no start page. Home = the orb (96 px, centred, upper third), one Fraunces greeting, one faint sentence, then two objects: the Flakk Key (navy card) and Your stay (linen card). Dock has 2 tabs: Stay | orb | Key.
- Guided self-presentation: the orb speaks first ("Good evening, Elena. Your room is ready from 15:00. Ask me anything."); the guest never has to learn the app.
- Check-in: one question per screen, display-2 title, vertical choice rows, one Continue. The dock is hidden during the flow; only the orb stays at the bottom centre.
- Flakk Key: hero "Room 104", lede "Until Saturday 11:00." (the exact check-out), a 160 px hold ring (hold 600 ms to unlock, see MOTION §7 and HAPTICS §3), door rows with status dots. Access ends at the exact check-out minute; afterwards the key card turns linen with "Your stay ended Sat 11:00. Thank you." and no ring.

### 3.4 flakk.app site

Same tokens, same type scale one step larger (hero 72 on desktop). Paper page, navy type, the orb as the only moving element above the fold. Sections separated by rules, never by alternating background bands. The motion web layer (92hg) follows MOTION.md §9.

### 3.5 Desktop EXEs (Flakk and Flakk Guest shells)

The console layout inside a native window. OS title bar only; no custom chrome, no in-app menu bar. Window min 1024 × 700; below 900 px wide the phone layout takes over. Native haptics do not exist on desktop; the EXE never vibrates or beeps.

---

## 4. Components (reference CSS in `flakk-bible.css`; class names are the contract)

| Component | Class | Anatomy and rules |
|---|---|---|
| Context line | `.fk-context` | first line of a screen, ink-faint, facts separated by " · " |
| Hero | `.fk-hero` | one Fraunces line; on tap may open a sheet (disclosure) |
| Lede | `.fk-lede` | one sentence; `<b>` for the fact, `<span>` for the rest |
| Section head | `.fk-section-head` | title left, count or "All" right, rule-strong under |
| Ledger | `.fk-ledger > .fk-stat` | 2 × 2 on phone, 1 × 4 on desktop, rules between, label / number+unit / note / optional 3 px bar |
| Row | `.fk-row` | lead (40 px initials disc or icon) / title + sub / trail (status, value, time, chevron); 64 px min; rule between; selected = amber-wash |
| Needs you item | `.fk-need` | sentence / reason / ONE action line |
| Action line | `.fk-action` | amber-ink text + "→", 44 px target |
| Status | `.fk-status.ok/.warn/.bad/.info/.amber` | dot + word |
| Primary button | `.fk-btn.pri` | amber fill, navy-deep text, 56 px, radius 16, full width on phone, min 200 on desktop |
| Secondary button | `.fk-btn.sec` | hairline outline, navy text |
| Ink button | `.fk-btn.ink` | navy fill: the final, money-moving or irreversible confirm |
| Field | `.fk-field` | label above, a rule under the value, amber 2 px rule on focus |
| Switch | `.fk-switch` | navy when on, cream when off |
| Check | `.fk-check` | 26 px circle, done = amber disc + navy tick, label fades (no strike-through) |
| Object | `.fk-object` / `.navy` | the only card; linen or navy (Flakk Key) |
| Sheet | `.fk-sheet` + `.fk-scrim` | paper, top radius 24, grabber, grows from the orb; desktop = right panel |
| Toast | `.fk-toast` | navy pill, one line, amber dot, 2.4 s, above the dock |
| Skeleton | `.fk-skel` | cream bars; appears only after 180 ms |
| Empty | `.fk-empty` | display-2 line + one sentence + at most one action |
| Dock | `.fk-dock` | see 3.1; buckle/orb from `flakk-buckle.css` |
| Sidebar | `.fk-side` | see 3.2 |

---

## 5. States

- **Empty**: a Fraunces display-2 line that states the fact ("No arrivals today."), one sentence of context ("The next one is Marcus Ólafsson, Friday 16:30."), at most one action. Never an illustration, never a grey icon.
- **Loading**: nothing for 180 ms. Then cream skeleton bars in the shape of the content (hero bar, lede bar, four stat pairs, three rows), opacity shimmer only. Content replaces skeleton with a 160 ms fade; never a layout jump (skeleton heights equal real heights).
- **Error**: a sentence in ink where the content would be ("Could not load today's bookings.") + one reason in ink-soft + one action ("Try again"). No red, no banner, no icon. The status dot `bad` is the only red allowed.
- **Offline**: a 2 px navy rule under the context line with the word "Offline" in ink-soft; actions that need the network turn secondary and say what will happen ("Sends when back online").
- **Success**: the control that was pressed becomes the confirmation for 1.2 s (amber button → navy "Sent" with a tick drawn in), then the list updates in place. A toast is used only when the result is elsewhere ("Payment link sent to Hulda").
- **Destructive confirm**: a sheet from the orb with display-2 question, one sentence of consequence, `.fk-btn.ink` to confirm and a text "Keep" to cancel. Never a browser `confirm()`.

---

## 6. Copy tone (EN + IS)

Calm, concrete, short. Sentence case. No exclamation marks, no emoji, no "Oops". Say the time, the name and the number. Address the user as "you" / "þú". Buttons are verbs. The orb speaks as a quiet concierge: it states, it offers, it never apologises twice.

| Situation | English | Íslenska |
|---|---|---|
| overview lede | 6 arriving, 4 leaving. 16 of 24 occupied. Two things need you. | 6 koma, 4 fara. 16 af 24 í notkun. Tvennt bíður þín. |
| needs-you | Hulda leaves with 42,000 kr open. Card declined at 08:12. | Hulda fer með 42.000 kr ógreiddar. Korti hafnað kl. 08:12. |
| action | Send payment link | Senda greiðsluhlekk |
| success | Payment link sent to Hulda. | Greiðsluhlekkur sendur til Huldu. |
| empty | No arrivals today. The next one is Friday 16:30. | Engar komur í dag. Sú næsta er föstudag kl. 16:30. |
| error | Could not load bookings. Try again. | Ekki tókst að sækja bókanir. Reyndu aftur. |
| destructive | Cancel Marcus Ólafsson's booking? He arrives tomorrow 16:30 and has paid 48,900 kr. | Hætta við bókun Marcusar Ólafssonar? Hann kemur á morgun kl. 16:30 og hefur greitt 48.900 kr. |
| guest greeting | Good evening, Elena. Your room is ready from 15:00. Ask me anything. | Gott kvöld, Elena. Herbergið er tilbúið frá kl. 15:00. Spurðu mig um hvað sem er. |
| key | Until Saturday 11:00. Hold the ring to unlock. | Til laugardags kl. 11:00. Haltu hringnum inni til að opna. |
| key ended | Your stay ended Saturday 11:00. Thank you. | Dvölinni lauk laugardag kl. 11:00. Takk fyrir komuna. |
| offline | Offline. Sends when back online. | Ekki nettenging. Sendist þegar samband næst. |

Numbers: Icelandic uses a point for thousands (42.000 kr) and "kl." before times; English uses a comma (42,000 kr) and 24-hour times. Dates: "Thu 19 Nov" / "fim. 19. nóv." Never relative-only ("in 2 h") without the absolute time nearby.

---

## 7. What changes for builders (decisions that override earlier work)

1. `flakk-luxe.css` (bsfa): drop the dark-mode blocks, the `.fk-pill` chips, the amber top bar on the selected tab, the amber-gradient hero card, the count tiles and count discs. Keep the desktop sidebar skeleton, re-skin it to §3.2. Port §3-§5 components from `flakk-bible.css`.
2. Dock labels: removed everywhere (icon-only, `aria-label` keeps the name). `flakk_design_check` keeps "exactly 4 tabs" (or 2); it must now also fail on a visible tab label and on unequal tab widths.
3. `<meta name="color-scheme">` becomes `light only`; every `prefers-color-scheme: dark` and `[data-theme="dark"]` rule inside the apps is deleted.
4. vj4u's `flakk-target.css` "Quiet Ledger" is adopted as the base; its `.seg` row and tab labels are removed.
5. The motion layer (92hg) stays additive and follows MOTION.md; the one change is the tab-press scale (0.96 → icon-only disc scale) and the label fade becomes moot.
6. Haptics: `flakk-haptics.js` stays the web engine; HAPTICS.md adds the native route through `window.flakkNative.haptics` and the exact map.

Vault: this bible is the design decision of 19.11.2026; see `REVIEW-GATE.md` for how it is enforced.
