Tema terang/gelap khusus komponen

Fitur web: color-scheme light-dark()

Meskipun lebih sering ditetapkan di root, properti color-scheme dapat ditetapkan di setiap elemen untuk memaksanya menggunakan skema warna yang berbeda dari bagian halaman lainnya. Hal ini dapat berguna untuk komponen yang harus selalu dilihat dalam skema warna tertentu (misalnya, selalu dalam mode gelap atau terang).

Contoh kasus penggunaan mencakup:

  • Elemen yang sering kali berada dalam mode gelap bahkan di halaman mode terang karena alasan estetika, misalnya blok kode, pemutar media, galeri foto
  • Area yang berisi media yang didesain untuk latar belakang terang (misalnya, gambar, video, ilustrasi, pratinjau cetak) dapat disetel ke mode terang meskipun bagian halaman lainnya menggunakan mode gelap.
  • Elemen yang skema warnanya dikontrol oleh setelan tingkat pengguna, seperti pratinjau komponen
  • Penyematan yang tidak mendukung mode terang dan gelap
  • Alat desain, peta, visualisasi, game, dll.

Kapan harus mengubah warna vs. kapan harus memaksa color-scheme?

Tidak semua elemen yang menggunakan teks lebih terang di latar belakang lebih gelap dalam mode terang atau teks lebih gelap di latar belakang lebih terang dalam mode gelap memerlukan color-scheme yang berbeda. Misalnya, tombol utama dapat dirender sebagai biru dengan teks putih dalam mode terang, tetapi hal itu tidak menjamin color-scheme: dark.

Sebagai aturan umum, elemen yang menggunakan color-scheme yang berbeda biasanya adalah platform kompleks yang menetapkan konteks visualnya sendiri, bukan penampung dangkal yang sederhana.

Saat mempertimbangkan untuk menggunakan color-scheme yang berbeda pada suatu elemen, tanyakan pada diri Anda:

  • Haruskah UI browser bawaan yang tidak disesuaikan (misalnya, kontrol formulir, scrollbar, dll.) menggunakan skema warna tersebut atau menyesuaikan dengan skema warna halaman? -> jika yang pertama, jangan gunakan color-scheme.
  • Apakah warna light-dark() harus di-resolve seperti pada bagian halaman lainnya atau berdasarkan penggantian? -> jika yang pertama, jangan gunakan color-scheme.
  • Haruskah keturunan berada di color-scheme tersebut? Jika tidak, jangan gunakan color-scheme.

Penerapan dasar

Penggantian khusus komponen biasanya (meskipun tidak mutlak) digunakan di halaman yang juga mendukung beberapa skema warna melalui color-scheme global. Untuk menerapkan mode gelap di seluruh halaman dengan baik, lihat Mode gelap.

Setelah color-scheme di seluruh halaman diterapkan, dan Anda menggunakan token warna yang sensitif terhadapnya (misalnya, melalui light-dark()), Anda cukup menetapkan color-scheme pada komponen tertentu untuk mengganti mode warna untuk subhierarki tersebut:

pre, code, .dark {
  color-scheme: dark;
}

Perlu diketahui bahwa beberapa browser otomatis menyesuaikan komponen ke skema warna yang berbeda. Untuk menerapkan skema warna yang ditentukan dalam semua kasus, gunakan only, yaitu color-scheme: only dark;, bukan color-scheme: dark;.

Menyesuaikan nilai non-warna

light-dark() saat ini hanya berfungsi untuk warna.

Praktik terbaik

  • WAJIB: Jangan tetapkan color-scheme pada elemen tanpa latar belakang, karena berisiko mencampur pasangan warna latar belakang dan teks dari skema warna yang berbeda, sehingga teks tidak dapat dibaca.
  • OPSIONAL: Meskipun lebih mudah untuk menggunakan kembali pasangan warna yang sama dengan mode gelap di seluruh halaman, kita dapat menentukan pasangan warna yang berbeda untuk komponen ini. Misalnya, kita mungkin ingin komponen mode gelap yang digunakan di halaman mode terang menjadi sedikit lebih terang daripada saat komponen mode gelap yang sama digunakan di halaman yang secara keseluruhan menggunakan mode gelap.

Masalah umum yang perlu diperhatikan

Hal penting yang perlu diperhatikan: Pewarisan warna light-dark()

light-dark() di-resolve pada waktu nilai yang dihitung. Artinya, properti <color> yang diwarisi dan ditetapkan ke warna light-dark() hanya akan meneruskan salah satu dari dua warna tersebut ke turunannya, bukan ekspresi light-dark() itu sendiri.

Hal ini mencakup:

  • Properti warna bawaan yang diwarisi, seperti color, accent-color, fill, stroke, text-shadow, caret-color
  • Semua properti kustom yang dapat diwariskan dan terdaftar dengan syntax: <color> dan inherits: true
  • Properti <color> lainnya yang ditetapkan ke inherit

