ACRM Design System — analýza stavu a plán přestavby na špičkový DS

Datum: 2. 9. 2026 · pro Štěpána (Art Director) · vzor kvality: atlassian.design Čísla jsou změřená (skripty v této session), ne odhadnutá. Zdroj appky = origin/main acrm (ne checkout /root/crm, který je 1 119 commitů pozadu).

0. Shrnutí

Diagnóza. To, čemu říkáme „kanon DS", je export z claude.ai/design: 97 HTML mockupů, tři paralelní kopie CSS a vlastní JavaScriptové „enginy", které znovu implementují obrazovky appky. Od exportu (9. 8.) se 35 z 36 komponentových karet nezměnilo, zatímco appka udělala 354 commitů do DS kódu. Tokeny naopak sedí (136 tokenů, shoda s tokens.css na mainu až na uvozovky). Pravda o komponentách dnes žije v kódu — @acrm/ui (39 komponent, typované props, 33 stories, 66 vizuálních snímků) a ds/*.css — a RULES §0.1 to už dnes říká: „zdroj pravdy je reálná appka, portuj z ní". DS web (fáze 1 z dneška) má správnou kostru, ale ukazuje zastaralé mockupy.

Cíl. DS na úrovni vzoru: rodiny komponent → podkomponenty, každá se stejnou anatomií stránky (Examples · Code · Usage · Accessibility · Changelog), příklady = živé komponenty z kódu s ukázkou kódu, props tabulky generované z typů, usage s Do/Don't, verzování a changelog, distribuce balíčkem do všech rep.

Cesta. Otočit zdroj pravdy na kód (packages/ui = komponenty + tokeny + stories + styly), DS repo = dokumentace + registr + web, HTML export → legacy/. Pět fází, měřitelné „hotovo" u každé komponenty, appka se konsoliduje ratchetem, distribuce balíčkem @acrm/ui místo zrcadel. Detail v §5–§8.

1. Současný stav — DS interně (/root/ds-export/extracted, repo acrm/design-system)

1.1 Obsah

1.2 Vazba na appku (měřeno ds:sync-check + porovnání souborů)

• Zrcadlo v repu (packages/ui/reference/screens): 20 karet z kanonu chybí, 23 se liší, 8 enginů _ds/* se liší → zrcadlo je kurátorská, zastaralá podmnožina.
• ds:sync-check (29 portů): 0 hodnotových driftů proti zrcadlu, ale 161 neadoptovaných selektorů (Person detail 82, segment-screen 22, app-shell 16), 85 chybějících, 148 schválených odchylek (ds-ok). Appka od karet vědomě odchází.

Závěr §1: Interní DS není systém, je to archiv designových záměrů z jedné epochy + tři kopie CSS. Tokeny a pravidla mají hodnotu; mockupy a enginy ne.

2. Současný stav — prezentace (:3777/ds, fáze 1 z 2. 9.)

Závěr §2: kostra webu je správná a stojí na tokenech; obsah, který ukazuje, je špatný (mockupy). Web musí číst z kódu.

3. Aplikace a reálná implementace kanonických komponent (origin/main)

3.1 Co existuje

3.2 Dluh v appce

Závěr §3: appka má skutečný, typovaný, testovaný komponentový systém a brány. Chybí mu (a) rozdělení „balíček vs. obrazovky" — enginy jsou v appce, (b) pokrytí stories per stav, (c) dokumentace, (d) publikace. To jsou přesně věci, které špičkový DS web potřebuje jako vstup.

4. Rozdíl proti vzoru (atlassian.design)

5. Cílová architektura

acrm/acrm (monorepo)                                   acrm/design-system (DS repo)
┌──────────────────────────────────┐                   ┌──────────────────────────────────────┐
│ packages/ui  = @acrm/ui          │  build artefakty  │ site/registry.json  (rodiny → pod-    │
│  ├ src/components  (39+)         │ ───────────────▶  │   komponenty → {react, třídy, stories,│
│  ├ src/tokens/tokens.css         │  • ladle static   │   status, since, docs})               │
│  ├ styles/*.css  (enginy z ds/)  │  • props.json     │ docs/<family>/<sub>.usage.md          │
│  ├ stories/**  (per podkomp.)    │  • tokens.css     │ docs/<family>/<sub>.a11y.md           │
│  └ CHANGELOG (changesets)        │  • git changelog  │ patterns/*.md + screenshoty devu      │
│ apps/web  = obrazovky (jen       │                   │ rules/*.md  (RULES rozdělený)         │
│   kompozice, žádný vlastní styl) │                   │ site/  (renderer :3777/ds, CSS)       │
│ CI: ds-validate · visual · ratchet│                   │ legacy/  (HTML export, read-only)     │
└──────────────────────────────────┘                   └──────────────────────────────────────┘
          │ publish @acrm/ui (GitLab package registry, semver)
          ▼
  jiná repa: `pnpm add @acrm/ui` — tokeny + komponenty + enginy; žádné zrcadlo, žádný ruční port

Principy

1. Kód je pravda. Komponenta existuje, když má typovaný export v @acrm/ui (nebo kanonickou třídu v styles/), stories per stav a vizuální snímek. Mockup není důkaz.
2. DS repo = dokumentace, registr, web. Nic, co by muselo být duplikátem kódu. Web vše ostatní generuje z artefaktů buildu.
3. Jedna rodina = jedna stránka na podkomponentu, stejná anatomie. Registr (registry.json) je jediné místo, kde se definuje hierarchie a mapování na kód.
4. Distribuce balíčkem. Zrcadla a ds:sync-check skončí; nahradí je verze balíčku + changelog + migrace.
5. Export z claude.ai → legacy/. Zůstane čitelný jako historie záměru; není linkovaný jako kanon; nic z něj se neportuje bez rozhodnutí AD.

6. Taxonomie: rodiny → podkomponenty (návrh, ukotveno v kódu)

Legenda: ✅ v kódu (@acrm/ui / .acrm-*) · ◐ v kódu jen jako obrazovková vrstva ds/*.css · ◯ jen v mockupu (kandidát).

Forms & input

1. Button — Button (primary · default · ghost · danger) ✅ · Icon button ✅ · Split button ◯ · Save button (dialer completion) ◐ · Kbd hint ✅
2. Text field — Input (text · email · url · code · number · short) ✅ · Textarea ✅ · Field (label · hint · error) ✅ · Input with icon/kbd ✅ · Slider ✅ · Tag input ✅ · Mention input ◐
3. Select — Select ✅ · Multi-select ✅ · Combobox ✅ · Record select ✅ · Nav select ✅ · Picker menu ✅
4. Choice — Checkbox ✅ · Radio ✅ · Switch ✅ · Segmented control ✅ · Option chips ✅
5. Date & time — Date field ✅ · Time field ✅ · Date range ✅ · Date-time range ✅ · Calendar ✅ · Picker panel ✅
6. Filter — Filter bar ◐ · Filter chip ◐ · Removable chip ✅

Overlays & dialogs

1. Dialog — Dialog (s · m · l) ✅ · Confirm ✅ · Window states (modeless · compact · min) ◐ · Drawer form ✅ · Record drawer ◐
2. Popover — Popover ✅ · Tooltip ✅ · Entity preview ✅

Navigation

1. App shell — Sidebar nav item ◐ · Top bar ◐ · Drawer slot ◐
2. Section top bar — Section top bar ✅ · Title with entity tile ✅
3. Tabs — Tab strip ✅ · Record tabs ◐

Records & data

1. Record list ✅ · 13. Record rail — Rail ✅ · Key-value row ✅ · Editable field ✅ · Multi-value ◐ · 14. Table — Segment table ◐ · Table row ◐ · 15. Task list ✅ · 16. Email list ◐ · 17. Deal card ✅ · 18. Stat tile ◐ · 19. Section block ◐ · 20. Timeline ◐ · 21. Note card ◐

Identity

1. Avatar — person · company × 16/24/32 ✅ · 23. Entity reference — default · mini · removable ✅ (jedna komponenta, 3 varianty — dnes 3 karty)

States & feedback

1. Empty state ✅ · 25. Error state ✅ · 26. Loading — Skeleton line · Skeleton list · Loader · List loader · Detail state screen ✅ · 27. Toast ◐ · 28. Notifications ◐ · 29. Status — Pill · Count badge ✅

AI

1. AI assistant ◐ · 31. Discussion ◯ (návrh)

Výsledek: 31 rodin, ~75 podkomponent; z toho ✅ 44, ◐ 27 (přesun ds/*.css → packages/ui/styles + story), ◯ 4 (kandidáti).

7. Anatomie stránky podkomponenty (pevná, generovaná z registru)

Components › Button › Icon button
Icon button   [canon ▾ since 0.3.0]   @acrm/ui · <IconButton>   Source · Story · Changelog
„Tlačítko, jehož význam nese ikona; vždy s tooltipem."
────────────────────────────────────────────────────────────────
 Examples │ Code │ Usage │ Accessibility │ Changelog
────────────────────────────────────────────────────────────────
Examples  = sekce v pevném pořadí per rodina: Default · Variants · Sizes · States (hover/focus/
            disabled/loading/selected) · With icon/kbd · Composition; každá = živý render (Ladle
            story v iframe) + přepínač „Code" se snippetem přesně té story.
Code      = install/import · Props (name · type · default · description — z TS typů) · CSS classes
            (kanonické třídy + tokeny, které komponenta používá) · Related.
Usage     = When to use · When not to use · Anatomy (očíslované části) · Best practices (Do / Don't
            páry s živým renderem) · Content (copy pravidla: sentence case, datum, částky…) · Related.
Accessibility = klávesnice · ARIA · fokus · kontrast (měřeno) · známé limity.
Changelog = commity mainu dotýkající se souborů komponenty + verze balíčku (changesets).
Vpravo: On this page · Implementation (verze, adopce per repo, počet použití).

Do/Don't a Content se plní z existujících AD rozhodnutí (RULES §0–§10, pilulky-střízlivost, tabular-nums jen tabulky, konvence roku, kompaktní částky, popisek = --label, nápověda = --hint, mono jen výkazy, žádný eyebrow v menu, FilterBar = Notion model…) — obsah už máme, jen je rozptýlený v paměti a MR.

8. Postup přestavby (fáze, DoD, odhad)

Pořadí: 0 → 1 → (2 ∥ 3) → 4 → 5. Fáze 2 je největší a jediná, kde se píše obsah — ten schvaluje AD po rodinách, ne najednou.

9. Governance

• Role: Art Director (Štěpán) — schvaluje taxonomii, kanon, usage texty; DS maintainer (Claude/FE) — registr, generátory, web, brány; přispěvatel (kterýkoli tým) — MR do acrm (kód + story) a do DS (docs, kandidát).
• Životní cyklus: candidate (MR v candidates/) → beta (v balíčku, bez záruky API) → canon (5 artefaktů, brány) → deprecated (náhrada + migrace v changelogu) → odstranění.
• Definition of done komponenty: story per sekci · vizuální snímek light+dark · props doc z typů · usage.md · a11y.md · usage pravidlo ve validátoru · záznam v registru.
• Pravidlo „kanon nahrazuje": nová varianta = stará mizí v témže MR (migrace), ne vedle sebe.
• Metriky na webu (Adoption): % podkomponent s DoD · dluh appky (inline styly, ds-ok, prefixy) · verze balíčku per repo.

10. Co rozhodnout teď (jedno rozhodnutí)

Schválit §5 (zdroj pravdy = kód, DS repo = docs + registr + web, export → legacy/) a §6 (31 rodin / 75 podkomponent). Po schválení začnu fází 0 a 1 (Button rodina end-to-end jako pilot, ~1 týden). Názvy podkomponent, pořadí sekcí v Examples a texty usage se ladí na webu pickerem, rodina po rodině.