ui-ux-pro-max-skill/cli/assets/scripts/tests/test_design_system_tokens.py

322 lines
13 KiB
Python

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Tests for --tokens dtcg|css export from the design-system generator.
Stdlib-only (unittest, not pytest) to match test_core.py -- this project ships
with zero external dependencies. The generate-tokens.cjs round-trip is skipped
when Node is missing; CI has Node.
Run with:
python -m unittest discover -s scripts/tests -v
or directly:
python scripts/tests/test_design_system_tokens.py
"""
import json
import re
import shutil
import subprocess
import sys
import tempfile
import unittest
from pathlib import Path
SCRIPTS_DIR = Path(__file__).resolve().parent.parent
sys.path.insert(0, str(SCRIPTS_DIR))
from design_system import ( # noqa: E402
SEMANTIC_COLOR_ENTRIES,
_contrast_ratio,
_HEX6,
build_design_tokens,
format_tokens_css,
format_tokens_dtcg,
generate_design_system,
)
ON_COLOR_PAIRS = (
("on_primary", "primary"),
("on_secondary", "secondary"),
("on_accent", "accent"),
("foreground", "background"),
("card_foreground", "card"),
("muted_foreground", "muted"),
("on_destructive", "destructive"),
)
SEARCH = SCRIPTS_DIR / "search.py"
REPO = next(
parent for parent in Path(__file__).resolve().parents
if (parent / "cli" / "assets" / "skills" / "design-system" / "scripts"
/ "generate-tokens.cjs").is_file()
)
GENERATE_TOKENS = (
REPO / "cli" / "assets" / "skills" / "design-system" / "scripts"
/ "generate-tokens.cjs"
)
HEX_TOKEN = re.compile(r"^#[0-9A-Fa-f]{6}$")
CSS_VAR = re.compile(r"^\s+(--[a-z0-9-]+):\s*(.+);\s*$", re.MULTILINE)
def _node_available():
return shutil.which("node") is not None
def _parse_css_vars(css: str) -> dict:
return {name: value for name, value in CSS_VAR.findall(css)}
class TokenExportTest(unittest.TestCase):
@classmethod
def setUpClass(cls):
cls.result = generate_design_system(
"fintech dashboard", "Ledgerly", token_format="dtcg"
)
cls.ds = cls.result["design_system"]
cls.tokens = cls.result["tokens"]
def test_color_mode_is_recorded(self):
self.assertIn(self.ds["color_mode"], ("light", "dark"))
def test_dtcg_shape_matches_starter_conventions(self):
tokens = self.tokens
self.assertEqual(tokens["$schema"], "https://design-tokens.org/schema.json")
self.assertIn("$description", tokens)
self.assertIn(self.ds["color_mode"], tokens["$description"])
self.assertIn("color", tokens)
self.assertIn("font", tokens)
self.assertIn("semantic", tokens)
semantic_color = tokens["semantic"]["color"]
for name in (
"primary", "on-primary", "background", "foreground",
"card", "muted", "border", "ring", "destructive",
):
self.assertIn(name, semantic_color)
self.assertEqual(semantic_color[name]["$type"], "color")
self.assertEqual(semantic_color[name]["$value"], "{color.%s}" % name)
self.assertEqual(tokens["color"][name]["$type"], "color")
self.assertRegex(tokens["color"][name]["$value"], HEX_TOKEN)
for role in ("heading", "body"):
self.assertEqual(tokens["font"][role]["$type"], "fontFamily")
self.assertTrue(tokens["font"][role]["$value"])
self.assertEqual(
tokens["semantic"]["font"][role]["$value"], "{font.%s}" % role
)
def test_every_exported_color_is_six_digit_hex(self):
for name, token in self.tokens["color"].items():
with self.subTest(color=name):
self.assertEqual(token["$type"], "color")
self.assertRegex(token["$value"], HEX_TOKEN)
self.assertTrue(_HEX6.match(token["$value"]))
def test_on_color_pairs_reuse_generator_contrast(self):
colors = self.ds["colors"]
for foreground, background in ON_COLOR_PAIRS:
with self.subTest(pair=foreground):
self.assertGreaterEqual(
_contrast_ratio(colors[foreground], colors[background]), 4.5
)
def test_css_uses_generate_tokens_variable_names(self):
css = format_tokens_css(self.tokens)
variables = _parse_css_vars(css)
for _label, key, css_var in SEMANTIC_COLOR_ENTRIES:
hex_val = self.ds["colors"].get(key)
if not hex_val:
continue
self.assertEqual(variables[css_var], hex_val)
self.assertIn("--font-heading", variables)
self.assertIn("--font-body", variables)
self.assertTrue(css.strip().startswith("/* Design Tokens"))
self.assertIn(":root {", css)
def test_dtcg_text_is_the_token_document(self):
parsed = json.loads(self.result["text"])
self.assertEqual(parsed["semantic"]["color"]["primary"]["$type"], "color")
self.assertNotIn("TARGET:", self.result["text"])
def test_css_token_format_prints_css(self):
result = generate_design_system(
"fintech dashboard", "Ledgerly", token_format="css"
)
self.assertIn("--color-primary:", result["text"])
self.assertEqual(result["tokens"]["color"]["primary"]["$value"],
_parse_css_vars(result["text"])["--color-primary"])
def test_spacing_tokens_only_when_density_is_set(self):
plain = build_design_tokens(
generate_design_system("fintech dashboard", "Ledgerly")["design_system"]
)
dense = build_design_tokens(
generate_design_system(
"fintech dashboard", "Ledgerly", density=9
)["design_system"]
)
self.assertNotIn("space", plain)
self.assertIn("space", dense)
self.assertIn("xs", dense["semantic"]["space"])
css_vars = _parse_css_vars(format_tokens_css(dense))
self.assertIn("--space-xs", css_vars)
class DarkModeTokenTest(unittest.TestCase):
def test_dark_query_marks_mode_and_emits_dark_surfaces(self):
result = generate_design_system(
"dark mode developer tool", "Nightshift", token_format="dtcg"
)
ds = result["design_system"]
tokens = result["tokens"]
self.assertEqual(ds["color_mode"], "dark")
self.assertIn("dark", tokens["$description"].lower())
background = tokens["color"]["background"]["$value"]
foreground = tokens["color"]["foreground"]["$value"]
self.assertRegex(background, HEX_TOKEN)
self.assertGreater(
_contrast_ratio(foreground, background), 4.5
)
css = format_tokens_css(tokens)
self.assertEqual(_parse_css_vars(css)["--color-background"], background)
class PersistTokenTest(unittest.TestCase):
def test_persist_dtcg_writes_tokens_json_beside_master(self):
with tempfile.TemporaryDirectory() as tmp:
result = generate_design_system(
"fintech dashboard", "Ledgerly", persist=True, output_dir=tmp,
token_format="dtcg",
)
folder = Path(tmp) / "design-system" / "ledgerly"
master = folder / "MASTER.md"
tokens_json = folder / "tokens.json"
self.assertTrue(master.exists())
self.assertTrue(tokens_json.exists())
self.assertFalse((folder / "tokens.css").exists())
self.assertIn(str(tokens_json), result["persistence"]["created_files"])
master_text = master.read_text(encoding="utf-8")
self.assertIn("tokens.json", master_text)
self.assertIn("master-level only", master_text)
parsed = json.loads(tokens_json.read_text(encoding="utf-8"))
self.assertEqual(parsed["semantic"]["color"]["primary"]["$type"], "color")
def test_persist_css_writes_json_and_css(self):
with tempfile.TemporaryDirectory() as tmp:
generate_design_system(
"fintech dashboard", "Ledgerly", persist=True, output_dir=tmp,
token_format="css",
)
folder = Path(tmp) / "design-system" / "ledgerly"
css_text = (folder / "tokens.css").read_text(encoding="utf-8")
self.assertIn("--color-primary:", css_text)
master = (folder / "MASTER.md").read_text(encoding="utf-8")
self.assertIn("tokens.css", master)
def test_page_overrides_do_not_write_page_tokens(self):
with tempfile.TemporaryDirectory() as tmp:
result = generate_design_system(
"fintech dashboard", "Ledgerly", persist=True, page="dashboard",
output_dir=tmp, token_format="dtcg",
)
folder = Path(tmp) / "design-system" / "ledgerly"
page = folder / "pages" / "dashboard.md"
self.assertTrue(page.exists())
self.assertTrue((folder / "tokens.json").exists())
self.assertFalse((folder / "pages" / "tokens.json").exists())
created = result["persistence"]["created_files"]
self.assertTrue(any(path.endswith("tokens.json") for path in created))
self.assertTrue(any(path.endswith("dashboard.md") for path in created))
def test_skip_if_exists_then_force(self):
with tempfile.TemporaryDirectory() as tmp:
first = generate_design_system(
"fintech dashboard", "Ledgerly", persist=True, output_dir=tmp,
token_format="dtcg",
)
tokens_json = Path(first["persistence"]["design_system_dir"]) / "tokens.json"
original = tokens_json.read_text(encoding="utf-8")
skipped = generate_design_system(
"beauty spa", "Ledgerly", persist=True, output_dir=tmp,
token_format="dtcg",
)
self.assertEqual(skipped["persistence"]["status"], "skipped_exists")
self.assertEqual(tokens_json.read_text(encoding="utf-8"), original)
forced = generate_design_system(
"beauty spa", "Ledgerly", persist=True, output_dir=tmp,
token_format="dtcg", force=True,
)
self.assertEqual(forced["persistence"]["status"], "success")
self.assertNotEqual(tokens_json.read_text(encoding="utf-8"), original)
class TokenCliTest(unittest.TestCase):
def run_search(self, *args):
return subprocess.run(
[sys.executable, str(SEARCH), *map(str, args)],
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
check=False,
)
def test_tokens_without_design_system_is_an_argparse_error(self):
proc = self.run_search("fintech dashboard", "--tokens", "dtcg")
self.assertNotEqual(proc.returncode, 0)
self.assertIn("--tokens", proc.stderr)
self.assertIn("--design-system", proc.stderr)
def test_cli_dtcg_stdout_is_json(self):
proc = self.run_search(
"fintech dashboard", "--design-system", "--tokens", "dtcg",
"-p", "Ledgerly",
)
self.assertEqual(proc.returncode, 0, proc.stderr)
payload = json.loads(proc.stdout)
self.assertEqual(payload["semantic"]["color"]["primary"]["$type"], "color")
def test_cli_css_stdout_has_root_variables(self):
proc = self.run_search(
"fintech dashboard", "--design-system", "--tokens", "css",
)
self.assertEqual(proc.returncode, 0, proc.stderr)
self.assertIn(":root {", proc.stdout)
self.assertIn("--color-primary:", proc.stdout)
def test_json_payload_includes_tokens(self):
proc = self.run_search(
"fintech dashboard", "--design-system", "--tokens", "dtcg", "--json",
)
self.assertEqual(proc.returncode, 0, proc.stderr)
payload = json.loads(proc.stdout)
self.assertIn("design_system", payload)
self.assertIn("tokens", payload)
self.assertIn("primary", payload["tokens"]["color"])
@unittest.skipUnless(_node_available(), "Node.js is required to round-trip tokens through generate-tokens.cjs")
class GenerateTokensRoundTripTest(unittest.TestCase):
def test_cjs_css_matches_tokens_css_output(self):
result = generate_design_system(
"fintech dashboard", "Ledgerly", token_format="css"
)
python_css = format_tokens_css(result["tokens"])
self.assertEqual(python_css, result["text"])
with tempfile.TemporaryDirectory() as tmp:
json_path = Path(tmp) / "tokens.json"
cjs_css_path = Path(tmp) / "from-cjs.css"
json_path.write_text(format_tokens_dtcg(result["tokens"]), encoding="utf-8")
proc = subprocess.run(
["node", str(GENERATE_TOKENS), "--config", str(json_path),
"-o", str(cjs_css_path)],
capture_output=True, text=True, encoding="utf-8", check=False,
)
self.assertEqual(proc.returncode, 0, proc.stderr)
cjs_css = cjs_css_path.read_text(encoding="utf-8")
self.assertEqual(cjs_css, python_css)
self.assertEqual(_parse_css_vars(cjs_css), _parse_css_vars(python_css))
if __name__ == "__main__":
unittest.main(verbosity=2)