Prisma

Style Scaling

Reference for Style Scaling

Style Scaling - Multi-Client Design System

Skill for scaling the DS across different styles/brands for multiple clients. The system separates concerns along 3 independent axes that can be freely combined.

How to Use This Skill

This skill is organized in 3 layers:

  1. This file (SKILL.md) - Architecture overview, axis system, presets, anti-patterns. Read this first.
  2. references/ - Deep-dive templates, contracts, and workflows. Read only what's relevant.
  3. Automated scripts - Run sync/validate commands listed below.

Quick navigation:

1. Design Intent Extraction (FIRST STEP)

Full tables + output template: references/design-intent-extraction.md

Before touching any token files, ALWAYS extract the design intent from the input (PDR, image, text). Separate into 3-axis decisions by reading visual cues:

Axis What to Extract Examples
Brand Dominant color, secondary, neutral base #003087 navy palette, zinc neutral
Density Spacing tightness, radius scale "Dashboard" compact, "Landing page" spacious
Visual Shadow depth, effects, decoration "Glass blur" liquid, "Flat" no shadow

Output format - Every scaling task MUST start with:

text
DESIGN INTENT EXTRACTION:
- Client/Project : _______________
- Brand color    : #XXXXXX palette candidate: {color-name}
- Density axis   : comfortable | compact | default | custom
- Visual axis    : default | glass/liquid | minimal | custom(___)
- Brand exists?  : YES (use themes/{existing}) | NO (create new)
- Style-mode?    : [preset name] | need to create new

2. Architecture - 3 Independent Axes

text
+------------------------------------------------------+
|                   Style System                       |
|                                                      |
|   BRAND (Axis 1)      DENSITY (Axis 2)    VISUAL     |
|   +----------+        +-----------+      (Axis 3)   |
|   | prisma   |        |comfortable|      +--------+  |
|   | aurora   |   x    | compact   |  x   |default |  |
|   | client-X |        | default   |      |glass   |  |
|   +----------+        +-----------+      |minimal |  |
|                                          +--------+  |
|                                                      |
|                                                      |
|   themes/*.json       style-modes/*.json    styles/  |
|                                         + config     |
+------------------------------------------------------+

These axes are orthogonal - mix freely:

  • Prisma brand + compact density + glass visual
  • Aurora brand + spacious density + minimal visual
  • Custom brand + default density + default visual

Why Scaling Is Automatic

Components reference indirection tokens, not primitives directly:

text
button.radius     {comp-radius}             style-mode decides
card.radius       {group-radius-default}    style-mode decides
button.color.bg   {base.primary}            theme decides
card.color.bg     {base.card}               theme decides

When adding a new client, all 36+ components automatically receive the new brand colors + density. No component token edits needed.

3. Pipeline and showcase-config

Full config schema + validation commands: references/pipeline-config.md

Key Concepts

  • sync-tokens.js --core generates design-system/tokens/variables.css (defaults)
  • sync-tokens.js {showcase-name} generates showcase/{name}/variables.css (defaults + overrides)
  • sync-tokens.js --all syncs all showcases
  • styleFallbacks in showcase-config.json inject at end of CSS blocks, override defaults
  • brandFallbacks override by brand (prisma, aurora, etc.)

Critical Rules

Rule Why
NEVER edit showcase/*/variables.css directly Pipeline will overwrite on next sync
All visual overrides go through styleFallbacks Single source of truth for overrides
Always run sync-tokens.js after config changes Config changes don't apply until sync

Quick Commands

bash
## Full pipeline after changes
node design-system/scripts/pipeline/run-pipeline.js --all

## Sync specific showcase only
node design-system/scripts/pipeline/sync-tokens.js {showcase-name}

## Validate single showcase CSS
node design-system/scripts/pipeline/lint-css.js showcase/{showcase-name}/style.css

## Check for undefined variables (expect: 0)
grep -c "undefined" showcase/{showcase-name}/variables.css

4. Style Mode Presets

Preset comp-radius group-radius section-radius Use case
default md (8px) lg (12px) xl (16px) Baseline - all modes scale from here
compact default (4px) md (8px) lg (12px) Dense data, dashboards (-1 step)
comfortable lg (12px) xl (16px) 2xl (24px) Consumer apps, forms (+1 step)

When client requests a density that ALREADY HAS a preset, use the preset. DO NOT create a new file.

Available Themes

Theme File Primary Color
Prisma themes/prisma.tokens.json prisma-blue
Aurora themes/aurora.tokens.json prisma-red

Available Visual Styles

Style File Effect
Liquid styles/liquid.json Glass/frosted/transparent effects

5. Adding a New Client - Overview

Full step-by-step with templates: references/client-onboarding.md

High-Level Flow

text
1. Extract design intent (section 1)
2. Add color palette to primitives (if needed - ASK User first!)
3. Create themes/{client}.tokens.json (copy aurora.tokens.json, replace refs)
4. Choose/create style-mode (check presets in section 4 first)
5. Add entry to showcase-config.json
6. Create showcase folder from template
7. Sync tokens, validate, verify in browser

Key Contracts

Contract Keys Reference
Theme JSON ~87 keys (59 base + 10 state-layer + 18 alpha) client-onboarding.md section 2
Style Mode JSON 22 keys exactly (8 section + 8 group + 6 comp) client-onboarding.md section 3
Color Palette 11 shades + 4 alpha variants client-onboarding.md section 1

6. Anti-patterns

Don't Do
Edit showcase/*/variables.css manually Use sync-tokens.js to generate variables.css
Copy theme file and edit inline randomly Copy then batch find/replace refs systematically
Create style-mode with keys missing/extra Match 22-key contract exactly
Hardcode brand color in showcase-config.json Use var(--color-{brand}-*)
Create showcase folder without config entry Always add to showcase-config.json first
Bypass pipeline for "quick test" Even tests go through pipeline
Add palette primitive without alpha variants Always add: 500-12, 500-24, 500-50, 400-24
Use CSS calc() for radius DS uses discrete tokens: md, lg, xl
Skip Design Intent Extraction ALWAYS start with section 1 - extract 3-axis decisions first

Reference Files

File Contents Read when...
design-intent-extraction.md 3-axis cue tables, output template, decision trees, client brief Receiving PDR/image/description, starting any scaling task
client-onboarding.md Palette template, theme contract, style-mode contract, scaffold checklist Creating new brand, theme, or style-mode
pipeline-config.md Config schema, styleFallbacks, validation commands, token flow diagrams Configuring showcase, debugging pipeline, understanding token flow
© 2026 VNPay JSC · Mar 16, 2026