Theme tokens

Where to put your overrides. Tokens are declared on :root and inherited, so a value you set on :root reaches the viewer and the surfaces that render into document.body (the signature dialog, the security modal, every popover), and a value on your own container reaches the viewer inside it: :root { --ks-accent: #e91e63; } for everything, including portalled dialogs (usually what you want); #invoice-viewer { --ks-accent: #e91e63; } for one viewer instance, if you host several. Your stylesheet loads after ours, so an override at equal specificity wins without !important. Two :root rules tie on specificity and source order decides — yours is later, so yours applies.

theme.mode and theme.accentColor are applied to the viewer's own root element inside your container, and mirrored to the portal layer so dialogs follow. With mode: 'light' (the default) your :root and container values reach the viewer and its dialogs; only on a dark page — a dark OS, or data-ks-theme="dark" on <html> — does the viewer declare the SDK's light values on itself, so it stays light. mode: 'dark' always declares the SDK's dark values on the viewer, over the page and over your :root values (your accentColor still applies). For a dark palette of your own, use mode: 'auto' (see the dark-theme recipe below). To style portalled surfaces directly, target .ks-portal — it is on every root the SDK renders outside the viewer. Dialogs, sheets and popovers live in one portal layer shared by the whole page. With several viewers in different themes or accents, they take the theme of the viewer created last. See Theme.

What you may target. Three things in the SDK's markup are a contract, kept across releases: the tokens (--ks-*): the colors, type, spacing and stacking, listed in the tables above — they are how a theme is written; the data attributes on the viewer element: data-ks-theme, data-ks-size, data-ks-pointer, data-ks-height, data-ks-toolbar, data-ks-nav, data-ks-panels, data-ks-touch, data-ks-text-edit, data-ks-phone, data-ks-rails, data-ks-tablet, data-ks-tool, data-ks-touch-drag and data-ks-print — see Layout; and the structural classes in the table above, for placing, sizing and hiding a region, not for repainting it. Every other class (.ks-tb-btn, say) is internal: it may change in any release without notice. Set the tokens instead; they are what we promise not to break.

Semantic tokens — the contract. These are the names to set. Every value in the tables is the light-theme default; the dark column is what the same token becomes under mode: 'dark' or a dark OS. The dark accent gets lighter, not darker: indigo-600 on near-black fails contrast, the same hue at 300 passes. If you override the accent for dark mode, do the same. With theme.accentColor, the other shades are derived for you from the theme itself: hover mixes toward --ks-text (darker on light, lighter on dark), and the wash mixes toward --ks-surface, so one color works in both themes.

Type, space, shape, motion do not change between themes. Spacing is a 4px step. Most type sizes the chrome draws are --ks-text-* steps — set --ks-font or a step to retune them in one place. A few stay fixed on purpose: the 16px an input needs on a touch screen (below it iOS zooms the page), text that depicts content such as a typed signature's preview, and a handful of optical sizes tuned to a specific cell (the phone dock and toolbar strip labels, some signature-dialog captions). --ks-text-xl, --ks-text-2xl, --ks-space-6 and --ks-ease-in are part of the scale but no component uses them yet; setting them has no visible effect today. --ks-accent-border (derived from accentColor) and --ks-field-border are still declared, but nothing reads them either.

Component tokens — per-component control. Each falls back to a semantic token. Set one to move a single component. The toolbar, ribbon, navigation bar, thumbnails, dialogs and page-area tables above list them.

What the theme does not touch. Some colors belong to the document, not to your UI, and deliberately ignore mode and your overrides of the chrome tokens. The page stays white in dark mode. A PDF is white because the document is white. Inverting it would change the content, turn a scan into a negative, and break the match between what is on screen and what will print. Only the ground around the page darkens. The page-layer tokens exist in one value for both themes. You can still retune them; they just do not follow mode. A focused or hovered field is outlined in --ks-accent. Also unthemed, because they become part of the saved file: annotation ink, highlight colors and stamp presets. What the user draws is content. Those are chosen in the tool's own options bar, and exporting the document keeps them exactly as drawn.

Stacking order. Every layer the SDK paints has a named z-index, so you can predict what sits above what and place your own chrome around it. To float your own header above the viewer's chrome but below its dialogs, sit between --ks-z-chrome and --ks-z-popover. The docked chrome, popovers, modals, toasts and the on-page marks, objects and handles use these layers; --ks-z-field and --ks-z-drag are reserved and not read by any layer. The signature dialog and Edit Text's floating sheet and hints sit at fixed values of 10000–10002, so only a value above 10002 guarantees your own chrome sits above everything of ours — except the license-required notice, which always stays on top.

Accessibility the SDK already handles. Keep these if you restyle; they are cheap and they are what the viewer is designed around so that everyone can use it — with a skip link, a roving toolbar, focus-trapped dialogs, live regions, the text layer and 44 px touch targets. Focus: every control shows a :focus-visible ring built from --ks-focus-ring and --ks-focus-offset. If you override the accent, the ring follows automatically. Do not set outline: none. The rule is scoped to .ks-viewer and .ks-portal, so it reaches dialogs too but never leaks into your own page. Reduced motion: under prefers-reduced-motion: reduce transitions drop to 1ms — not 0, so transitionend handlers still fire and nothing that waits on one stalls. Forced colors: under forced-colors: active the focus ring switches to the system Highlight color, and the ribbon re-states its selected tab and active tool with system keywords — a background wash alone disappears in that mode. If you restyle a selected state with color only, add a border or outline for this case. Contrast: the defaults are designed for WCAG AA contrast against their own surfaces. If you change the accent, check --ks-accent-text against it — a light accent needs dark text on it.

Recipe: just our brand color. new PDFViewer(container, doc, { theme: { accentColor: '#e91e63' } }); — hover, subtle and border shades are derived from it. Nothing else to set.

Recipe: follow the OS. new PDFViewer(container, doc, { theme: { mode: 'auto' } });

Recipe: switching theme live. Keep theme.mode: 'auto' and set the attribute on <html> from your own theme toggle. The viewer and its dialogs switch immediately, with no rebuild: document.documentElement.dataset.ksTheme = isDark ? 'dark' : 'light';. Remove the attribute to follow the OS again.

Recipe: our whole design system. Override the semantic tokens once, as in the example above. With the default mode: 'light' these values apply wherever the page around the viewer is light; with mode: 'auto' they apply in both themes. To give dark its own values, add a dark block too.

Recipe: a dark theme of your own. Leave theme.mode at 'auto' and redefine the tokens under both selectors, as in the example above: the first (:root[data-ks-theme='dark']) for a page that sets data-ks-theme="dark" on <html> itself, the second (@media (prefers-color-scheme: dark) { :root:not([data-ks-theme='light']) { … } }) for a dark OS. (An explicit theme.mode: 'dark' uses the SDK's own dark palette — your accentColor still applies.)

Recipe: a denser toolbar. :root { --ks-toolbar-height: 56px; --ks-space-2: 6px; }. In a compact or narrow viewer the toolbar uses its own smaller heights.

Recipe: replace our chrome entirely. new PDFViewer(container, doc, { toolbar: { layout: 'none' }, sidebar: { rail: false }, navigation: { pageControls: false, zoomControls: false } }) (rail: false for your own Pages button, not ours beside it), then your buttons, our SDK: activateTool and download are async — viewer.activateTool('highlight').catch(...) rejects with INVALID_ARGUMENT (the tool is off here), FEATURE_NOT_LICENSED (not in the license) or PERMISSION_DENIED (the document forbids it); myHighlightButton.hidden = !viewer.isToolEnabled('highlight'); myUndoButton.onclick = () => void viewer.undo(); mySaveButton.onclick = () => void viewer.createExporter().download(). Which button is pressed comes from toolChanged: between tools the resting tool runs — Select by default — so it reports 'selectText' from the first paint, and Search and Manage Pages are panels (the exported PANEL_TOOL_NAMES): activating them leaves activeTool as it was. Your Pages button opens or closes through viewer.openPanel(viewer.activePanel === 'pages' ? null : 'pages') and follows panelChanged, whoever made the change — the drawer's backdrop, Escape inside the drawer, a resize. The page area, panels and every tool still work; only our chrome is gone. On a phone the active tool's options still rise in the inspector sheet above your own bar (see Layout). See PDFViewer for what you can drive, and Bring your own chrome.