Màu sắc

Hợp đồng màu ba vai trò

Đây là luật quan trọng nhất của hệ thống. Mọi sắc màu — thương hiệu, trạng thái, accent, accent riêng của từng app — đều có ba biến thể, và hậu tố nói chính xác nó được phép xuất hiện ở đâu. Chọn sai là lỗi tương phản, không phải chuyện gu.

Sai, và cách sửa

Mọi tỉ lệ trong bảng đó đo ở bảng mặc định, theme sáng — trạng thái của một app khi chưa đặt gì. Đổi bảng thì số đổi, nhưng không cứu được hàng nào: mỗi hàng sai ở vai trò, không phải ở giá trị, và hai bảng chỉ khác nhau ở giá trị đứng sau một cái tên.

Hai bảng tương phản, một bộ component

Gói có hai bảng màu hoàn chỉnh. Bảng nào đang dùng là một cài đặt của người dùng, độc lập với sáng và tối — mỗi bảng có nhánh sáng và nhánh tối riêng, nên tổng cộng có bốn trạng thái màu.

// app/layout.tsx — a Server Component. ContrastProvider renders its own
// anti-flash script inside <body>; nothing goes in <head>.
import { ContrastProvider, ThemeProvider } from '@comitor/ui/shell'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider>
          <ContrastProvider>{children}</ContrastProvider>
        </ThemeProvider>
      </body>
    </html>
  )
}

'use client'

// A settings page. The label and description follow ComitorLocaleProvider —
// "High contrast" in English, "Tương phản cao" under locale="vi" — so there is
// nothing to pass; `labels` is only for wording of your own.
import { ContrastToggle } from '@comitor/ui/shell'

export function DisplaySettings() {
  return <ContrastToggle />
}

Thương hiệu — thang gold

Bảy nấc. gold-300 là --primary ở theme sáng, gold-200 là --primary ở theme tối. Mọi nấc khác trong thang có mặt vì có một token vai trò trỏ vào nó.

Trung tính thương hiệu

Cặp ink/paper của brand book. Tách khỏi thang ash — hai màu này ấm, ash thì không. --background và --card là #FFFFFF trơn ở theme sáng và #0E1116 / #16181D ở theme tối.

Trung tính — thang ash

Chỉ sáu nấc: 50 / 100 / 300 / 500 / 700 / 900. Các khoảng trống là cố ý. Nếu thang này vẫn tên gray-*, thì gray-200/400/600/800 sẽ lặng lẽ rơi xuống màu gray dựng sẵn của Tailwind v4 — ngả xanh dương, trong khi xám Comitor ngả tím — và hai thứ sẽ trộn lẫn trong một component. Đổi namespace thành ash-* nghĩa là một nấc thiếu chỉ là không có gì lúc build, chứ không phải màu lệch lúc chạy. gray-* không thuộc design system này.

Màu accent — vai trò fill

Các màu này được chọn để làm nền: fill đặc, hoặc tint /5–/20. Không bao giờ dùng chúng làm chữ. Lưu ý không có --red-foreground: #D64545 đặc không mang được chữ trắng (4,38:1) lẫn chữ ink (4,32:1), nên fill đỏ cần chứa chữ thì đi qua --destructive.

Màu accent — vai trò ink

Cùng sáu sắc màu, cố định ở một nấc đủ tối để đọc được trên nền trang hoặc trên tint /5–/20 của chính nó. Ở theme tối, mỗi màu trỏ ngược về màu fill, nên text-teal-ink viết một lần và đúng ở cả hai theme. Hex hiển thị là của theme sáng.

Sắc nhận diện — blue, purple, pink

Ba sắc màu hoàn toàn không mang nghĩa trạng thái, thêm ở 3.10.0 cho tông avatar và icon app, thay cho navy, ash và neutral — ba màu xám ngả xanh khiến các app khác nhau trông như cùng một màu. Mỗi màu có đủ ba vai trò: fill, một nấc ink đọc được trên nền trắng và trên tint /15, /20 của chính nó, và từ 3.11.0 thêm -foreground cho chữ trên fill đặc, nên chúng cũng dùng được làm accent khung của một app. Không bao giờ dùng chúng để nói một việc thành công hay thất bại. Hex hiển thị là của theme sáng; fill ở theme tối là #82A8F5, #A78BFA và #FF69B4, và các nấc ink trỏ ngược về chúng.

