Skip to content

docs(kit): describe what a token does, not which look uses it - #58

Merged
Bccorb merged 1 commit into
mainfrom
docs/tokens-describe-themselves
Aug 23, 2026
Merged

docs(kit): describe what a token does, not which look uses it#58
Bccorb merged 1 commit into
mainfrom
docs/tokens-describe-themselves

Conversation

@Bccorb

@Bccorb Bccorb commented Aug 23, 2026

Copy link
Copy Markdown
Contributor

Summary

Four comments in index.css explained a token by naming the looks that set it:

  • display-stretch was "the whole distance between Blueprint's condensed
    capitals and Cinematic's expanded ones"
  • data-cell was "a kit decision: Console is tight, Cinematic is loose"
  • rule was "hairline in most kits, heavy in Editorial, double in Almanac"
  • auto-grid was "two columns in Cinematic and four in Blueprint"

None of those names exist in this repository. They belong to one consumer's set of
themes, so the stylesheet was documenting somebody else's product rather than the
lever it actually ships, and a project scaffolded from here reads these comments
with no idea what any of it refers to.

Follows #57, which removed the last literal reference
of that kind from the README. This is the same problem in a milder form.

What changed

Comments only. No token, value, selector or class is touched, so the built CSS is
byte for byte what it was. Each comment now says what a theme can do with the
token: one download covering condensed through expanded, a readout wanting tight
rows against a showy theme wanting loose ones, a hairline a theme may make heavy
or double into a masthead rule, an airy theme landing on two columns where a dense
one lands on four.

Release impact

No changeset. Comments do not reach a scaffolded project's behaviour.

Checks

npm run validate and npm run format:check both pass. The two template copies
are synced from shared/react-app as usual, which is why three files change for
one edit.

Four comments in index.css explained a token by naming the looks that set it, so
the stylesheet documented one consumer's set of themes rather than the lever
itself. A project scaffolded from here has none of those names, and the comments
read as notes about somebody else's product.

Same tokens, described by what a theme can do with them.

(cherry picked from commit 7d1a103)
@Bccorb
Bccorb merged commit 81cec01 into main Aug 23, 2026
3 checks passed
@Bccorb
Bccorb deleted the docs/tokens-describe-themselves branch August 23, 2026 22:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant