design-system

Design System

A design system shared by multiple sites: base colors, layers, functional colors, fonts, and corner radii are shared, and each product only swaps the interface accent color. This skill covers three things: analyzing a site's theme color, onboarding a new site or new theme, and checking whether plugins honor the contract. The color values themselves are not here; they are in the design system directory tokens.json(format see references/token-format.md）。

First find the design system

Search in order and stop at the first hit: the path given by the user → the current repository's design-system/tokens.json → the repository AGENTS.md/CLAUDE.md the brand repository path stated in. If none exist, ask the user; do not invent a set of color values yourself.

Once found, run a check first to confirm the starting point is good:

python3 scripts/check_tokens.py <design-system>/tokens.json

1. Analyze a site's theme color

Use when the user gives a URL, asks about its theme color or color approach, or wants to reference it.

First define the analysis target. Marketing sites (home page, pricing page) and product interfaces (the app after login) often differ in color: marketing pages can use gradients and background videos, while the product interface uses only one accent color. First confirm which one the user wants, and state the actual analyzed address in the conclusion.

Evidence grading. Determine the conclusion in the following order, and in the conclusion mark which level each color value belongs to:

Level	Source	Usage
Measured in interface	The getComputedStyle	of buttons, focus rings, selected states, links, and other elements actually rendered in the product interface; use to determine the conclusion
Variable definitions	Theme variables named by the product itself, e.g. --<产品>-theme-accent-color、--primary	shows the product defined this color; whether it is the interface accent color depends on the visibility check in the next paragraph
Assets or third-party corroboration	App icons, illustrations, background video pixels, CLI/terminal color schemes, a swatch in a general palette, third-party DESIGN.md collections	Used only for cross-checking; does not determine the conclusion on its own

Defined does not mean in use. A variable may be named accent or theme, yet the interface may barely use it. For each candidate accent color, list which visible elements it actually appears on and whether it can be seen in normal use: a color that appears only on states such as keyboard focus rings or occasional notification dots cannot be called the interface accent color. When the normally visible buttons, selected states, links, and icons are all black, white, and gray, say plainly that the interface is black and white, then list separately on one line the colors that are "defined but barely visible" and where they appear.

Icons and illustrations often use gradients; taking a pixel average yields a color that does not exist in the interface. CLI terminal color schemes must account for terminal readability, are usually taken from a general palette, and are not the same set as the web interface. When corroboration conflicts with measurement, measurement wins, and state both conflicting values in the conclusion.

Interfaces that require login. Ask the user to log in in the browser first, then use the host's browser tools to connect to this logged-in page and measure. Do not log in on the user's behalf and do not enter account credentials. If it cannot be seen, mark this part as UNVERIFIED, and do not substitute the colors of the marketing page or icon.

1. Use dembrandt to extract the actually rendered colors (pin the version). Run it directly first; if it reports a missing browser, then run install-browser, which may produce no output for a long time when a browser already exists locally or another process is downloading one:

   npx -y dembrandt@0.39.2 <url> --shadcn --wcag --save-output
   npx -y dembrandt@0.39.2 install-browser   # 只在上一条报缺浏览器时
   

