Skip to main content

SDK: Palette

The Palette client provides methods for managing design tokens, registering components, exporting token bundles, and searching across the design system.

Access it via client.palette.

Tokens​

List design tokens​

const tokens = await client.palette.tokens.list();
// tokens: Token[]

Returns an array of Token objects:

interface Token {
  id: string;
  name: string;
  value: string;
  category: string;
  description?: string;
  createdAt: string;
}

Create a design token​

const token = await client.palette.tokens.create({
  name: "color-primary",
  value: "#2563eb",
  category: "color",
  description: "Primary brand color",
});

Components​

List components​

const components = await client.palette.components.list();
// components: Component[]

Returns an array of Component objects:

interface Component {
  id: string;
  name: string;
  description: string;
  props: ComponentProp[];
  variants: ComponentVariant[];
  createdAt: string;
}

interface ComponentProp {
  name: string;
  type: string;
  required: boolean;
  defaultValue?: string;
}

interface ComponentVariant {
  name: string;
  props: Record<string, string>;
}

Register a component​

const component = await client.palette.components.create({
  name: "CalendarGrid",
  description: "Renders a monthly calendar grid with selectable days",
});

Add a prop to a component​

await client.palette.components.addProp(component.id, {
  name: "selectedDate",
  type: "Date",
  required: false,
  defaultValue: "new Date()",
});

Add a variant to a component​

await client.palette.components.addVariant(component.id, {
  name: "compact",
  props: { size: "sm", showWeekNumbers: "false" },
});

Export​

Export all design tokens in a given format:

// Export as CSS custom properties
const css = await client.palette.export("css");
// :root { --color-primary: #2563eb; --spacing-sm: 0.5rem; ... }

// Export as JSON
const json = await client.palette.export("json");
// { "color-primary": "#2563eb", "spacing-sm": "0.5rem", ... }

Search across token names, component names, and descriptions:

const results = await client.palette.search("calendar");

Full Example​

import { createClient } from "@the-shift/sdk";

const client = createClient({
  gatewayUrl: "https://app.the-shift.dev",
  apiKey: process.env.SHIFT_API_KEY,
});

// Create design tokens
await client.palette.tokens.create({
  name: "color-primary",
  value: "#2563eb",
  category: "color",
});

await client.palette.tokens.create({
  name: "color-surface",
  value: "#f8fafc",
  category: "color",
});

await client.palette.tokens.create({
  name: "spacing-sm",
  value: "0.5rem",
  category: "spacing",
});

await client.palette.tokens.create({
  name: "font-family-sans",
  value: "Inter, system-ui, sans-serif",
  category: "typography",
});

// Register a component with props and variants
const grid = await client.palette.components.create({
  name: "CalendarGrid",
  description: "Monthly calendar grid with selectable days",
});

await client.palette.components.addProp(grid.id, {
  name: "month",
  type: "number",
  required: true,
});

await client.palette.components.addProp(grid.id, {
  name: "year",
  type: "number",
  required: true,
});

await client.palette.components.addVariant(grid.id, {
  name: "compact",
  props: { size: "sm" },
});

// Export tokens
const css = await client.palette.export("css");
console.log(css);

// Search
const results = await client.palette.search("calendar");
console.log(`Found ${results.length} results`);