Ghi đè một token

App được phép khai báo lại bất kỳ biến nào trong số này trong CSS của mình. Ba trường hợp đi kèm một nghĩa vụ, vì một giá trị thứ hai ở chỗ khác trong file được suy ra từ giá trị đang đổi và sẽ không đổi theo.

Đổi một accent thì tính lại nấc ink của nó

--teal-ink, --green-ink và --red-ink là hex viết thẳng. Chúng là kết quả đã cố định của color-mix(in srgb, <hue>, --ink 30–40%), không phải biểu thức sống — nên ghi đè --teal sẽ tô lại mọi tint mà để chữ bên trên đứng nguyên chỗ cũ. Đặt nấc ink trong cùng khối, và đo hai lần: trên nền trang và trên tint /15 của màu mới. Cả hai số đo phải đạt 4,5:1; thường tint là chỗ chật hơn.

Hai sắc màu còn lại hỏng theo cùng kiểu vì một lý do khác. --yellow-ink mượn --gold-500 chứ không suy ra từ --yellow, còn --navy-ink là một hex riêng ở theme tối. Cả hai cũng không bám theo fill của mình.

Bề mặt dòng bảng được trộn sẵn

--table-row-stripe và --table-row-hover là kết quả trộn phẳng của hai token khác: --muted ở 30% và ở 50%, đã trộn sẵn lên --card. Ở theme sáng đó là #FDFDFD và #FBFBFC; ở theme tối, #181B20 và #1A1D23. Đổi --muted hay --card thì hai token này lặng lẽ lệch nhịp — không có lỗi gì, chỉ là sọc xen kẽ không còn là một sắc độ của bề mặt bên dưới nữa. Tính lại cả hai.

Chúng đục vì bắt buộc chứ không phải vì sở thích. Cột ghim lấy bg-inherit từ dòng của nó, nên còn chút alpha nào trong nền dòng là ô ghim thành trong mờ, và các cột cuộn bên dưới hiện xuyên qua. Và chúng viết bằng hex chứ không bằng color-mix() vì cùng lý do với các nấc ink: cổng tương phản của gói đọc token dưới dạng giá trị hex viết thẳng, và token nó không đọc được là token nó không kiểm được.

Accent riêng của app là khai báo CSS, không phải style inline

Mỗi app trong hệ sinh thái tô accent riêng của mình. Khai báo nó trong stylesheet của app, sau dòng import gói, kèm nhánh .dark — không phải style inline trên <body>. Một giá trị inline duy nhất không có chỗ cho nhánh tối, và accent đủ tối để đọc trên nền trắng gần như luôn quá tối để đọc trên #0E1116.

/* app/globals.css — after @import "@comitor/ui/styles.css" */

:root {
  --app-accent: #1F8A8B;            /* solid fill and /5–/20 tints only        */
  --app-accent-foreground: #0E1116; /* text on that solid fill      → 4.56:1   */
  --app-accent-ink: #1A6668;        /* the app colour on the page   → 6.68:1   */
}

.dark {
  --app-accent: #2DD4BF;
  --app-accent-foreground: #0E1116; /* 10.16:1                                 */
  --app-accent-ink: #2DD4BF;        /* 10.16:1 on --background                 */
}

Ba biến, không phải hai. Bỏ --app-accent-ink thì mọi dấu active trên thanh bên và khung icon của PageHeader rơi về gold mặc định — đọc được, nhưng sai màu, và không gì báo cho biết. Gói cố ý không suy nấc ink từ --app-accent bằng color-mix(): mỗi sắc màu cần một hệ số khác nhau, và phép suy tự động cho ra một tỉ lệ chưa ai đo. Thêm cả --app-accent-foreground mỗi khi accent của app sáng hơn hoặc tối hơn gold.

Một giới hạn đã biết của cổng tương phản: mọi token cần một giá trị mặc định trong :root

