Palette Data Model

Palette manages five collections: tokens, components, patterns, standards, and accessibility rules. All entities use nanoid(8) identifiers and support both file-based and Convex storage backends.

DesignToken

A design primitive representing a single value in the design system.

interface DesignToken {
  id: string;                                    // nanoid(8)
  name: string;                                  // Unique name
  category: TokenCategory;                       // Classification
  value: string | { default: string; dark?: string }; // Token value (with optional dark mode)
  cssVariable?: string;                          // CSS custom property name
  tailwindKey?: string;                          // Tailwind config key
  group?: string;                                // Logical group (e.g., "brand", "semantic")
  description?: string;
  tags?: string[];
  created: string;                               // ISO 8601
  updated: string;                               // ISO 8601
}

type TokenCategory =
  | "color" | "typography" | "spacing" | "shadow" | "border"
  | "radius" | "opacity" | "z-index" | "breakpoint" | "motion"
  | "size" | "custom";

Component

A UI component specification with props, variants, and examples.

interface Component {
  id: string;                   // nanoid(8)
  name: string;                 // Unique name
  status: ComponentStatus;      // Lifecycle stage
  category?: string;            // Grouping category
  description?: string;
  props: ComponentProp[];       // Prop definitions
  variants: ComponentVariant[]; // Visual/behavioral variants
  examples: ComponentExample[]; // Usage examples
  tokens?: string[];            // Linked token IDs
  a11y?: string[];              // Linked a11y rule IDs
  tags?: string[];
  created: string;              // ISO 8601
  updated: string;              // ISO 8601
}

type ComponentStatus = "draft" | "review" | "stable" | "deprecated";

interface ComponentProp {
  name: string;
  type: string;          // TypeScript type expression
  required?: boolean;
  default?: string;
  description?: string;
}

interface ComponentVariant {
  name: string;
  description?: string;
}

interface ComponentExample {
  title: string;
  code: string;          // JSX/TSX snippet
  description?: string;
}

Pattern

A reusable UI pattern documenting a problem/solution approach.

interface Pattern {
  id: string;               // nanoid(8)
  name: string;
  category: PatternCategory;
  problem?: string;         // Problem statement
  solution?: string;        // Solution description
  steps?: PatternStep[];    // Step-by-step guide
  components?: string[];    // Linked component IDs
  examples?: string[];
  doList?: string[];        // Best practices
  dontList?: string[];      // Anti-patterns
  tags?: string[];
  created: string;          // ISO 8601
  updated: string;          // ISO 8601
}

type PatternCategory =
  | "navigation" | "forms" | "feedback" | "data-display"
  | "layout" | "auth" | "onboarding" | "error-handling"
  | "search" | "custom";

interface PatternStep {
  order: number;
  title: string;
  description?: string;
}

Standard

A brand or design standard with categorized rules.

interface Standard {
  id: string;               // nanoid(8)
  name: string;
  category: StandardCategory;
  rules: string[];          // List of rules
  doList?: string[];
  dontList?: string[];
  description?: string;
  tags?: string[];
  created: string;          // ISO 8601
  updated: string;          // ISO 8601
}

type StandardCategory =
  | "logo" | "imagery" | "iconography" | "responsive"
  | "color-usage" | "layout-grid" | "motion" | "custom";

A11yRule

An accessibility requirement with WCAG references.

interface A11yRule {
  id: string;               // nanoid(8)
  name: string;
  category: A11yCategory;
  severity: A11ySeverity;
  wcag?: string;            // WCAG criterion reference
  guidance?: string;        // Implementation guidance
  components?: string[];    // Linked component IDs
  tags?: string[];
  created: string;          // ISO 8601
  updated: string;          // ISO 8601
}

type A11yCategory =
  | "aria" | "color-contrast" | "keyboard" | "screen-reader"
  | "focus" | "motion" | "text" | "forms" | "custom";

type A11ySeverity = "must" | "should" | "may";

Storage

File-Based (SHIFT_STORAGE=file)

.palette/
  tokens/<id>.json
  components/<id>.json
  patterns/<id>.json
  standards/<id>.json
  a11y/<id>.json

Convex (SHIFT_STORAGE=convex)

Tables use the palette_ prefix:

Table	Description
palette_tokens	Design token records
palette_components	Component specifications
palette_patterns	UI pattern records
palette_standards	Standard records
palette_a11y	Accessibility rules

Each record includes a sid field (shift ID) that maps to the application-level id.