2. dembrandt only gives "which colors appeared",--dark-mode Dark variables often can't be read either. Which color buttons, the current item, and the selected state each use must be measured: open the page with Playwright (or the host's built-in browser tool),waitUntil: "domcontentloaded" then wait a few more seconds (marketing sites often have long-lived connections,networkidle will time out), read for these kinds of elements getComputedStyle（background-color、color、border-color、box-shadow、font-weight), and read :root the CSS variables on. For dark mode use colorScheme: "dark" a browser context and read again.

   • When the page has several kinds of solid buttons, list them all: the one with the largest area on the first screen whose copy is the main action (trial, sign up, start) counts as the primary button; the rest are written as secondary buttons. A brand-colored button is not necessarily the primary button.
   • When the outer element reads rgba(0, 0, 0, 0) the color is mostly painted on the inner element or on ::before/::after , so look inward, or read the CSS variables the button uses.
   • When you hit a human verification challenge (e.g. Cloudflare's "Verify you are human"), do not bypass it: use only dembrandt's result for this page and state that it was not measured.
   • When the page redirects to another domain, state in the conclusion which address was actually analyzed.
   • If the page itself is black-and-white with no chroma, say so outright; then go to official brand materials, design system repositories, or product source code to find its signature color, and state the source.
   • If first-hand brand materials (official brand guidelines, design system repositories) can be found, use them to check the accent color.
   • When looking for an existing DESIGN.md reference, check in order VoltAgent/official-design-md(first-hand materials published officially by the brand),VoltAgent/awesome-design-md、Meliwat/awesome-ios-design-md(iOS apps),bergside/awesome-design-skills. These collections are incomplete and their values may be outdated; treat them only as corroborating evidence. When they conflict with measurements, go with the measurements and note it.

3. Output one table and a summary of no more than 5 practices, answering these questions:

   • Is the analyzed thing a marketing site or a product interface, and what is the actual address?
   • Which is the interface accent color (color value and source variable name); which visible elements does it appear on, can it usually be seen, is its area large or does it only appear in "dots"? If the interface is black-and-white, say so outright; list colors that are defined but almost invisible separately.
   • Are the neutrals cool, warm, or pure gray; does the layering rely on lines, brightness, or shadows?
   • Is the primary button text white or dark, what is the WCAG contrast ratio, and does it pass?
   • Is the selected state a solid block, a pale tinted background, or a vertical bar; is the background tinted with the brand color?
   • Label each color value as "measured in interface", "variable definition", or "asset or third-party corroboration"; label inferences separately as "inference". If a page visible only after login was not seen, write UNVERIFIED, and do not guess.

4. When the user wants to borrow from it, map the conclusions onto tokens.json roles, and build a comparison page so the user can see the real thing before deciding. Do not directly modify tokens.json。

2. Onboarding a new site or new theme

New site：

1. From tokens.json generate CSS variables (use the design system's own script if it has one; otherwise resolve references per the rules in token-format) and put them into the site styles.
2. Add to the root element data-accent="<主题>", and for dark mode add .dark。
3. In components write only semantic roles, e.g. var(--primary) ; replace each hard-coded color with the closest role one by one; if none fits, note it down and ask the user, and do not invent new roles.
4. Run the plugin checks from Section 3, then look at real pages once in light mode and once in dark mode.

New theme (new UI accent color): add to themes an item: a 12-step color scale (one light set, one dark set),solid、solid-foreground，solid defined by the button rules below. Run check_tokens.py, and only when all pass is it done.

Button rules：

• Color: keep the theme hue, push OKLCH chroma to the gamut limit, then adjust lightness. White text is about 4:1 in light mode and about 3:1 in dark mode, so solid is usually written as { "light": …, "dark": … }。
• Text: white, font weight 500, not 600.
• Shape: primary buttons use pill rounded corners (radius.pill); secondary buttons use black and white (light mode: black background, white text; dark mode: white background, black text).
• Contrast: primary buttons with white text only require ≥ 3.0, below WCAG AA's 4.5; this is a deliberate trade-off: ByteDance Arco, Semi, and Jimeng's solid buttons all use saturated colors with white text, measured at about 3.check_tokens.py Check this pair against 3.0.
• Rejected approaches: original color with near-black text (ugly); darkening the original color to 4.5 and then pairing with white text (looks gray, not like the original color); original color with a dark text of the same hue (unnatural).
• If the product itself is black and white, just use black-and-white buttons, inverted between light and dark modes.
• When unsure, make samples in both light and dark modes and show the user the real thing before deciding.

3. Check whether the plugin honors the contract

The plugin uses only semantic roles: no hardcoded color values,var() with no fallback colors, no references to roles that don't exist in the design system. Missing variables should break visibly, so people notice the theme isn't wired up.

python3 scripts/lint_plugin.py <插件目录> --tokens <design-system>/tokens.json

The script reports each item of 文件:行 — 问题 — 改法, and exits 1 if there are problems. Intentionally kept color values (e.g., a brand logo's fixed color) should have design-system-ignore written on the same line with the reason. The script only locates candidates: colors in logos, illustrations, and screenshots don't count as violations; judge each one before changing it.

When the plugin's registration or loading structure needs changes, hand that to code-plugin-architecture; this skill only handles colors and the theme contract.

Delivery

• Analysis: a table plus a summary of the approach, stating what was analyzed, with an evidence level marked for each color value.
• Integration: which files were changed, the results ofcheck_tokens.py and lint_plugin.py , and page verification in both light and dark modes. If the page wasn't viewed, write UNVERIFIED。
• Check: a list of issues and fixes; only make changes when the user asks.