Migration Guide

This guide covers migrating an existing ArtasceOne app to Crystal. The process involves three steps: adding tokens, mapping existing values, and adopting components.

Step 1: Add Crystal Tokens

Install the packages and import the CSS:

pnpm --filter YOUR_APP add @artasce/crystal-tokens@workspace:* @artasce/crystal-ui@workspace:*

app/globals.css

@import '@artasce/crystal-tokens/css';

Set the theme on your root element:

<html data-crystal="diamond" data-crystallization="clean">

Step 2: Map Custom Tokens

Many apps define custom CSS variables. Map them to Crystal equivalents:

Common Mappings

Custom Token	Crystal Equivalent
`--background`, `--bg`	`var(--crystal-bg)`
`--foreground`, `--text-color`	`var(--crystal-text)`
`--card`, `--surface`	`var(--crystal-surface)`
`--border`	`var(--crystal-border)`
`--primary`	`var(--crystal-primary)`
`--accent`, `--highlight`	`var(--crystal-accent)`
`--muted`, `--secondary-bg`	`var(--crystal-bg-subtle)`
`--muted-foreground`	`var(--crystal-text-muted)`

App-Specific Prefixes

Some apps use branded prefixes. Replace them with Crystal tokens:

/* Before (mademoiselle) */
.hero { color: var(--mad-text); background: var(--mad-bg); }

/* After */
.hero { color: var(--crystal-text); background: var(--crystal-bg); }

/* Before (voyavacations) */
.card { border: 1px solid var(--voya-border); }

/* After */
.card { border: 1px solid var(--crystal-border); }

Step 3: Adopt Components

Replace custom card/tile/grid implementations with Crystal components:

Cards

/* Before */
<div className="rounded-lg border bg-white p-4 shadow-sm">
  <h3 className="font-semibold">Title</h3>
  <p className="text-gray-600">Description</p>
</div>

/* After */
import { CrystalCard } from '@artasce/crystal-ui';
<CrystalCard title="Title" description="Description" />

Grids

/* Before */
<div className="grid grid-cols-3 gap-4">
  {items.map(item => <Card key={item.id} {...item} />)}
</div>

/* After */
import { CrystalGrid, CrystalCard } from '@artasce/crystal-ui';
<CrystalGrid columns={3} gap="md">
  {items.map(item => <CrystalCard key={item.id} {...item} />)}
</CrystalGrid>

Surfaces

/* Before */
<div className="bg-gray-50 border rounded-lg p-6">Content</div>

/* After */
import { CrystalTile } from '@artasce/crystal-ui';
<CrystalTile variant="surface" padding="lg">Content</CrystalTile>

Step 4: Remove Old Variables

After migrating, remove the custom token definitions from your CSS. Crystal tokens are now the source of truth.

Search for patterns like:

--YOUR_PREFIX-* custom properties
Hardcoded color values (#09090b, #fafafa, etc.)
Static border-radius values (replace with var(--crystal-radius))
Static box-shadow values (replace with var(--crystal-shadow))

Incremental Migration

You don't need to migrate everything at once. Crystal tokens work alongside existing styles:

Week 1: Add Crystal tokens, set theme, map backgrounds and text colors
Week 2: Replace card and grid components
Week 3: Adopt crystallization variables (radius, shadow, motion)
Week 4: Remove old custom properties, clean up

Brand-Theme Mapping

Each portfolio brand maps to a Crystal theme:

Brand	Theme	Crystallization
OpsCenter	Onyx	Edge
artasce.com	Diamond	Clean
Mademoiselle	Amethyst	Dream
ACModels	Ruby	Bold
VoyaVacations	Citrine	Clean
SyncFocus	Sapphire	Edge
Modolla	Emerald	Clean

Troubleshooting

Tokens not applying

Check that data-crystal is set on the <html> element, not a child:

<!-- Correct -->
<html data-crystal="onyx">

<!-- Wrong (tokens won't cascade) -->
<div data-crystal="onyx">

Crystal themes handle dark mode through theme selection, not prefers-color-scheme. If your app uses class="dark" or data-theme="dark", switch to a dark Crystal theme (onyx, garnet, sapphire, amethyst, ruby, emerald, topaz, obsidian).

Tailwind conflicts

If Tailwind's default theme values conflict with Crystal tokens, ensure Crystal's CSS import comes after Tailwind's base:

@import 'tailwindcss';
/* Crystal must come after Tailwind */
@import '@artasce/crystal-tokens/css';