# Profitway - design system

> Identyfikacja wizualna Profitway (profitway.pl), agencji 360 z Warszawy. Ten plik jest
> skrotem dla AI: najwazniejsze wartosci i wskazniki do pelnych regul. Nie zgaduj wartosci
> HEX ani rozmiarow - wszystkie sa tutaj albo w tokens.json.

Wersja biblioteki: 1.12.0
Zrodlo prawdy: repozytorium profitway-lib-design

## Kolory marki

- Profitway Orange `#FF5900` - akcenty, CTA, sygnet, punktory
- White `#FFFFFF` - tekst i logo na ciemnym tle
- Black `#000000` - logo mono, kreacje achromatyczne
- Dark Gray `#0E0E0E` - tlo stron i mailingow (tylko digital)
- Gray `#202020` - tekst na jasnym tle, napis w logo kolorowym

Pomaranczowy jest akcentem, nie tlem. Tekst drugorzedny zapisujemy jako biel z alfa
(white/45, white/55, white/65), nie osobnym tokenem - na roznych tlach ten sam szary
HEX daje inny kontrast.

Tokeny kolorow: 63. Tylko 3 z nich maja wartosc z palety marki, reszta to odcienie
z makiet w rolach opisanych przy tokenie (szarosci, cieple brazy, odcienie akcentu,
statusy, konsola AI) - docs/colors.md. Wszystkich tokenow: 271 - kolory, style
typografii (46, kazdy z rozmiarem, interlinia i czesto waga), odstepy,
promienie, cienie, gradienty, breakpointy i animacje. Wartosci: tokens.json.

## Typografia

- Naglowki, przyciski, eyebrow: Metropolis 600 (`font-display`).
- Tekst: Figtree 300 (`font-sans`, domyslny). Token `text-*` nie niesie kroju.
- Fallback z brandbooka: "Helvetica Neue", Helvetica, Arial, sans-serif.
- Oba kroje sa w paczce (assets/fonts/, Figtree jako plik zmienny 300-900 z latin-ext).
  Aplikacja Next laduje je przez next/font; kazda inna importuje
  `@profitwaypl/design/fonts.css` (@font-face + zmienne --font-metropolis/--font-figtree).
- W mailach webfontow nie wymuszamy.

## Uklad

- Kontener 1416px zewnetrznych = 1320px tresci + 2x48px marginesu.
- Rytm sekcji: 128 / 104 / 80px.
- Przyciski sa prawie ostre: promien 2px. To cecha marki, nie niedopatrzenie.
- Breakpointy (makieta +1px, bo makiety sa desktop-first): sm 561px, md 821px, lg 961px, xl 1151px, 2xl 1601px.

## Assety

15 plikow w 3 grupach: logo i sygnet w wariantach kolorowym
i mono na jasne i ciemne tlo, animacje Lottie, fonty. Rejestr z opisem "kiedy uzyc":
assets.json (z publicznym adresem kazdego pliku). Logo: docs/logo.md, w React komponenty
Logo i Sygnet z @profitwaypl/design/marketing. Nigdy nie odtwarzaj znaku marki recznie -
uzyj pliku albo komponentu.

## Ruch

Tokeny animate-*: 30, zestawy klatek kluczowych w keyframes.css: 28
(dwa tokeny graja cudze klatki w innym tempie). Ruch ma cos komunikowac, nie ozdabiac.
Kazda animacja musi byc wylaczana przez prefers-reduced-motion - to wymog
dostepnosci, nie preferencja.

## Dostepnosc

WCAG 2.2 AA. Kontrast tekstu 4.5:1 na tle, na ktorym tekst faktycznie stoi. Pomaranczowy
na bieli daje ok. 3.1:1 - wystarcza dla duzego tekstu i obrysow, nie dla akapitu; biala
etykieta na pomaranczowym przycisku ma 3.14:1 (otwarta sprawa).
Cele dotykowe minimum 44x44px. Zadne narzedzie nie moze byc tylko na desktop.

## Pelne reguly

- docs/colors.md - piec kolorow marki, 63 tokeny implementacyjne i ich rodziny, tekst drugorzedny
- docs/typography.md - kroje w paczce, fonts.css, stosy fontow, skala i role stylow, rozbieznosc H1-H6
- docs/logo.md - warianty, pole ochronne, czego nie robimy
- docs/icons.md - punktory, rejestr ikon, sprzecznosc fill kontra Lucide
- docs/motion.md - 30 tokenow animacji na 28 zestawach klatek, `prefers-reduced-motion`, Lottie
- docs/layout.md - kontener, rytm, 13 promieni, cienie, gradienty, breakpointy, okruszki
- docs/accessibility.md - WCAG 2.2 AA: kontrast, klawiatura, semantyka, dotyk
- docs/email.md - maile transakcyjne i marketingowe - kontrakt
- docs/app.md - warstwa narzedzi (shadcn/ui)
- docs/mcp.md - zasady pisania serwerow MCP
- docs/claude-design-system.md - wyslanie biblioteki na konto Claude jako design system

## Otwarte rozbieznosci

Rozbieznosci miedzy brandbookiem PDF a kodem i sprawy zakresu systemu, ktore czekaja na
decyzje dyrektora. Do czasu rozstrzygniecia obowiazuje kod, bo jest wdrozony i widoczny
dla klientow. Opcje i rekomendacje: docs/README.md.

1. `text-h3` w kodzie to H4 z brandbooka (typography.md)
2. Tekst ponizej minimum 18px z brandbooka (typography.md)
3. Ikony: "tylko fill" kontra Lucide (icons.md)
4. Napis w logo kolorowym: `#202020` czy czarny (logo.md)
5. H1 i brakujace H5-H6 (typography.md)
6. Kolory spoza palety marki (colors.md)
7. Biala etykieta na pomaranczowym przycisku ma 3,14:1 (accessibility.md)
8. Jasny motyw dla narzedzi (app.md)
9. Maile po angielsku i dane rejestrowe w stopce (email.md)
10. Stary serwer MCP brandbooka w HQ (mcp.md)

## Jak to konsumowac

- Aplikacja: `pnpm add @profitwaypl/design`, potem po imporcie Tailwinda
  `@import "@profitwaypl/design/tokens.css"` i `@import "@profitwaypl/design/keyframes.css"`
  (bez tego drugiego tokeny animate-* nie maja swoich klatek kluczowych).
- Fonty poza Next.js: `@import "@profitwaypl/design/fonts.css"` (w Next: next/font).
- Narzedzia na shadcn/ui: dodatkowo `@import "@profitwaypl/design/shadcn.css"` i komponenty
  z `@profitwaypl/design/app` - docs/app.md.
- Strona marketingowa: prymitywy z `@profitwaypl/design/marketing`.
- Maile: manifest szablonow `@profitwaypl/design/email/manifest.json`, kontrakt i API
  renderowania w docs/email.md.
- Poza JS (maile, PDF): dist/tokens.json, mapa `resolved` - wartosci bez zadnego var(),
  stosy fontow rozpisane na nazwy rodzin.
- Agenci AI: serwer MCP tej biblioteki - docs/mcp.md.
- Claude: design system do wgrania na konto - docs/claude-design-system.md.
