# Best practices — a Urbino Manager UI-projektből kondenzálva

**Forrás.** A Urbino Manager UI-csapat 2026.05.27-i lezáró tapasztalata (~35 chat, 9-lépéses terv lefutva).
**Cél olvasó.** Te magad, vagy egy másik Claude design-projekt tervezője, aki az Urbino-családon belül egy új surface-t (polgári mobil / polgári public web / field-worker app) tervez.

---

## Mit csináljunk MINDIG

### 1. UX-explorer-first a nem-triviális döntéseknél

Minden cross-cutting döntés előtt **2-3 alternatíva vizualizálva**. Egy külön `*-explorer.html`-fájl, ami egymás mellett mutatja a mintákat, a pro/kontrákkal és a választás-indoklással.

**Példák:**
- `tier-2-ux-explorer.html` — 14 lista-szintű UX-döntés (oszlop-sorrend, density, sort-default, row-click viselkedés)
- `tier-3-content-explorer.html` — ContentEditor split-view vs full-width
- `tier-3.5-validation-explorer.html` — Form-validation szövegezés-minták
- `s6_5-beallitas-nav-explorer.html` — LeftNav-szerkezet 5 minta

Az explorer **mindig** rögzít egy choice-t a végén — egy `D-X`-bejegyzéssel a `DECISIONS.md`-ben.

### 2. Döntés-napló (`DECISIONS.md` D-X)

**Minden cross-cutting UX-döntés rögzítve** a `DECISIONS.md`-ben, sorszámozva (D-1, D-2, ..., D-20 a manager-projektnél). Per-bejegyzés:
- **Dátum.**
- **Tárgy.** Mit döntöttünk.
- **Kontextus.** Miért merült fel, mire vonatkozik.
- **Opciók.** Mit fontoltunk, és miért vetettük el a többit.
- **Döntés.** Egy mondat.
- **Hatás.** Mely fájl(ok) változnak ettől.

A `DECISIONS.md` a HANDOFF.md-ben hivatkozott; a fejlesztő olvashatja vissza, miért így döntöttünk.

### 3. Audit-checkpointok a kritikus mérföldkövek után

**Minden nagyobb fázis után egy `AUDIT-X.md`** — független felülvizsgálat. Listázza:
- Mi készült el, mi maradt félben
- Inkonzisztenciák a screen-mock vs. organism-katalógus között
- Spec-eltérések (a screen-mock eltér a spec-szövegtől)
- TODO-jegyzék a következő iterre

A manager-projektben `AUDIT.md` (6. lépés után) + `AUDIT-2.md` (8. lépés után). A 2. audit feltárt **3 inline-organism-pótlást** a screen-mockokon, amiket a HANDOFF.md a fejlesztőnek explicit listáz.

### 4. Spec-fedés-leltár

**Egy spec-fedés-leltár** (4-listás minta: ✅ teljes / ⚠ részleges / 🟡 felülmaradt / 🔍 UI-találmány) **per spec-fejezet**. A manager-projektben: `SPEC-COVERAGE-A1A2A3.md` + `-A4A5.md` + `-A6A7A8A9.md` + `-A10A11A12.md` — összesen 4 fájl × ~370 elem.

Az output: a screen-mock **minden mező/végpont/UI-elem-szinten lefedi-e a spec-et**, és mely területeken találtunk ki nem-spec-rögzítettet (`🔍` = UI-találmány, ami spec-csapat-döntés-jelölt).

### 5. SPEC-FEEDBACK-csomag — a spec-csapatnak

Külön deliverable, **NEM a fejlesztőnek**. A spec-csomag dokumentumain végzett **javasolt módosítások konszolidálva**, 4 prioritás-szekcióban:
1. **P0 KRITIKUS** (pilot-blokkoló)
2. **Érdemi spec-bővítések** (új DTO-mezok, új végpontok)
3. **Spec-szelídítések** (1-mondat-átírások)
4. **Háttér / minor** (alacsony prioritás)

Per-tétel egy döntés-státusz mezővel: `accepted` / `rejected` / `under-review` / `deferred`. A management vagy a spec-csapat ezt tölti ki.

A manager-projektben: 40 SF-tétel, 32 accepted/confirmed + 4 under-review + 4 deferred. A spec-csapat-válasz **a pilot-átadás függő pontja**.

### 6. Spec-hivatkozás a kódban / mockban

Minden komponens kommentjében:

```jsx
// Spec: 60_tartalom.md §4.2.5 — News mezősablon
// Forrás: manager-system/preview/screens/a10-hirek-szerkeszto.html
// D-X: manager-system/DECISIONS.md D-13 (ContentEditor publish-bar gomb-sorrend)
```

