# SCREEN-CONVENTIONS — Urbino Manager · screen-mock konvenciók

**Dátum.** 2026.05.24 · **Forrás-állapot.** 28 screen-fájl a `manager-system/preview/screens/`-ben. **Cél.** A 9. lépés (átadási csomag) előtti vizuális és strukturális konvenciók dokumentálása. A Claude Code-átadás során ez a fájl mondja meg, "így van a 28 screen mintázva, így kell az új-screent is".

**Olvasási útmutató.** Minden szekció: **A konvenció** · **Miért így** · **Példa fájl(ok)**. Az `[eltérés]` blokk dokumentálja az explicit kivételeket; ezeket NEM hibaként, hanem indokolt különbségként kezeli.

> **Scope.** Ez a fájl **konvenció-dokumentum, NEM fix-up checklist.** A 28 meglévő screen-mock fizikai módosítását NEM írja elő (l. user-megbeszélés 2026.05.24: regresszió-kockázat + Claude Code Angular-portolás redundáns React-cleanup-pal). A meglévő inkonzisztenciák az AUDIT-2.md cleanup-listájában szerepelnek; ez a fájl ÚJ screen építéséhez ad mintát, NEM régi javításához.

---

## 1. Fájl-struktúra — a 4 kötelező blokk

Minden screen-mock-fájl 4 strukturális blokkból áll, ebben a sorrendben:

```html
<!doctype html>
<html lang="hu">
<head>
  <!-- 1. META + TITLE + THUMBNAIL -->
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <title>Urbino Manager · S<N> — A<N> <Screen-név> (screen)</title>
  <template id="__bundler_thumbnail" data-bg-color="#2E63EB">
    <svg>...</svg>  <!-- bundler-szplash, 1200×800 -->
  </template>

  <!-- 2. CSS LINK-TAG SOR — DS előbb, manager utoljára -->
  <link rel="stylesheet" href="../../../design-system/colors_and_type.css">
  <link rel="stylesheet" href="../../../design-system/components/layout.css">
  <!-- ... per-screen szükséges DS-component-css-ek ... -->
  <link rel="stylesheet" href="../../organisms/_styles.css">  <!-- MINDIG utolsó -->

  <!-- 3. INLINE CSS — screen-scope szabályok -->
  <style>
    /* screen-header sablon (copy-paste-elhető) */
    /* a<N>-page > * + * { margin-top: ... } */
    /* a<N>-* per-screen helper-osztályok */
  </style>
</head>
<body class="urbino-mgr">

  <!-- 4a. SCREEN-HEADER (kötelező HI-FI mockon, OPCIONÁLIS explorer-fájlon) -->
  <header class="screen-header">
    <div class="screen-header__id">A<N></div>
    <div class="screen-header__body">
      <h1 class="screen-header__title">...</h1>
      <p class="screen-header__purpose">...</p>
      <div class="screen-header__refs">
        <span><strong>Spec:</strong> <code>...md</code></span>
        <span><strong>Döntések:</strong> D-<N>, ...</span>
      </div>
    </div>
  </header>

  <!-- 4b. ROOT + SCRIPT-SRC SOR -->
  <div id="root"></div>
  <script src="https://unpkg.com/react@18.3.1/...integrity-hash...></script>
  <script src="https://unpkg.com/react-dom@18.3.1/...integrity-hash...></script>
  <script src="https://unpkg.com/@babel/standalone@7.29.0/...integrity-hash...></script>
  <script src="../../data/mock.js"></script>                  <!-- chrome-mock -->
  <script type="text/babel" src="../../../design-canvas.jsx"></script>
  <script type="text/babel" src="../../organisms/icon.jsx"></script>      <!-- mindig elsőként -->
  <script type="text/babel" src="../../organisms/<other>.jsx"></script>   <!-- függés-rendben -->
  <script type="text/babel">
    // 5. INLINE BABEL — a screen-mock kompoziciója
    // A. Mock-data (per-screen, kanonikus a screenhez)
    // B. Helper-komponensek
    // C. State-komponensek (StateNormal, StateLoading, ...)
    // D. <App> root + <DesignCanvas><DCSection><DCArtboard>...
    // E. ReactDOM.createRoot(...).render(<App />);
  </script>
</body>
</html>
```

