ceos/opencode
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(tui): add generated V2 theme reference (#38396)

Browse source
This commit is contained in:
James Long 2026-07-22 18:30:31 -04:00 • committed by GitHub
commit 381f6c47b4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
11 changed files with 381 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

5
.github/workflows/test.yml vendored
View file

@ -97,6 +97,11 @@ jobs:
working-directory: packages/client
run: bun run check:generated
- name: Check generated documentation
if: runner.os == 'Linux'
working-directory: packages/docs
run: bun run check:generated
e2e:
name: e2e (${{ matrix.settings.name }})
if: github.ref_name != 'v2' && github.head_ref != 'v2'

11
packages/docs/README.md
View file

@ -19,4 +19,15 @@ bun validate
bun broken-links
```
The V2 theme token reference is generated from
`packages/tui/src/theme/v2/schema.ts`. Regenerate it after schema changes:
```bash
bun run generate
```
`bun validate` checks that the committed snippet is current. The repository's
generation workflow also refreshes it on pushes to `dev`, so Mintlify always
receives the generated MDX as part of the published docs tree.
The hosted preview is available at [opencode.mintlify.site](https://opencode.mintlify.site).

1
packages/docs/docs.json
View file

@ -38,6 +38,7 @@
"attachments",
"compaction",
"warming",
"themes",
"formatters",
"lsp",
"references"

2
packages/docs/index.mdx
View file

@ -158,6 +158,6 @@ limitations and safety details.
## Customize
Make OpenCode your own by [picking a theme](https://opencode.ai/docs/themes), [customizing
Make OpenCode your own by [picking a theme](/themes), [customizing
keybinds](https://opencode.ai/docs/keybinds), [configuring formatters](/formatters), [creating commands](/commands), or
editing the [OpenCode config](/config).

10
packages/docs/package.json
View file

@ -3,11 +3,15 @@
"name": "@opencode-ai/docs",
"private": true,
"scripts": {
"dev": "bun --bun mint dev --no-open --port 3333",
"validate": "bun --bun mint validate",
"dev": "bun run generate && bun --bun mint dev --no-open --port 3333",
"generate": "bun script/generate-theme-tokens.ts",
"check:generated": "bun script/generate-theme-tokens.ts --check",
"validate": "bun run check:generated && bun --bun mint validate",
"broken-links": "bun --bun mint broken-links"
},
"devDependencies": {
"mint": "4.2.666"
"effect": "catalog:",
"mint": "4.2.666",
"prettier": "3.6.2"
}
}

136
packages/docs/script/generate-theme-tokens.ts Normal file
View file

@ -0,0 +1,136 @@
#!/usr/bin/env bun
import { Schema, SchemaAST } from "effect"
import { format } from "prettier"
import { ThemeDefinition, ThemeFile } from "../../tui/src/theme/v2/schema"
const target = import.meta.dir + "/../snippets/generated/theme-tokens.mdx"
const root = requireObject(ThemeDefinition.ast)
const hue = requireObject(requireField(root, "hue").type)
const hueNames = hue.propertySignatures.map((field) => String(field.name))
const hueSteps = requireObject(requireField(hue, hueNames[0]).type).propertySignatures.map((field) =>
String(field.name),
)
const contexts = root.propertySignatures
.map((field) => String(field.name))
.filter((name) => name.startsWith("@context:"))
const tokens = root.propertySignatures
.filter((field) => {
const name = String(field.name)
return name !== "hue" && name !== "categorical" && !name.startsWith("@context:")
})
.flatMap((field) => tokenPaths(field.type, String(field.name)))
const groups = Map.groupBy(tokens, (token) =>
token
.split(".")
.slice(0, token.split(".").length > 2 ? 2 : 1)
.join("."),
)
const table = [...groups]
.map(([group, values]) => `| \`${group}\` | ${values.map((value) => `\`${value}\``).join("<br />")} |`)
.join("\n")
const example = {
version: 2,
light: {
hue: {
accent: "$hue.purple",
interactive: "$hue.purple",
},
text: {
default: "$hue.neutral.900",
},
background: {
default: "#fafafa",
},
},
dark: {
mergeMode: true,
text: {
default: "$hue.neutral.100",
},
background: {
default: "#101014",
},
},
} satisfies ThemeFile
Schema.decodeUnknownSync(ThemeFile)(example)
const output = await format(
`{/* Generated by packages/docs/script/generate-theme-tokens.ts. Do not edit. */}
\`\`\`json title="my-theme.json"
${JSON.stringify(example, null, 2)}
\`\`\`
## Token reference
This reference is generated from the Effect schema in
\`packages/tui/src/theme/v2/schema.ts\`. Changes to the runtime schema update
this section through \`bun run generate\`.
### Hue tokens
Every hue is a ${hueSteps.length}-step scale. Define a scale with all of these
steps, or alias it to another hue with a value such as \`$hue.blue\`.
| | Values |
| --- | --- |
| Hues | ${hueNames.map((name) => `\`${name}\``).join(", ")} |
| Steps | ${hueSteps.map((step) => `\`${step}\``).join(", ")} |
Reference a hue color as \`$hue.<name>.<step>\`, for example
\`$hue.interactive.500\`.
### Semantic tokens
Semantic values can reference another token by prefixing its path with \`$\`,
for example \`$text.default\`. Stateful tokens inherit their \`default\`
value when a state is omitted.
| Group | Tokens |
| --- | --- |
${table}
### Contexts
${contexts.map((context) => `\`${context}\``).join(" and ")} accept partial
overrides of the semantic tokens above. Components apply these contexts to
surfaces that need different contrast without changing the base theme.
`,
{ parser: "mdx", printWidth: 120, semi: false },
)
if (process.argv.includes("--check")) {
const current = await Bun.file(target).text()
if (current === output) process.exit(0)
console.error("Generated theme token documentation is stale. Run `bun run generate` from packages/docs.")
process.exit(1)
}
await Bun.write(target, output)
function requireObject(ast: SchemaAST.AST): SchemaAST.Objects {
if (SchemaAST.isObjects(ast)) return ast
if (SchemaAST.isUnion(ast)) {
const object = ast.types.map(findObject).find((value) => value !== undefined)
if (object) return object
}
throw new Error(`Expected an object schema, received ${ast._tag}`)
}
function findObject(ast: SchemaAST.AST): SchemaAST.Objects | undefined {
if (SchemaAST.isObjects(ast)) return ast
if (SchemaAST.isUnion(ast)) return ast.types.map(findObject).find((value) => value !== undefined)
if (SchemaAST.isSuspend(ast)) return findObject(ast.thunk())
}
function requireField(ast: SchemaAST.Objects, name: string) {
const field = ast.propertySignatures.find((field) => String(field.name) === name)
if (field) return field
throw new Error(`Theme schema field not found: ${name}`)
}
function tokenPaths(ast: SchemaAST.AST, prefix: string): string[] {
const object = findObject(ast)
if (!object || object.propertySignatures.length === 0) return [prefix]
return object.propertySignatures.flatMap((field) => tokenPaths(field.type, `${prefix}.${String(field.name)}`))
}

79
packages/docs/snippets/generated/theme-tokens.mdx Normal file
View file

@ -0,0 +1,79 @@
{/* Generated by packages/docs/script/generate-theme-tokens.ts. Do not edit. */}
```json title="my-theme.json"
{
"version": 2,
"light": {
"hue": {
"accent": "$hue.purple",
"interactive": "$hue.purple"
},
"text": {
"default": "$hue.neutral.900"
},
"background": {
"default": "#fafafa"
}
},
"dark": {
"mergeMode": true,
"text": {
"default": "$hue.neutral.100"
},
"background": {
"default": "#101014"
}
}
}
```
## Token reference
This reference is generated from the Effect schema in
`packages/tui/src/theme/v2/schema.ts`. Changes to the runtime schema update
this section through `bun run generate`.
### Hue tokens
Every hue is a 9-step scale. Define a scale with all of these
steps, or alias it to another hue with a value such as `$hue.blue`.
| | Values |
| ----- | -------------------------------------------------------------------------------------------------------- |
| Hues | `gray`, `red`, `orange`, `yellow`, `green`, `cyan`, `blue`, `purple`, `accent`, `interactive`, `neutral` |
| Steps | `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900` |
Reference a hue color as `$hue.<name>.<step>`, for example
`$hue.interactive.500`.
### Semantic tokens
Semantic values can reference another token by prefixing its path with `$`,
for example `$text.default`. Stateful tokens inherit their `default`
value when a state is omitted.
| Group | Tokens |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text` | `text.default`<br />`text.subdued` |
| `text.action` | `text.action.primary.default`<br />`text.action.primary.$hovered`<br />`text.action.primary.$focused`<br />`text.action.primary.$pressed`<br />`text.action.primary.$selected`<br />`text.action.primary.$disabled`<br />`text.action.destructive.default`<br />`text.action.destructive.$hovered`<br />`text.action.destructive.$focused`<br />`text.action.destructive.$pressed`<br />`text.action.destructive.$selected`<br />`text.action.destructive.$disabled` |
| `text.formfield` | `text.formfield.default`<br />`text.formfield.$hovered`<br />`text.formfield.$focused`<br />`text.formfield.$pressed`<br />`text.formfield.$selected`<br />`text.formfield.$disabled` |
| `text.feedback` | `text.feedback.error.default`<br />`text.feedback.error.subdued`<br />`text.feedback.warning.default`<br />`text.feedback.warning.subdued`<br />`text.feedback.success.default`<br />`text.feedback.success.subdued`<br />`text.feedback.info.default`<br />`text.feedback.info.subdued` |
| `background` | `background.default` |
| `background.surface` | `background.surface.offset`<br />`background.surface.overlay` |
| `background.action` | `background.action.primary.default`<br />`background.action.primary.$hovered`<br />`background.action.primary.$focused`<br />`background.action.primary.$pressed`<br />`background.action.primary.$selected`<br />`background.action.primary.$disabled`<br />`background.action.destructive.default`<br />`background.action.destructive.$hovered`<br />`background.action.destructive.$focused`<br />`background.action.destructive.$pressed`<br />`background.action.destructive.$selected`<br />`background.action.destructive.$disabled` |
| `background.formfield` | `background.formfield.default`<br />`background.formfield.$hovered`<br />`background.formfield.$focused`<br />`background.formfield.$pressed`<br />`background.formfield.$selected`<br />`background.formfield.$disabled` |
| `background.feedback` | `background.feedback.error.default`<br />`background.feedback.warning.default`<br />`background.feedback.success.default`<br />`background.feedback.info.default` |
| `border` | `border.default` |
| `scrollbar` | `scrollbar.default` |
| `diff.text` | `diff.text.added`<br />`diff.text.removed`<br />`diff.text.context`<br />`diff.text.hunkHeader` |
| `diff.background` | `diff.background.added`<br />`diff.background.removed`<br />`diff.background.context` |
| `diff.highlight` | `diff.highlight.added`<br />`diff.highlight.removed` |
| `diff.lineNumber` | `diff.lineNumber.text`<br />`diff.lineNumber.background.added`<br />`diff.lineNumber.background.removed` |
| `syntax` | `syntax.comment`<br />`syntax.keyword`<br />`syntax.function`<br />`syntax.variable`<br />`syntax.string`<br />`syntax.number`<br />`syntax.type`<br />`syntax.operator`<br />`syntax.punctuation` |
| `markdown` | `markdown.text`<br />`markdown.heading`<br />`markdown.link`<br />`markdown.linkText`<br />`markdown.code`<br />`markdown.blockQuote`<br />`markdown.emphasis`<br />`markdown.strong`<br />`markdown.horizontalRule`<br />`markdown.listItem`<br />`markdown.listEnumeration`<br />`markdown.image`<br />`markdown.imageText`<br />`markdown.codeBlock` |
### Contexts
`@context:elevated` and `@context:overlay` accept partial
overrides of the semantic tokens above. Components apply these contexts to
surfaces that need different contrast without changing the base theme.

