Průvodce pro agenta v cizím repu

Pro AI agenta, který staví jiný produkt než acrm/acrm, ale má se držet téhož design systému.

Nečekej na zprávu od Art Directora ani od agenta na .131. Všechno, co potřebuješ vědět o tom, co existuje a jak to vypadá, si přečteš sám ze strojových endpointů. Člověk rozhoduje jen o tom, co v systému ještě není — a i na to je postup níž, ne čekání.

1. Prvních 60 vteřin

DS=http://192.168.230.131:3777/ds

curl -s $DS/_version.json      # HEAD kanonu, datum, dirty/conflict příznak
curl -s $DS/_index.json        # celý katalog strojově: kategorie → rodiny → podkomponenty
curl -s $DS/_search.json       # plochý index pro hledání (název, URL, skupina, text)
curl -s $DS/_tokens.css        # tokeny (barvy, sazba, spacing) — jediný zdroj hodnot

Nic z toho nepotřebuje autentizaci a všechno je na LAN dostupné. Když endpoint neodpoví, zastav se a napiš to — nedomýšlej si hodnoty z paměti.

2. Kde je pravda (v tomhle pořadí)

  1. Kód v acrm/acrm — packages/ui (komponenty, src/tokens/tokens.css, stories/**) a apps/web/src/ds*.css. Co dělá kód, to je pravda.
  2. Registr site/registry.json (= /ds/_index.json) — jediné místo hierarchie: co existuje, jak se to jmenuje, jaký to má stav, jaké třídy a soubory.
  3. docs/<rodina>/<sub>.usage.md a .a11y.md — kdy to použít, kdy ne, anatomie, limity.
  4. legacy/NENÍ kanon. Je to historický export záměru. Nic z něj neportuj.

Mockup, screenshot ani tvoje paměť pravda nejsou.

3. Jak si najít prvek (bez ptaní)

# „potřebuju něco na štítek/stav" — hledej NEJDŘÍV v názvu; text (.x) je hodně široký
# a shodí ti do výsledků kdeco (`aria-label` v popisu jiného prvku apod.).
curl -s $DS/_search.json | jq -r '.[] | select(.t|test("pill|badge";"i")) | "\(.t)  —  \(.u)"'
#   Pill        —  /ds/components/status/pill
#   Count badge —  /ds/components/status/count-badge
# Index obsahuje i TOKENY a foundations, takže se stejně hledá i hodnota:
curl -s $DS/_search.json | jq -r '.[] | select(.t|startswith("--")) | .t' | head

# co všechno je v kategorii
curl -s $DS/_index.json | jq -r '.families[] | select(.category=="Records & data") | .id'

# detail podkomponenty: stav, shrnutí, třídy, soubory
curl -s $DS/_index.json | jq '.families[] | select(.id=="status") | .subcomponents[]'

Stránka prvku (pro člověka i pro čtení textu): $DS/components/<rodina>/<sub> — taby ?tab=examples|code|usage|accessibility|changelog.

Stav podkomponenty čti vždy: canon = používej · beta = používej, ale počítej se změnou · candidate = ještě neexistuje v kódu, nestav na tom · deprecated = nepoužívej, koukni na replacedBy.

4. Jak DS použít v cizím repu

@acrm/ui není publikovaný balíček — je to workspace package uvnitř acrm/acrm. Cizí repo si ho tedy nenainstaluje. DS je proto CSS-first: kontrakt jsou tokeny + názvy tříd, ne import.

  1. Vezmi tokeny. curl -s $DS/_tokens.css -o src/styles/ds-tokens.css a načti je jako první.

⚠️ Pozor na fonty. tokens.css odkazuje na písma absolutní cestou — url('/ds/_fonts/Geist-Variable.woff2'). Jakmile soubor servíruješ ze svého originu, ta cesta míří na tvůj server a fonty spadnou na 404. Buď je při stažení přepiš na plnou adresu:

``bash curl -s $DS/_tokens.css | sed "s#url('/ds/_fonts/#url('$DS/_fonts/#g" > src/styles/ds-tokens.css ``

…nebo si _fonts/ stáhni k sobě a cestu si přepiš na vlastní. Nekopíruj @font-face ručně.

  1. Nikdy neopisuj hodnoty. Žádné #eeeff1, žádné 13px — vždy var(--border), var(--cell). Když hodnota v tokenech není, je to nález; napiš ho, nevymýšlej si vlastní.
  2. Emituj kanonické třídy. Label je <span class="acrm-pill blue">, tlačítko .acrm-btn, výpis .il / .il-row. Třídy jsou v registru u každé podkomponenty (classes).
  3. Engine CSS portuj 1:1. Potřebuješ-li i kresbu (ne jen tokeny), vezmi ji z $DS/_archive.tar.gz (celý kanon, 3 MB) nebo z acrm/acrm a neupravuj ji — jinak se ti to rozejde a nikdo si toho nevšimne.
  4. React komponenty jsou interní ACRM. Kdo je chce, portuje chování podle usage.md + a11y.md, ne odhadem z obrázku.

4b. Závazná designová pravidla (výtah z $DS/RULES.md + rozhodnutí AD)

  • Containment budget: max 1 úroveň rámování. Rám jen jako skutečná hranice (input, panel, overlay). Seznam = ikona + text + mezera, žádný okraj kolem řádku. Ikona je ikona, ne dlaždice.
  • Jeden akcent na obrazovku. Červená (critical) jen pro „něco je špatně".
  • Sentence case, žádné verzálky. Dropdown/popover nikdy nemá nadpis nad položkami.
  • Žádné vysvětlivky v UI — srozumitelnost řeší UX, ne odstavce textu.
  • Popisek pole = var(--label), nápověda pod polem = var(--hint). Monospace jen finanční výkazy + kbd/kód. tabular-nums jen u čísel v tabulkách, nikdy u datumů.
  • Datum: rok jen když je potřeba („26. 8." / „14. 11. 27"). Částky pod 10 000 nezkracovat, výš 12,5k / 1,3M.
  • Kanon nahrazuje, nedoplňuje: nový vzor se portuje rekonstrukcí 1:1, starý prvek mizí.
  • Měř, neodhaduj. Hodnoty z DS jsou přesné; parita se ověřuje měřením v prohlížeči.
  • Před publikací obrazovky: spočítej úrovně rámů (>1 dekorativní = zploštit), ke každému okraji jedna věta „jakou hranici tvoří", „šlo by to jen prostorem a hierarchií?".

4c. Když na 192.168.230.131 nedosáhneš

Klonuj [email protected]:acrm/design-system.git (registr = site/registry.json, pravidla RULES.md, docs docs/<rodina>/<sub>.*.md) a acrm/acrm (tokeny packages/ui/src/tokens/tokens.css, CSS apps/web/src/ds.css + apps/web/src/ds/*.css). Endpointy z bodu 1 mají v repu tyto ekvivalenty; nic jiného zdroj není.

5. Když prvek neexistuje

Tohle je jediné místo, kde vstupuje člověk — a i tak se neptáš zprávou, ale návrhem.

  1. Ověř, že opravdu neexistuje: _search.json + _index.json, a přečti si related u nejbližší podkomponenty. Většina „chybějících" prvků je varianta něčeho, co už je.
  2. Když fakt chybí, založ candidate: MR do acrm/design-system do složky candidates/ s kartou (živý HTML render) a krátkým README — k čemu to je, proč kanon nestačí, naměřené hodnoty. Životní cyklus: candidate → beta → canon → deprecated.
  3. Nestav si lokální variantu „zatím". Ta „zatím" varianta je přesně to, jak vznikly tři paralelní systémy topbarů a pět stopgap souborů s ikonami.
  4. Rozhodnutí AD se pak projeví v registru — poznáš to podle status a approvedAt.

6. Co nikdy nedělej

  • Needituj packages/ui ani zrcadlo packages/ui/reference/ ručně (v ACRM to hlídá ds:sync-check).
  • Needituj generované soubory — např. icon set se generuje (pnpm ds:icons z allowlistu).
  • Neportuj nic z legacy/. Nepoužívej DesignSync ani design projekty na claude.ai — mrtvé odbočky.
  • Nekopíruj hodnoty z DS webu okem ze screenshotu. Měř, nebo si vezmi token.
  • Nedávej vlastní barvu, když existuje tón. Červená (critical) je rezervovaná pro „něco je špatně".

7. Jak poznat, že se kanon pohnul

curl -s $DS/_version.json | jq -r .head    # porovnej s tím, co máš uložené

dirty: true nebo conflict: true = kanon je zrovna rozpracovaný; počkej, nebo se zeptej. Když si držíš zrcadlo, zapiš si k němu HEAD (v ACRM to dělá MIRROR-VERSION.json).

8. Checklist před otevřením MR

  • [ ] Prvek, který stavím, v registru není — ověřeno v _index.json, ne z paměti.
  • [ ] Používám kanonické třídy a jen tokeny, žádná natvrdo hodnota.
  • [ ] Přečetl jsem usage.md i a11y.md dané podkomponenty.
  • [ ] Ověřil jsem výsledek v prohlížeči — vzhled i chování, ne jen že to zkompiluje.
  • [ ] Co je klikací, jde ovládat i klávesnicí (a má viditelný focus).
  • [ ] Rozdíly proti kanonu jsem napsal předem, ne schoval do popisu MR.

9. Když si nevíš rady

Napiš to nahlas i s tím, co jsi zkusil a co ti vyšlo — čísla, ne dojmy. Lepší jedna přesná otázka než tiše postavená odchylka. Ale ptej se až po bodech 1–5; drtivá většina odpovědí je v _index.json.

Source: docs/AGENT-GUIDE.md · GitLab