# Reading your theme

> Prints everything your app's theme advertises — every group, every token, each token's value or its light/dark pair, and the style props each group feeds — separating what this app declares from what it inherits from the kit.

<!-- id: local-reading-your-theme · area: local · stability: stable · html: https://osysharp.com/reference/local/reading-your-theme/ -->

## Summary        {#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      {#signature}

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

## Description    {#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`  {#kit}

`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       {#examples}

```console
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:

```console
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:

```json
{
  "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       {#see-also}

[theme tokens](https://osysharp.com/reference/ui/theming/) — how a theme is written, and what a mode map means.

[Osysharp.Ui (the UI kit)](https://osysharp.com/reference/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?](https://osysharp.com/reference/testing/theme/) — asserting a token's value from a test, and what the refusal tells you when the name is wrong.

[Understanding your app](https://osysharp.com/reference/local/understanding-your-app/) — the app's resolved model, which reports its themes among everything else.