Cổng kiểm màu của gói có thể trỏ vào stylesheet đã ghi đè của chính app (nó đọc COMITOR_UI_STYLES và COMITOR_UI_SRC). Khi làm vậy, cần biết nó đọc gì: chỉ bốn khối — :root, .dark, [data-contrast="high"] và .dark[data-contrast="high"]. Nó không bao giờ mở [data-density] hay [data-font-size].

Nên một token kích thước chỉ khai báo trong khối mật độ hay khối cỡ chữ thì, với cổng, là chuỗi rỗng. Điều đó quan trọng vì cổng quyết định chấm một fill khắt khe đến đâu dựa vào hình mà luật CSS vẽ ra: một trục cố định từ 24px trở xuống, hoặc một thanh rộng hết bề ngang, là bằng chứng mạnh rằng đây là một dấu hiệu mang nghĩa, và dấu hiệu phải đạt 3:1. Một độ dài nó không tính ra được làm mọi phép thử đó thành sai, nên dấu hiệu bị đọc như một bề mặt thường và ngưỡng nó phải đạt không bao giờ được áp. Hướng hỏng là hướng tệ: không phải báo nhầm, mà là cho qua nhầm.

Luật rút ra: cả năm token mật độ — --row-py, --menu-item-py, --list-item-py, --nav-item-py, --table-head-h — đều mang giá trị comfortable trong :root, và khối mật độ chỉ viết lại nó. Thêm token thứ sáu cũng theo cách đó. Chỉ khai báo trong khối mật độ vẫn chạy hoàn hảo trên trình duyệt — chính vì thế thiếu sót này dễ lọt vào bản phát hành.

Token vai trò

Đây là những tên một component dùng tới. Tên nào cũng được khai báo trong khối @theme inline của styles.css — chính khối đó biến chúng thành utility của Tailwind. Danh sách dưới đây là bộ đã phát hành — tên nào không có ở đây thì không tồn tại.

Chữ inline gánh việc thật. Nó nhúng var(--x) vào utility được sinh ra, nên utility tính biến ngay trên trình duyệt và .dark { --primary } vẫn tô lại nó lúc chạy. @theme trơn thì cố định giá trị lúc build — mọi utility sẽ đóng cứng hex của theme sáng và theme tối đơn giản là ngừng chạy. Nếu fork styles.css, giữ lại từ khoá này.

Cũng có trong gói và theo cùng hợp đồng: bộ ngữ nghĩa của shadcn (--background, --foreground, --card, --popover, --primary, --secondary, --muted, --accent, mỗi token kèm một -foreground), năm nấc biểu đồ --chart-1 … --chart-5, và bốn nấc độ nổi shadow-surface / control / card / overlay.

Tương phản

Bảng mặc định không đạt mọi ngưỡng WCAG, và giả vờ như có sẽ khiến ai đó đi "sửa" một giá trị được chọn có chủ ý. Các chỗ hụt dưới đây là quyết định đã ghi lại. Chỗ để nâng chúng là bảng tương phản cao, không phải bảng mặc định.

Chỗ hụt đã biết của bảng mặc định

Tám hàng đó là hồ sơ của design system, chép từ khối ở đầu styles.css. Chúng là quyết định về token, không phải số đếm chỗ dùng. Đếm chỗ dùng là việc của cổng, và trước 1.6.0 cổng không làm được việc đó ở đây: nó gộp khối [data-contrast="high"] vào cả hai bảng biến của nó, nên mỗi lần chạy đều đo bảng tương phản cao hai lần và in hai kết quả ra thành “sáng” và “tối”. Bảng mặc định — bảng của app khi chưa đặt gì — chưa từng được đo.

Từ 1.6.0, bảng màu là một trục riêng, nên cổng đo bốn tổ hợp thay vì hai, và hai bảng chịu hai mức yêu cầu khác nhau. Bảng tương phản cao chặn: vi phạm ở đó làm hỏng build, và hiện không có vi phạm nào. Bảng mặc định được đo và in ra, không chặn — mỗi lần chạy kết thúc bằng một con số, hiện là 384 cặp dưới ngưỡng, 78% trong đó từ ba token: --muted-foreground, --destructive-ink và --input. Nâng chúng nghĩa là sửa giá trị token, làm đổi diện mạo của mọi app, nên đó vẫn là quyết định của design system chứ không phải thứ đi kèm một bản sửa cổng. Đọc con số đó như một khoản nợ có sổ ghi, không phải giấy chứng nhận sạch — và mọi số liệu “sáng” viết trước 1.6.0 hãy coi là của bảng tương phản cao cho tới khi được đo lại.

