feat(design-systems): central prose — guidance on the system, rationale on tokens
CI & Build / Python lint (push) Successful in 3s
CI & Build / Plugin hooks (push) Successful in 9s
CI & Build / integration (push) Successful in 19s
CI & Build / TypeScript typecheck (push) Failing after 20s
CI & Build / Python tests (push) Successful in 44s
CI & Build / Build & push image (push) Skipped

Last piece of the architecture in #2296. The operator: "the prose doesn't have
to live as one offs, there's a central system for managing it."

Two fields, both free-form:

  design_systems.guidance   the narrative a token table cannot hold — aesthetic,
                            voice and tone, what is deliberately out of scope.
  design_tokens.rationale   WHY a token is this value, which is a different
                            question from `purpose` (what it is FOR). "Success
                            equals Moss, aligned by design" is a rationale;
                            "page bg, deepest surface" is a purpose. Rules carry
                            the first routinely and a token row had nowhere to
                            put it.

Free-form rather than a column per category, deliberately. A schema with
`voice`, `aesthetic` and `scope` columns would bake one rulebook's table of
contents into every install (rule #115), leaving the next install three empty
columns and nowhere for what it actually cares about. Both nullable: a design
system with no prose at all is complete, not a draft.

`rationale` cascades like `purpose` — deepest non-empty wins — so an app
overriding a colour keeps the family's reasoning rather than blanking it. Same
argument as `supersedes`: the override was about the value, not the meaning.

In the generated sheet the inline comment prefers `purpose` and falls back to
`rationale`, so a token carrying only the why still says something instead of
rendering bare.
This commit is contained in:
2026-07-30 21:52:16 -04:00
parent 46d88f9e7e
commit 0f80b790c7
12 changed files with 203 additions and 11 deletions
+5 -2
View File
@@ -97,6 +97,7 @@ class ResolvedToken:
contributions: dict[str, tuple[Contribution, ...]]
group_name: str | None
purpose: str | None
rationale: str | None
supersedes: tuple[str, ...]
order_index: int
@@ -133,6 +134,7 @@ class ResolvedToken:
"name": self.name,
"group_name": self.group_name,
"purpose": self.purpose,
"rationale": self.rationale,
"supersedes": list(self.supersedes),
"order_index": self.order_index,
"value_by_mode": self.value_by_mode,
@@ -210,11 +212,11 @@ def resolve_tokens(
meta = metadata.setdefault(
token.name,
{
"group_name": None, "purpose": None,
"group_name": None, "purpose": None, "rationale": None,
"supersedes": None, "order_index": None,
},
)
for field in ("group_name", "purpose"):
for field in ("group_name", "purpose", "rationale"):
if meta[field] is None:
meta[field] = getattr(token, field, None)
# order_index alone treats 0 as UNSTATED rather than "first",
@@ -240,6 +242,7 @@ def resolve_tokens(
},
group_name=metadata[name]["group_name"],
purpose=metadata[name]["purpose"],
rationale=metadata[name]["rationale"],
supersedes=metadata[name]["supersedes"] or (),
order_index=metadata[name]["order_index"] or 0,
)