# Greenmedical DS — guide pre AI agentov

Template-based design system pre NaMaximum / Greenmedical e-shop.
Stack-agnostic: vanilla HTML + CSS + JSON. Žiadne npm, žiadny build.

## TL;DR pre agenta

1. **Tokens** sú v `tokens.css` (CSS custom properties) — toto je zdroj pravdy.
2. **Templates** v `templates/` sú reálne, funkčné HTML stránky (PDP, Cart) — slúžia ako referencia + copy-paste base.
3. **Prototypes** v `prototypes/` sú React/JSX zdrojáky tých templatov — čítaj ich keď potrebuješ pochopiť stav, dáta, logiku.
4. **Showcase** (`index.html`) je human-facing preview — neimportuj z neho do projektov.
5. Konzument berie `tokens.css` + `assets/fonts/` + požadovaný HTML/CSS z `templates/`. Hotovo.

## Reálny projekt (kde žije business logika)

Tento DS je **iba vzhľad**. Skutočná business logika (cenotvorba, sklad, variant rezolúcia, AJAX, množstevné zľavy, gift logic, auth, kontrola dostupnosti) žije v **real projekte**:

**Lokácia:** `~/Library/LocalDevelopment/sandbox/venalio-greenmedical/`
**Origin:** `gitlab.blueweb.sk/bwsro/venalio/venalio-greenmedical`
**Stack:** Nette PHP + Latte templating + Doctrine ORM

### Kde hľadať business logiku

| Otázka | Pozri sem |
|---|---|
| Cena variantu, discount, permanent_price | `app/templates/FrontendModule/namaximum/Product/_form.latte` (483 LOC) + `app/Facades/DiscountFacade.php` |
| Stock, days_availability, stock_option_id, restock | `_form.latte` + `app/Model/Repositories/Product*Repository.php` |
| Množstevné zľavy (qty tiers) | `app/Facades/DiscountFacade.php` + variant data v `_form.latte` |
| Gift bonus pri variant kúpe | `app/Facades/GiftsFacade.php` + `app/Model/Repositories/GiftCategoriesRepository.php` + `app/Model/Repositories/BonusProductsRepository.php` |
| Free shipping progress | `app/templates/FrontendModule/namaximum/Cart/default.latte` + `app/Facades/DeliveryFacade.php` |
| PDP rendering, AJAX form, signal handlers | `app/FrontendModule/Presenters/ProductPresenter.php` |
| Cart rendering, line items, qty change AJAX | `app/FrontendModule/Presenters/CartPresenter.php` |
| Variant matrix (size × flavor kombinácie) | `_form.latte` cez `$missingValues` array (cascading availability) |
| Doctrine entities | `app/Entities/` (málo) + repositories v `app/Model/Repositories/` (veľa) |
| Doctrine repositories (Product/Variant/Cart/Discount/Gift) | `app/Model/Repositories/Products*Repository.php`, `Carts*Repository.php`, `Discount*Repository.php`, `Gift*Repository.php` |
| Forms (frontend) | `app/FrontendModule/Forms/` |
| Forms (backend admin) | `app/BackendModule/CatalogModule/Forms/`, `app/BackendModule/ContentModule/Form/` |
| i18n + tenant translations | `app/Localization/Translator.php` (custom service, prečítaj implementáciu) |
| Routing (custom URL routes, product routes, domain routing) | `app/Routing/RouterFactory.php` + `ProductRoute.php` + `DomainRoute.php` |
| Multi-tenant `platform=venalio` | `app/Bootstrap.php` + module configs |
| Pricing facades (cenotvorba, currency, VAT) | `app/Facades/DiscountFacade.php`, `CurrencyConversionFacade.php`, `app/Model/VatValidator.php` |
| Cart facade (košík business rules) | `app/FrontendModule/Facades/CartFacade.php` (frontend) + `app/Facades/OrderFacade.php` (orders) + `CartsRepository.php` |

### Vzťah DS ↔ real

- **DS prototypy** (`prototypes/*.jsx`) majú **mock dáta** v `D_VARIANTS` matrix — simulujú výstup business logiky pre vizuálny preview cez tweaks panel. **Nie sú zdroj pravdy pre business pravidlá.**
- Keď user pýta na **vzhľad** alebo **UI správanie** — odpoveď je v DS (templates, JSX, tokens).
- Keď user pýta na **business pravidlo** alebo **prečo sa správa takto v reále** — odpoveď je v real projekte (Latte, PHP, Doctrine).
- Keď user pýta na **flow medzi tým** (ako prototype mapuje na real impl) — pozri `WORKFLOW.md` v tomto repo.

### Anti-pattern

Neodpovedaj že business logika je v `prototypes/PDPDesktop.jsx`. To sú iba mock dáta + UI state pre prototype. Reálne pravidlá sú v Nette PHP + Latte v real projekte.

## Token vocabulary (REÁLNE názvy z `tokens.css`)

