Theming Vendo surfaces with the VendoTheme token shape

Init extracts .vendo/theme.json. The theme has this exact shape:

export interface VendoTheme {
  colors: { background: string; surface: string; text: string; muted: string; accent: string; accentText: string; danger: string; border: string };
  typography: { fontFamily: string; headingFamily?: string; baseSize: string };
  radius: { small: string; medium: string; large: string };
  density: "compact" | "comfortable";
  motion: "full" | "reduced";
}

Init wires this file into the scaffolded <VendoRoot theme={...}> at build time (sync regenerates it on each build), so a fresh install renders on brand without passing theme by hand. Pass partial runtime overrides through VendoProvider.theme. Shipped chrome derives its colors, typography, radius, density, and motion from these tokens. It does not hardcode a Vendo brand. Generation receives the same theme. Optional .vendo/design-rules.md adds generation-time design rules without changing runtime tokens.

Emitted CSS variables

VendoRoot emits stable CSS custom properties derived from density and motion. Chrome and the prewired primitives read them directly, and you can consume the same variables from your own styles. The --vendo-density-* and --vendo-motion-* names below are stable — new variables may be added under these prefixes, but the ones listed here will not be renamed.

Density

density: "compact" tightens control sizes, padding, and gaps; density: "comfortable" relaxes them. Every compact value is less than or equal to its comfortable counterpart.

Variable	`compact`	`comfortable`
`--vendo-density-control-height`	`32px`	`38px`
`--vendo-density-control-padding`	`6px 10px`	`9px 12px`
`--vendo-density-card-padding`	`12px`	`16px`
`--vendo-density-content-gap`	`7px`	`10px`
`--vendo-density-inline-gap`	`5px`	`7px`
`--vendo-density-field-gap`	`4px`	`6px`
`--vendo-density-table-padding`	`7px 10px`	`10px 12px`
`--vendo-density-badge-height`	`20px`	`24px`
`--vendo-density-badge-padding`	`3px 7px`	`5px 9px`
`--vendo-density-stat-padding`	`9px 11px`	`12px 14px`
`--vendo-density-tabs-padding`	`3px`	`4px`
`--vendo-density-tab-height`	`26px`	`30px`
`--vendo-density-tab-padding`	`4px 8px`	`6px 10px`

Color scheme

VendoRoot derives color-scheme from the WCAG relative luminance of colors.background and exposes it as --vendo-color-scheme. Backgrounds below the flip point (L < 0.179) resolve to dark; everything else, including unparseable values, resolves to light.

Variable	Light background	Dark background
`--vendo-color-scheme`	`light`	`dark`

Chrome uses this variable to activate light-dark() branches, so a dark-brand host automatically gets the dark chrome treatment without any extra configuration. Set colors.background in .vendo/theme.json (or through a VendoProvider.theme override) and the scheme follows.

.vendo/theme.json

{
  "colors": {
    "background": "#14151a",
    "surface": "#1b1c22",
    "text": "#f5f5f7"
  }
}

Reference --vendo-color-scheme from your own styles if you want custom surfaces to track the same flip:

.my-card {
  color-scheme: var(--vendo-color-scheme);
}

Motion

motion: "reduced" collapses --vendo-motion-duration to 0ms so chrome respects user reduced-motion preferences. The easing curve stays constant.

Variable	`full`	`reduced`
`--vendo-motion-duration`	`160ms`	`0ms`
`--vendo-motion-easing`	`cubic-bezier(0.2, 0.8, 0.2, 1)`	`cubic-bezier(0.2, 0.8, 0.2, 1)`

Reference the variables from your own CSS to keep custom surfaces in sync with the current theme:

.my-card {
  padding: var(--vendo-density-card-padding);
  transition: background-color var(--vendo-motion-duration) var(--vendo-motion-easing);
}

Mobile takeover

Shipped overlay, page, and palette chrome switch to a full-viewport takeover at viewports 767px wide and narrower. The takeover covers the host layout instead of docking inside a squeezed column and portals to document.body so transformed host ancestors cannot confine it. It honors iOS safe-area insets on all four edges. On touch devices (pointer: coarse), the composer and palette search render at 16px to prevent iOS auto-zoom, and icon buttons and the overlay close control expand to a 44px touch target. Desktop chrome is unchanged. The takeover surface stamps a stable --fl-kb-inset CSS variable derived from visualViewport so the composer lifts above the on-screen keyboard. Read it from your own styles if you render a custom surface inside a takeover:

.my-mobile-footer {
  padding-bottom: calc(env(safe-area-inset-bottom, 0px) + var(--fl-kb-inset, 0px));
}

--fl-kb-inset is 0px when no keyboard is open and outside of takeover mode.

​Emitted CSS variables

​Density

​Color scheme

​Motion

​Mobile takeover

Emitted CSS variables

Density

Color scheme

Motion

Mobile takeover