Gotowy DESIGN.md do skopiowania: nasz styl QKI krok po kroku
Budujemy DESIGN.md z prawdziwego CSS naszej strony: kolory, fonty Signal Grotesk i Signal Serif, proste narożniki. Pokazujemy plik, prawdziwy wynik lintera Google i jak podpiąć go pod agenta.
✳QKI Analytics
✳BUDOWANIE
QKI Analytics
Krótka odpowiedź
Otwórz CSS swojej strony, wypisz kolory, fonty i narożniki, wklej je jako tokeny na górę DESIGN.md, a pod spodem napisz po ludzku, jak ich używać i czego nie robić. Sprawdź plik linterem Google i dopisz w AGENTS.md, żeby agent go wczytywał.
Poniżej robimy to na naszej stronie, qkianalytics.pl. Wszystkie wartości są z naszego kodu, nic nie jest wymyślone.
Skąd wzięliśmy wartości
Nasza strona to Next.js. Wygląd, który widzisz, robi motyw Signal w pliku src/app/signal.css. Stamtąd są kolory domyślnego, ciemnego motywu (np. tło #10151a, tekst #edf1f5, akcent #a9cfff), fonty Signal Grotesk (400, 500, 600) i Signal Serif kursywą, nagłówki z grubością 500, line-height 1.05 i letter-spacing -.05em, oraz prawie wszędzie border-radius 0, czyli proste narożniki. Jeden wyjątek: okrągła ikonka w klasie signal-round-link (border-radius:100%).
Uwaga na pułapkę, w którą sami wpadliśmy: w layoucie są też importy Manrope, Bebas Neue i JetBrains Mono, ale komentarz w kodzie mówi, że widoczne fonty daje Signal, a te starsze ładują się tylko na trasach, które ich używają. Starsze pliki CSS mają też fioletową paletę. Zawsze sprawdzaj, co strona naprawdę pokazuje, a nie pierwszy plik z kolorami.
Plik do skopiowania
Format według specyfikacji Google Labs (wersja alpha). Podmień wartości na swoje.
DESIGN.md: QKI Analytics, motyw ciemny
---
name: QKI Analytics Signal
colors:
background: "#10151a"
surface: "#1c2630"
surface-hover: "#263543"
on-background: "#edf1f5"
on-surface: "#d3dee7"
muted: "#b7c5d0"
outline: "#37414b"
primary: "#a9cfff"
on-primary: "#10151a"
typography:
headline-lg:
fontFamily: Signal Grotesk
fontSize: 34px
fontWeight: 500
lineHeight: 1.05
letterSpacing: -0.05em
headline-md:
fontFamily: Signal Grotesk
fontSize: 24px
fontWeight: 500
lineHeight: 1.05
letterSpacing: -0.05em
body-md:
fontFamily: Signal Grotesk
fontSize: 16px
fontWeight: 400
lineHeight: 1.5
label-sm:
fontFamily: Signal Grotesk
fontSize: 13px
fontWeight: 500
lineHeight: 1.4
quote:
fontFamily: Signal Serif
fontSize: 18px
fontWeight: 400
lineHeight: 1.4
rounded:
none: 0px
components:
button-primary:
backgroundColor: "{colors.on-background}"
textColor: "{colors.background}"
typography: "{typography.label-sm}"
rounded: "{rounded.none}"
card:
backgroundColor: "{colors.surface}"
textColor: "{colors.on-surface}"
rounded: "{rounded.none}"
---
## Overview
Spokojny, redakcyjny serwis o AI. Ciemne, granatowe tło, jasny tekst, jeden chłodny akcent. Ma wyglądać jak magazyn, nie jak landing startupu.
## Colors
Tło `background` i karty `surface` to dwa odcienie granatu. Tekst główny `on-background`, treść `on-surface`, podpisy `muted`. Akcent `primary` (jasny błękit) tylko na linki i stan aktywny, nigdy jako duże tło. Linie oddzielające: `outline`. Bez gradientów i fioletu.
## Typography
Jedna rodzina bezszeryfowa (Signal Grotesk) na wszystko. Nagłówki średniej grubości (500), ciasne (line-height 1.05, letter-spacing -0.05em), bez wersalików. Signal Serif kursywą tylko do cytatów i wyróżnień.
## Layout
Dużo powietrza, siatka redakcyjna, linie `outline` zamiast cieni. Teksty w kolumnie czytelnej szerokości.
## Shapes
Prawie wszystkie narożniki proste (0px). Jedyny wyjątek: okrągła ikonka w linku (signal-round-link). Żadnych zaokrąglonych kart ani przycisków-pigułek.
## Components
Przycisk główny: jasne tło `on-background`, ciemny tekst. Karta: `surface`, cienka linia `outline`, bez cienia.
## Do's and Don'ts
- Do: jeden akcent, proste narożniki, linie zamiast cieni.
- Don't: gradienty, glow, emoji w nagłówkach, zaokrąglone karty, więcej niż dwie rodziny fontów.
Sprawdzamy linterem: prawdziwy wynik
Uruchomiliśmy linter Google 16.10.2026, pakiet @google/design.md w wersji 0.4.0, poleceniem npx -p @google/design.md@0.4.0 designmd lint DESIGN.md. Poniżej wynik bez żadnych zmian.
Zero błędów. Dwa ostrzeżenia mówią, że kolorów muted i surface-hover nie używa żaden komponent. To prawda: używamy ich w prozie (podpisy, najechanie myszą), a nie w tokenach komponentów. Info o braku sekcji spacing znaczy, że odstępy agent dobierze sam. Mamy dwa wyjścia: dopisać komponenty i skalę odstępów albo świadomie to zostawić.
Jeśli brak skali odstępów jest świadomą decyzją, specyfikacja pozwala dopisać w tokenach omitted: [spacing]. Sprawdziliśmy to tą samą wersją lintera: zamiast missing-sections pojawia się wtedy info „spacing intentionally omitted — no spacing tokens will be validated”. W pokazanym pliku tego wpisu nie ma, dlatego w wyniku widać info missing-sections.
Wynik lintera (16.10.2026, v0.4.0)
{
"findings": [
{
"severity": "warning",
"path": "colors.surface-hover",
"message": "'surface-hover' is defined but never referenced by any component.",
"rule": "orphaned-tokens"
},
{
"severity": "warning",
"path": "colors.muted",
"message": "'muted' is defined but never referenced by any component.",
"rule": "orphaned-tokens"
},
{
"severity": "info",
"message": "Design system defines 9 colors, 5 typography scales, 1 rounding level, 2 components.",
"rule": "token-summary"
},
{
"severity": "info",
"path": "spacing",
"message": "No 'spacing' section defined. Layout spacing will fall back to agent defaults.",
"rule": "missing-sections"
}
],
"summary": {
"errors": 0,
"warnings": 2,
"infos": 2
}
}
Podpinamy pod agenta
Wrzuć DESIGN.md do katalogu głównego projektu i dodaj do AGENTS.md (albo CLAUDE.md) krótką regułę. Tak, jak Vercel używa AGENTS.md jako drogowskazu do swojego skilla.
Fragment AGENTS.md (nasza propozycja)
## Wygląd
Przed każdą zmianą UI wczytaj DESIGN.md.
Kolory, fonty i narożniki bierz tylko z tokenów. Nie dodawaj gradientów ani zaokrągleń.
Po zmianie uruchom: npx @google/design.md lint DESIGN.md
Sprawdź swój plik
Lista kontrolna
Każdy kolor w tokenach znajdziesz w CSS strony, która jest naprawdę widoczna.
Fonty sprawdzone w kodzie (layout, @font-face), a nie zgadnięte z wyglądu.
Linter zwraca 0 błędów; ostrzeżenia rozumiesz i świadomie zostawiasz albo poprawiasz.
W sekcji Do's and Don'ts jest to, co agent u ciebie najczęściej psuje.
AGENTS.md kieruje agenta do DESIGN.md.
Najczęstsze błędy
Kopiowanie wartości ze starego CSS, którego strona już nie używa.
Same tokeny bez prozy: agent zna kolory, ale nie wie, kiedy których użyć.
Wpisywanie do pliku, że coś „zawsze działa”. Vercel w swoim teście miał błąd na każdej stronie, z plikiem i bez.
Źródła i dalsza lektura
Materiały, na których opiera się ten tekst. Instrukcje i przykładowe scenariusze są propozycjami redakcji.