A fejlesztő (vagy a Claude Code) bármikor visszanyomozza, miért így van.

### 7. Realisztikus magyar mock-data

A mock-rekordok **NEM** "lorem ipsum"-ok. **Magyar nevek, balatonalmadi.hu domainek, valós koordináták**:

- Tóth Béla / Kovács Anna / Szabó Zoltán / Varga Eszter
- 8220 Balatonalmádi, Petőfi Sándor utca 12.
- 47.0344, 18.0244 (Balatonalmádi-szerű koordináták)
- "Útkarbantartó csapat", "Közvilágítás csapat"
- ALM-1052 (display ID minta)

A pilot-átadás után a `seed-data-balatonalmadi-pilot.json` egyetlen forrás-fájlból betöltődik a tenant-DB-be.

### 8. Mock-data konszolidálása JSON-be a végén

Ne hagyd, hogy a mock-adatok 20+ HTML-screen-fájlban szétszórtan duplikálódjanak. A pilot-átadás előtt **egy konszolidált JSON-fájl** (`seed-data-balatonalmadi-pilot.json`):
- 1 tenant + 8 user + 4 group + 12 category + ~50 ticket + activity-log + notes + 9 news + 7 events + 8 city-info + 5 weekly-report = ~270 rekord
- ~100 KB, FK-konzisztens

A fejlesztő ezzel **az első napon** seed-eli a DB-jét és lát realisztikus tartalmat.

### 9. i18n-kulcsok kondenzálása JSON-be

Az minden screen-mock literal-szövegét **egy `i18n-keys-X.json`-be konszolidáljuk**, nested kulcs-struktúrával (`ngx-translate` / Flutter `intl`-kompatibilis):

```json
{
  "manager": {
    "ticket": { "status": { "uj": "Új", "jovahagyva": "Jóváhagyva" } },
    "common": { "action": { "save": "Mentés", "cancel": "Mégse" } }
  }
}
```

A manager-projektben 351 leaf-kulcs / 21 KB. **Ezt a fejlesztő nem fogja egyenként a HTML-mockokból kihámozni.**

### 10. HANDOFF.md mint cross-mapping-réteg

A fejlesztő-átadás **NEM kódot** ad, hanem **átképezési térképet** a mock-világ → cél-tech-stack között.

A manager-projektben: 42 React-mock organism × meglévő Angular `core/`-minta. Pl. *`DataTable` → `[tableState]` directive + `TableStateConfig`*. A cross-mapping a HANDOFF.md egyetlen szekciójában (~80 sor tábla).

**A polgári-projektben** ez: 15-20 HTML-mock widget × Flutter widget-minta (`urbino_theme.dart` szolgáltatások). Pl. *`BottomSheet` → `showModalBottomSheet()` + `Container(decoration: BoxDecoration(borderRadius: BorderRadius.vertical(top: Radius.circular(22))))`*.

### 11. Onboarding-checklist a fejlesztőnek/Claude Code-nak

A HANDOFF.md végén egy **first 5 hours** lista: mit olvass elsőként, melyik fáj nyisd, mivel indítsd a kódolást. A manager-projektben ez egy 5-szakaszos timeline (0-30 perc olvasás → 30-60 felmérés → 60-90 mock-böngészés → 90-180 seed-data + i18n → 180+ első feature).

A polgári-projekten valószínűleg **A bejelentés-felvétel 3-step flow** lesz az első Flutter-feature.

### 12. README + Urbino-hub HTML

Minden átadási csomag tartalmaz:
- **`README.md`** — 1-oldalas belépő útmutató ("hol kezdjem?")
- **`Urbino X.html`** — egy önálló navigációs hub, ami a teljes projekt áttekintését adja a böngészőben (a manager-en: `Urbino Manager.html`)

A `README.md` és a hub-HTML együtt **5 percnyi munka** a kibontás után, és **megszünteti a "hol kezdjek?"-szorongást** a fejlesztő-csapatnak.

### 13. Tone-of-voice + terminológia

Minden tervezési döntés a **DS `TONE-OF-VOICE.md`**-jét követi. **Vocabulary-szabályok**:
- "bejelentés" (NEM ticket / ügyirat / kérelem)
- "lakos" (NEM felhasználó / állampolgár / ügyfél)
- "megoldva" (NEM lezárva / intézkedve)
- "Urbino" (NEM VárosApp — régi név)

A manager-projektben az `i18n-keys-mgr.json` minden kulcsa ezt tükrözi.

---

## Mit NE csináljunk

### 1. NE generálj Angular/Flutter kódot a design-projektben

