JudgmentKit Tokens

Usage

Use token roles to describe what a visual choice is doing: separating a surface, marking focus, showing status, identifying risk, or recording completion. The CSS custom properties below are portable defaults for generated interfaces. Repo-approved design systems can replace them only through a complete design_system_adapter selected by the implementation contract; incomplete adapters fail instead of falling back to these defaults.

Appearance

JudgmentKit provides light and dark values. The default is system-detected: generated surfaces should follow the user's operating-system or browser color-scheme preference. Do not add a visible appearance toggle unless the activity specifically needs a persistent preference.

Use light values as the default token map.
Use dark values inside the system color-scheme media query.
Keep appearance controls out of the UI unless they support the activity.

Values

The role-first layer exists because agents need to choose visual intent before choosing a brand palette. The values make that intent renderable and reviewable without pretending this is a full component library.

:root {
  color-scheme: light dark;
  --jk-color-canvas: #f8f7f2;
  --jk-color-surface: #ffffff;
  --jk-color-text: #171717;
  --jk-color-muted: #61615c;
  --jk-color-border: #d7d3c8;
  --jk-color-focus: #245f73;
  --jk-color-success: #2e6b48;
  --jk-color-warning: #8a5a16;
  --jk-color-risk: #8f342f;
  --jk-color-disabled: #8a8f93;
  --jk-color-receipt: #23615f;
  --jk-space-2: 0.5rem;
  --jk-space-3: 0.75rem;
  --jk-space-4: 1rem;
  --jk-radius-control: 4px;
  --jk-radius-panel: 8px;
  --jk-focus-ring: 0 0 0 3px rgba(36, 95, 115, 0.28);
}

@media (prefers-color-scheme: dark) {
  :root {
    --jk-color-canvas: #101312;
    --jk-color-surface: #181d1b;
    --jk-color-text: #f2f4ef;
    --jk-color-muted: #b8c0bb;
    --jk-color-border: #39423f;
    --jk-color-focus: #7db6c7;
    --jk-color-success: #82c99a;
    --jk-color-warning: #e0b15d;
    --jk-color-risk: #e37d76;
    --jk-color-disabled: #7d8580;
    --jk-color-receipt: #80cbc7;
    --jk-space-2: 0.5rem;
    --jk-space-3: 0.75rem;
    --jk-space-4: 1rem;
    --jk-radius-control: 4px;
    --jk-radius-panel: 8px;
    --jk-focus-ring: 0 0 0 3px rgba(125, 182, 199, 0.38);
  }
}

Portable CSS custom properties
Property	Value	Role	Use
`--jk-color-canvas`	`#f8f7f2`	`surface`	page canvas and application background
`--jk-color-surface`	`#ffffff`	`surface`	panels, cards, overlays, and work regions
`--jk-color-text`	`#171717`	`text`	primary readable text
`--jk-color-muted`	`#61615c`	`text`	secondary labels and supporting text
`--jk-color-border`	`#d7d3c8`	`border`	dividers, control outlines, and grouped evidence
`--jk-color-focus`	`#245f73`	`focus`	visible focus rings and active affordances
`--jk-color-success`	`#2e6b48`	`status`	approved, completed, and successful states
`--jk-color-warning`	`#8a5a16`	`status`	warning, waiting, and needs-attention states
`--jk-color-risk`	`#8f342f`	`risk`	risk, escalation, and destructive action states
`--jk-color-disabled`	`#8a8f93`	`disabled`	disabled controls with visible rationale
`--jk-color-receipt`	`#23615f`	`receipt`	handoff receipts and completion confirmation
`--jk-space-2`	`0.5rem`	`surface`	compact gaps inside dense controls
`--jk-space-3`	`0.75rem`	`surface`	row gaps and adjacent evidence spacing
`--jk-space-4`	`1rem`	`surface`	panel padding and section rhythm
`--jk-radius-control`	`4px`	`border`	buttons, inputs, and compact controls
`--jk-radius-panel`	`8px`	`surface`	cards, panels, and bounded work areas
`--jk-focus-ring`	`0 0 0 3px rgba(36, 95, 115, 0.28)`	`focus`	focus-visible outline around interactive controls

Token roles

JudgmentKit token roles
Role	Families	Use	Review check
`surface`	color, elevation	backgrounds, panels, overlays, and work-surface regions	Check that panels, overlays, and page regions are visually distinct without adding clutter.
`text`	color, type	body copy, headings, labels, and dense operational text	Check readable contrast, line length, and hierarchy before decorative styling.
`border`	color, radius	control boundaries, dividers, panels, and grouped evidence	Use borders to clarify grouping, control bounds, and evidence adjacency.
`focus`	color, motion	visible focus indicators and keyboard navigation affordances	Keyboard focus must remain visible and easy to follow.
`status`	color, semantic	success, warning, error, loading, and empty states	Pair status treatment with visible words and state changes.
`decision`	color, density	primary decision controls and bounded action groups	Primary and destructive actions need clear separation and labels.
`risk`	color, semantic	risk, escalation, destructive, or externally committing actions	Escalation and destructive states need visible context, not just stronger color.
`disabled`	color, semantic	disabled controls and unavailable state reasons	Disabled controls need an unavailable reason when the next step matters.
`receipt`	color, semantic	completion, confirmation, and handoff receipt states	Completion states should leave a clear confirmation or handoff record.

Examples

Status that has visible meaning

Use
Pair status color with text such as Approved, Warning, Returned, or Complete.

Watch for
Do not rely on color alone for decisions, errors, or progress.
Focus that is easy to find

Use
Use focus roles for keyboard-visible controls and clear active regions.

Watch for
Do not remove focus styling to make a layout look cleaner.

Accessibility

Color cannot be the only way a user understands status, error, risk, or completion.
Focus treatment must be visible for keyboard users and must not be hidden by surrounding layout.
Status, risk, disabled, and receipt states need visible text or nearby context.