← Back to Capabilities

Capability

Design System & Token Architecture

A token-driven design system compiled from a single JSON source, distributed as a versioned npm package, and consumed at runtime through CSS custom properties with live theme switching.

Build & Distribution Pipeline

How tokens travel from a single JSON source of truth into production code.

01

Define in JSON

Tokens are authored in standardized JSON files adhering to the W3C Design Token Community Group (DTCG) specification.

02

Compile with Style Dictionary

Style Dictionary transforms the token JSON into CSS Custom Properties (--ksv-ds-*) and strongly-typed TypeScript constants.

03

Publish to NPM Registry

Packaged and versioned as @svinayaka/siddi-design-system on GitHub Packages with automated CI releases.

04

Consume with Zero JS Overhead

Imported via native CSS @layer tokens, themes;. Theme switching executes via data-ksv-ds-theme without JavaScript runtime recalculations.

Token Architecture (3-Tier Hierarchy)

Tokens are decoupled into three distinct layers of abstraction to ensure scalability, effortless dark-mode switching, and safe component-level overrides.

Layer 1

Primitives

Raw, literal values with zero design context. Includes 15-hue color scales (50-950), 4px spacing scale, font scales, radii, and shadows.

// Raw color & measurement values--ksv-ds-color-indigo-600: #4f46e5;--ksv-ds-space-4: 1rem;
Layer 2

Semantics

System-wide roles and intent. Aliases Layer 1 primitives and automatically swaps values between Light and Dark modes without changing component markup.

// Contextual roles (theme-aware)--ksv-ds-interactive-primary--ksv-ds-bg-surface
Layer 3

Components

Scoped directly to individual component anatomy (Button, Input, Badge, Card). Enables isolated styling overrides without affecting global semantics.

// Scoped component contracts--btn-primary-bg: var(--interactive-primary);--input-border: var(--border-default);

Primitive color scales (Layer 1)

15 hue families, each with an 11-step scale (50–950). Every value is a raw primitive token with zero contextual meaning; components never reference these directly — they are aliased by Layer 2 semantic tokens instead.

neutral
50
100
200
300
400
500
600
700
800
900
950
primary
50
100
200
300
400
500
600
700
800
900
950
accent
50
100
200
300
400
500
600
700
800
900
950
success
50
100
200
300
400
500
600
700
800
900
950
warning
50
100
200
300
400
500
600
700
800
900
950
danger
50
100
200
300
400
500
600
700
800
900
950
info
50
100
200
300
400
500
600
700
800
900
950
slate
50
100
200
300
400
500
600
700
800
900
950
indigo
50
100
200
300
400
500
600
700
800
900
950
cyan
50
100
200
300
400
500
600
700
800
900
950
emerald
50
100
200
300
400
500
600
700
800
900
950
amber
50
100
200
300
400
500
600
700
800
900
950
rose
50
100
200
300
400
500
600
700
800
900
950
sky
50
100
200
300
400
500
600
700
800
900
950
violet
50
100
200
300
400
500
600
700
800
900
950

Semantic colors (Layer 2)

System-wide roles and intent. These tokens alias Layer 1 primitives and automatically swap values between Light and Dark themes without changing component markup.

Background
--ksv-ds-bg-canvas
--ksv-ds-bg-surface
--ksv-ds-bg-surface-elevated
--ksv-ds-bg-surface-sunken
--ksv-ds-bg-subtle
--ksv-ds-bg-muted
Text
--ksv-ds-text-primary
--ksv-ds-text-secondary
--ksv-ds-text-tertiary
--ksv-ds-text-muted
--ksv-ds-text-inverse
--ksv-ds-text-brand
--ksv-ds-text-link
Border
--ksv-ds-border-subtle
--ksv-ds-border-default
--ksv-ds-border-strong
--ksv-ds-border-focus
Interactive
--ksv-ds-interactive-primary
--ksv-ds-interactive-primary-hover
--ksv-ds-interactive-secondary
--ksv-ds-interactive-accent
--ksv-ds-interactive-danger
--ksv-ds-interactive-disabled
Status
--ksv-ds-status-success-bg
--ksv-ds-status-warning-bg
--ksv-ds-status-danger-bg
--ksv-ds-status-info-bg

Component tokens (Layer 3)

Component-scoped tokens isolate styling to a single component's anatomy and states. They map directly to Layer 2 semantic tokens, enabling independent customization without affecting the rest of the design system.

Button

--btn-*
--btn-primary-bg→var(--ksv-ds-interactive-primary)
--btn-hover-bg→var(--ksv-ds-interactive-primary-hover)
--btn-text→var(--ksv-ds-interactive-primary-text)
--btn-radius→var(--ksv-ds-radius-md)

Form Input

--input-*
--input-bg→var(--ksv-ds-bg-surface)
--input-border→var(--ksv-ds-border-default)
--input-focus-border→var(--ksv-ds-border-focus)
--input-radius→var(--ksv-ds-radius-md)

Badge / Tag

--badge-*
• Success• Warning• Danger
--badge-bg→var(--ksv-ds-status-success-bg)
--badge-border→var(--ksv-ds-status-success-border)
--badge-text→var(--ksv-ds-status-success-text)
--badge-radius→var(--ksv-ds-radius-full)

Card Surface

