feat(design-systems): declare what to write instead, rather than what not to

Milestone #254 step 6, first half (#2295) — and this reframes the task rather
than answering it. The operator's call:

  "in this case we should declare what should be used in place of pure white,
   it's not a prohibition it's what should be used in its place."

None of the three options on the table (a constraints record / the panel reads
both sources / negative token rows) was right, because all three kept the
prohibition as a KIND OF THING. It isn't one. "Pure white is never text" is the
shadow cast by a positive fact — text is Parchment — and a design system that
stores what things ARE has no row for a ban because it never needed one.

So `design_tokens` gains `supersedes`: the literal values this token should be
written instead of. `--color-text-on-action` supersedes `#fff` / `#ffffff`. Same
fact as the rule, stated forwards, and now actionable — a finding can say what
to write rather than only objecting.

It has to be DECLARED, not derived, and that is the crux: `#fff` and Parchment
`#E8E4D8` are different colours, so no value-matching check could ever have
connected them. That mismatch is precisely why the prohibition looked
unrepresentable until it was turned around.

`supersedes` cascades on EMPTINESS rather than on None. A child overriding a
colour says nothing about which literals it replaces, and blanking the family's
declaration there would silently disarm the check for every app that customises
the token — while a child that states its own list replaces it wholesale.

Two things this deliberately does NOT do:

  - It does not feed the drift panel. Superseded literals live in component CSS,
    which `designDrift.ts` cannot see and already documents as a blind spot.
    This is input for the source lint (#2277). Declaring it with nothing
    consuming it yet is honest; wiring it to a panel that cannot check it would
    not be.
  - It does not remove the panel's `prohibited_color` arm yet — that happens
    when the panel is repointed at a resolved system, which needs #2288 first.

The declaration also exposes a missing token: most of the 67 hardcoded
`color: #fff` (#2275) are text on a coloured action button, and the system has
no token for that role at all. Every view hardcodes it. Declaring the token that
was never there is the first real output of the operator's framing.

tests/test_design_cascade.py

@@ -102,10 +102,11 @@ def test_the_guard_survives_a_hierarchy_that_is_already_corrupt():
 # because resolve_tokens is pure and duck-typed — which is the whole reason it
 # lives here rather than inside the service.
 
-def _token(name, value_by_mode, group_name=None, purpose=None, order_index=0):
+def _token(name, value_by_mode, group_name=None, purpose=None, order_index=0,
+           supersedes=None):
     return SimpleNamespace(
         name=name, value_by_mode=value_by_mode, group_name=group_name,
-        purpose=purpose, order_index=order_index,
+        purpose=purpose, order_index=order_index, supersedes=supersedes or [],
     )
 
 
@@ -310,3 +311,79 @@ def test_resolution_terminates_on_a_corrupt_hierarchy():
     assert set(resolved) == {"--fs-a", "--fs-b"}
     # Each system contributes exactly once, not endlessly.
     assert len(resolved["--fs-a"].contributions["base"]) == 1
+
+
+# --- supersedes -------------------------------------------------------------
+#
+# The declaration that replaces a prohibition. A design system stores what things
+# ARE, so "pure white is never text" has no row — but "write this token instead
+# of #fff" does, and it is the same fact stated forwards.
+
+def test_supersedes_is_inherited_when_the_override_is_silent_about_it():
+    """LOAD-BEARING. A child overriding a colour says nothing about which
+    literals it replaces, and blanking the family's declaration there would
+    silently disarm the check for every app that customises the token."""
+    resolved = _by_name(resolve_tokens(
+        APP, PARENTS,
+        {
+            FAMILY: [_token("--fs-text", {"base": "#e8e4d8"}, supersedes=["#fff", "#ffffff"])],
+            APP: [_token("--fs-text", {"base": "#f0ece0"})],
+        },
+    ))
+    text = resolved["--fs-text"]
+    assert text.supersedes == ("#fff", "#ffffff")
+    assert text.value_by_mode == {"base": "#f0ece0"}   # the value still overrode
+
+
+def test_an_override_that_states_its_own_supersedes_replaces_the_list():
+    """Whole-list replacement, not a merge — an app that means "only #fff" must
+    be able to say so without inheriting entries it deliberately dropped."""
+    resolved = _by_name(resolve_tokens(
+        APP, PARENTS,
+        {
+            FAMILY: [_token("--fs-text", {"base": "a"}, supersedes=["#fff", "#ffffff"])],
+            APP: [_token("--fs-text", {"base": "b"}, supersedes=["#fff"])],
+        },
+    ))
+    assert resolved["--fs-text"].supersedes == ("#fff",)
+
+
+def test_a_token_that_supersedes_nothing_resolves_to_an_empty_tuple():
+    """Most tokens replace nothing. That has to be an empty sequence rather than
+    None, so no caller has to test for two kinds of nothing."""
+    resolved = _by_name(resolve_tokens(
+        FAMILY, PARENTS, {FAMILY: [_token("--fs-radius-md", {"base": "8px"})]},
+    ))
+    assert resolved["--fs-radius-md"].supersedes == ()
+
+
+def test_supersedes_survives_serialisation_as_a_list():
+    resolved = _by_name(resolve_tokens(
+        FAMILY, PARENTS,
+        {FAMILY: [_token("--fs-text", {"base": "#e8e4d8"}, supersedes=["#fff"])]},
+    ))
+    assert resolved["--fs-text"].to_dict()["supersedes"] == ["#fff"]
+
+
+def test_the_superseded_literal_need_not_match_the_tokens_own_value():
+    """The whole reason this is DECLARED rather than derived. `#fff` and
+    Parchment are different colours, so a value-matching rule could never have
+    connected them — which is why the prohibition looked unrepresentable until
+    it was turned around."""
+    resolved = _by_name(resolve_tokens(
+        FAMILY, PARENTS,
+        {FAMILY: [_token("--fs-text", {"base": "#e8e4d8"}, supersedes=["#fff"])]},
+    ))
+    text = resolved["--fs-text"]
+    assert text.value_by_mode["base"] not in text.supersedes
+
+
+def test_rows_without_a_supersedes_attribute_at_all_still_resolve():
+    """Duck-typed input: a caller passing rows from before the column existed
+    must not crash the cascade."""
+    legacy = SimpleNamespace(
+        name="--fs-x", value_by_mode={"base": "a"},
+        group_name=None, purpose=None, order_index=0,
+    )
+    resolved = _by_name(resolve_tokens(FAMILY, PARENTS, {FAMILY: [legacy]}))
+    assert resolved["--fs-x"].supersedes == ()

tests/test_mcp_tool_design_systems.py

@@ -189,3 +189,24 @@ async def test_resolve_returns_serialised_tokens_with_their_provenance():
         {"system_id": 2, "value": "#5b4a8a"},
         {"system_id": 1, "value": "#6b2118"},
     ]
+
+
+@pytest.mark.asyncio
+async def test_update_token_can_clear_supersedes_with_an_empty_list():
+    """`[]` means "this token replaces nothing after all" — a real edit. Guarded
+    on `is not None` so it isn't swallowed as "unchanged", the same trap #2077
+    recorded for update_snippet."""
+    with patch("scribe.mcp.tools.design_systems.ds_svc") as svc:
+        svc.update_token = AsyncMock(return_value=_fake_token())
+        from scribe.mcp.tools.design_systems import update_design_token
+        await update_design_token(token_id=9, supersedes=[])
+    assert svc.update_token.await_args.kwargs["supersedes"] == []
+
+
+@pytest.mark.asyncio
+async def test_update_token_leaves_supersedes_alone_when_omitted():
+    with patch("scribe.mcp.tools.design_systems.ds_svc") as svc:
+        svc.update_token = AsyncMock(return_value=_fake_token())
+        from scribe.mcp.tools.design_systems import update_design_token
+        await update_design_token(token_id=9, purpose="text on action surfaces")
+    assert "supersedes" not in svc.update_token.await_args.kwargs

tests/test_services_design_systems.py

@@ -236,3 +236,41 @@ async def test_resolve_scopes_the_hierarchy_to_the_systems_OWNER_not_the_caller(
 
     assert result == []                                   # empty chain, not None
     assert parent_map.await_args.args[1] == owner         # NOT `caller`
+
+
+# --- supersedes (step 6's reframe) ------------------------------------------
+
+@pytest.mark.asyncio
+async def test_create_token_supersedes_defaults_to_an_empty_list_not_json_null():
+    """Same NOT NULL reasoning as value_by_mode: absence gets one spelling."""
+    mock_session = _make_mock_session()
+    captured = {}
+    mock_session.add = MagicMock(
+        side_effect=lambda obj: captured.update(supersedes=obj.supersedes)
+    )
+    with patch("scribe.services.design_systems.async_session") as mock_cls, \
+         patch("scribe.services.design_systems.access") as acc:
+        acc.can_write_design_system = AsyncMock(return_value=True)
+        mock_cls.return_value = mock_session
+        from scribe.services.design_systems import create_token
+        await create_token(user_id=1, design_system_id=3, name="--fs-x", supersedes=None)
+    assert captured["supersedes"] == []
+
+
+@pytest.mark.asyncio
+async def test_create_token_records_the_literals_it_replaces():
+    mock_session = _make_mock_session()
+    captured = {}
+    mock_session.add = MagicMock(
+        side_effect=lambda obj: captured.update(supersedes=obj.supersedes)
+    )
+    with patch("scribe.services.design_systems.async_session") as mock_cls, \
+         patch("scribe.services.design_systems.access") as acc:
+        acc.can_write_design_system = AsyncMock(return_value=True)
+        mock_cls.return_value = mock_session
+        from scribe.services.design_systems import create_token
+        await create_token(
+            user_id=1, design_system_id=3, name="--fs-text-on-action",
+            value_by_mode={"base": "#e8e4d8"}, supersedes=["#fff", "#ffffff"],
+        )
+    assert captured["supersedes"] == ["#fff", "#ffffff"]