Design Tokens | Cognivo

Installation

pnpm add @cognivo/tokens

/* Import in CSS */
@import '@cognivo/tokens';

/* Or in JS */
import '@cognivo/tokens/dist/index.css';

Dark Mode

All tokens respond to the data-theme attribute. Light is the default; dark overrides semantic tokens only.

<!-- Light theme (default) -->
<html>

<!-- Dark theme -->
<html data-theme="dark">

<!-- Toggle with JS -->
<script>
  document.documentElement.setAttribute('data-theme', 'dark');
</script>

Token Breakdown

1,800+ tokens organized across 9 categories:

196

AI States

Confidence levels, anomaly severity, thinking animation, insight types.

Borders

Radius (8 steps), width (4 steps), and style tokens.

777

Colors

Action, status, surface, brand, and AI state colors across light and dark themes.

102

Component

Button, input, card, modal, badge, table, and more — per-component sizing.

Elevation

5 shadow levels with light and dark variants.

Font Base

3 font families, 10 sizes, 9 weights, 5 line heights, 6 letter spacings.

Motion

5 durations (0-350ms) and 5 easing curves.

Spacing

17-step scale from 0 to 96px. Base unit: 8px.

162

Typography

6 heading styles, 5 body, 3 label sizes, caption, code, and overline presets.

3-Tier Architecture

Tokens follow a strict hierarchy: Tier 3 → Tier 2 → Tier 1. Always prefer higher-tier tokens.

Tier 1: Core Primitives

~310 tokens

Raw values with no semantic meaning. The building blocks.

--cg-gray-500#737373Gray palette midpoint

--cg-spacing-1616pxBase spacing unit

--cg-font-size-md16pxMedium body text

--cg-border-radius-15012pxMedium radius

--cg-brand-ai-accent#DFFF61Brand lime-yellow

Tier 2: Semantic Tokens

~700+ tokens

Map primitives to UI intent. These are what you use in components.

--cg-color-action-primary-background-defaultLime accentPrimary button fill

--cg-color-status-success-textGreenSuccess state text

--cg-color-surface-container-backgroundDark grayPage background

--cg-typography-heading-h1-fontSize48pxH1 heading size

--cg-ai-confidence-high-colorTealHigh confidence indicator

Tier 3: Component Tokens

~102 tokens

Component-specific sizing and spacing. Used internally by components.

--cg-component-button-height-md40pxMedium button height

--cg-component-input-height-md44pxMedium input height

--cg-component-card-radius12pxCard border radius

--cg-component-modal-radius16pxModal border radius

--cg-component-badge-height-md24pxBadge height

Rule: Never use Tier 1 palette tokens (--cg-gray-*, --cg-red-*) directly in components. Use Tier 2 semantic tokens (--cg-color-action-*, --cg-color-status-*) instead.

Spacing Scale

17-step scale based on 8px grid. Use --cg-spacing-{value}.

--cg-spacing-00px

--cg-spacing-11px

--cg-spacing-22px

--cg-spacing-44px

--cg-spacing-66px

--cg-spacing-88px

--cg-spacing-1212px

--cg-spacing-1616px

--cg-spacing-2020px

--cg-spacing-2424px

--cg-spacing-3232px

--cg-spacing-4040px

--cg-spacing-4848px

--cg-spacing-5656px

--cg-spacing-6464px

--cg-spacing-8080px

--cg-spacing-9696px

Typography

Font Families

--cg-font-family-primaryInterUI text, body copy

--cg-font-family-displaySatoshiHeadings, marketing

--cg-font-family-monoFira CodeCode, data, badges

Size Scale

10 sizes from xs (12px) to 5xl (60px). Use --cg-font-size-{size}.

Typography Presets

Composite tokens for full type styles: --cg-typography-heading-h1-fontSize,--cg-typography-body-large-lineHeight, etc. Covers 6 headings, 5 body, 3 label, caption, code, and overline.

Elevation

5-level shadow system. Automatically adjusts for dark mode.

Level	Token	Shadow	Use
1	`--cg-elevation-1`	0 1px 3px	Cards, inputs
2	`--cg-elevation-2`	0 4px 6px	Hover states, tooltips
3	`--cg-elevation-3`	0 10px 15px	Dropdowns, popovers
4	`--cg-elevation-4`	0 20px 25px	Modals
5	`--cg-elevation-5`	0 25px 50px	Drawers, command palette

Motion

Durations

Token	Value	Use
`--cg-motion-duration-instant`	0ms	Immediate feedback
`--cg-motion-duration-fast`	80ms	Micro-interactions
`--cg-motion-duration-normal`	150ms	Standard transitions
`--cg-motion-duration-slow`	250ms	Complex animations
`--cg-motion-duration-slower`	350ms	Page transitions

Easing Curves

Token	Curve	Use
`--cg-motion-easing-default`	cubic-bezier(0.4, 0, 0.2, 1)	Standard
`--cg-motion-easing-enter`	cubic-bezier(0, 0, 0.2, 1)	Elements appearing
`--cg-motion-easing-exit`	cubic-bezier(0.4, 0, 1, 1)	Elements leaving
`--cg-motion-easing-bounce`	cubic-bezier(0.34, 1.56, 0.64, 1)	Spring/playful
`--cg-motion-easing-color`	cubic-bezier(0, 0, 0.58, 1)	Color/opacity