--card-*
Surface ContainerReads elevation & subtle border tokens
--card-bg→var(--ksv-ds-bg-surface-elevated)
--card-border→var(--ksv-ds-border-subtle)
--card-radius→var(--ksv-ds-radius-lg)
--card-shadow→var(--ksv-ds-shadow-sm)

Typography

Font families, a 12-step size scale, 7 weights, 6 line-height ratios, and 6 letter-spacing tokens — all consumed as tokens.

Families
font-sans
The quick brown fox jumps over the lazy dog.
font-display
The quick brown fox jumps over the lazy dog.
font-mono
The quick brown fox jumps over the lazy dog.
font-serif
The quick brown fox jumps over the lazy dog.
Sizes
text-2xs
Design tokens
text-xs
Design tokens
text-sm
Design tokens
text-base
Design tokens
text-lg
Design tokens
text-xl
Design tokens
text-2xl
Design tokens
text-3xl
Design tokens
text-4xl
Design tokens
text-5xl
Design tokens
text-6xl
Design tokens
text-7xl
Design tokens
Weights
font-weight-light
The quick brown fox
font-weight-regular
The quick brown fox
font-weight-medium
The quick brown fox
font-weight-semibold
The quick brown fox
font-weight-bold
The quick brown fox
font-weight-extrabold
The quick brown fox
font-weight-black
The quick brown fox
Leading
leading-none
Line-height is one of the most overlooked typographic decisions. A well-chosen leading ratio makes body text readable at every size.
leading-tight
Line-height is one of the most overlooked typographic decisions. A well-chosen leading ratio makes body text readable at every size.
leading-snug
Line-height is one of the most overlooked typographic decisions. A well-chosen leading ratio makes body text readable at every size.
leading-normal
Line-height is one of the most overlooked typographic decisions. A well-chosen leading ratio makes body text readable at every size.
leading-relaxed
Line-height is one of the most overlooked typographic decisions. A well-chosen leading ratio makes body text readable at every size.
leading-loose
Line-height is one of the most overlooked typographic decisions. A well-chosen leading ratio makes body text readable at every size.
Tracking
tracking-tighter
Letter spacing and optical kerning tokens.
tracking-tight
Letter spacing and optical kerning tokens.
tracking-normal
Letter spacing and optical kerning tokens.
tracking-wide
Letter spacing and optical kerning tokens.
tracking-wider
Letter spacing and optical kerning tokens.
tracking-widest
Letter spacing and optical kerning tokens.

Spacing

A 4px-based scale from 0 to 8rem. Every margin, padding, and gap in the UI is drawn from these tokens — no arbitrary pixel values.

space-0
var(--ksv-ds-space-0)
space-1
var(--ksv-ds-space-1)
space-2
var(--ksv-ds-space-2)
space-3
var(--ksv-ds-space-3)
space-4
var(--ksv-ds-space-4)
space-5
var(--ksv-ds-space-5)
space-6
var(--ksv-ds-space-6)
space-8
var(--ksv-ds-space-8)
space-10
var(--ksv-ds-space-10)
space-12
var(--ksv-ds-space-12)
space-16
var(--ksv-ds-space-16)
space-20
var(--ksv-ds-space-20)
space-24
var(--ksv-ds-space-24)
space-32
var(--ksv-ds-space-32)

Radius

A 9-step radius scale from sharp (0) to fully rounded (9999px). Components pick a radius; you control the overall feel of the UI by changing one token.

radius-none
radius-xs
radius-sm
radius-md
radius-lg
radius-xl
radius-2xl
radius-3xl
radius-full

Elevation

Seven shadow tokens for consistent depth. Together with radius and border color, they define the visual “surface” of every component.

shadow-xs
shadow-sm
shadow-md
shadow-lg
shadow-xl
shadow-2xl
shadow-inner

Motion

Curves and timing tokens that bring physics-based realism to interfaces. Click Play to watch each token shape the animation in real time.

Easing Curves
ease-defaultStandard UI transitions
var(--ksv-ds-ease-default)
ease-inElements exiting view
var(--ksv-ds-ease-in)
ease-outElements entering view
var(--ksv-ds-ease-out)
ease-in-outState toggles & transforms
var(--ksv-ds-ease-in-out)
ease-springPlayful bouncy emphasis
var(--ksv-ds-ease-spring)
Duration Scale
duration-fastMicro-interactions & tooltips (150ms)
var(--ksv-ds-duration-fast)
duration-normalButton states & color shifts (200ms)
var(--ksv-ds-duration-normal)
duration-slowDropdowns & modal overlays (300ms)
var(--ksv-ds-duration-slow)
duration-slowerDrawers & page transitions (500ms)
var(--ksv-ds-duration-slower)

How tokens compose into UI

Everything above is the raw vocabulary. Here's what happens when tokens compose into a real component — colors, spacing, radius, and typography all working together, with a live theme toggle.

Live preview

Token-driven card

This card reads colors, spacing, radius, and typography from --ksv-ds-* tokens. Change a control above and the CSS variables update instantly.

--ksv-ds-interactive-primaryInteractivePrimary (#4f46e5)
--ksv-ds-radius-demoRadiusLg (0.5rem)
data-ksv-ds-themelight

Where this shipped

  • PowerSchool — 60+ Web Components in a shared design system across React and Angular apps.
  • Accessibility — Internal audit raised from 78% to 94% via WCAG 2.1 AA and VPAT evaluations. View Accessibility Capability →