A design-projekt **vizuális tervet és HANDOFF.md-t szállít**, NEM kódot. A Claude Code (vagy a fejlesztő) képezi át az Angular/Flutter-világba a meglévő infrastruktúra ismereté­vel.

**Kivétel:** ha a meglévő infrastruktúra hiányzik (pl. új projekt, üres repó), és tényleg Angular-starter kell. A manager-projektnél eredetileg starter-szállítást terveztünk, **de Q1 felülbírálva** — a meglévő `core/`-réteg miatt felesleges volt.

### 2. NE pótold az organism-eket inline-szerkesztéssel a screen-mockban

Ha egy screen-mock egy hiányzó organism-et "összerakok inline most"-mintán pótol, **a fejlesztő rosszul portolja**. A manager-projektnél 3 ilyen pótlást a `AUDIT-2.md` §3.3 listázott, és a HANDOFF.md explicit jegyzékbe vette. **Jobb az organism-et először kanonikus formában felépíteni**, és a screen-mock azt használja.

### 3. NE szórjuk szét a mock-data-t a screen-mock-fájlokon

Minden screen-mock saját `USERS`-tömböt + `GROUPS`-tömböt + ... = 8 különböző mock-szettel **6 közös user-rekordra hivatkozik** → inkonzisztens. A pilot-átadás előtt **mindenképp** konszolidált JSON-be.

### 4. NE kezdj el screen-mockot az organism-katalógus előtt

A screen-mockok **vékony composition-réteg**: `AppShell + PageHeader + organism-instance-ok`. Ha az organism-ek még forrnak, a screen-mockok újra-és-újra változnak.

### 5. NE találj ki UI-elemet spec-igazolás nélkül

Minden új UI-elem (`PhoneBanner` az A2-n, a `STATE_BADGE` az A12-n, a custom `PdfInlineStub` az A5-n) **vagy spec-rögzített**, vagy `🔍 UI-találmány`-jelöléssel rögzített a SPEC-COVERAGE-ban, hogy a spec-csapat eldönthesse:
- spec-be felveszik
- vagy visszavonjuk a mockból

A manager-projektnél 14 ilyen UI-találmány keletkezett, 11 visszavont (mock-fix), 3 spec-felé jegyzett.

### 6. NE rögzíts mértékegységeket "mock"-ban a komponens-spec-ben

A 28 screen-mockon **konkrét pixel-számok** voltak rögzítve a CSS-ekben (pl. `grid-template-columns: 36px 1fr 200px 100px 130px 16px`). Ez **NEM** a komponens-spec; ez a mock-implementáció. A komponens-spec a HANDOFF.md cross-mapping-jében elvont mintán ("a sor kebab-cellát kap" — NEM "44px szélességű kebab-cella").

### 7. NE keverjük denormalizált szöveget a stable-ID DTO-szerződéssel

Az `ActivityTimeline`-rekord **stable-ID-tripletet** hordoz a DTO-ban (`eventType` + `fromValue` + `toValue` + `actorId`), NEM denormalizált magyar szöveget. A manager-projekt React-mock **eredetileg denormalizáltan kezdte**, és a SF-12 alapján **iter 7 előtt** mindent stable-ID-formátumra konvertáltunk.

A polgári-projektnél ez különösen érdekes — a polgári `push notification body` is i18n-sablon-kitöltött szöveg, NEM denormalizált payload. **Eleve stable-ID szerződéssel kezdj!**

### 8. NE add hozzá az átadáskor "csillaggal jelölt nyitott kérdéseket"

A HANDOFF.md NEM "kérdés-jegyzék" + "követelmény-katalógus" mix. **A `under-review` SF-tételek külön szekcióban** (HANDOFF.md §4.3), CSAK 3-4 db. A fő törzs csak akkor szerepel, ha a döntés véglegesített.

A manager-projektnél 16 [★] kérdést végigvettünk a `HANDOFF-PREP.md`-ben, a végleges állapotot a HANDOFF.md csak hivatkozja.

### 9. NE iterálj 1-1 organism-en végeláthatatlanul

UX-explorerrel **1 iter alatt eldől**, melyik mintát választjuk. Utána a Hi-Fi-mock **1-2 iter alatt** megépül. Ha 4+ iter telik 1 organism-en, **valami nincs rendben** — talán a scope túl nagy, a spec ütközik egy másikkal, vagy egy döntés-naplós választás kell.

### 10. NE hagyd, hogy a kontextus 70%+ menjen

A Claude session-ben az **iter-snipping kulcsfontosságú**. Régi-iter-ek tartalma a fájlokban kódolva van, a chat-kontextusból ki lehet snipelni. Ha a session 70%-on jár, **valószínűleg csak egy nagy iter-t bír még**.

