Styling & variables

Styling model

Canvas Timeline keeps high-density visuals on the canvas renderer so scroll, zoom, and playback stay fast. CSS still controls the lower-count DOM pieces around that canvas.

This split keeps the editor performance model intact: CSS can follow your app theme, but clips, tracks, rulers, markers, and similarly dense visuals do not become hundreds of DOM nodes.

Timeline.ClipInteractionLayer follows the same boundary. It renders one hovered, selected, or actively edited clip affordance and uses pointer capture for the active edit. CSS variables can style that one affordance, but repeated clip bodies, labels, and selected borders remain canvas-painted.

For advanced customization of the canvas drawing pipeline (including overrides, custom canvas layers, and theme/metrics configuration), see the Canvas renderer customization guide.

Stylesheet entrypoints

Canvas Timeline follows shadcn’s ownership model: your app defines semantic tokens, and package components consume them. Because this is a packaged component library rather than copied source, the components also need a small mechanics stylesheet for layout, hit targets, pointer behavior, canvas sizing, grabbers, scrollbars, intrinsic affordance shapes, and accessibility helpers.

For the clearest shadcn-like split, import the mechanical layer and the token-consuming style layer explicitly:

import '@techsquidtv/canvas-timeline/base.css';
import '@techsquidtv/canvas-timeline/theme.css';

base.css contains required geometry, stacking, pointer behavior, hit-area rules, and intrinsic affordance shapes only. It is not a visual theme: it does not set colors, borders, shadows, typography, focus treatment, or theme radii. Import it by itself only when your app provides every visual rule for the DOM chrome:

import '@techsquidtv/canvas-timeline/base.css';

theme.css contains shadcn-token-driven visual treatment for package-owned DOM interaction chrome, optional timeline shell/control utility classes, and the timeline variables that the canvas renderer resolves. It consumes app-owned tokens such as --background, --foreground, --border, --input, and --ring; it does not define those app theme tokens for you.

styles.css is only the bundled import of those two package layers:

import '@techsquidtv/canvas-timeline/styles.css';

CSS variables

theme.css expects tokens such as --background, --foreground, --border, --input, --ring, --primary, --muted, --muted-foreground, --accent, --destructive, --radius, --font-sans, and --font-mono.

Apps that do not use shadcn should define the same semantic tokens before using theme.css, or set explicit --timeline-* variables on a timeline or standalone primitive container after importing the package stylesheet.

The default timeline tokens map to shadcn semantics. Override --timeline-* tokens on a timeline container when you want a local timeline-specific treatment without changing the rest of your app’s shadcn theme.

Use app semantic tokens such as --background, --foreground, --border, --primary, and --ring for product chrome, panels, dialogs, media previews, and page or demo layout. Use --timeline-* tokens for exported Canvas Timeline primitives and renderer visuals. Use app-local or demo-local tokens for custom composition details that are not part of the timeline package contract.

Surface Tokens

Ruler And Tracks

Clips And Markers

Playhead, In/Out, And Snap Feedback

Scrollbars

Controls

Inputs And Timecode Fields

Nested theme scoping

Define shadcn semantic tokens at your app boundary. Canvas Timeline components read those tokens from the nearest scope, so the same import follows normal shadcn dark-mode scoping:

.dark {
  --background: oklch(0.17352 0 0);
  --foreground: oklch(0.985 0 0);
  --card: oklch(0.205 0 0);
  --card-foreground: oklch(0.985 0 0);
  --border: oklch(1 0 0 / 12%);
  --input: oklch(1 0 0 / 15%);
  --ring: oklch(0.75 0.18 85);
  --primary: oklch(0.75 0.18 85);
  --primary-foreground: oklch(0.145 0 0);
  --muted: oklch(0.2024 0 0);
  --muted-foreground: oklch(0.708 0 0);
  --accent: oklch(0.269 0 0);
  --accent-foreground: oklch(0.985 0 0);
  --destructive: oklch(0.704 0.191 22.216);
  --radius: 0.625rem;
  --font-sans:
    system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell,
    'Open Sans', 'Helvetica Neue', sans-serif;
  --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
}

Set timeline tokens on the package root or a selector that targets package roots after importing package CSS only when you need a local component-specific override:

.editor-theme .timeline-root,
.editor-theme .timecode-input {
  --timeline-marker: var(--muted-foreground);
  --timeline-clip-border-selected: var(--foreground);
  --timeline-playhead: var(--primary);
  --timeline-inout-accent: oklch(0.62 0.16 250);
}