129
packages/docs/themes.mdx Normal file
View file

@ -0,0 +1,129 @@
---
title: "Themes"
description: "Choose a built-in TUI theme or create a custom color scheme."
---
import ThemeTokens from "/snippets/generated/theme-tokens.mdx"
OpenCode includes built-in light and dark themes and can load custom themes
from your global configuration or a project directory. The default theme is
`opencode`.
## Choose a theme
In the full-screen TUI, run:
```text
/themes
```
You can also open the picker with `ctrl+x`, then `t`, using the
default keybindings.
Use `/settings` to change both the theme and its color mode. OpenCode supports
three modes:
| Mode | Behavior |
| -------- | -------------------------------------------------------- |
| `system` | Follow the terminal's detected light or dark appearance. |
| `dark` | Always use the theme's dark colors. |
| `light` | Always use the theme's light colors. |
Your selection is stored in `~/.config/opencode/cli.json`, or the equivalent
path under `$XDG_CONFIG_HOME`:
```json title="cli.json"
{
"theme": {
"name": "tokyonight",
"mode": "system"
}
}
```
<Note>
Theme selection applies to the full-screen TUI. Direct interactive runs use colors derived from the terminal palette
and honor only the color mode.
</Note>
## Built-in themes
OpenCode currently includes:
| | | |
| ------------ | ------------------- | ---------------------- |
| `aura` | `ayu` | `carbonfox` |
| `catppuccin` | `catppuccin-frappe` | `catppuccin-macchiato` |
| `cobalt2` | `cursor` | `dracula` |
| `everforest` | `flexoki` | `github` |
| `gruvbox` | `kanagawa` | `lucent-orng` |
| `material` | `matrix` | `mercury` |
| `monokai` | `nightowl` | `nord` |
| `one-dark` | `opencode` | `orng` |
| `osaka-jade` | `palenight` | `rosepine` |
| `solarized` | `synthwave84` | `tokyonight` |
| `vercel` | `vesper` | `zenburn` |
When OpenCode can read your terminal palette, the picker also includes
`system`. The `system` theme generates its colors from your terminal's
foreground, background, and ANSI palette.
## Custom themes
Create a JSON file in either of these locations:
```text
~/.config/opencode/themes/my-theme.json
.opencode/themes/my-theme.json
```
OpenCode checks the global theme directory first, followed by every
`.opencode/themes` directory from the filesystem root down to the current
directory. A more local file with the same filename overrides an earlier one.
The filename becomes the theme name, so `my-theme.json` appears as `my-theme`.
Custom theme files must be strict JSON. Comments and trailing commas are not
supported.
### Format
V2 themes organize colors into hue scales and semantic tokens. Set `version`
to `2` and define at least one of `light` or `dark`:
<Warning>
Native V2 custom theme files are not loaded directly by the current beta. Existing custom files use the V1 format and
are migrated to these tokens at runtime. This reference tracks the native V2 schema while direct file loading is
completed.
</Warning>
By default, a theme inherits OpenCode's complete theme, so you only need to
define overrides. Set `mergeMode` to `true` to inherit one mode from the other
before applying that mode's overrides. Set `standalone` to `true` only when you
intend to supply a complete independent theme.
Each token accepts:
- A hex color such as `"#5c9cf5"`
- `"transparent"` to use the terminal default
- A hue reference such as `"$hue.blue.500"`
- Another semantic token reference such as `"$text.default"`
Syntax and markdown tokens accept hex colors and hue references. Other
semantic tokens can reference any semantic token.
<ThemeTokens />
If you add or edit a custom theme while OpenCode is running, restart the TUI to
reload it.
## Terminal colors
Themes display most accurately in a terminal with truecolor support. Check
your terminal with:
```bash
echo $COLORTERM
```
Most modern terminals report `truecolor` or `24bit`. Without truecolor,
OpenCode approximates theme colors using the available terminal palette.

