spec-to-ui 0.1.0 → 0.2.0

package/skills/ui-ux-pro-max/scripts/tests/test_data_contracts.py

@@ -0,0 +1,421 @@
+#!/usr/bin/env python3
+"""Cross-file semantic contracts for curated design data."""
+
+import copy
+import csv
+import json
+import re
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+SCRIPTS_DIR = Path(__file__).resolve().parent.parent
+DATA_DIR = SCRIPTS_DIR.parent / "data"
+sys.path.insert(0, str(SCRIPTS_DIR))
+
+from core import AVAILABLE_STACKS, STACK_CONFIG  # noqa: E402
+from design_system import DesignSystemGenerator  # noqa: E402
+from reasoning_contract import apply_decision_rules, parse_decision_rules  # noqa: E402
+import validate_data  # noqa: E402
+from validate_data import _check_reasoning_contract  # noqa: E402
+
+
+def read_rows(name):
+    with (DATA_DIR / name).open(encoding="utf-8", newline="") as handle:
+        return list(csv.DictReader(handle))
+
+
+def split_values(value, delimiter):
+    return [part.strip() for part in value.split(delimiter) if part.strip()]
+
+
+def style_identities(row):
+    return [
+        row["Style ID"], row["Style Category"],
+        *split_values(row["Aliases"], "|"),
+    ]
+
+
+class TestStyleIdentityContract(unittest.TestCase):
+    def setUp(self):
+        self.styles = read_rows("styles.csv")
+
+    def test_ids_aliases_status_and_parents_are_unambiguous(self):
+        ids = {row["Style ID"] for row in self.styles}
+        self.assertEqual(len(ids), len(self.styles))
+        aliases = {}
+        for row in self.styles:
+            style_id = row["Style ID"]
+            self.assertRegex(style_id, r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+            self.assertIn(row["Status"], {"active", "supplemental", "deprecated"})
+            parent = row["Parent Style ID"]
+            if parent:
+                self.assertIn(parent, ids)
+                self.assertNotEqual(parent, style_id)
+            if row["Status"] == "supplemental":
+                self.assertTrue(parent)
+            if row["Status"] == "deprecated":
+                has_redirect = bool(row["Replacement Domain"] and row["Replacement ID"])
+                self.assertNotEqual(bool(parent), has_redirect)
+            for alias in split_values(row["Aliases"], "|"):
+                self.assertNotIn(alias.casefold(), aliases)
+                aliases[alias.casefold()] = style_id
+
+    def test_every_product_and_reasoning_style_reference_resolves(self):
+        lookup = {}
+        for row in self.styles:
+            lookup.update(
+                (identity.casefold(), row["Style ID"])
+                for identity in style_identities(row)
+            )
+
+        references = []
+        for row in read_rows("products.csv"):
+            references.extend(split_values(row["Primary Style Recommendation"], "+"))
+            references.extend(split_values(row["Secondary Styles"], ","))
+        for row in read_rows("ui-reasoning.csv"):
+            references.extend(split_values(row["Style_Priority"], "+"))
+        unresolved = sorted({
+            reference for reference in references
+            if reference.casefold() not in lookup
+        })
+        self.assertEqual([], unresolved)
+
+
+class TestReasoningContract(unittest.TestCase):
+    def test_known_product_sets_match_exactly(self):
+        product_rows = read_rows("products.csv")
+        color_rows = read_rows("colors.csv")
+        reasoning_rows = read_rows("ui-reasoning.csv")
+        self.assertEqual([192, 192, 192], [
+            len(product_rows), len(color_rows), len(reasoning_rows)])
+        products = {row["Product Type"] for row in product_rows}
+        colors = {row["Product Type"] for row in color_rows}
+        reasoning = {row["UI_Category"] for row in reasoning_rows}
+        self.assertEqual(products, colors)
+        self.assertEqual(products, reasoning)
+        self.assertEqual(len(products), 192)
+
+    def test_decision_rules_use_closed_array_grammar(self):
+        for row in read_rows("ui-reasoning.csv"):
+            with self.subTest(category=row["UI_Category"]):
+                parsed = parse_decision_rules(row["Decision_Rules"])
+                self.assertTrue(all(isinstance(actions, list) for actions in parsed.values()))
+
+    def test_duplicate_unknown_keys_and_unknown_actions_fail_closed(self):
+        invalid = (
+            '{"must_have":["constraint:first"],"must_have":["constraint:second"]}',
+            '{"if_not_supported":["constraint:test"]}',
+            '{"must_have":["execute:arbitrary"]}',
+            '{"must_have":[["constraint:nested"]]}',
+            '{"must_have":[{"constraint":"nested"}]}',
+        )
+        for raw in invalid:
+            with self.subTest(raw=raw), self.assertRaises(ValueError):
+                parse_decision_rules(raw)
+
+    def test_must_have_and_explicit_signals_are_applied_and_reported(self):
+        rules = parse_decision_rules(
+            '{"must_have":["constraint:keyboard-navigation"],'
+            '"if_mobile":["constraint:optimize-touch-targets"]}')
+        desktop = apply_decision_rules(rules, "accessible government portal")
+        mobile = apply_decision_rules(rules, "accessible mobile government portal")
+        self.assertEqual(desktop["constraints"], ["keyboard-navigation"])
+        self.assertEqual(
+            mobile["constraints"], ["keyboard-navigation", "optimize-touch-targets"])
+        self.assertEqual(
+            [item["condition"] for item in mobile["activated"]],
+            ["must_have", "if_mobile"],
+        )
+
+    def test_generator_matches_reasoning_exactly_and_defaults_only_for_unknown(self):
+        generator = DesignSystemGenerator()
+        categories = [row["Product Type"] for row in read_rows("products.csv")]
+        for category in categories:
+            with self.subTest(category=category):
+                self.assertEqual(generator._find_reasoning_rule(category)["UI_Category"], category)
+        self.assertEqual(generator._find_reasoning_rule("Government"), {})
+        self.assertTrue(generator._apply_reasoning("External Unknown", "unknown")["is_default"])
+
+    def test_reasoning_patterns_reference_landing_identities(self):
+        patterns = set()
+        for row in read_rows("landing.csv"):
+            patterns.add(row["Pattern Name"])
+            patterns.update(alias for alias in row["Aliases"].split("|") if alias)
+        reasoning = read_rows("ui-reasoning.csv")
+        self.assertEqual(192, len(reasoning))
+        for row in reasoning:
+            with self.subTest(category=row["UI_Category"]):
+                self.assertIn(row["Recommended_Pattern"], patterns)
+
+    def test_every_known_product_generates_a_traceable_landing_pattern(self):
+        generator = DesignSystemGenerator()
+        patterns = {row["Pattern Name"] for row in read_rows("landing.csv")}
+        for category in (row["Product Type"] for row in read_rows("products.csv")):
+            with self.subTest(category=category):
+                result = generator.generate(category)
+                self.assertIn(result["source_identities"]["landing"], patterns)
+
+    def test_representative_new_products_generate_traceable_sources(self):
+        generator = DesignSystemGenerator()
+        styles = {row["Style ID"] for row in read_rows("styles.csv")}
+        colors = {row["Product Type"] for row in read_rows("colors.csv")}
+        typography = {row["Font Pairing Name"] for row in read_rows("typography.csv")}
+        patterns = {row["Pattern Name"] for row in read_rows("landing.csv")}
+        cases = {
+            "government grant portal accessible trustworthy": "Grant / Funding Portal",
+            "API developer portal documentation": "API Developer Portal",
+            "academic journal scholarly publishing accessible": "Academic Journal / Scholarly Publishing",
+            "patient portal mobile secure": "Patient Portal / Health Records",
+            "status page outage monitoring": "Status Page / Incident Management",
+        }
+        for query, category in cases.items():
+            with self.subTest(query=query):
+                result = generator.generate(query)
+                sources = result["source_identities"]
+                self.assertEqual(category, result["category"])
+                self.assertFalse(result["reasoning_default"])
+                self.assertEqual(category, sources["product"])
+                self.assertEqual(category, sources["reasoning"])
+                self.assertIn(sources["style"], styles)
+                self.assertIn(sources["color"], colors)
+                self.assertIn(sources["typography"], typography)
+                self.assertIn(sources["landing"], patterns)
+
+    def test_constraints_reach_domain_queries(self):
+        generator = DesignSystemGenerator()
+        calls = []
+
+        def capture(query, domain, max_results):
+            calls.append((domain, query))
+            return {"domain": domain, "count": 0, "results": []}
+
+        reasoning = {
+            "pattern": "Unmapped Pattern",
+            "color_mood": "Trustworthy",
+            "typography_mood": "Readable",
+            "constraints": ["keyboard-navigation", "touch-targets"],
+        }
+        with patch("design_system.search", side_effect=capture):
+            generator._multi_domain_search(
+                "public portal", "Government Portal", reasoning, ["Minimalism"])
+        queried = {domain: query for domain, query in calls}
+        for domain in ("style", "color", "typography", "landing"):
+            with self.subTest(domain=domain):
+                self.assertIn("keyboard navigation", queried[domain])
+
+    def test_canonical_style_priority_is_not_limited_to_bm25_top_three(self):
+        generator = DesignSystemGenerator()
+        unrelated = [
+            generator._resolve_style("Kinetic Brutalism (Mobile)"),
+            generator._resolve_style("Glassmorphism"),
+        ]
+        selected = generator._select_best_match(unrelated, ["Brutalism"])
+        self.assertEqual("brutalism", selected["Style ID"])
+
+    def test_duplicate_semantic_reasoning_labels_fail_validation(self):
+        product = {"Product Type": "Duplicate"}
+        color = {"Product Type": "Duplicate"}
+        reasoning = {
+            "UI_Category": "Duplicate", "Decision_Rules": "{}", "Confidence": ""
+        }
+        problems = []
+        _check_reasoning_contract(
+            [product, dict(product)], [color, dict(color)],
+            [reasoning, dict(reasoning)], set(), set(), problems,
+        )
+        self.assertTrue(any("duplicate" in problem.lower() for problem in problems))
+
+    def test_every_exact_product_label_resolves_to_itself(self):
+        generator = DesignSystemGenerator()
+        for row in read_rows("products.csv"):
+            category = row["Product Type"]
+            with self.subTest(category=category):
+                result = generator.generate(category)
+                reasoning = generator._apply_reasoning(category, category)
+                expected = [
+                    generator._resolve_style(priority).get("Style ID")
+                    for priority in reasoning["style_priority"]
+                ]
+                expected = [style_id for style_id in expected if style_id]
+                self.assertEqual(category, result["category"])
+                self.assertFalse(result["reasoning_default"])
+                self.assertTrue(expected)
+                self.assertEqual(expected[0], result["style"]["id"])
+
+    def test_style_aliases_have_one_exact_owner(self):
+        generator = DesignSystemGenerator()
+        self.assertEqual(
+            generator._resolve_style("Minimalism")["Style ID"],
+            "minimalism-and-swiss-style",
+        )
+        self.assertEqual(generator._resolve_style("Clean Science"), {})
+        self.assertEqual(
+            generator._resolve_style("Holographic/HUD")["Style ID"],
+            "hud-sci-fi-fui",
+        )
+
+
+class TestLandingAndStackContract(unittest.TestCase):
+    def test_landing_sections_use_one_delimiter(self):
+        for row in read_rows("landing.csv"):
+            with self.subTest(pattern=row["Pattern Name"]):
+                sections = row["Section Order"].split(" > ")
+                self.assertGreaterEqual(len(sections), 2)
+                self.assertTrue(all(section.strip() for section in sections))
+                self.assertFalse(any(re.match(r"^\d+\.\s", section) for section in sections))
+
+    def test_stack_schema_is_additive_and_uniform(self):
+        for stack in AVAILABLE_STACKS:
+            path = DATA_DIR / STACK_CONFIG[stack]["file"]
+            with path.open(encoding="utf-8", newline="") as handle:
+                reader = csv.DictReader(handle)
+                self.assertTrue({"Applies To", "Status", "Verified At"} <= set(reader.fieldnames or []))
+                for row in reader:
+                    self.assertIn(row["Status"], {"active", "supplemental", "deprecated", "unverified"})
+
+    def test_provenance_sidecar_has_stable_shape(self):
+        payload = json.loads((DATA_DIR / "data-provenance.json").read_text(encoding="utf-8"))
+        self.assertEqual(payload["schemaVersion"], 1)
+        self.assertIsInstance(payload["records"], list)
+        for record in payload["records"]:
+            self.assertTrue({"entityKind", "entityId", "sourceFile", "status", "verifiedAt", "sources"} <= set(record))
+            self.assertIsInstance(record["sources"], list)
+            source_types = {source.get("type") for source in record["sources"]}
+            if source_types <= {"derived"}:
+                self.assertEqual("needs-review", record["sla"])
+
+    def test_provenance_rejects_bad_shapes_enums_and_hosts_without_crashing(self):
+        canonical = json.loads(
+            (DATA_DIR / "data-provenance.json").read_text(encoding="utf-8")
+        )
+        cases = [[], None, "invalid"]
+        malformed_record = copy.deepcopy(canonical)
+        malformed_record["records"].append(None)
+        cases.append(malformed_record)
+        malformed_source = copy.deepcopy(canonical)
+        malformed_source["records"][0]["sources"] = [None]
+        cases.append(malformed_source)
+        unapproved_source = copy.deepcopy(canonical)
+        official = next(
+            record for record in unapproved_source["records"]
+            if any(source.get("type") == "official" for source in record["sources"])
+        )
+        official["sources"] = [
+            {"type": "official", "ref": "https://evil.example/fake"}
+        ]
+        cases.append(unapproved_source)
+        invalid_enums = copy.deepcopy(canonical)
+        invalid_enums["records"][0].update(
+            status="invented", sla="whenever", confidence=float("nan")
+        )
+        cases.append(invalid_enums)
+
+        reasoning, styles = read_rows("ui-reasoning.csv"), read_rows("styles.csv")
+        for index, payload in enumerate(cases):
+            with self.subTest(case=index), tempfile.TemporaryDirectory() as directory:
+                root = Path(directory)
+                (root / "data-provenance.json").write_text(
+                    json.dumps(payload), encoding="utf-8"
+                )
+                problems = []
+                with patch.object(validate_data, "DATA_DIR", root):
+                    validate_data._check_provenance(reasoning, styles, problems)
+                self.assertTrue(problems)
+
+    def test_dataset_provenance_scope_binds_real_rows_and_fields(self):
+        problems = []
+        valid = validate_data._valid_dataset_source_key(
+            "colors.csv", {"Scope": "No 1-192; Notes field"},
+            ("dataset-contract", "valid"), problems,
+        )
+        self.assertTrue(valid)
+        self.assertEqual([], problems)
+        stack_problems = []
+        self.assertTrue(validate_data._valid_dataset_source_key(
+            "stacks/html-tailwind.csv", {"Scope": "No 57-59; Guideline field"},
+            ("dataset-contract", "valid-stack"), stack_problems,
+        ))
+        self.assertEqual([], stack_problems)
+        for source_file, source_key in (
+            ("unknown.csv", {"Scope": "No 1; Notes field"}),
+            ("colors.csv", {"Scope": "No 999; Notes field"}),
+            ("colors.csv", {"Scope": "No 1; Invented Field"}),
+        ):
+            with self.subTest(source_file=source_file, source_key=source_key):
+                problems = []
+                self.assertFalse(validate_data._valid_dataset_source_key(
+                    source_file, source_key, ("dataset-contract", "bad"), problems
+                ))
+                self.assertTrue(problems)
+
+
+class TestGeneratedCatalogContract(unittest.TestCase):
+    def load_json(self, name):
+        return json.loads((DATA_DIR / name).read_text(encoding="utf-8"))
+
+    def test_canonical_catalogs_and_provenance_are_release_ready(self):
+        problems = validate_data.validate()
+        self.assertEqual([], [problem for problem in problems if "catalog" in problem])
+
+    def test_font_license_and_typography_drift_fail_closed(self):
+        fonts = read_rows("google-fonts.csv")
+        licenses = self.load_json("google-font-licenses.json")
+        licenses["families"][0]["license"] = "UNKNOWN"
+        problems = []
+        validate_data._check_font_catalog(
+            fonts, licenses, read_rows("typography.csv"), problems
+        )
+        self.assertTrue(any("invalid active family" in problem for problem in problems))
+
+        missing_font = copy.deepcopy(read_rows("typography.csv"))
+        missing_font[0]["Google Fonts URL"] = (
+            "https://fonts.googleapis.com/css2?family=Invented+Sans:wght@400"
+        )
+        problems = []
+        validate_data._check_font_catalog(
+            fonts, self.load_json("google-font-licenses.json"), missing_font, problems
+        )
+        self.assertTrue(any("absent from approved catalog" in problem for problem in problems))
+
+    def test_font_source_revision_and_exclusion_policy_fail_closed(self):
+        fonts = read_rows("google-fonts.csv")
+        typography = read_rows("typography.csv")
+        licenses = self.load_json("google-font-licenses.json")
+        licenses["excludedFamilies"][0]["source"] = "https://github.com/google/fonts"
+        problems = []
+        validate_data._check_font_catalog(fonts, licenses, typography, problems)
+        self.assertFalse(any("invalid exclusion" in problem for problem in problems))
+
+        licenses["excludedFamilies"][0]["source"] = "https://github.com/other/fonts"
+        licenses["source"]["revision"] = "main"
+        problems = []
+        validate_data._check_font_catalog(fonts, licenses, typography, problems)
+        self.assertTrue(any("invalid exclusion" in problem for problem in problems))
+        self.assertTrue(any("invalid source revision" in problem for problem in problems))
+
+    def test_curated_icon_and_summary_drift_fail_closed(self):
+        manifest = self.load_json("phosphor-icons-upstream.json")
+        manifest["icons"][0]["clientImport"] = (
+            'import { Wrong } from "@phosphor-icons/react"'
+        )
+        problems = []
+        validate_data._check_phosphor_catalog(read_rows("icons.csv"), manifest, problems)
+        self.assertTrue(any("invalid identity or imports" in problem for problem in problems))
+
+        summary = self.load_json("catalog-summary.json")
+        summary["counts"]["googleFonts"] -= 1
+        problems = []
+        validate_data._check_catalog_summary(
+            summary,
+            self.load_json("google-font-licenses.json"),
+            self.load_json("phosphor-icons-upstream.json"),
+            problems,
+        )
+        self.assertTrue(any("stale count for googleFonts" in problem for problem in problems))
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/skills/ui-ux-pro-max/scripts/tests/test_design_system_mode.py

@@ -0,0 +1,233 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Regression tests for color-mode coherence in design_system.py (issue #428).
+
+Style, palette and anti-patterns used to be resolved independently, so a
+dark-primary style could be returned alongside a light palette and a
+"Dark mode by default" anti-pattern.
+
+Stdlib-only (unittest, not pytest) to match test_core.py -- this project ships
+with zero external dependencies.
+
+Run with:
+    python -m unittest discover -s scripts/tests -v
+or directly:
+    python scripts/tests/test_design_system_mode.py
+"""
+
+import re
+import sys
+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
+    _filter_anti_patterns_for_mode,
+    _contrast_ratio,
+    _mode_support_labels,
+    _palette_is_dark,
+    _query_wants_dark,
+    _relative_luminance,
+    _resolve_color_mode,
+    _select_palette_for_mode,
+    _style_is_dark_primary,
+    BOX_WIDTH,
+    DesignSystemGenerator,
+    format_ascii_box,
+    format_markdown,
+    format_master_md,
+)  # noqa: I001 - private helpers first, public class last
+
+LIGHT_PALETTE = {"Product Type": "SaaS", "Background": "#F8FAFC", "Foreground": "#020617"}
+DARK_PALETTE = {"Product Type": "Fintech/Crypto", "Background": "#0F172A", "Foreground": "#F8FAFC"}
+
+# Verbatim from styles.csv row "Modern Dark (Cinema Mobile)".
+DARK_PRIMARY_STYLE = {
+    "Style Category": "Modern Dark (Cinema Mobile)",
+    "Light Mode ✓": "✓ Light mode only as exception",
+    "Dark Mode ✓": "✓ Dark Mode Primary",
+}
+DUAL_MODE_STYLE = {
+    "Style Category": "Minimalism",
+    "Light Mode ✓": "✓ Full",
+    "Dark Mode ✓": "✓ Full",
+}
+
+
+class TestLuminance(unittest.TestCase):
+    def test_parses_six_and_three_digit_hex(self):
+        self.assertAlmostEqual(_relative_luminance("#FFFFFF"), 1.0, places=6)
+        self.assertAlmostEqual(_relative_luminance("#000000"), 0.0, places=6)
+        self.assertAlmostEqual(_relative_luminance("#FFF"), 1.0, places=6)
+
+    def test_returns_none_for_unparseable(self):
+        for value in ("", "nope", "#12", "#GGGGGG", None):
+            self.assertIsNone(_relative_luminance(value))
+
+    def test_classifies_backgrounds_from_the_shipped_data(self):
+        # Lightest dark background and darkest light background in colors.csv.
+        self.assertTrue(_palette_is_dark({"Background": "#1F2937"}))
+        self.assertFalse(_palette_is_dark({"Background": "#E8ECF1"}))
+
+    def test_missing_background_is_not_dark(self):
+        self.assertFalse(_palette_is_dark({}))
+        self.assertFalse(_palette_is_dark(None))
+
+
+class TestModeResolution(unittest.TestCase):
+    def test_dark_primary_style_detected(self):
+        self.assertTrue(_style_is_dark_primary(DARK_PRIMARY_STYLE))
+
+    def test_dual_mode_style_is_not_dark_primary(self):
+        self.assertFalse(_style_is_dark_primary(DUAL_MODE_STYLE))
+        self.assertFalse(_style_is_dark_primary({}))
+
+    def test_query_keywords(self):
+        self.assertTrue(_query_wants_dark("fintech B2B professional dark mode"))
+        self.assertTrue(_query_wants_dark("gaming app OLED"))
+        self.assertFalse(_query_wants_dark("healthcare clinic booking app"))
+        self.assertFalse(_query_wants_dark(""))
+
+    def test_either_signal_resolves_dark(self):
+        self.assertEqual(_resolve_color_mode("saas dark mode", DUAL_MODE_STYLE), "dark")
+        self.assertEqual(_resolve_color_mode("saas", DARK_PRIMARY_STYLE), "dark")
+        self.assertEqual(_resolve_color_mode("saas", DUAL_MODE_STYLE), "light")
+
+
+class TestPaletteSelection(unittest.TestCase):
+    def test_dark_mode_skips_light_palettes(self):
+        chosen = _select_palette_for_mode([LIGHT_PALETTE, DARK_PALETTE], "dark")
+        self.assertEqual(chosen["Background"], "#0F172A")
+
+    def test_dark_mode_falls_back_to_top_hit_when_no_dark_ramp_exists(self):
+        chosen = _select_palette_for_mode([LIGHT_PALETTE], "dark")
+        self.assertEqual(chosen["Background"], "#F8FAFC")
+
+    def test_light_mode_keeps_the_existing_top_hit_behaviour(self):
+        chosen = _select_palette_for_mode([DARK_PALETTE, LIGHT_PALETTE], "light")
+        self.assertEqual(chosen["Background"], "#0F172A")
+
+    def test_empty_results(self):
+        self.assertEqual(_select_palette_for_mode([], "dark"), {})
+
+    def test_category_identity_wins_over_unrelated_dark_palette(self):
+        chosen = _select_palette_for_mode(
+            [LIGHT_PALETTE, DARK_PALETTE], "dark", "SaaS")
+        self.assertEqual("SaaS", chosen["Product Type"])
+        self.assertEqual("derived-dark", chosen["_mode_derivation"])
+        self.assertTrue(_palette_is_dark(chosen))
+        self.assertGreaterEqual(
+            _contrast_ratio(chosen["Ring"], chosen["Background"]), 3.0)
+
+
+class TestAntiPatternGating(unittest.TestCase):
+    def test_dark_clause_dropped_others_kept(self):
+        result = _filter_anti_patterns_for_mode(
+            "Excessive animation + Dark mode by default", "dark")
+        self.assertEqual(result, "Excessive animation")
+
+    def test_light_mode_is_a_no_op(self):
+        original = "Excessive animation + Dark mode by default"
+        self.assertEqual(_filter_anti_patterns_for_mode(original, "light"), original)
+
+    def test_unrelated_anti_patterns_survive_dark_mode(self):
+        original = "Complex jargon + Tiny tap targets"
+        self.assertEqual(_filter_anti_patterns_for_mode(original, "dark"), original)
+
+    def test_empty_input(self):
+        self.assertEqual(_filter_anti_patterns_for_mode("", "dark"), "")
+
+
+class TestEndToEndCoherence(unittest.TestCase):
+    """The exact reproduction from issue #428."""
+
+    QUERY = "SaaS invoicing fintech B2B professional dark mode"
+
+    def test_dark_query_gets_a_dark_background(self):
+        ds = DesignSystemGenerator().generate(self.QUERY)
+        background = ds["colors"]["background"]
+        self.assertTrue(
+            _palette_is_dark({"Background": background}),
+            "dark-mode query returned a light background: {}".format(background),
+        )
+
+    def test_generator_exports_every_semantic_foreground_pair(self):
+        colors = DesignSystemGenerator().generate("SaaS dashboard")["colors"]
+        pairs = (
+            ("on_primary", "primary"),
+            ("on_secondary", "secondary"),
+            ("on_accent", "accent"),
+            ("foreground", "background"),
+            ("card_foreground", "card"),
+            ("muted_foreground", "muted"),
+            ("on_destructive", "destructive"),
+        )
+        for foreground, background in pairs:
+            with self.subTest(pair=foreground):
+                self.assertTrue(colors[foreground])
+                self.assertTrue(colors[background])
+                self.assertGreaterEqual(
+                    _contrast_ratio(colors[foreground], colors[background]), 4.5
+                )
+        self.assertEqual(colors["on_cta"], colors["on_accent"])
+
+    def test_dark_query_foreground_is_lighter_than_background(self):
+        ds = DesignSystemGenerator().generate(self.QUERY)
+        background = _relative_luminance(ds["colors"]["background"])
+        foreground = _relative_luminance(ds["colors"]["foreground"])
+        self.assertIsNotNone(background)
+        self.assertIsNotNone(foreground)
+        self.assertGreater(foreground, background)
+
+    def test_dark_query_does_not_advise_against_dark_mode(self):
+        ds = DesignSystemGenerator().generate(self.QUERY)
+        self.assertNotIn("dark mode", ds["anti_patterns"].lower())
+
+    def test_light_query_keeps_a_light_background(self):
+        ds = DesignSystemGenerator().generate("healthcare clinic booking app")
+        self.assertFalse(_palette_is_dark({"Background": ds["colors"]["background"]}))
+
+
+class TestLightResultOutputCoherence(unittest.TestCase):
+    """A light result that avoids dark mode must not also call dark "supported"."""
+
+    QUERY = "beauty spa wellness"
+
+    @classmethod
+    def setUpClass(cls):
+        cls.ds = DesignSystemGenerator().generate(cls.QUERY, "Serenity Spa")
+
+    def test_dark_support_is_qualified_when_the_product_avoids_dark_mode(self):
+        self.assertIn("dark mode", self.ds["anti_patterns"].lower())
+        light, dark = _mode_support_labels(self.ds["style"], self.ds["anti_patterns"])
+        self.assertIn("avoid for this product", dark)
+        self.assertIn("avoid for this product", format_ascii_box(self.ds))
+        self.assertIn("avoid for this product", format_markdown(self.ds))
+
+    def test_labels_unchanged_when_dark_mode_is_not_avoided(self):
+        style = {"light_mode": "supported", "dark_mode": "supported"}
+        self.assertEqual(_mode_support_labels(style, "Harsh animations"),
+                         ("supported", "supported"))
+
+    def test_ascii_box_lines_never_overflow_the_border(self):
+        for query in (self.QUERY, "SaaS invoicing fintech B2B professional dark mode"):
+            with self.subTest(query=query):
+                ds = DesignSystemGenerator().generate(query, motion=7)
+                widths = {len(re.sub(r"\033\[[0-9;]*m", "", line))
+                          for line in format_ascii_box(ds).splitlines()}
+                self.assertEqual(widths, {BOX_WIDTH + 1})
+
+    def test_master_button_text_meets_contrast_on_its_background(self):
+        colors = self.ds["colors"]
+        master = format_master_md(self.ds)
+        primary = re.search(r"\.btn-primary \{\n  background: (#\w+);\n  color: (#\w+);", master)
+        secondary = re.search(r"\.btn-secondary \{\n  background: transparent;\n  color: (#\w+);", master)
+        self.assertGreaterEqual(_contrast_ratio(primary.group(2), primary.group(1)), 4.5)
+        self.assertGreaterEqual(_contrast_ratio(secondary.group(1), colors["background"]), 4.5)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)