**Példa.** `a4-fooldal.html`, `a5-riportok-lista.html`, `a10-hirek-szerkeszto.html` — mind a 4 blokkot pontosan ebben a sorrendben hordozza.

---

## 2. CSS link-tag sorrend (KÖTELEZŐ)

**A konvenció.** A `<link rel="stylesheet">` tag-eknek **ebben a sorrendben** kell betöltődniük:

```
1. design-system/colors_and_type.css        (tokenek + alap)
2. design-system/components/layout.css      (--u-page, .u-page--*)
3. design-system/components/<component>.css (per-screen szükséges DS-component-ek)
   — gyakori: avatar, breadcrumb, button, card, chip, dialog, form-field,
     icon, input, list-tile, pagination, popover, table, tabs, toast
4. manager-system/organisms/_styles.css     (MINDIG az utolsó)
```

**Miért így.** A CSS-cascade a sorrend-szerinti utolsó-deklaráció-wins elvét követi. A DS-szabályok először érvénybe lépnek (default-token-értékek), majd a manager-organism-szabályok felülbírálhatják a manager-specifikus mintákon. **Ha a `_styles.css` előbb betöltődik, a DS-tab-color override-okat a manager-cascade nem éri el.**

**Konkrét eset.** A `_styles.css` `.mgr-tab-filter` szelektor magyarázata az `[data-tone="overdue"]` modifierre — ezt a `tabs.css` `.u-tabs__count` szabályait felülírja. Ha a sorrend fordított, az overdue-dot szín nem érvényesül.

**Eltérés.** Az UX-explorer fájlok (`*-explorer.html`) kevesebb DS-component-css-t használnak — csak a `colors_and_type.css` + `layout.css` + esetenként 1-2 component, mert az inline `.ux-card__*` mockoknak nincs szükségük a teljes komponens-set-re. ✅

---

## 3. Script-src sorrend (KÖTELEZŐ)

**A konvenció.**

```
1. React + ReactDOM + Babel (UMD + integrity-hash, PINNED)
2. data/mock.js                              (chrome-mock: tenant + currentUser + navCounts)
3. design-canvas.jsx                         (DesignCanvas + DCSection + DCArtboard)
4. organisms/icon.jsx                        (MgrIcon — szinte minden organism függ tőle)
5. organisms/<egyéb>.jsx                     (függés-rendben — l. ORGANISMS.md "Cross-organism fogyasztások")
```

**Függés-rend szabályok** (AUDIT.md 4.1):
- `icon.jsx` mindig az **első** organism-script (MgrIcon-t minden más organism `window.Icon`-ként alias-ezi).
- `icon-picker.jsx` `category-tree-editor.jsx` ELŐTT (CTE fogyasztja az iconGlyph-et).
- `map-widget.jsx` `location-picker.jsx` ELŐTT (LP fogyasztja a MapWidget-et).
- `user-picker.jsx` `group-member-list.jsx` ELŐTT (GML edit-mode-ban beágyazva UP-t használ).
- `publish-state-chip.jsx` + `cover-image-uploader.jsx` + `rich-text-editor.jsx` + `photo-uploader.jsx` MIND `content-editor.jsx` ELŐTT.
- A többi: betűrendben, vagy a screen-fájl logikai csoportosítása szerint.

**Miért így.** A `Object.assign(window, ...)` exportok script-tag-sorrendben futnak; a fogyasztó wrapper-IIFE az `window.X`-et destrukturálva olvassa be — ha a fogyasztó előbb fut, `undefined`-et kap.

**Példa.** `a4-fooldal.html:215-225` mind a 8 organismet függés-rendben tölti: `icon → page-header → app-shell → user-chip → empty-state → status-track → kpi-card → team-performance-table`.

