# Ekstraktor DESIGN.md: analiza designu dowolnej strony z Claude > Kompletny praktyczny przewodnik po korzystaniu ze skilla DESIGN.md Extractor dla Claude Code: ekstrakcja wizualnych tokenów, generowanie pliku DESIGN.md, interaktywny podgląd HTML oraz eksport do Tailwind CSS. ## 1. Czym jest DESIGN.md Extractor i dlaczego ekstrakcja systemów designu jest niezbędna W nowoczesnym developmentie webowym systemy designu pozostają zazwyczaj zamknięte lub rozproszone: ukryte w prywatnych plikach Figma, rozrzucone po dziesiątkach plików CSS lub istniejące jedynie w pamięci wiodącego projektanta. Gdy developer musi stworzyć interfejs na podstawie referencji lub szybko przejąć wizualny język strony klienta, spędza godziny na ręcznym kopiowaniu kodów hex z DevTools i mierzeniu promieni zaokrągleń przycisków linijką. **DESIGN.md Extractor** to wyspecjalizowany skill dla Claude Code, który w pełni automatyzuje proces reverse-engineeringu webdesignu. Agent analizuje żywą stronę, odczytuje tokeny systemowe bezpośrednio z DOM oraz CSS, a następnie generuje maszynowo czytelny artefakt `DESIGN.md` wraz z autonomiczną wizualną witryną `design-preview.html`. ```mermaid flowchart TD A["URL сайту або назва бренду
'stripe.com'"] --> B["Claude Code + design-md-extractor"] B --> C["DOM & CSS Parser
(Зчитування :root змінних, обчислення стилів)"] C --> D["Екстракція 4 категорій токенів
(Кольори, шрифти, відступи, радіуси)"] D --> E["Генерація DESIGN.md
(YAML-специфікація + дизайн-бриф)"] D --> F["Збірка design-preview.html
(Офлайн UI-кіт на чистих токенах)"] E & F --> G["Експорт у Tailwind CSS / Figma / Кодову базу"] ``` ### Porównanie ręcznej analizy i pracy ze skillem | Etap pracy | Ręczna analiza przez DevTools | Wykorzystanie DESIGN.md Extractor | | :--- | :--- | :--- | | **Zbieranie palety kolorów** | Ręczne kopiowanie dziesiątek pojedynczych reguł `color` i `background` | Automatyczne wyodrębnienie pełnej hierarchii (~35 tokenów) z `:root` | | **Analiza typografii** | Wybiórcze mierzenie `font-size` przy różnych nagłówkach | Siedmiopoziomowa standaryzowana skala z interlinią i trackingiem | | **Siatka i odstępy** | Subiektywne oceny paddingów i marginów między blokami | Dokładny matematyczny krok siatki modularnej (np. baza 8px) | | **Format wyniku** | Rozproszone notatki w notesie lub surowe zrzuty ekranu | Standaryzowany `DESIGN.md` i interaktywny UI-kit w HTML | | **Czas na projekt** | Od 3 do 6 godzin rutynowej pracy | Mniej niż 60 sekund na pełny cykl generowania | > [!NOTE] > Skill współpracuje z otwartym kodem źródłowym strony i wyodrębnia faktyczne parametry, których przeglądarka używa do renderowania, unikając zgadywania lub subiektywnych interpretacji. --- ## 2. Architektura i zasada działania: od URL-a do systemu designu Potok roboczy ekstraktora składa się z kilku powiązanych faz, które zapewniają precyzję zbierania danych. ### Algorytm analizy krok po kroku 1. **Ładowanie i renderowanie strony:** Claude odwołuje się do docelowego URL-a, pobierając pełny dokument HTML oraz dołączone arkusze stylów. 2. **Parsowanie globalnych zmiennych `:root`:** agent znajduje zadeklarowane custom properties CSS (`--color-primary`, `--font-sans`, `--spacing-unit`, `--radius-lg`). 3. **Obliczanie Computed Styles:** dla elementów bez jawnych zmiennych CSS skrypt analizuje kluczowe komponenty (przyciski, nagłówki, inputy, nawigację), odczytując rzeczywiste wartości obliczone przez przeglądarkę. 4. **Normalizacja i strukturyzacja:** surowe kolory są sprowadzane do kanonicznego formatu HEX/OKLCH, a fonty dopasowywane do katalogu Google Fonts lub systemowych stacków. 5. **Generowanie artefaktów:** utworzenie pliku specyfikacji `DESIGN.md` oraz kompilacja autonomicznej strony podglądu HTML. > [!TIP] > Jeśli strona korzysta z frameworków utility-first (np. Tailwind CSS), skill rozpoznaje klasy `p-4`, `rounded-xl`, `bg-slate-900` i rekonstruuje bazową konfigurację motywu. --- ## 3. Cztery wymiary tokenów wizualnych: kolory, typografia, odstępy, kształt DESIGN.md Extractor wydobywa i porządkuje tokeny wizualne według czterech głównych kategorii, tworząc spójny system. ### Paleta kolorów (Colors) Ekstraktor formuje rozszerzoną paletę składającą się z około 35 funkcjonalnych tokenów zgodnie ze standardami Material Design 3 oraz Radix UI: - **Akcenty brandowe:** `primary`, `secondary`, `tertiary` oraz ich kontrastowe pary `on-primary`, `on-secondary`. - **Powierzchnie i warstwy:** `background`, `surface`, `surface-variant`, `surface-container` (od najjaśniejszego do najciemniejszego poziomu wyniesienia). - **Stany systemowe:** `error`, `warning`, `success`, `info` wraz z odpowiednimi kontrastami tekstowymi. - **Odcienie neutralne:** `outline`, `outline-variant`, `scrim`, `shadow`. ### Hierarchia typograficzna (Typography) System czcionek opisany jest poprzez 7 standaryzowanych poziomów: | Poziom tokenu | Przeznaczenie | Typowy rozmiar | Wysokość linii | Grubość krój | | :--- | :--- | :--- | :--- | :--- | | **`headline-xl`** | Główne banery, Hero H1 | 48px – 64px | 1.1 – 1.15 | Bold / ExtraBold | | **`headline-lg`** | Nagłówki sekcji H2 | 32px – 40px | 1.2 | SemiBold | | **`title-md`** | Nagłówki kart H3 | 20px – 24px | 1.3 | Medium / SemiBold | | **`body-lg`** | Leady, tekst wprowadzający | 18px | 1.5 – 1.6 | Regular | | **`body-md`** | Główny tekst strony | 15px – 16px | 1.5 – 1.6 | Regular | | **`label-md`** | Przyciski, zakładki, badge'e | 13px – 14px | 1.2 – 1.4 | Medium | | **`label-sm`** | Podpisy pól, disclaimer'y | 11px – 12px | 1.3 | Regular / Medium | ### Siatka modularna i odstępy (Spacing) Skill definiuje bazowy moduł siatki (zazwyczaj 4px lub 8px) i buduje harmonijną skalę: - `xs` (4px), `sm` (8px), `md` (16px), `lg` (24px), `xl` (32px), `2xl` (48px). - Utrwalane są również globalne parametry layoutu: maksymalna szerokość kontenera (`max-width: 1280px`) oraz poziome marginesy bezpieczeństwa (`gutter: 24px`). ### Geometria kształtów i głębia (Shapes & Elevation) - **Promienie:** skala zaokrągleń od `none` (0px) do `full` (9999px dla okrągłych awatarów i przycisków typu pill). - **Cienie (Box Shadows):** wielowarstwowe cienie służące do tworzenia głębi (`shadow-sm`, `shadow-md`, `shadow-xl`), imitujące fizyczne wyniesienie kart nad tło. --- ## 4. Anatomia artefaktu DESIGN.md: specyfikacja YAML i sekcje Prose Plik `DESIGN.md` zaprojektowano jako dokument hybrydowy: jego górna część to ścisła struktura YAML dla linterów, kompilatorów i generatorów kodu, a dolna – profesjonalny brief designowy dla ludzi i asystentów AI. ### Przykładowa struktura YAML-frontmatter ```yaml --- name: "Acme Cloud Platform" extractedFrom: "https://acme.example.com" version: "1.0.0" colors: primary: "#4F46E5" on-primary: "#FFFFFF" primary-container: "#EEF2FF" secondary: "#06B6D4" background: "#0F172A" surface: "#1E293B" surface-variant: "#334155" on-surface: "#F8FAFC" outline: "#475569" typography: fontFamilySans: "'Inter', -apple-system, sans-serif" fontFamilyMono: "'JetBrains Mono', monospace" headline-xl: fontSize: "48px" lineHeight: "1.1" fontWeight: "800" letterSpacing: "-0.02em" body-md: fontSize: "16px" lineHeight: "1.5" fontWeight: "400" letterSpacing: "0em" spacing: base: "8px" sm: "8px" md: "16px" lg: "24px" xl: "32px" shapes: borderRadiusSm: "4px" borderRadiusMd: "8px" borderRadiusLg: "16px" borderRadiusFull: "9999px" --- ``` ### Siedem opisowych sekcji (Prose Sections) Po bloku YAML plik zawiera 7 szczegółowych sekcji inżynierskich: 1. **Brand & Style Personality:** tonalność marki (np. *"Surowy minimalizm inżynierski w stylu Linear"* lub *"Ciepły fintech konsumencki w stylu Stripe"*). 2. **Color Palette Rationale:** zasady łączenia kolorów oraz wymagania dostępności kontrastu WCAG AA. 3. **Typography Rhythm:** zasady hierarchii nagłówków i wyrównania do linii bazowej. 4. **Layout & Spacing Philosophy:** zasady organizacji siatki, punkty kontrolne responsywności (breakpoints). 5. **Elevation & Depth:** wykorzystanie warstwowości, gradientów i rozmycia tła (backdrop-filter blur). 6. **Shape & Border Language:** filozofia zaokrągleń, grubość obramowań i konturów. 7. **Component Blueprints:** gotowe wzorce do budowy przycisków, inputów, kart i menu nawigacyjnych. --- ## 5. Interaktywny podgląd: architektura design-preview.html Razem z dokumentem `DESIGN.md` skill tworzy autonomiczny plik HTML `design-preview.html`. Jest to pełnoprawna, interaktywna witryna designowa. ```mermaid flowchart LR subgraph design_preview_html["design-preview.html (Офлайн-вітрина)"] P["Колірна палітра
(Клік копіює HEX/RGB)"] T["Шрифтовий стенд
(Google Fonts лінійка)"] C["UI Sandbox
(Кнопки, картки, форми)"] S["Демо-екран
(Синтезований макет)"] end design_preview_html --> B["Відкриття у будь-якому браузері
(Без node_modules, без бекенду)"] ``` ### Zalety autonomicznego podglądu - **Zero Dependencies:** plik nie wymaga Node.js, serwera webowego ani zewnętrznych bibliotek. Wystarczy dwukrotnie kliknąć plik w Finderze lub Eksploratorze Windows. - **Wbudowane assety:** ikony i grafika osadzone są w formacie Inline SVG lub Base64, co gwarantuje działanie witryny nawet bez połączenia z siecią. - **Kopiowanie tokenów jednym kliknięciem:** kliknięcie dowolnego pola koloru automatycznie kopiuje odpowiadającą wartość do schowka. - **Interaktywne stany:** wszystkie komponenty obsługują pseudoklasy `:hover`, `:focus-visible`, `:active` oraz `:disabled`. --- ## 6. Instalacja i uruchomienie skilla w Claude Code Skill `design-md-extractor` aktywowany jest naturalnymi poleceniami w dialogu lub przez specjalne wywołanie slash-command. ### Polecenia uruchamiające w terminalu :::tabs @tab Bezpośredni URL ```text /design-md-extractor https://linear.app ``` @tab Nazwa marki ```text Create a comprehensive DESIGN.md and preview for Stripe dashboard ``` @tab Plik lokalny lub makietę ```text Analyze the design system from our prototype at http://localhost:3000 and export DESIGN.md ``` ::: ### Co dzieje się po wysłaniu polecenia 1. Claude Code uruchamia wewnętrzne skrypty zbierania stylów. 2. Agent wyświetla postęp skanowania: czytanie zmiennych CSS, analiza fontów, pomiar komponentów. 3. W katalogu głównym repozytorium pojawiają się pliki `DESIGN.md` oraz `design-preview.html`. 4. Agent proponuje otwarcie pliku HTML w przeglądarce (`open design-preview.html`). --- ## 7. Integracja tokenów w Tailwind CSS, Figma i React Uzyskane tokeny łatwo integrują się z realnym procesem produkcyjnym bez konieczności ręcznego przepisywania konfiguracji. ### Eksport do konfiguracji Tailwind CSS Wykorzystuj wyodrębnione wartości bezpośrednio w `tailwind.config.ts`: ```typescript import type { Config } from 'tailwindcss'; const config: Config = { content: ['./src/**/*.{js,ts,jsx,tsx,mdx}'], theme: { extend: { colors: { brand: { primary: '#4F46E5', 'on-primary': '#FFFFFF', surface: '#1E293B', background: '#0F172A', }, }, borderRadius: { sm: '4px', md: '8px', lg: '16px', }, fontFamily: { sans: ['Inter', 'sans-serif'], }, }, }, plugins: [], }; export default config; ``` ### Podłączanie przez CSS Custom Properties Możesz również zaimportować zmienne do pliku `globals.css`: ```css :root { --color-primary: #4f46e5; --color-on-primary: #ffffff; --color-surface: #1e293b; --radius-md: 8px; --spacing-base: 8px; } ``` ### Synchronizacja z Figma przez Tokens Studio Blok YAML z pliku `DESIGN.md` można przekonwertować do formatu JSON (`tokens.json`) i zaimportować do pluginu **Tokens Studio for Figma**, natychmiast tworząc zestaw zmiennych Figma Variables. --- ## 8. Praktyczne scenariusze biznesowe i przypadki użycia Ekstraktor systemów designu to niezastąpione narzędzie do szybkiego rozwoju produktu i analityki. ### Cztery główne scenariusze zastosowania 1. **Reverse-engineering i analiza konkurencji:** Uzyskaj pełny rozkład stylu liderów branży (Linear, Vercel, Apple, Stripe) jeszcze przed napisaniem pierwszej linii własnego CSS. 2. **Onboarding do nowego projektu klienta:** Zamiast długich ankiet dotyczących brandbooka, wystarczy uruchomić ekstraktor na obecnej stronie klienta i w minutę otrzymać gotową bazę stylów. 3. **Budowa MVP bez projektanta:** Założyciele startupów mogą wziąć wizualną harmonię udanego produktu za podstawę, dostosować kolory akcentowe i uzyskać profesjonalny wygląd aplikacji od pierwszego dnia. 4. **Zasilanie systemów agentowych:** Plik `DESIGN.md` działa jako kontekst systemowy dla innych asystentów AI, gwarantując, że nowe strony generowane przez modele będą ściśle zgodne z zadanym systemem designu. --- ## 9. Warsztat praktyczny: ekstrakcja systemu designu i budowa komponentu Spróbujmy przejść pełny cykl: od analizy strony do stworzenia nowego komponentu React na podstawie uzyskanych tokenów. ### Krok 1. Uruchomienie ekstrakcji docelowej strony Otwórz terminal w swoim projekcie i wykonaj: ```text Extract design system from https://news.ycombinator.com or your preferred inspiration website ``` Claude zbierze dane i wygeneruje `DESIGN.md`. ### Krok 2. Przegląd wygenerowanego UI-kita Otwórz otrzymany podgląd w przeglądarce internetowej: ```bash open design-preview.html ``` Upewnij się, że paleta, kontrastowość i rozmiary typograficzne odpowiadają estetyce strony. ### Krok 3. Generowanie komponentu na podstawie pliku DESIGN.md Postaw zadanie Claude Code z bezpośrednim odniesieniem do stworzonej specyfikacji: ```text Using the tokens and component rules defined in DESIGN.md, create a responsive PricingCard component in src/components/PricingCard.tsx with primary and secondary CTA buttons. ``` Claude odczyta dokładne promienie, cienie i kolory z `DESIGN.md` i stworzy komponent organicznie wpisujący się w docelowy system designu: ```typescript import React from 'react'; interface PricingCardProps { title: string; price: string; features: string[]; isPopular?: boolean; } export const PricingCard: React.FC = ({ title, price, features, isPopular }) => { return (

{title}

{price}
); }; ``` --- ## 10. Szybka samoocena i podsumowująca checklista Utrwal wiedzę na temat pracy z ekstraktorem systemów designu. ### Pytania kontrolne > **1. Skąd DESIGN.md Extractor pobiera dokładne wartości kolorów i fontów?** > > > [!TIP] > > **Odpowiedź:** Skill odczytuje rzeczywiste custom properties CSS (`:root`) oraz style obliczone (Computed Styles) bezpośrednio z DOM żywej strony, zamiast generować wartości losowo. > **2. Jakie dwa kluczowe pliki są tworzone w wyniku działania skilla?** > > > [!TIP] > > **Odpowiedź:** Maszynowo czytelny dokument `DESIGN.md` (z nagłówkiem YAML i 7 sekcjami tekstowymi) oraz samowystarczalna strona podglądu offline `design-preview.html`. > **3. Jak plik DESIGN.md pomaga w pracy innych skilli AI Claude?** > > > [!TIP] > > **Odpowiedź:** Służy on jako sztywny kontekst designowy: generatory interfejsów AI czytają tokeny z `DESIGN.md` i tworzą nowe komponenty, które są w 100% spójne z marką.