Dokumentasi

Apa itu DESIGN.md?

DESIGN.md adalah file teks biasa yang mendeskripsikan sistem desain untuk agen AI. Front matter YAML di bagian atas menyimpan token desain yang persis: warna, tipografi, spacing, sudut membulat, dan komponen. Isi markdown di bawahnya menjelaskan bagaimana dan mengapa token itu diterapkan. Manusia dan agen sama-sama bisa membacanya, mengeditnya, dan menerapkannya.

README.md menjelaskan apa itu sebuah proyek. AGENTS.md memberi tahu agen coding cara membangunnya. DESIGN.md memberi tahu bagaimana tampilan dan nuansanya, sehingga layar-layar yang dibuat agen memakai satu palet, skala tipografi, dan bahasa komponen yang sama, bukan saling menyimpang.

Asal-usul DESIGN.md

Google memperkenalkan DESIGN.md bersama Google Stitch, alat desain AI miliknya, sebagai pasangan desain dari AGENTS.md. Google Labs memublikasikan format ini sebagai spesifikasi terbuka di repository google-labs-code/design.md dengan lisensi Apache 2.0. Spesifikasi DESIGN.md berlabel alpha, jadi formatnya bisa berubah seiring perkembangannya.

Repository yang sama menyediakan paket npm, @google/design.md, dengan perintah lint yang mengecek struktur, referensi token yang rusak, dan kontras WCAG, serta perintah diff yang membandingkan dua versi file token demi token.

Anatomi file DESIGN.md

Setiap file DESIGN.md punya dua lapisan. Front matter YAML berisi token desain yang bisa dibaca mesin, seperti nilai warna yang persis, properti font, skala spacing, dan referensi token komponen. Isi markdown memberikan alasan desain yang bisa dibaca manusia.

Spesifikasi memperlakukan token sebagai nilai normatif dan teks sebagai konteks penerapannya. Token memberi agen nilai yang presisi. Teks menjelaskan mengapa nilai-nilai itu ada dan bagaimana memakainya secara konsisten di semua layar.

---
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

Delapan bagian kanonis

Isi markdown memakai heading ##. Bagian boleh dihilangkan jika tidak relevan, tetapi jika ada, urutannya harus seperti ini. Heading yang muncul dua kali membuat file tidak valid; bagian yang tidak dikenal tetap dipertahankan.

Overview (juga Brand & Style). Tampilan dan nuansa dalam beberapa kalimat: suasana, kepadatan, karakter.
Colors. Setiap token warna dan perannya, seperti aksi utama atau permukaan halaman.
Typography. Font family dan skala tipografi, dari headline display hingga label kecil.
Layout (juga Layout & Spacing). Skala spacing, grid, lebar konten, dan gutter.
Elevation & Depth (juga Elevation). Cara permukaan dipisahkan: bayangan, border, tint.
Shapes. Radius sudut dan aturan bentuk lainnya.
Components. Tombol, input, kartu, dan atom lainnya, beserta token dan state-nya.
Do's and Don'ts. Aturan yang tidak boleh dilanggar agen.

Isi markdown ringkas dengan setiap bagian kanonis sesuai urutan. Sesuaikan isinya dengan produk Anda, pertahankan heading dan urutannya.

## 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

Token desain dan skema

DESIGN.md menyematkan token desain sebagai front matter YAML di awal file. Blok front matter diawali baris yang berisi persis --- dan diakhiri dengan pembatas yang sama.

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>

Nama skala yang umum antara lain xs, sm, md, lg, xl, dan full, tetapi key deskriptif apa pun valid. Token spacing ada di YAML di bawah spacing: dan dijelaskan di bagian Layout pada isi markdown.

Jenis token

Color: String warna CSS apa pun yang valid. Hex dalam bentuk #RRGGBB adalah default yang disarankan, misalnya "#1A1C1E".
Dimension: Angka ditambah satuan px, em, atau rem. Contoh:48px,-0.02em.
Token Reference: Diapit kurung kurawal dan menunjuk ke sebuah nilai di pohon YAML. Contoh:{colors.primary}.
Typography: Objek gabungan berisi properti font seperti family, ukuran, ketebalan, line height, dan letter spacing. Lihat Properti tipografi.