Bảng tương phản cao đổi những gì

Số liệu của theme sáng. Lưu ý --border được nâng lên 2,49:1 chứ không lên tới nấc viền control: nó đóng khung mọi thẻ và mọi dòng bảng, và kéo nó ngang --input sẽ xoá ranh giới giữa "cái này thao tác được" và "đây là một đường kẻ". Cũng lưu ý --control-on thành #B48700 chứ không phải gold-500 — gold-500 đạt ngưỡng nhưng trông như nâu ô liu, và một chế độ tương phản không được đổi sắc thương hiệu.

…và những gì nó đổi thêm ở theme tối

Tương phản cao là trục thứ hai, không phải theme thứ hai, nên nó có nhánh tối riêng: .dark[data-contrast="high"]. Khoảng nửa bảng trên sẽ sai nếu để nhánh sáng áp xuống theme tối — #A4A4A6 là xám nhạt, và trên #16181D nó thành một đường kẻ chói mắt thay vì một đường kẻ lặng. Nên nhánh tối khai báo lại các token đó ở giá trị cho ra cùng tỉ lệ từ phía bên kia.

Bốn hàng cuối là những hàng nhánh sáng không có tương đương. Ở theme sáng, các accent có cùng hex ở cả hai bảng; ở theme tối chúng được nâng lên nấc sáng hơn, và các nấc ink tự đi theo, không tốn gì — theme tối khai báo --teal-ink: var(--teal) và tương tự cho green, red và yellow, nên nâng fill là nâng chữ theo, không phải giữ đồng bộ giá trị thứ hai nào. Đó là phần được hưởng từ một luật trông như thừa ở nhánh sáng. Cũng lưu ý độ ưu tiên (specificity): [data-contrast="high"] và .dark đều nặng (0,1,0), nên chính thứ tự các khối trong styles.css mới khiến việc này chạy được.

Các cặp đạt

Mức xếp hạng tính cho chữ cỡ thường: AA là từ 4,5:1 trở lên, AAA là từ 7:1 trở lên. Một cặp nằm giữa 4,5 và 7 chỉ đạt AA, không hơn, dù trông dễ đọc đến đâu.

Token ngoài Tailwind — @comitor/ui/tokens

Một entry riêng xuất các giá trị này dưới dạng object TypeScript thuần, cho những nơi không có Tailwind để biên dịch class: render canvas, xuất PDF, thư viện biểu đồ chạy bằng hex, và HTML email. Entry này không có peer dependency nào.

Đọc cho chính xác: @comitor/ui/tokens không phải bản sao của entry chính, nó chính là module token của entry chính. @comitor/ui có export * from './tokens.js', nên /tokens là tập con thực sự của . — tách ra cửa riêng chỉ để mã cần hằng số có thể bỏ qua hẳn React và Tailwind. Import semantic từ cửa nào cũng nhận đúng một object, không phải hai bản sao có thể lệch nhau. Dùng /tokens trong worker, trình render mail hay script; ở mọi chỗ khác, dùng cửa nào đã được import sẵn.

import { accentInk, chart, getAvatarToneColors, layout, semantic } from '@comitor/ui/tokens'

// Canvas, PDF export, chart libraries with no Tailwind, HTML email.
const series = chart.light[0]                     // '#E8B824'
const headerPx = layout.headerHeight              // 56
const errorText = semantic.dark.destructiveInk    // '#D64545'
const successText = accentInk.light.green         // '#216A48'

// Same tone table and same hash as getAvatarToneClasses() in '@comitor/ui',
// so one person gets one colour on the web and in email alike.
const { background, foreground } = getAvatarToneColors('Nguyen Duc Thanh', 'light')