A manager-projektnél ezt korán implementálva: kb. 14-17 snip-műveletet hajtottunk végre a 35 chat alatt, és sosem mentünk 60% fölé.

---

## Mikor érdemes kérdezni

### Cross-cutting döntés ELŐTT

Ha egy döntés **több screenre kihat** (pl. a manager-nél a Settings-nav-szerkezet, a Tartalom-ág publish-flow, az ActivityTimeline DTO-szerződés), **kérdezd meg a managementet** előbb. Kettő opcióval, indoklással. A manager-projektnél a `D-13` (DataTable-bővítés), `D-14` (Settings-nav), `D-17` (publish-bar) mind management-jóváhagyással születtek.

### Spec-konfliktus észlelésekor

Ha a screen-mock-szándék **eltér a spec-szövegtől**, NE módosítsd a mockot, NE módosítsd a specet — **jegyezz fel egy `🔍` SF-tételt** a `SPEC-FEEDBACK`-be, és kérdezz. Lehet, hogy:
- a mock helyes és a spec elavult (→ spec-szelídítés)
- a spec helyes és a mock-szándék rossz (→ mock-fix)
- mindkettő nyitott (→ management-döntés)

### Iter-térkép elágazáskor

Ha 2+ útvonal lehetséges az iter-utolsó-szakaszában (pl. starter-Angular vs. nincs starter, vagy mock-fix-csomag-most vs. HANDOFF.md-jegyzék), **kérdezz**. A manager-projektben Q1 (starter-szállítás) felülbírálva Iter 7-ben — ha nem kérdeztünk volna, felesleges munkára pazaroltunk volna 1-2 iter-t.

---

## A polgári-projektre fókuszáltan

### Mire figyelj különösen

1. **Mobile tap-targets.** Minden interaktív elem **≥ 44×44px**. A DS-ben `--u-tap-min: 44px`.
2. **Bottom-sheet vs. dialog vs. modal.** Mobile-on a bottom-sheet szinte mindig jobb, mint a center-modal. Csak megerősítés (Sí/Nem) marad center-dialog.
3. **Long-press, swipe, drag.** A natív gesture-pattern-ek (swipe-to-delete, long-press menü, pull-to-refresh) **iOS-en és Android-en eltérőek**. Kérdezd meg a stakeholdert, melyik mintát kövessük.
4. **Theming switch.** A `urbino_theme.dart` `light` mode mellett **dark mode** kell-e a pilotra? A DS jelenleg `Phase 2 backlog`-ban jelöli.
5. **Push notification engedély-kérés időzítése.** **NE** az appindításkor kérd; **első értelmes pillanatban** (pl. a bejelentés-felvétel után, mikor a polgár tudja, miért jönne push). A manager-en NEM volt ez.
6. **Map-widget Loading + Error állapotok.** OSM-tile-letöltés lassú lehet; a pilot-Balaton wifi-lefedettsége vegyes. Tervezz **skeleton + retry** UX-t.

### Mit szabadon átvehetsz a manager-ből

- **A 9-lépéses minta váza** (a Tier-szintek redukálva).
- **A DECISIONS.md / ORGANISMS.md / SITEMAP.md** dokumentum-szerkezete.
- **A SPEC-COVERAGE 4-listás minta** (✅ ⚠ 🟡 🔍).
- **A `SPEC-FEEDBACK-FOR-SPEC-TEAM.md`** 4-szekciós szerkezete.
- **A `seed-data-balatonalmadi-pilot.json`** — közös a manager-rel (a polgári app ugyanazokat a bejelentéseket látja, csak más szemszögből).
- **A HANDOFF.md 10-szekciós szerkezete** (Áttekintés → P0 fix → Cross-mapping → Onboarding-checklist).

### Mit kell újra-tervezni

- **Tier-besorolás** — a polgári app sokkal kisebb felület, valószínűleg 3 tier elég.
- **iOS/Android frame-mintát** vs. manager fix-layout-ot.
- **Mobile-screenshot-szerkezet** (375-414px szélesség).
- **Citizen tone-of-voice arányok** (70-80% warm).
- **Push + bottom-sheet + gesture-pattern**-ek.
- **OSM-tiles + GPS-pattern**.
- **A polgári-spec teljesen más DTO-kkal** (`ReportCreateDto` vs. manager `TicketListDto`).

---

*Ez a best-practice-jegyzet a Urbino Manager UI-csapat 2026.05.27-i tapasztalatából kondenzálva. Az új polgári-projekt szabadon eltérhet ezektől, ha indokolt — de minden eltérés szándékos legyen, NEM véletlen.*