**Pinned-versions.** A React + ReactDOM + Babel SHA-384 integrity-hash-szel rögzített verziókat használ (`react@18.3.1`, `babel-standalone@7.29.0`). **Sose használj nem-pinned URL-t** (l. system-prompt React + Babel section); a Claude Code-átadáskor a fejlesztő ezt Angular-import-ra cseréli, de a mock-szinten kötelezően-pinned.

---

## 4. Screen-header pattern

**A konvenció.** Minden hi-fi screen-mock kötelezően kezdődik egy `<header class="screen-header">` blokkal a `<body>` tetején, a `<div id="root">` ELŐTT. A blokk 3 sub-elemet hordoz:

```html
<header class="screen-header">
  <div class="screen-header__id">A<N></div>          <!-- 44×44 kék badge -->
  <div class="screen-header__body">
    <h1 class="screen-header__title">
      Screen-név <code>/url/path</code>              <!-- mono-formátumú route a code-tagben -->
    </h1>
    <p class="screen-header__purpose">
      Egy-két mondat a vezetőről + spec-szám.        <!-- ~120-200 char, text-wrap: pretty -->
    </p>
    <div class="screen-header__refs">
      <span><strong>Spec:</strong> <code>10_bejelentes_lista_es_adatlap.md</code> §4.2</span>
      <span><strong>Döntések:</strong> D-3, D-13</span>
    </div>
  </div>
</header>
```

**A `screen-header__*` CSS-szabályok** minden screen-fájl `<style>` blokkjának első ~10 sora. Ezek **copy-pastelendőek** szabályonként, mert nincsenek a `_styles.css`-ben:
- `--u-blue-50` háttér + `--u-blue-200` border-bottom
- 20px függőleges + 32px vízszintes padding
- 44×44 `.screen-header__id` `--u-primary` háttéren, 18px Display-font
- 18px `__title`, 13px `__purpose`, 12px `__refs`

**Miért így.** A screen-header **belső dokumentáció** — egy fejlesztő a HTML-fájlt megnyitva azonnal lát screen-azonosítót, spec-hivatkozást, döntés-naplót. Ezt a Claude Code-átadás során NEM hagyjuk el — kontextus-bridge a mock ↔ Angular-component között.