Advanced Easing (Transition Tokens)

Use --cg-transition-easing-spring for UI feedback (button press, toggle flip),--cg-transition-easing-overshoot for attention-grabbing entrances (badges, toasts, modals),--cg-transition-easing-bounce for tasteful pop animations (accordion expand, popover reveal), and --cg-transition-easing-materialize for content materialization (streaming text, skeleton-to-content swaps).

Token	Curve	Use
`--cg-transition-easing-spring`	cubic-bezier(0.34, 1.56, 0.64, 1)	UI feedback, springy snap
`--cg-transition-easing-overshoot`	cubic-bezier(0.68, -0.55, 0.265, 1.55)	Attention-grabbing entrances
`--cg-transition-easing-bounce`	cubic-bezier(0.16, 1, 0.3, 1)	Tasteful pop animations
`--cg-transition-easing-materialize`	cubic-bezier(0.16, 1, 0.3, 1)	Content materialization

AI State Tokens

196 tokens for AI-specific UI states. Unique to Cognivo.

Confidence Levels

--cg-ai-confidence-high-colorScore ≥ 80% — teal

--cg-ai-confidence-medium-colorScore 50-79% — yellow

--cg-ai-confidence-low-colorScore < 50% — red

Anomaly Detection

4 severity levels (critical, high, medium, low) with glow effects for visual urgency.

Thinking Animation

--cg-ai-thinking-duration1400msFull cycle duration

--cg-ai-thinking-dot-size6-10pxDot indicator size range

Insight Types

4 insight categories with dedicated colors and icons: explanation, forecast, classification, optimization.

Recently Added Tokens

New tokens added in the latest release.

Layout & Breakpoints

--cg-layout-breakpoint-sm640pxSmall screens

--cg-layout-breakpoint-md768pxMedium screens

--cg-layout-breakpoint-lg1024pxLarge screens

--cg-layout-breakpoint-xl1280pxExtra large

--cg-layout-breakpoint-2xl1536pxUltra wide

--cg-layout-grid-columns12Grid column count

--cg-layout-grid-gap-md16pxMedium grid gap

Aspect Ratios

--cg-layout-aspect-ratio-square11:1

--cg-layout-aspect-ratio-video16/9Video standard

--cg-layout-aspect-ratio-card3/2Card preview

--cg-layout-aspect-ratio-portrait3/4Portrait images

--cg-layout-aspect-ratio-ultrawide21/9Ultra wide

Overlays & Focus Shadows

--cg-overlay-white-subtlergba(255,255,255,0.04)Glass/premium effects

--cg-overlay-white-mediumrgba(255,255,255,0.12)Frosted glass

--cg-shadow-focus-error0 0 0 3px rgba(239,68,68,0.2)Error input ring

--cg-shadow-focus-success0 0 0 3px rgba(34,197,94,0.2)Success input ring

--cg-shadow-focus-primary0 0 0 3px rgba(223,255,97,0.2)Primary focus ring

Elevation Shadows

Large Spacing

--cg-spacing-128128pxPage section gaps

--cg-spacing-160160pxLarge section spacing

--cg-spacing-192192pxHero padding

--cg-spacing-256256pxFull section spacing

Usage Example

.my-card {
  background: var(--cg-color-surface-card-background-default);
  border: 1px solid var(--cg-color-surface-card-border);
  border-radius: var(--cg-component-card-radius);
  padding: var(--cg-spacing-24);
  box-shadow: var(--cg-elevation-1);
  transition: box-shadow var(--cg-motion-duration-normal) var(--cg-motion-easing-default);
}

.my-card:hover {
  box-shadow: var(--cg-elevation-2);
}

.confidence-badge {
  background: var(--cg-ai-confidence-high-background);
  color: var(--cg-ai-confidence-high-color);
  font: var(--cg-font-size-xs) var(--cg-font-family-mono);
}

Naming Convention

--cg-[category]-[subcategory]-[property]-[variant]-[state]

Examples:
  --cg-color-action-primary-background-default
  --cg-color-status-success-text
  --cg-typography-heading-h1-fontSize
  --cg-component-button-height-md
  --cg-motion-duration-normal
  --cg-ai-confidence-high-color

Enforcement

The @cognivo/eslint-plugin package ships lint rules that enforce the token system. All rules run at error level after v0.4 — CI fails on any raw hex, rgba, fake token, or fallback in component CSS.

Install

pnpm add -D @cognivo/eslint-plugin

Rules

Rule	Description
`no-raw-hex`	Reject raw hex values (`#fff`) in component CSS — use semantic tokens.
`no-raw-rgba`	Reject raw `rgba()` / `rgb()` literals — use surface and overlay tokens.
`no-transition-all`	Reject `transition: all` — always specify an explicit property list.
`no-fake-tokens`	Reject references to tokens that do not exist in `@cognivo/tokens`.
`no-token-fallbacks`	Reject `var(--cg-x, fallback)` — tokens are guaranteed to resolve.
`cg-token-prefix`	All design tokens authored by Cognivo must use the `--cg-` prefix.

Enable in eslint.config.js

import cognivo from '@cognivo/eslint-plugin';

export default [
  cognivo.configs.recommended,
  // ...rest of your config
];

Note: All rules are error level after v0.4. CI fails on any raw hex, rgba, fake token, or fallback in component CSS.