Czym jest DESIGN.md?

Skąd pochodzi DESIGN.md#

Budowa pliku DESIGN.md#

---
name: DevFocus Dark
colors:
  primary: "#2665fd"
  secondary: "#475569"
  surface: "#0b1326"
  on-surface: "#dae2fd"
  error: "#ffb4ab"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
rounded:
  md: 8px
---

# Design System

## Overview
A focused, minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.

## Colors
- **Primary** (#2665fd): CTAs, active states, key interactive elements
- **Secondary** (#475569): Supporting UI, chips, secondary actions
- **Surface** (#0b1326): Page backgrounds
- **On-surface** (#dae2fd): Primary text on dark backgrounds
- **Error** (#ffb4ab): Validation errors, destructive actions

## Typography
- **Headlines**: Inter, semi-bold
- **Body**: Inter, regular, 14-16px
- **Labels**: Inter, medium, 12px, uppercase for section headers

## Components
- **Buttons**: Rounded (8px), primary uses brand blue fill
- **Inputs**: 1px border, subtle surface-variant background
- **Cards**: No elevation, relies on border and background contrast

## Do's and Don'ts
- Do use the primary color sparingly, only for the most important action
- Don't mix rounded and sharp corners in the same view
- Do maintain 4:1 contrast ratio for all text

Osiem kanonicznych sekcji#

Treść w Markdown używa nagłówków ##. Sekcje można pominąć, gdy nie są istotne, ale jeśli występują, powinny zachować tę kolejność. Nagłówek, który pojawia się dwa razy, czyni plik niepoprawnym; nieznane sekcje są zachowywane.

1. Overview (także Brand & Style). Wygląd i charakter w kilku zdaniach: nastrój, gęstość, osobowość.
2. Colors. Każdy token koloru i jego rola, na przykład główne akcje lub powierzchnie strony.
3. Typography. Rodziny fontów i skala typograficzna, od dużych nagłówków po małe etykiety.
4. Layout (także Layout & Spacing). Skala odstępów, siatka, szerokości treści i marginesy.
5. Elevation & Depth (także Elevation). Jak oddzielają się powierzchnie: cienie, obramowania, odcienie.
6. Shapes. Zaokrąglenia narożników i inne zasady kształtów.
7. Components. Przyciski, pola, karty i inne atomy, z ich tokenami i stanami.
8. Do's and Don'ts. Zasady, których agent nie powinien łamać.

Zwięzła treść w Markdown z każdą kanoniczną sekcją po kolei. Dopasuj treść do swojego produktu, zachowaj nagłówki i kolejność.

## Overview
A minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.

## Colors
- Primary (#2665fd): CTAs and active states
- Surface (#0b1326): Page backgrounds
- On-surface (#dae2fd): Text on dark backgrounds

## Typography
- Headlines: Inter, semibold
- Body: Inter, regular, 14-16px
- Labels: Inter, medium, 12px, uppercase

## Layout
- 8px base spacing unit, scale: 4 / 8 / 16 / 24 / 32 / 48
- Max content width 720px with 24px gutters on mobile

## Elevation & Depth
- Surfaces rely on background contrast instead of shadow
- Overlays use an 8 percent white tint on dark surfaces

## Shapes
- Rounded 8px for controls, 16px for cards
- Avoid mixing sharp and rounded corners in one view

## Components
- Buttons: 8px rounded, primary filled with brand blue
- Inputs: 1px border, subtle surface-variant background
- Cards: no elevation, rely on border and background contrast

## Do's and Don'ts
- Do use the primary color sparingly, for the most important action
- Don't mix rounded and sharp corners in one view
- Do maintain at least a 4:1 contrast ratio for all text

Tokeny projektowe i schemat#

DESIGN.md zawiera tokeny projektowe jako front matter w YAML na początku pliku. Blok front matter zaczyna się linią zawierającą dokładnie --- i kończy tym samym ogranicznikiem.

version: <string>
name: <string>
description: <string>
colors:
  <token-name>: <Color>
typography:
  <token-name>: <Typography>
rounded:
  <scale-level>: <Dimension>
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <token-name>: <string | token reference>

Typowe nazwy skali to xs, sm, md, lg, xl i full, ale każdy opisowy klucz jest poprawny. Tokeny odstępów są w YAML pod spacing: i opisane w sekcji Layout treści w Markdown.

Typy tokenów

Kolor

Dowolny poprawny ciąg koloru CSS. Zalecanym domyślnym zapisem jest hex w formie #RRGGBB, na przykład "#1A1C1E".

Wymiar

Liczba z jednostką px, em lub rem. Przykłady:48px,-0.02em.

Odwołanie do tokenu

Ujęte w nawiasy klamrowe i wskazujące wartość w drzewie YAML. Przykład:{colors.primary}.

Typografia

Obiekt złożony z właściwościami fontu, takimi jak rodzina, rozmiar, grubość, interlinia i odstęp między literami. Zobacz Właściwości typografii.

Właściwości typografii

fontFamily

Nazwa rodziny fontu.

fontSize

Rozmiar fontu jako wymiar.

fontWeight

Liczbowa grubość, np. 400 lub 700.

lineHeight

Wymiar lub mnożnik bez jednostki. Zalecane są wartości bez jednostki.

letterSpacing

Korekta odstępu między literami jako wymiar.

fontFeature

Konfiguruje font-feature-settings.

fontVariation

Konfiguruje font-variation-settings.

Odwołania do tokenów

Odwołanie do tokenu jest ujęte w nawiasy klamrowe i zawiera ścieżkę obiektu do innej wartości w drzewie YAML. W większości grup tokenów odwołanie powinno wskazywać wartość prostą, a nie grupę. W sekcji components dozwolone są odwołania do wartości złożonych, takich jak poziomy typografii.

components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
  button-primary-hover:
    backgroundColor: "{colors.primary-70}"

Komponenty

backgroundColor

Kolor

textColor

Kolor

typography

Typografia

rounded

Wymiar

padding

Wymiar

size

Wymiar

height

Wymiar

width

Wymiar

Zalecane nazwy tokenów

Jak agenci AI używają DESIGN.md#

## Design
Follow DESIGN.md for every UI change: use its color, typography,
spacing and component tokens instead of inventing new values.

Claude Code

Czyta pliki w repozytorium i przy starcie wczytuje CLAUDE.md. Dodaj tam linię wskazującą DESIGN.md albo wspomnij o pliku w prompcie.

Cursor

Dodaj DESIGN.md do kontekstu czatu albo odwołaj się do niego w regule projektu, aby dotyczył każdej prośby o UI.

GitHub Copilot

Wskaż DESIGN.md w pliku instrukcji Copilot w repozytorium albo dołącz go w czacie, gdy prosisz o pracę nad UI.

Google Stitch

Tu format się narodził. Stitch używa DESIGN.md, aby generowane ekrany miały jedną paletę, skalę typograficzną i język komponentów.

Agent bierze dokładne wartości z tokenów (hex głównego przycisku, rozmiar etykiety body-md) i na podstawie tekstu decyduje, gdzie ich użyć.

DESIGN.md vs AGENTS.md vs README.md#

Te trzy pliki leżą obok siebie i odpowiadają na różne pytania. DESIGN.md nie zastępuje AGENTS.md; oba działają razem.

Prawdziwe przykłady DESIGN.md#

Najszybciej zrozumiesz format, czytając kilka prawdziwych plików. Każda z tych stron galerii pokazuje DESIGN.md wyodrębniony z publicznej strony marki, z jej paletą i próbkami typografii. Nie są to oficjalne wytyczne marek.

• DESIGN.md Stripe
• DESIGN.md Anthropic
• DESIGN.md Airbnb
• DESIGN.md Linear
• DESIGN.md Notion
• DESIGN.md Supabase

Przeglądaj wszystkie przykłady DESIGN.md

Jak zdobyć DESIGN.md#

1. Napisz go ręcznie. Zacznij od specyfikacji i przykładów powyżej, a potem sprawdź plik darmowym Walidatorem DESIGN.md lub poleceniem lint od Google.
2. Zacznij od przykładu. Skopiuj plik z galerii i zmień tokeny oraz tekst, aby pasowały do twojego produktu.
3. Wygeneruj go z działającej strony. Wklej publiczny URL do Design Extractor. Renderuje on stronę w przeglądarce i zwraca DESIGN.md z jej kolorami, typografią, odstępami i komponentami, zgodny z powyższą specyfikacją. Strona generatora DESIGN.md wyjaśnia, co dostajesz. Ta sama ekstrakcja działa w rozszerzeniu Chrome i z poziomu twojego agenta przez serwer MCP.