Reading your theme

Summary#

Prints the whole token vocabulary you may write in this app: the groups your own theme declares, plus the ones you inherit from the UI kit, each group tagged with the kind of value it holds and the style props that draw from it. It needs no platform and no database: it parses, nothing else.

Signature#

osy theme [group…] [--mine] [--json]

Description#

A token is only useful at a slot that accepts it, and the question you actually have is never "what tokens exist" — it is "I have a color: to fill, what goes in it". So the listing is arranged the way that question is asked:

• Every group is printed with the KIND it holds — Colors is a Color, Length is a Length — and with the style props that draw from it. Both halves come from the compiler's own tables, so this cannot offer you a prop that would then refuse the token.
• Every token is printed with its value. A name alone does not answer "which one do I want": a font size is chosen by its size, a radius by how round it is.
• A mode map prints BOTH sides. "One value" and "differs by mode" are different facts about a design system, and a light value that looks right is exactly how a dark one that does not gets shipped.
• What you declared and what you inherited are told apart. Merging them answers "what may I write" correctly and "what did I write" not at all — and the second is what you need when deciding whether to shadow a token. --mine drops the inherited half entirely.

Naming one or more groups narrows the listing to those groups. A group the theme does not have is refused with the ones it does, and the command exits non-zero — a listing that answers nothing and exits 0 is indistinguishable from a theme with nothing in it.

How it differs from osy kit tokens#

osy kit tokens answers "what does the bundled kit ship" — a fact about the platform, the same for every app. osy theme answers "what may I write here", which is the kit's groups plus your own theme. When a token assertion or a style prop is handed a name the theme does not have, the refusal names this verb, because the app's own half is the half you cannot read anywhere else.

Examples#

osy theme                      # every group, yours and the kit's
osy theme Colors               # one group
osy theme Colors FontSize      # two
osy theme --mine               # only what this app declares
osy theme --json               # the same, for tooling

A group prints its kind and what draws from it, then its tokens:

theme Brand (7 token(s) in 3 group(s), declared here)
  Colors (Color) → AccentColor, Bg, Border, CaretColor, Color, Fill
    Ink = #111318
    Paper = #ffffff
    Accent = #00566f / #5fc8e8 (light/dark)
  Radius (Radius) → Rounded
    Sm = 6px
    Lg = 14px

The JSON keeps the two halves apart, and carries the same type and feeds per group:

{
  "declared": [ { "name": "Brand", "groups": [
    { "name": "Colors", "type": "Color", "feeds": ["AccentColor", "Bg", "Border"],
      "tokens": [ { "name": "Accent", "value": null, "light": "#00566f", "dark": "#5fc8e8" } ] } ] } ],
  "inherited": [ { "name": "Ui", "groups": [ ] } ]
}

See also#

theme tokens — how a theme is written, and what a mode map means.

Osysharp.Ui (the UI kit) — what the bundled kit ships, including the theme it gives you.

Theme assertions — does the app really look the way the theme says? — asserting a token's value from a test, and what the refusal tells you when the name is wrong.

Understanding your app — the app's resolved model, which reports its themes among everything else.