### Colors
| Var | Hex | Použitie |
|---|---|---|
| `--color-1` | `#0077BC` | Primary brand blue. CTA bg, links, active state. |
| `--color-1-light` | `#00AEEF` | Hover na CTA, info strip. |
| `--color-1-lighter` | `#BED0D7` | Subtle borders, focus shadow. |
| `--color-1-darker` | `#1A5282` | Pressed state, header secondary. |
| `--color-1-tint` | `#F0F7FC` | Selected radio card bg, soft surface. |
| `--color-2` | `#F96628` | Secondary orange. **Pozor**: použiť striedmo. |
| `--color-sale` | `#DD3030` | Reálne sale ceny (nie len discount badge). |
| `--color-error` | `#E6452B` | Form errors. |
| `--color-error-bg` | `#FFD7D7` | Error message bg. |
| `--color-success` | `#26BB59` | In-stock pill, success states. |
| `--color-success-bg` | `rgba(38,187,89,.08)` | Success message bg. |
| `--color-ok` | `#428011` | Free shipping note. |
| `--color-warn-bg` | `#FFF7E6` | Warning message bg. |
| `--color-warn-border` | `#F3DFA5` | Warning border. |
| `--color-warn-ink` | `#8A5A00` | Warning text. |

### Neutrals
| Var | Hex | Použitie |
|---|---|---|
| `--ink` | `#1B1B1B` | Body text default. |
| `--ink-2` | `#111` | Display headings. |
| `--ink-3` | `#333` | Secondary body. |
| `--muted` | `#666` | Captions, meta. |
| `--muted-2` | `#8B8B8B` | Placeholder, disabled. |
| `--line` | `#E2E8F0` | Card/input border. |
| `--line-soft` | `#EEE` | Dividers. |
| `--bg-soft` | `#F7FAFC` | Row hover, soft surface. |
| `--bg-alt` | `#F4F4F4` | Alt section surface. |
| `--surface` | `#FFF` | Default card/page bg. |

### Typography
- `--font-heading` = `'Montserrat', system-ui, ...` (display + UI chrome)
- `--font-body` = `'Satoshi', system-ui, ...` (body + tabular numerics)
- Sizes: `--fs-display` (48px), `--fs-h1` (32px), `--fs-h2` (22px), `--fs-h3` (18px), `--fs-body` (15px), `--fs-body-sm` (14px), `--fs-caption` (13px), `--fs-label` (13px), `--fs-micro` (11px)
- Line-heights: `--lh-display` (1.05), `--lh-h1` (1.15), `--lh-body` (1.5), `--lh-caption` (1.4), `--lh-label` (1.2)
- Letter-spacing: `--ls-display` (-0.02em), `--ls-h1` (-0.01em), `--ls-caption` (0.02em), `--ls-label` (0.08em)
- Weights: `--fw-reg` (400), `--fw-med` (500), `--fw-semi` (600), `--fw-bold` (700), `--fw-black` (900)

### Spacing (8pt grid)
`--s-1` (4px), `--s-2` (8px), `--s-3` (12px), `--s-4` (16px), `--s-5` (20px), `--s-6` (24px), `--s-8` (32px), `--s-12` (48px), `--s-16` (64px), `--s-24` (96px)

### Radii
`--r-sm` (6px), `--r-md` (10px), `--r-lg` (14px), `--r-pill` (999px)

### Elevation
- `--shadow-sm` — micro lift na karty, inputy
- `--shadow-md` — primary CTA hover, modals
- `--shadow-focus-ring` — focus-visible outline alternative

### Motion
- `--ease-out` = `cubic-bezier(.2,.8,.2,1)`
- `--dur-fast` (120ms), `--dur-med` (180ms), `--dur-slow` (280ms)

## Class naming conventions

Existujúce templates používajú **page-scoped prefix** convention:
- `.pdp-d-*` = PDP desktop scope (`pdp-desktop.css`)
- `.pdp-m-*` = PDP mobile scope (`pdp-mobile.css`)
- `.cart-*` = Cart scope (`cart-desktop.css`, `cart-mobile.css`)

**Toto je zámerné** — každý template je samostatne extrahovateľný a nemá kolízie. Keď extraktuješ kus do iného projektu:

- **Variant A (zachovaj prefix):** Skopíruj sekciu `.pdp-d-*` ako-je → bezpečné, žiadne kolízie.
- **Variant B (preimenuj):** Find/replace `.pdp-d-` → `.tvoj-prefix-` keď chceš čistejší naming.

V budúcnosti, keď budeme re-authorovať komponenty do `components/`, pôjdeme čistou BEM konvenciou (`.pill__price`, `.pill--selected`). Zatiaľ tam nič nie je.

## Workflow pre konzumenta (typický prompt agentovi)

Keď ťa userprosi vygenerovať UI pre iný projekt (napr. Latte template, React, Vue):

1. **Načítaj `tokens.css`** do hosting projektu (`<link>` alebo `@import`).
2. **Načítaj fonty:** skopíruj `assets/fonts/` alebo nahraj do CDN, uprav `@font-face` cesty v `tokens.css`.
3. **Identifikuj požadovaný UI patch** — PDP? Cart? Komponent z PDP (variant pill, restock modal)?
4. **Otvor relevantný template** v `templates/{name}.html` + jeho `.css` súbor.
5. **Skopíruj** požadovaný HTML blok + súvisiace CSS rules (filtruj podľa class prefixu).
6. **Adaptuj** na cieľový framework: JSX → React, HTML → Latte/Twig/Blade. Logiku stavu pozri v `prototypes/PDPDesktop.jsx` (D_VARIANTS matrix, useEffect-y, atď.).
7. **Zachovaj** všetky `var(--...)` referencie. **Nikdy** neinlinuj brand farby ako hex.

## Anti-patterns (čo NErob)

- ❌ Nepíš `color: #0077BC` — vždy `color: var(--color-1)`.
- ❌ Nekopíruj `pdp-desktop.css` celý do projektu — sú v ňom 3 800 LOC, vyber len čo potrebuješ.
- ❌ Neimportuj z `showcase/` — to je iba UI pre human review.
- ❌ Nepoužívaj `.pdp-d-*` prefix v projekte ktorý nie je PDP — premenuj alebo zachovaj iba pre PDP-relevantné kúsky.
- ❌ Negeneruj nové farby. Ak chýba semantic token (napr. `--color-info`), pridaj ho do `tokens.css` so zdôvodnením.

## Locale

- Primárna lokalizácia: **SK**.
- HU strings: `prototypes/pdp-i18n.jsx` (export `i18n.hu.*`).
- Konzument by mal extrahovať strings do svojho i18n systému (Latte `_('...')`, React i18next, atď.).

## Štruktúra repa

```
greenmedical-ds/
├── tokens.css                # ⭐ design tokens (zdroj pravdy)
├── manifest.json             # brand metadata + index
├── README.md                 # human intro
├── AGENTS.md                 # tento súbor
│
├── templates/                # reálne, funkčné HTML referencie
│   ├── pdp-desktop.html      # + pdp-desktop.css
│   ├── pdp-mobile.html       # + pdp-mobile.css
│   ├── cart-desktop.html     # + cart-desktop.css
│   └── cart-mobile.html      # + cart-mobile.css
│
├── prototypes/               # React/JSX zdrojáky templatov (referencia)
│   ├── PDPDesktop.jsx, PDPMobile.jsx
│   ├── Cart.jsx, CartMobile.jsx, CartParts.jsx
│   ├── Icons.jsx             # SVG icon komponenty
│   ├── pdp-i18n.jsx          # SK + HU strings
│   └── ios-frame.jsx         # mobile preview shell
│
├── components/               # (zatiaľ prázdne — re-authoring on demand)
├── patterns/                 # (zatiaľ prázdne)
│
├── showcase/                 # human-facing preview (nie pre import)
│   ├── showcase.css
│   └── showcase.js
│
├── index.html                # showcase entry (GH/Cloudflare Pages)
└── assets/
    ├── fonts/                # Montserrat + Satoshi woff2
    ├── badges/               # GMO-free, vegan, lacto-free SVG
    ├── certifications/       # HACCP, GMP, EU Organic SVG
    ├── icons/                # (rezervované pre custom SVG sprite)
    ├── img/                  # placeholder produktové obrázky
    ├── heureka.png
    ├── logo-namaximum.svg
    ├── logo-min.svg
    └── logo-black.png
```

## Cross-project workflow

DS nie je samostatný produkt. Konzument je **Venalio Greenmedical** (Nette / Latte, `gitlab.blueweb.sk/bwsro/venalio/venalio-greenmedical`) cez `git subtree` ako `vendor/greenmedical-ds/`.

Tok je bidirectional:

- **DS → real**: `tokens.css` + `templates/` ako zdroj pravdy. Real projekt `git subtree pull` po DS version bumpe.
- **Real → DS**: production bug / edge case → designer fixne prototyp v DS → version bump → real znova pull.

Prototyp lifecycle (`manifest.json → templates[].status`): `draft` → `wip` → `approved` → `impl-in-progress` → `live`.

Full spec, role responsibilities, scenáre a presné príkazy: [`WORKFLOW.md`](WORKFLOW.md).

## Versioning

- SemVer v `manifest.json`.
- Token zmena (rename, value change) = minor bump.
- Pridanie nového tokenu = patch.
- Premenovanie tokenu = major (breaking).
- `CHANGELOG.md` — keď sa repo rozbehne, pridaj.

## Otázky / problémy

Ak zistíš v `tokens.css` chýbajúci semantic alias, hardcoded hex v templates, alebo nesúlad medzi prototype a template — **flagni to v PR namiesto silent fix**. Token systém má byť stabilný kontrakt.