Overview
Kappa components style themselves through semantic tokens such as--kappa-control and --kappa-subtle. The theme declares every token in both modes, so light and dark are equal targets and no component carries its own palette.
The same tokens drive application surfaces, controls, status messaging, and selection states. The preview uses real Kappa controls inside two explicit mode scopes.
data-kappa-theme="light"data-kappa-theme="dark"Install and Use
Import the theme stylesheet once in your application entry point. Component imports never inject a global theme or reset, so the import stays explicit.
import "@dicehub/kappa/styles/theme-kappa.css";Consume tokens in your own CSS alongside Kappa components.
.panel {
border: 1px solid var(--kappa-line);
border-radius: 0.5rem;
background: var(--kappa-base);
color: var(--kappa-default);
}
.panel__meta {
color: var(--kappa-subtle);
}Tooling and documentation read the same metadata from the public JSON export@dicehub/kappa/styles/tokens.json.
import tokens from "@dicehub/kappa/styles/tokens.json";
tokens.tokens.map((token) => token.name);Modes
Light is the default. The canonical attribute is data-kappa-theme with the values light and dark. The legacy data-mode attribute keeps working: data-kappa-theme takes precedence over data-mode on the same element, and nested scopes override their ancestors.
<!-- Light is the default. Declare the mode on the document or on a section. -->
<html data-kappa-theme="light">
<section data-kappa-theme="dark">
<p>Dark scope inside a light document.</p>
</section>
<!-- Compatibility: the legacy attribute keeps working. -->
<html data-mode="dark">Scopes nest. A section with an explicit mode keeps its own values, and the theme sets a matching color-scheme so native controls and scrollbars follow.
Override tokens where your application needs its own palette. Overrides inherit down the tree, so a component scope can carry a different accent than the page.
:root {
--kappa-accent-solid: #3b46c9;
--kappa-accent-contrast: #ffffff;
}
.hero {
--kappa-selected-background: #0f172a;
--kappa-selected-contrast: #ffffff;
}Popups follow their real DOM ancestry. A dialog or combobox popup is portaled, so it matches the element it is mounted into: theme the document root, or mount the portal inside the scope you want.
Token Reference
Every token lists its purpose, both configured values, and copy controls for the whole variable expression, the light value, and the dark value. Values that alias another token show the expression and the value it resolves to.
54 tokens
Values stay selectable: when the browser blocks clipboard access, select the value text and copy it manually.
Surfaces
Page, panel, and control backgrounds, plus their recessed and overlay steps.
--kappa-canvasApplication page background behind every surface.
#fafafa#030303--kappa-baseBase panel surface for cards, popovers, and raised regions.
Previously undefined, so components fell back to #ffffff in both modes.
#ffffff#0f0f0f--kappa-controlInteractive control surface for inputs, buttons, and menus.
#ffffff#18181b--kappa-tintRecessed surface for grouped rows, tracks, and low-emphasis fills.
#f2f3f5#262626--kappa-overlayHover and overlay fill for rows, options, and quiet controls.
#e9ebef#303034--kappa-disabled-surfaceFill for disabled inputs and disabled previews.
Aliases --kappa-tint. Disabled text is exempt from contrast minimums.
var(--kappa-tint) → #f2f3f5var(--kappa-tint) → #262626--kappa-readonly-surfaceFill for read-only fields that stay focusable.
Aliases --kappa-tint.
var(--kappa-tint) → #f2f3f5var(--kappa-tint) → #262626Text
Body copy, emphasis, supporting text, and placeholders.
--kappa-defaultDefault body and control text.
#171717#f5f5f5--kappa-strongHighest-emphasis headings, values, and selected labels.
Previously provided by the documentation shell as --docs-strong.
#0a0a0a#fafafa--kappa-subtleSupporting text, labels, and icons.
Light value corrected from #737373 (4.27:1 on tint) to #696969 (4.95:1 on tint).
#696969#a1a1a1--kappa-mutedPlaceholders and inactive copy.
Aliases --kappa-subtle so placeholders move with supporting text.
var(--kappa-subtle) → #696969var(--kappa-subtle) → #a1a1a1Accent
The dicehub accent for links, selected indicators, and solid actions.
--kappa-accentAccent text, links, and selected indicators.
#2479b6#7185ff--kappa-accent-solidSolid accent fill for primary actions and checked controls.
#247ab7#247ab7--kappa-accent-contrastText and icons placed on --kappa-accent-solid.
#ffffff#ffffffSelection
Selected states that pair a fill with readable contrast text.
--kappa-selected-backgroundFill for selected items that invert to a strong surface.
Takes the fill role of the deprecated --kappa-selected.
#0a0a0a#fafafa--kappa-selected-contrastText and icons placed on --kappa-selected-background.
Required whenever you keep a --kappa-selected override.
#ffffff#0f0f0f--kappa-selected-textSelected text on an unchanged surface, without a fill.
Takes the text role of the deprecated --kappa-selected.
var(--kappa-strong) → #0a0a0avar(--kappa-strong) → #fafafaStatus
Informational, success, warning, and danger colors as text, solid fill, and tint.
--kappa-infoInformational border and indicator color.
Matches --kappa-info-solid.
#175cd3#175cd3--kappa-info-textInformational text and icons on tint or surface fills.
#175cd3#93c5fd--kappa-info-solidSolid informational fill for banners and notice actions.
#175cd3#175cd3--kappa-info-tintInformational tinted surface.
#dbeafe#10233f--kappa-successSuccess border and completion indicator.
Matches --kappa-success-solid; used by Input OTP completion.
#027a48#027a48--kappa-success-textSuccess text and icons on tint or surface fills.
#027a48#86efac--kappa-success-solidSolid success fill for confirmations and actions.
#027a48#027a48--kappa-success-tintSuccess tinted surface.
#d1fadf#102f20--kappa-warningWarning border and indicator color.
Matches --kappa-warning-solid.
#b54708#b54708--kappa-warning-textWarning text and icons on tint or surface fills.
#b54708#fde68a--kappa-warning-solidSolid warning fill for alerts and caution actions.
#b54708#b54708--kappa-warning-tintWarning tinted surface.
#fef0c7#3b2f10--kappa-dangerDanger border and invalid-state indicator.
Matches --kappa-danger-solid in light mode; the dark indicator is raised for field borders.
#b42318#f87171--kappa-danger-textDanger text and icons on tint or surface fills.
#b42318#fca5a5--kappa-danger-solidSolid danger fill for destructive actions.
#b42318#b42318--kappa-danger-tintDanger tinted surface.
#fee4e2#3b1716Charts
Ordered series colors for data visualization in light and dark themes.
--kappa-chart-1First chart series and primary data emphasis.
#247ab7#8292ff--kappa-chart-2Second chart series.
#087f8c#4cc4d0--kappa-chart-3Third chart series.
#bb5a15#f4a261--kappa-chart-4Fourth chart series.
#337a4b#70c58a--kappa-chart-5Fifth chart series.
#9f3f75#e084b4--kappa-chart-6Sixth chart series.
#684bb6#a78bfa--kappa-chart-7Seventh chart series.
#ae3d39#f3837e--kappa-chart-8Eighth chart series.
#596579#aeb6c3Borders and focus
Hairline separators, stronger boundaries, and keyboard focus rings.
--kappa-hairlineSubtle inner edge for nested separators and dividers.
Decorative boundary; not held to a contrast minimum.
#e7eaef#262626--kappa-lineStandard border for controls, cards, and layout separators.
Decorative boundary; not held to a contrast minimum.
#e7eaef#262626--kappa-input-borderResting border for text inputs and field controls.
Decorative boundary; interactive hover and focus use --kappa-focus.
#dcdcdc#52525b--kappa-line-strongDecorative boundary that is stronger than the hairline: grips, keycaps, and scrollbar thumbs.
Decorative only: 1.60:1 on light controls and 2.29:1 on dark controls. When a boundary must convey essential state, use --kappa-strong or --kappa-focus, or pair it with a fill. Dark value added by the theme.
#c7cdd6#52525b--kappa-focusFocus ring color for keyboard focus.
#247ab7#247ab7--kappa-focus-softTranslucent halo behind focus rings and selected text.
20% alpha in light mode, 24% in dark mode.
rgba(36, 122, 183, 0.2)#247ab73dSupporting
Shadows, backdrops, and the compatibility values existing components require.
--kappa-shadowResting elevation for raised surfaces; removed in dark mode.
0 1px 2px rgba(16, 24, 40, 0.05)none--kappa-popover-shadowElevation for popovers, menus, and floating panels.
0 8px 24px -6px rgba(16, 24, 40, 0.12), 0 2px 4px -2px rgba(16, 24, 40, 0.06)0 16px 40px -12px rgba(0, 0, 0, 0.72)--kappa-emphasisNeutral mix color for pressed overlays; not a text color.
Color mixing only; use --kappa-strong for emphasized text.
#17191f#17191f--kappa-badge-betaBeta badge outline color for the Badge component.
Aliases --kappa-accent.
var(--kappa-accent) → #2479b6var(--kappa-accent) → #7185ff--kappa-badge-invertedInverted badge fill for the Badge component.
Aliases --kappa-strong.
var(--kappa-strong) → #0a0a0avar(--kappa-strong) → #fafafa--kappa-badge-inverted-contrastInverted badge label color for the Badge component.
Aliases --kappa-base.
var(--kappa-base) → #ffffffvar(--kappa-base) → #0f0f0f--kappa-banner-focusFocus ring used inside Banner surfaces.
Light mode matches --kappa-focus; dark mode raises to a lighter blue on banner tints.
#247ab7#93c5fdContrast
Recommended foreground and background pairs. Text pairs hold at least 4.5:1 and non-text indicators at least 3:1, measured from unrounded luminance ratios in both modes.
Decorative boundaries such as --kappa-hairline and--kappa-line-strong, plus disabled surfaces and labels, are exempt from these minimums. When a boundary has to convey essential state, use--kappa-strong or --kappa-focus, or pair the boundary with a fill. Meeting these minimums does not certify every combination an application can build, and color alone never carries meaning: pair status and selection with labels, icons, or text.
| Pair | Foreground | Background | Minimum | Light | Dark |
|---|---|---|---|---|---|
| Default text on canvasPrimary reading pair for page-level copy. | --kappa-default | --kappa-canvas | 4.5:1 | 17.18:1 | 18.92:1 |
| Default text on controlsInputs, buttons, and menu labels. | --kappa-default | --kappa-control | 4.5:1 | 17.93:1 | 16.25:1 |
| Default text on tintCopy inside recessed panels and grouped rows. | --kappa-default | --kappa-tint | 4.5:1 | 16.15:1 | 13.88:1 |
| Strong text on baseHeadings and emphasized values on raised surfaces. | --kappa-strong | --kappa-base | 4.5:1 | 19.80:1 | 18.36:1 |
| Supporting text on tintThe pair that set the light supporting-text value. | --kappa-subtle | --kappa-tint | 4.5:1 | 4.94:1 | 5.86:1 |
| Supporting text on overlayLabels that sit on hover and overlay fills. | --kappa-subtle | --kappa-overlay | 4.5:1 | 4.60:1 | 5.09:1 |
| Placeholder text on controlsPlaceholders and empty-state copy in fields. | --kappa-muted | --kappa-control | 4.5:1 | 5.49:1 | 6.86:1 |
| Accent text on controlsLinks, selected indicators, and accent labels. | --kappa-accent | --kappa-control | 4.5:1 | 4.68:1 | 5.48:1 |
| Text on solid accentPrimary action and checked-control label pair. | --kappa-accent-contrast | --kappa-accent-solid | 4.5:1 | 4.62:1 | 4.62:1 |
| Text on selection fillPressed toolbar buttons and selected calendar days. | --kappa-selected-contrast | --kappa-selected-background | 4.5:1 | 19.80:1 | 18.36:1 |
| Selected text on canvasChecked options that mark selection with text alone. | --kappa-selected-text | --kappa-canvas | 4.5:1 | 18.97:1 | 19.76:1 |
| Info text on info tintInformational banners and status badges. | --kappa-info-text | --kappa-info-tint | 4.5:1 | 4.91:1 | 8.73:1 |
| Success text on success tintSuccess banners and status badges. | --kappa-success-text | --kappa-success-tint | 4.5:1 | 4.76:1 | 10.32:1 |
| Warning text on warning tintWarning banners and status badges. | --kappa-warning-text | --kappa-warning-tint | 4.5:1 | 4.78:1 | 10.54:1 |
| Danger text on danger tintError banners, invalid fields, and status badges. | --kappa-danger-text | --kappa-danger-tint | 4.5:1 | 5.45:1 | 8.38:1 |
| Label on solid infoNotice actions that fill with the informational solid. | --kappa-accent-contrast | --kappa-info-solid | 4.5:1 | 5.99:1 | 5.99:1 |
| Label on solid successConfirmation actions that fill with the success solid. | --kappa-accent-contrast | --kappa-success-solid | 4.5:1 | 5.41:1 | 5.41:1 |
| Label on solid warningCaution actions that fill with the warning solid. | --kappa-accent-contrast | --kappa-warning-solid | 4.5:1 | 5.43:1 | 5.43:1 |
| Label on solid dangerDestructive actions that fill with the danger solid. | --kappa-accent-contrast | --kappa-danger-solid | 4.5:1 | 6.57:1 | 6.57:1 |
| Focus ring on controlsKeyboard focus around inputs, buttons, and option rows. | --kappa-focus | --kappa-control | 3:1 | 4.62:1 | 3.83:1 |
| Focus ring on canvasKeyboard focus on page-level surfaces. | --kappa-focus | --kappa-canvas | 3:1 | 4.43:1 | 4.46:1 |
| Selection fill on baseSelected fill against the surface it replaces. | --kappa-selected-background | --kappa-base | 3:1 | 19.80:1 | 18.36:1 |
| Danger indicator on controlsInvalid border and error indicator on fields. | --kappa-danger | --kappa-control | 3:1 | 6.57:1 | 6.40:1 |
Maintenance
packages/kappa/scripts/theme-generator/config.ts is the source of truth, with tokens, contrast pairs, and deprecations in sibling modules. The generator validates groups, modes, references, cycles, and contrast metadata, then writessrc/styles/theme-kappa.css and src/styles/tokens.json.
pnpm --filter @dicehub/kappa codegen:themes
pnpm --filter @dicehub/kappa check:themesTheme generation runs before the library build, and the type check fails when the generated files drift from the configuration. The library build then re-verifies the packed assets with check:theme-build.
Compatibility and deprecations
--kappa-selectedis withdrawn. Use--kappa-selected-background, --kappa-selected-contrast, --kappa-selected-textinstead. Withdrawn as a global default because a single value served both selection fills and selection text. Component fallback chains still read an explicit --kappa-selected override first; set --kappa-selected-contrast beside it so the pair stays readable.
Documentation values
The previews and component pages in this site render @dicehub/kappa components. The docs shell maps its own variables to the theme and keeps documentation-only values, such as the Geist font stack, the translucent header overlay, and the shell success accent, in its own stylesheet.
This reference is one server-rendered Vue island. It marks itself withdata-markdown-keep so the Markdown export carries the complete token table, while ordinary demo islands stay out of Markdown.