Artinya, Anda harus:

  • JANGAN mendaftarkan properti kustom yang dimaksudkan untuk menyimpan token desain (misalnya, --surface-color) sebagai <color>. Token harus mempertahankan ekspresi light-dark()-nya tetap aktif sehingga turunannya dapat di-resolve ulang di bawah color-scheme yang berbeda.
  • Saat menetapkan color-scheme pada elemen, tentukan ulang properti <color> yang diwarisi yang mungkin telah ditetapkan ke nilai light-dark() (secara langsung atau melalui token desain), meskipun ke token desain yang sama.
  • TIDAK menggunakan inherit pada properti <color> di elemen dengan penggantian color-scheme (boleh digunakan pada turunannya).
  • LAKUKAN penggunaan properti <color> terdaftar untuk kasus penggunaan yang berlawanan: saat Anda sengaja ingin mengambil snapshot warna yang di-resolve ancestor dan mencegahnya di-resolve ulang di bawah color-scheme turunan. Misalnya, mengambil latar belakang halaman untuk digunakan di tempat lain.
  • Jika Anda perlu menganimasikan warna, gunakan properti <color> terpisah yang terdaftar di @property pada elemen yang dianimasikan (pendaftaran diperlukan untuk interpolasi warna) — ini bukan token desain, melainkan target animasi per elemen, sehingga tidak bertentangan dengan aturan di atas.

Contoh:

:root {
    --accent-color: light-dark(blue, skyblue);
    --surface-color: light-dark(white, #222);
    --text-color: light-dark(#111, white);

    color-scheme: light dark;
    accent-color: var(--accent-color);
    color: var(--text-color);
}

body {
    /* --surface-color dynamically switches despite being inherited because --surface-color is not registered */
    background: var(--surface-color);
}

pre, code {
    color-scheme: dark;
    background: var(--surface-color);

    /* Without this, accent-color would be blue, not skyblue! */
    accent-color: var(--accent-color);

    /* Without this, text-color would be #111, not white! */
    color: var(--text-color);
}

Masalah yang perlu diperhatikan saat menggunakan color-scheme

  • Chrome dan Firefox mematuhi color-scheme untuk iframe: keduanya merender halaman tersemat dalam skema warna yang benar dan menyesuaikan kueri media prefers-color-scheme halaman tersemat untuk mencerminkan color-scheme konteks penyematan. Safari tidak melakukannya, dan me-resolve prefers-color-scheme ke setelan sistem bahkan di dalam iframe.
    • Jika Anda mengontrol induk dan iframe: teruskan skema warna induk ke iframe secara eksplisit — melalui parameter URL (?theme=dark) pada waktu pembuatan iframe, atau melalui postMessage() (yang juga memungkinkan Anda bereaksi terhadap perubahan runtime). Di iframe, tetapkan class di <html> (dan/atau color-scheme di :root) dari sinyal tersebut, bukan mengandalkan prefers-color-scheme.
    • Jika Anda hanya mengontrol halaman yang disematkan: tidak ada cara yang andal untuk mendeteksi color-scheme konteks penyematan dari dalam iframe di Safari. Ekspos parameter tema eksplisit di API sematan Anda (misalnya, string kueri atau protokol postMessage) dan dokumentasikan untuk penyemat.

Strategi penggantian

Penggantian & dukungan browser untuk skema warna

Properti color-scheme adalah progressive enhancement. Browser yang tidak mendukungnya akan mengabaikan properti ini dan menggunakan UI mode terang default.

Untuk menyesuaikan dengan preferensi pengguna di browser lama, gunakan kueri media prefers-color-scheme untuk memberikan warna yang berbeda saat mode gelap lebih disukai.

  • GUNAKAN kueri media untuk mengaktifkan properti kustom di :root atau html
  • Hindari penggunaan kueri media pada setiap komponen, kecuali jika komponen tersebut memerlukan jenis penyesuaian mode gelap yang sangat spesifik selain warna.
:root {
  /* Define brand colors for each mode */
  --color-brand-light: #0056b3;
  --color-brand-dark: #00e5ff;
  --color-brand: var(--color-brand-light);

  /* MANDATORY: Fallback for browsers without light-dark support */
  @media (prefers-color-scheme: dark) {
    --color-brand: var(--color-brand-dark);
  }

  /* Ignored in older browsers */
  color-scheme: light dark;
}

button.primary {
    background-color: var(--color-brand);
}

Penggantian & dukungan browser untuk light-dark()

Untuk browser yang mendukung color-scheme, tetapi belum mendukung light-dark(), versi warna terang dan gelap harus ditentukan terlebih dahulu sebagai properti kustom, dan kueri media prefers-color-scheme harus digunakan untuk menetapkan warna untuk masing-masing mode seperti dalam contoh di bawah:

:root {
  /* Define browser UI accent color for each mode */
  --brand-accent-light: #0056b3;
  --brand-accent-dark: #00e5ff;
  --accent-color: var(--brand-accent-light);

  /* MANDATORY: Fallback for browsers without light-dark support */
  @media (prefers-color-scheme: dark) {
    --accent-color: var(--brand-accent-dark);
  }

  /* OPTIONAL: use light-dark() for more control of built-in UI colors */
  @supports (color: light-dark(white, black)) {
    --accent-color: light-dark(var(--brand-accent-light), var(--brand-accent-dark));
  }

  /* MANDATORY: Automatically adapt native UI to user system preferences */
  color-scheme: light dark;

  /* Example inherited color property */
  accent-color: var(--accent-color);
}

pre, code {
  color-scheme: dark;

  /* **Mandatory**: any inherited color properties must be set again, even if to the same design tokens */
  accent-color: var(--accent-color);
}