Quick Start

This guide gets Crystal working in a Next.js app. For other frameworks, see the concepts below and adapt accordingly.

1. Import Crystal Tokens

Add Crystal's CSS to your root layout or global stylesheet:

app/globals.css

@import 'tailwindcss';

/* Crystal tokens define all theme variables */
@import '@artasce/crystal-tokens/css';

Alternatively, define theme tokens inline in your CSS (see the Colors page for all token values).

2. Set a Theme

Add the data-crystal attribute to your <html> element:

app/layout.tsx

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" data-crystal="diamond">
      <body>{children}</body>
    </html>
  );
}

Available themes: diamond, onyx, garnet, sapphire, amethyst, citrine, ruby, emerald, opal, quartz, topaz, obsidian.

3. Set a Crystallization (Optional)

Crystallizations control shape personality (radius, shadow, motion):

<html lang="en" data-crystal="sapphire" data-crystallization="edge">

Available: clean (default), dream, edge, luxe, bold.

4. Use Components

app/page.tsx

import { CrystalTile, CrystalCard, CrystalGrid } from '@artasce/crystal-ui';

export default function Page() {
  return (
    <CrystalGrid columns={3} gap="md">
      <CrystalCard
        title="Foundations"
        description="Colors, spacing, typography"
        href="/docs/foundations/colors"
      />
      <CrystalCard
        title="Components"
        description="60+ themed React components"
        href="/docs/components"
      />
      <CrystalCard
        title="Themes"
        description="8 gemstone-inspired palettes"
        href="/docs/foundations/colors"
      />
    </CrystalGrid>
  );
}

5. Use Tokens in CSS

Crystal tokens work as standard CSS custom properties:

.hero {
  background: var(--crystal-bg);
  color: var(--crystal-text);
  padding: var(--spacing-6) var(--spacing-4);
  border-radius: var(--crystal-radius);
}

.hero h1 {
  color: var(--crystal-primary);
}

.hero .accent {
  color: var(--crystal-accent);
}

6. Use Tokens in Tailwind

Crystal's spacing scale maps to Tailwind utilities:

<div class="p-4 gap-2 bg-[var(--crystal-surface)] text-[var(--crystal-text)]">
  <h2 class="text-[var(--crystal-primary)]">Title</h2>
  <p class="text-[var(--crystal-text-secondary)]">Description</p>
</div>

Core Concepts

Dual-Axis System

Crystal has two independent axes:

Theme (Axis 1) — Color palette. Set via data-crystal attribute.
Crystallization (Axis 2) — Shape personality. Set via data-crystallization attribute.

These combine freely: any theme works with any crystallization, giving you 13 themes x 5 crystallizations = 65 visual combinations.

Semantic Tokens

Never use raw hex values. Crystal tokens are semantic — they describe function, not appearance:

Do	Don't
`var(--crystal-text)`	`#09090b`
`var(--crystal-surface)`	`#ffffff`
`var(--crystal-accent)`	`#06b6d4`

This ensures your UI adapts automatically when themes change.

Fibonacci Spacing

Crystal uses a Fibonacci-inspired spacing scale instead of linear increments:

0 → 4 → 8 → 16 → 24 → 40 → 64 → 104 → 168 → 272

Use var(--spacing-N) in CSS or Tailwind spacing utilities (p-3 = 16px, gap-5 = 40px).

On this page