Project Arceus

Design System Change Propagation

CircuitDS uses a sophisticated token system to ensure changes propagate automatically across all components. This system reduces manual updates and maintains consistency throughout the application.

Token Hierarchy

The three-layer token hierarchy ensures changes cascade properly through the system.

1. Primitive Tokens

--eva-dark-teal: #1a4a47;

2. Semantic Tokens

--background: var(--eva-dark-teal);

3. Component Styles

background-color: var(--background);

/* 1. Primitive Tokens */
--eva-dark-teal: #1a4a47;
--sds-size-space-400: 16px;

/* 2. Semantic Tokens */
--background: var(--eva-dark-teal);
--surface-background: var(--eva-mid-teal);

/* 3. Component Styles */
.component {
  background-color: var(--background);
  padding: var(--sds-size-space-400);
}

Automatic Change Propagation

When a design token is updated, the change automatically propagates through the system. Here's how it works:

Change Propagation Example

Example of how changing a primitive token affects the entire system.

1. Update primitive token:

--eva-dark-teal: #2c5c58;

2. Semantic tokens update automatically:

--background: var(--eva-dark-teal) → #2c5c58

3. Components reflect changes:

All components using --background are updated

/* Before Update */
--eva-dark-teal: #1a4a47;
--background: var(--eva-dark-teal);
.component { background-color: var(--background); }

/* After Update */
--eva-dark-teal: #2c5c58;
--background: var(--eva-dark-teal); /* Auto-updates */
.component { background-color: var(--background); } /* Reflects new color */

Best Practices

Token Usage Guidelines

Follow these practices to ensure changes propagate correctly.

/* ✅ DO: Use semantic tokens in components */
.component {
  color: var(--text-primary);
  background: var(--surface-background);
}

/* ❌ DON'T: Use primitive tokens directly */
.component {
  color: var(--eva-light-yellow);
  background: var(--eva-dark-teal);
}

/* ✅ DO: Create new semantic tokens for specific use cases */
:root {
  --custom-component-background: var(--surface-background);
}

/* ✅ DO: Use spacing tokens for consistent layout */
.component {
  padding: var(--sds-size-space-400);
  gap: var(--sds-size-space-200);
}