Properti tipografi

fontFamily: Nama font family.
fontSize: Ukuran font sebagai dimension.
fontWeight: Ketebalan numerik seperti 400 atau 700.
lineHeight: Dimension atau pengali tanpa satuan. Nilai tanpa satuan disarankan.
letterSpacing: Penyesuaian letter spacing sebagai dimension.
fontFeature: Mengatur font-feature-settings.
fontVariation: Mengatur font-variation-settings.

Referensi token

Referensi token diapit kurung kurawal dan berisi path objek ke nilai lain di pohon YAML. Untuk sebagian besar grup token, referensi sebaiknya menunjuk ke nilai primitif, bukan ke grup. Di dalam bagian components, referensi ke nilai gabungan seperti level tipografi diperbolehkan.

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

Komponen

Bagian components memuat panduan gaya untuk atom komponen seperti tombol, chip, list, input, checkbox, radio button, dan tooltip. Sistem desain boleh mendefinisikan komponen tambahan yang penting bagi domain produknya.

Varian untuk state hover, active, atau pressed didefinisikan sebagai entri komponen terpisah dengan nama key yang berkaitan, seperti button-primary-hover.

backgroundColor: Color
textColor: Color
typography: Typography
rounded: Dimension
padding: Dimension
size: Dimension
height: Dimension
width: Dimension

Nama token yang disarankan

Nama-nama ini adalah panduan, bukan kewajiban. Nama-nama ini memberi default yang berguna agar konsisten antarsistem.

Warna: primary, secondary, tertiary, neutral, surface, on-surface, error

Tipografi: headline-display, headline-lg, headline-md, body-lg, body-md, body-sm, label-lg, label-md, label-sm

Rounded: none, sm, md, lg, xl, full

Cara agen AI memakai DESIGN.md

Taruh DESIGN.md di root repository Anda, di samping README.md dan AGENTS.md. Agen apa pun yang punya akses file bisa membacanya, tetapi sebagian besar tidak memuatnya sendiri. Arahkan ke file itu dari instruksi yang sudah dibaca agen Anda, atau sebutkan di prompt saat Anda meminta pekerjaan UI. Petunjuk singkat sudah cukup:

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

Claude Code: Membaca file di repo Anda dan memuat CLAUDE.md saat mulai. Tambahkan satu baris di sana yang menunjuk ke DESIGN.md, atau sebutkan file itu di prompt Anda.
Cursor: Tambahkan DESIGN.md ke konteks chat, atau rujuk dari project rule agar berlaku untuk setiap permintaan UI.
GitHub Copilot: Arahkan ke DESIGN.md dari file instruksi Copilot di repository Anda, atau lampirkan di chat saat Anda meminta pekerjaan UI.
Google Stitch: Tempat format ini berawal. Stitch memakai DESIGN.md agar layar yang dihasilkan memakai satu palet, skala tipografi, dan bahasa komponen yang sama.

Agen lalu mengambil nilai persis dari token (hex untuk tombol primary, ukuran label body-md) dan memakai teksnya untuk menentukan di mana nilai itu dipakai.

DESIGN.md vs AGENTS.md vs README.md

Ketiga file ini berdampingan dan menjawab pertanyaan yang berbeda. DESIGN.md tidak menggantikan AGENTS.md; keduanya saling melengkapi.

File	Ditulis untuk	Menjawab
`README.md`	Orang yang memakai atau berkontribusi pada proyek	Apa ini, dan bagaimana cara menjalankannya?
`AGENTS.md`	Agen coding	Bagaimana cara membangun, menguji, dan mengubah kode ini?
`DESIGN.md`	Agen coding dan desain	Bagaimana seharusnya tampilan dan nuansa antarmukanya?

Contoh DESIGN.md nyata

Cara tercepat memahami format ini adalah dengan membaca beberapa file nyata. Setiap halaman galeri ini menampilkan DESIGN.md yang diekstrak dari website publik brand tersebut, lengkap dengan palet dan contoh tipografinya. File-file ini bukan pedoman brand resmi.