**[eltérés #1] — `a1-bejelentes-lista-explorer.html`** *(szándékos, dokumentált)*.
Az A1-lista UX-explorer-fájl saját inline `.ph__*` osztálycsaládot használ a screen-header helyett (l. `a1-bejelentes-lista-explorer.html:452-456`). Ez **explorer-jellegű decoration** — a screen-mock-szabványoknak nem kell megfelelnie, mert maga is a screen-szintű kérdéseket vázolja fel. Új-screen építésekor a fenti standard `screen-header`-pattert kötelezően használd; ez az egyetlen ismert eltérés.

**[eltérés #2] — explorer-fájlok** *(megengedett)*.
A többi 5 explorer (`a1-adatlap-explorer`, `a1-mobile-explorer`, `a5-explorer`, `a7-lista-explorer`, `a8-explorer`, `s6_5-explorer`, `s13-explorer`, `a10-explorer`) kötelezően screen-header-t hord, de a `screen-header__id` mezőben kreatív azonosítók is elférnek (pl. `S6.5`, `S13`).

---

## 5. PageHeader vs. screen-header — két különböző dolog

**KRITIKUS megkülönböztetés.** Ezek két különálló elem:

| | `screen-header` | `PageHeader` |
|---|---|---|
| **Hol él?** | A screen-mock-fájl `<body>` tetején, a `<div id="root">` ELŐTT | Az `AppShell` content-területén belül, a React-render fában |
| **Mit jelenít meg?** | A screen-mock metaadatait (mock-doksi) | A renderelt admin-felület page-szintű címét és CTA-it |
| **Hogyan néz ki?** | Kék banner, screen-id badge | DS-szabványos cím + actions slot |
| **Megmarad a productionben?** | NEM — mock-szintű decoration | IGEN — kanonikus organism |

A `screen-header` a screen-mock-fájl **dokumentációja**, a `PageHeader` a render-fa **része**. A 9. lépés Angular-portoláskor a `screen-header` eltűnik (mock-only), a `PageHeader` mint `<app-page-header>` komponens létezik tovább.

---

## 6. Page-class és flow-spacing minta

**A konvenció.** Minden screen az `AppShell`-en belül egy `.a<N>-page` osztályú root-divet vesz fel, amely:

```css
.a<N>-page {
  /* lehet padding/max-width per-screen */
}
.a<N>-page > * + * {
  margin-top: var(--u-space-4);  /* vagy 3, 5 — döntés-szabad */
}
```

**A `> * + *` minta** a "flow-spacing" rövidítése: a közvetlen child-ek közé `gap` helyett margin-top-ot rak az első kivételével. A 28 screenből **12-ben jelenik meg** (AUDIT-2.md 5.2).

**Megfontolandó alternatíva** (jövőre): a DS `--u-page-py` + flexbox `gap` minta. Most kötelezetlen — az inline-`> * + *` és a flex+gap egyenértékűen elfogadott. **Új screen építésekor mindkettő OK, de a teljes screen-fájlon belül egységesen.**

---

## 7. State-mátrix konvenció — `DesignCanvas` + `DCSection` + `DCArtboard`

**A konvenció.** A screen-mock-fájl 1-2 `DCSection`-ben gyűjti az állapotait (`State<X>` komponens-szerű React-komponenseket):

```jsx
const W = 1280;
const H_NORMAL = 1280;  // per-screen-állapot magasság-konstans
const H_LOADING = 900;
const H_EMPTY = 600;
// ...

const App = () => (
  <DesignCanvas>
    <DCSection
      id="primary"
      title="A<N> <screen-név> — fő állapot"
      subtitle="...">
      <DCArtboard id="normal" label="1 · Normál snapshot — ..." width={W} height={H_NORMAL}>
        <StateNormal />
      </DCArtboard>
    </DCSection>
    <DCSection
      id="states"
      title="A<N> <screen-név> — másodlagos állapotok"
      subtitle="...">
      <DCArtboard id="loading"  label="2 · Loading skeleton ..." width={W} height={H_LOADING}>...</DCArtboard>
      <DCArtboard id="empty"    label="3 · Empty state ..." width={W} height={H_EMPTY}>...</DCArtboard>
    </DCSection>
  </DesignCanvas>
);
```

**Konvenciók a DCArtboard-en:**
- `id` snake_case (`normal`, `loading-overlay`, `editing-members`, `first-time`)
- `label` `<sorszám> · <rövid-magyarázat> — <megerősítő részlet>` (lásd példák)
- `width` általában **`W = 1280`** desktop-screenekre, **`960`** vagy **`820`** UX-explorer artboardokra, **`375`** mobil-screenekre
- `height` egy **per-state magasság-konstans** (`H_NORMAL`, `H_LOADING`, `H_EMPTY`) — fix érték, nem dinamikus, mert a Canvas méretezi a viewport-ot

**Miért így.** A DesignCanvas pan/zoom-grid felülete; a fix-méretű artboard megengedi a vizuális összehasonlítást side-by-side. A magasság-konstans pre-mért érték — minden state egy konkrét állapot snapshot-ja, nem responsive container.

---

## 8. Mock-data konvenció (per-screen)

**A konvenció.** A `data/mock.js` 3 hasznos kulcsot szállít (`tenant`, `currentUser`, `navCounts`), amelyek **chrome-mock-ként** szolgálnak: az `AppShell → LeftNav` ezt fogyasztja a tenant-név és felhasználói avatar megjelenítésére. **A screen-tartalmi mock-ok per-screen inline-definiáltak**, mert (a) a 28 screen-fájl mindegyike más-más adatmodelt fed, (b) a központi mock újra-fogyasztása zavart kelt, ha a screen-fájl gazdagabb adatszerkezettel él.

**Példa per-screen mock** (`a1-bejelentes-lista.html` mintán):

```jsx
const TICKETS_ALL = [
  { id: 1, displayId: 'BA-2026-1058', title: 'Kátyú a Petőfi utcán', status: 'jovahagyva',
    priority: 'Normal', categoryId: 'utak', assignedUserId: 3, dueDate: '2026-05-25',
    createdAt: '2026-05-20T14:32', isOverdue: false, /* ... */ },
  // ... 50 elem összesen
];
const STATUS_LABELS = { uj: 'Új', jovahagyva: 'Jóváhagyva', /* ... */ };
const TABS = [
  { key: 'open', label: 'Új', count: TICKETS_ALL.filter(t => t.status === 'uj').length },
  // ...
];
```

**Konvenciók:**
- A mock-szekciók a `<script type="text/babel">` blokk legtetején, kommentált fejezet-szeparátorokkal (`/* =========...... Mock — A1 tickets =========... */`).
- Az enum-értékek (status, priority) **a spec-modell-mátrix kis-betűs változatát** használják (`status: 'jovahagyva'`), nem a magyar display-szöveget (`'Jóváhagyva'`).
- Display-szöveg-leképezések külön konstans (`STATUS_LABELS`, `PRIO_LABELS`, `ROLE_LABELS`).
- ID-k egész számok (`id: 3`), displayId-k spec-szerű (`'BA-2026-1058'`).

**Cross-screen inkonzisztencia ismert** (AUDIT-2.md 6.2): az `a7-csoport-adatlap` és `a8-felhasználók-lista` átfedő rekordnévvel, de eltérő id-vel dolgozik. **Új screen építésekor ne keverj id-t** más screen-fájl mockjával, de név-és e-mail-konzisztenciát tartsd fenn (pl. "Szabó Zoltán" mindig "szabo.z@balatonalmadi.hu" + initials "SZ").

---

## 9. Naming-konvenció — CSS osztályok és React-komponensek

**CSS osztály-prefix per screen.** Minden screen-fájl saját `.a<N>-*` (vagy `.a<N><suffix>-*`) prefix-szel él az inline CSS-blokkban:

| Screen | Prefix | Megj. |
|---|---|---|
| A1 lista | `.a1-*` | bejelentes-lista.html |
| A1 lista mobile | `.a1m-*` | mobil-vetület |
| A1 adatlap | `.a1d-*` | adatlap-suffix |
| A5 adatlap | `.a5d-*` | uo. |
| A7 adatlap | `.a7d-*` | uo. |
| A8 adatlap | `.a8d-*` *(vagy `.mgr-user-detail-*`)* | a8-felhasznalok-adatlap.html **erősen** a `mgr-user-detail` family-re támaszkodik (l. AUDIT-2.md 5.1) |
| A10 lista | `.a10-*` | uo. |
| A10 szerkesztő | `.a10e-*` | szerkesztő-suffix |

**Belső struktúra BEM-szerű:**
- `__elem` (child element): `.a4-head__title`, `.a4-head__cta-block`
- `--mod` (modifier): `.a8-uc__av--invited`, `.a5d-status--generating`

**React-komponens-nevek.** A `State<X>` (artboard-szintű state-mock) + a `<X>Cell`, `<X>Row`, `<X>Card`, `<X>Section` (intra-screen helper) minták. Helper-komponensek a `<script>` blokkon belül, a State-komponensek alatt — nem a `window`-ra exportáltak (mock-szintű).

**Miért így.** A `.a<N>-*` prefix szigorúan elválasztja a screen-fájl saját szabályait a globális `.mgr-*` family-ktől. Egyetlen szivárgás sincs ismert (`grep -E "\.mgr-" inline-CSS` minden screen-fájlon üres).

---

## 10. Inline CSS volume — mi mehet inline, mi nem

**A konvenció.**

| Hol él? | Mi? |
|---|---|
| `manager-system/organisms/_styles.css` | Organism-szintű (`.mgr-<organism>-*` osztályok). Egy organism teljes vizuális szerződése egy szekcióban. |
| Screen-fájl inline `<style>` | Screen-scope helper (`.a<N>-*`, `.a<N>d-*`). Csak az adott screen-en élő layout-mintázat. |
| Component-szintű inline `style={}` | Csak ha **valóban dinamikus** (pl. `width: ${pct}%`). Statikus stílust soha. |

**A 4810 sornyi inline CSS** (közel-egyenlő az `_styles.css`-szel) szándékos: a screen-fájlok screen-szintű mintáit nem akarjuk a globális `_styles.css`-be hígítani — ott `mgr-*` osztály-bloat lenne. **Új screen építésekor a screen-scope CSS bátran inline.**

**[eltérés]** Az `a8-beallitasok-felhasznalok-adatlap.html` mindössze 21 sornyi inline CSS-t hord, mert a teljes layout a `mgr-user-detail-*` organism-szintű family-re támaszkodik. Ez **erősebb organism-fogyasztás-minta**, helyes, és új user-adatlap-építésre is mintaként szolgál.

---

## 11. Iconography — `<Icon name="..." size={N} />`

**A konvenció.** Minden organism + screen-fájl egységesen használja:

```jsx
const Icon = window.MgrIcon;
// ...
<Icon name="plus" size={14} />
<Icon name="arrow-left" size={16} />
<Icon name="chevron-right" size={14} />
```

**Méretek:**
- 14px — gomb-belső, inline szöveg
- 16px — sor-szintű inline (DataTable cella, list-item)
- 20px — page-header, nav-item
- 28px — nagyobb decoration (KpiCard, EmptyState)

**Színek.** `currentColor` (alapértelmezett) — soha ne állítsd külön. A szöveg-szín fölött öröklődik.

**Lucide-pótlás.** A `MgrIcon` egy 50-ikon-mappolás-rétget rendel a Lucide-stroke-stílushoz. Hiányzó ikon esetén: új-key felvétele az `icon.jsx` `ICON_MAP` objektumába, NEM inline SVG a screen-fájlban.

---

## 12. Hivatkozott tételek

- **AUDIT.md** (2026.05.22) — Tier-0..Tier-4 záró audit, ami a screen-fázis indítása előtt készült.
- **AUDIT-2.md** (2026.05.24) — 8. lépés végi audit. **3 cleanup-tétel** a SCREEN-CONVENTIONS.md scope-ján belül lefutva (P0 — `_styles.css` header-komment + halott `<script>` 2 helyen). A többi a HANDOFF.md scope.
- **DECISIONS.md** D-1..D-17 — Az UX-döntés-napló. Minden screen-mock-fájlnak a `screen-header__refs` szekciójában hivatkoznia kell a releváns D-számot.
- **ORGANISMS.md** — A kanonikus organism-API + Tier-besorolás. **A screen-mock-fájl ENNEK alapján fogyaszt, NEM saját inline-implementációval.** (3 ismert inline-pótlás az AUDIT-2.md 3.3-ban dokumentált, HANDOFF.md-ben átadási megjegyzés.)

---

## Záró összegzés

A 28 screen-fájl **konzisztens 11 dimenzión át** (fájl-struktúra, CSS link-tag-sorrend, script-src-sorrend, screen-header, page-class, state-mátrix, mock-konvenció, naming, inline CSS volume, iconography, font-méretek). **2 explicit eltérés**: az A1-lista-explorer saját `.ph__*` decoration-családja, és az A8-adatlap erős `mgr-user-detail`-family-fogyasztása. Mindkettő indokolt, dokumentált.

A 9. lépés átadásakor a fejlesztő ezt a fájlt kapja mint "új-screen-build-mintát"; a fenti 11 dimenzió mellett a kanonikus organism-API (ORGANISMS.md) és a HANDOFF.md PrimeNG-mappingje együtt elegendő.

*Ez a dokumentum az 1.3 iter eredménye. Folytatás: 1.4 HANDOFF-PREP.md (átadás-előkészítő kérdések).*