2
packages/tui/src/theme/v2/schema.ts
View file

@ -243,7 +243,7 @@ const MergeModeDefinition = Schema.Struct({
"@context:overlay": Schema.optional(ThemeTokensDefinition),
})
export type MergeModeDefinition = Schema.Schema.Type<typeof MergeModeDefinition>
export const ModeDefinition = Schema.Union([FileThemeDefinition, MergeModeDefinition])
export const ModeDefinition = Schema.Union([MergeModeDefinition, FileThemeDefinition])
export type ModeDefinition = Schema.Schema.Type<typeof ModeDefinition>
const FileMetadata = {

11
packages/tui/test/theme/v2/resolve.test.ts
View file

@ -192,8 +192,15 @@ test("standalone themes skip OpenCode defaults and use the red core fallback", (
})
test("uses defaults for the selected mode when it merges the other mode", () => {
const theme = resolveThemeFile({ version: 2, light: { hue: light.hue }, dark: { mergeMode: true } }, "dark")
expect(theme.background.default.toInts()).toEqual(resolveTheme(dark).background.default.toInts())
const theme = resolveThemeFile(
{
version: 2,
light: { hue: light.hue, background: { default: "#123456" } },
dark: { mergeMode: true },
},
"dark",
)
expect(theme.background.default.toInts()).toEqual([18, 52, 86, 255])
})
test("resolves matched action variants and states", () => {

2
script/generate.ts
View file

@ -6,4 +6,6 @@ await $`bun ./packages/sdk/js/script/build.ts`
await $`bun dev generate > ../sdk/openapi.json`.cwd("packages/opencode")
await $`bun run generate`.cwd("packages/docs")
await $`./script/format.ts`