Jelajahi semua contoh DESIGN.md

Cara mendapatkan DESIGN.md

Tulis secara manual. Mulai dari spesifikasi dan contoh di atas, lalu cek file-nya dengan Validator DESIGN.md gratis atau perintah lint dari Google.
Mulai dari contoh. Salin file dari galeri, lalu edit token dan teksnya agar sesuai dengan produk Anda.
Buat dari website live. Tempel URL publik ke Design Extractor. Design Extractor merender situs di browser dan mengembalikan DESIGN.md berisi warna, tipografi, spacing, dan komponennya yang mengikuti spesifikasi di atas. Halaman DESIGN.md generator menjelaskan apa yang Anda dapatkan. Ekstraksi yang sama berjalan dari ekstensi Chrome dan dari agen Anda lewat server MCP.

FAQ

Pertanyaan tentang DESIGN.md

Jawaban singkat tentang format DESIGN.md, asal-usulnya, dan cara memakainya dengan agen AI.

DESIGN.md adalah file teks biasa yang mendeskripsikan sistem desain untuk agen AI. Front matter YAML di bagian atas menyimpan token yang persis (warna, tipografi, spacing, sudut membulat, dan komponen), dan isi markdown di bawahnya menjelaskan bagaimana dan mengapa token itu diterapkan. Agen membaca token untuk nilainya dan teks untuk maksudnya.

Google memperkenalkan DESIGN.md bersama Stitch, alat desain AI miliknya. Google Labs memublikasikan spesifikasinya di GitHub (google-labs-code/design.md) dengan lisensi Apache 2.0. Format ini berlabel alpha, jadi bisa berubah seiring perkembangannya.

AGENTS.md memberi tahu agen coding cara membangun dan mengerjakan sebuah proyek: perintah, konvensi, pengujian. DESIGN.md memberi tahu bagaimana tampilan dan nuansa produknya: warna, tipografi, spacing, bentuk, dan komponen. README.md ditujukan bagi manusia yang memakai atau berkontribusi pada proyek. Banyak repo menyimpan ketiganya berdampingan.

Taruh di root repository, di samping README.md dan AGENTS.md, agar agen yang punya akses file bisa menemukannya. Lalu arahkan ke file itu dari instruksi yang sudah dimuat agen Anda, seperti AGENTS.md, CLAUDE.md, Cursor rule, atau instruksi Copilot Anda, atau sebutkan di prompt saat Anda meminta pekerjaan UI.

Tidak. Spesifikasi mengizinkan Anda menghilangkan bagian yang tidak relevan, tetapi bagian yang Anda pertahankan harus mengikuti urutan kanonis: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. Heading bagian tidak boleh muncul dua kali, dan bagian yang tidak dikenal tetap dipertahankan, bukan ditolak.

Paket npm @google/design.md dari Google punya perintah lint yang mengecek struktur, referensi token yang rusak, dan kontras WCAG. Design Extractor juga punya Validator DESIGN.md gratis yang mengecek struktur dan token di browser Anda serta menampilkan pratinjau file, tanpa mengunggahnya.

Tulis secara manual dari spesifikasi, salin satu dari galeri contoh nyata sebagai titik awal, atau buat dari situs live-nya. Design Extractor menerima URL publik, merender situs di browser, lalu mengembalikan DESIGN.md berisi warna, tipografi, spacing, dan komponennya, siap ditaruh di repo Anda.

Ingin satu untuk situs yang Anda suka?

Tempel URL publik dan dapatkan DESIGN.md-nya.

Ekstrak situs

Jenis token

Properti tipografi

Referensi token

Komponen

Nama token yang disarankan

Pertanyaan tentang DESIGN.md

Apa itu file DESIGN.md?

Siapa yang membuat format DESIGN.md?

Apa perbedaan DESIGN.md dan AGENTS.md?

Di mana saya menaruh DESIGN.md di proyek saya?

Apakah saya butuh kedelapan bagian?

Bagaimana cara mengecek apakah DESIGN.md valid?

Bagaimana cara mendapatkan DESIGN.md untuk website yang sudah ada?