@strata-ds/core

The runtime component library for Strata — connect your React app to your design system and ship updates live.

@strata-ds/core is a dynamic React component library and stylesheet runtime. It enables teams to consume design tokens and components directly from a centralised Strata design system, ensuring that what designers create is exactly what developers ship — consistently, across platforms, and in real time.

Design once in Strata. Ship everywhere.

Table of Contents

• Why @strata-ds/core?
• Quick Start (< 5 Minutes)
• 5-Minute Integration Checklist
• Project Setup (React)
• Using Design System Components
• Debugging and Troubleshooting
• Customisation and Overrides
• Dynamic Updates (Hot-Reloading)
• Registry API
• Component Factory
• Key Features

Why @strata-ds/core?

The Problem

Design and engineering teams often drift apart:

• Designers update Figma files
• Developers re-implement styles manually
• Components slowly diverge from the original design
• Consistency breaks across products and platforms

This results in duplicate work, inconsistent UI, broken design intent, and slow iteration.

The Solution

@strata-ds/core bridges this gap by acting as:

• A component library
• A stylesheet generator runtime
• A live consumer of design tokens and components

All powered by your Strata project.

Instead of hardcoding styles, components dynamically reference design tokens fetched from the design system. This establishes a single source of truth for design.

Who Is This For?

| Persona | Value | |---------|-------| | Solopreneurs | "I don't need a designer — I can sync from Figma and ship brand-consistent UI myself." | | Frontend Engineers | "Design tokens live in one place. No more manual style updates across 10 repositories." | | Entrepreneurs | "My team ships faster because design changes propagate automatically." | | Designers | "What I create in Strata is exactly what users see — no 'lost in translation' moments." |

Core Principles

1. Separation of Concerns

@strata-ds/core strictly separates:

• Variables (Design Tokens) — Colors, spacing, typography, radii, shadows, etc.
• Components — Buttons, Cards, Forms, Navbars, etc.

Components never own styles directly — they reference tokens.

2. Single Source of Truth

Design tokens live in your Strata project, not inside applications.

• Tokens are defined once
• Components reference them dynamically
• Updates propagate automatically

3. Dynamic & Real-Time Sync

@strata-ds/core can:

• Fetch updated tokens and components from the Strata backend
• Detect changes via checksum
• Rebuild styles automatically
• Fall back to cached data when offline

Architecture Overview

Figma / Style Dictionary
        ↓
Strata Design System
        ↓
Machine-parseable JSON
        ↓
@strata-ds/core Component Library
        ↓
Your React Application

Quick Start (< 5 Minutes)

🚀 New to Strata? Get your first component rendering in 4 steps.

Step 1: Install

npm install @strata-ds/core
# or
yarn add @strata-ds/core

Step 2: Get Your Credentials

Go to strata.charisol.io → Your Project → Publish & Sync tab:

• Copy your Project ID (e.g., abc123def456)
• Copy your Sync Token (starts with pt_live_)

Step 3: Wrap Your App

✅ Recommended: CDN Snapshot Sync (1 request per poll, edge-cached)

"use client"; // Next.js App Router only
import { StrataProvider } from "@strata-ds/core";

export default function RootLayout({
	children,
}: {
	children: React.ReactNode;
}) {
	return (
		<StrataProvider
			syncEnabled={true}
			projectId="YOUR_PROJECT_ID"
			snapshotCdnBase="https://cdn.strata.charisol.io"
			syncToken="pt_live_your_token_here"
			syncInterval={5000}
		>
			{children}
		</StrataProvider>
	);
}

💡 Replace YOUR_PROJECT_ID and pt_live_your_token_here with values from Step 2.

"use client";
import { StrataProvider } from "@strata-ds/core";

export default function RootLayout({
	children,
}: {
	children: React.ReactNode;
}) {
	return (
		<StrataProvider
			syncEnabled={true}
			syncUrl="https://api-production-charisol-design-system-be.aws.charisol.io/v1/project/YOUR_PROJECT_ID/data"
			syncToken="pt_live_your_token_here"
			syncInterval={3000}
		>
			{children}
		</StrataProvider>
	);
}

Why CDN is better:

• ✅ 1 request instead of 3 (faster, cheaper)
• ✅ Edge-cached for global performance
• ✅ Atomic updates (no partial states)

Step 4: Use Your Components

"use client";
import { useComponents } from "@strata-ds/core";

function App() {
	const { Button, Navbar } = useComponents();

	return (
		<>
			{Button && (
				<Button onClick={() => console.log("clicked")}>Click me</Button>
			)}
			{Navbar && <Navbar />}
		</>
	);
}

Not seeing components? → Jump to Debugging and Troubleshooting.

5-Minute Integration Checklist

Use this checklist to verify your setup after following Quick Start above.

Before you start:

• [ ] Created a project at strata.charisol.io
• [ ] Imported your design tokens (Style Dictionary JSON or Figma)
• [ ] Published your project (dashboard shows "✅ Published")

Integration:

• [ ] Installed @strata-ds/core via npm/yarn
• [ ] Copied projectId from dashboard URL or project settings
• [ ] Copied syncToken from Publish & Sync tab (starts with pt_live_)
• [ ] Wrapped app with <StrataProvider> using CDN Snapshot Sync (recommended)
• [ ] Imported @strata-ds/core/dist/styles.css in root layout
• [ ] Rendered first component with useComponents()

Verification:

• [ ] Opened DevTools → Console and saw 🔄 Starting design system sync...
• [ ] Console shows 📊 Components available: ...
• [ ] Component renders on screen with correct styles
• [ ] Added <StrataDebug /> and verified connection status is ✅ Connected

Stuck? → Jump to Debugging and Troubleshooting.

Project Setup (React)

@strata-ds/core works with React 18+, Next.js (App Router or Pages Router), and any standard React setup.

1. Create a new project

npx create-next-app@latest my-strata-app --typescript
cd my-strata-app
npm install @strata-ds/core

2. Integrate the StrataProvider

Wrap your application's root component with StrataProvider. This provider manages the connection to the Strata backend.

| Prop | Type | Description | | :----------------- | :------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | syncEnabled | boolean | If true, the library will fetch and sync tokens/components from the server. | | snapshotCdnBase | string | Recommended. Base CDN URL for snapshot files (e.g. "https://cdn.strata.charisol.io"). When set together with projectId, the provider fetches a single strata.json snapshot per poll cycle instead of 3 API calls. Takes precedence over syncUrl. | | projectId | string | Your Strata project ID (shown in the dashboard URL and project settings). Required when using snapshotCdnBase. | | syncUrl | string | Legacy base sync URL. StrataProvider will append /variables, /components, and /custom to this URL. Ignored when snapshotCdnBase + projectId are provided. | | syncInterval | number | Polling interval in milliseconds to check for design system updates. Default: 3000. | | syncToken | string | Sync token from your project dashboard. When set, all sync requests carry Authorization: Bearer <token>. Required if your project is not fully public. | | initialData | DesignSystemData | Initial design system data to use before the first sync. | | userDesignSystem | DesignSystemData | Override design system data — useful for storybook, testing, or static mode. Takes precedence over initialData. | | onSyncError | (error: { code: number; message: string; source: string }) => void | Callback invoked when a sync cycle fails. code is the HTTP status (0 for non-HTTP errors), message is a human-readable description, and source is "cdn" or "sync". | | onSyncSuccess | (data: DesignSystemData) => void | Callback invoked whenever a sync cycle succeeds with new data. |

// app/layout.tsx (Next.js App Router)
"use client";
import { StrataProvider } from "@strata-ds/core";

export default function RootLayout({
	children,
}: {
	children: React.ReactNode;
}) {
	return (
		<html lang="en">
			<body>
				<StrataProvider
					syncEnabled={true}
					projectId="YOUR_PROJECT_ID"
					snapshotCdnBase="https://cdn.strata.charisol.io"
					syncInterval={5000}
				>
					{children}
				</StrataProvider>
			</body>
		</html>
	);
}

💡 Replace YOUR_PROJECT_ID with the ID from your Strata project dashboard. For private projects, add syncToken="pt_live_your_token_here" (get it from the Publish & Sync tab).

Sync token authentication

If your project has a sync token set in the Strata dashboard, pass it as syncToken. Every polling request will automatically include Authorization: Bearer <token>.

Projects with syncToken set are only readable by clients that present the correct token. This is the recommended way to gate read access to your design system without managing user accounts.

<StrataProvider
	syncEnabled={true}
	projectId="YOUR_PROJECT_ID"
	snapshotCdnBase="https://cdn.strata.charisol.io"
	syncToken="pt_live_your_token_here"
	syncInterval={5000}
>
	{children}
</StrataProvider>

Using Design System Components

@strata-ds/core provides dynamic access to your components defined in Strata.

Accessing Components with useComponents

"use client";
import { useComponents } from "@strata-ds/core";

function AppContent() {
	// Components are named exactly as you defined them in your Strata project
	const { Button, Navbar, Card } = useComponents();

	return (
		<>
			{/* Render conditionally while components are loading */}
			{Button && (
				<Button onClick={() => console.log("clicked")}>Click me</Button>
			)}

			{Card && <Card style={{ padding: "20px" }}>Card content here</Card>}
		</>
	);
}

Accessing Design System Context with useStrata

"use client";
import { useStrata } from "@strata-ds/core";

function StatusBar() {
	const { designSystem, syncStatus, lastSynced } = useStrata();

	return (
		<div>
			<p>Sync status: {syncStatus}</p>
			<p>Last synced: {lastSynced?.toLocaleTimeString() || "Never"}</p>
			<p>Components: {Object.keys(designSystem.components).join(", ")}</p>
		</div>
	);
}

Debugging and Troubleshooting

Quick Debug Panel

Add <StrataDebug /> anywhere inside <StrataProvider> to inspect:

• ✅ Active sync mode (CDN vs Legacy)
• ✅ Connection status
• ✅ Loaded components
• ✅ Sync token presence (never shows the actual token)

"use client";
import { StrataDebug } from "@strata-ds/core";

function App() {
	return (
		<>
			<StrataDebug />
			{/* Your app content */}
		</>
	);
}

The panel automatically displays the relevant fields for the active sync mode:

• CDN mode (snapshotCdnBase + projectId set): shows ✅ CDN Snapshot, Project ID, resolved Snapshot URL, token presence, and sync interval.
• Legacy mode (syncUrl set): shows ⚠️ Legacy (3 requests/poll), Sync URL, token presence, and sync interval.
• Disabled: shows ❌ Disabled.

🔒 The syncToken value is never rendered — the panel only shows ✅ Present or ❌ None.

Common Issues

| Problem | Solution | |---------|----------| | 401 Unauthorized | Your syncToken is invalid or expired. Go to Publish & Sync tab in your Strata project and copy a fresh token. | | 403 Forbidden | Your project has CORS restrictions. Add your domain to allowedOrigins in your Strata project settings. | | Components not rendering | 1. Check projectId matches your dashboard URL2. Verify components exist in your Strata project3. Open DevTools → Console and look for 🔄 Starting design system sync... | | Styles broken / unstyled | You forgot to import CSS! Add to your root layout: import "@strata-ds/core/dist/styles.css"; | | TypeScript errors | Your component names must match exactly (case-sensitive). Check useComponents() return type in DevTools. |

Network Debugging

Open DevTools → Network tab and filter by:

CDN Mode (snapshotCdnBase + projectId set):

• Look for: https://cdn.strata.charisol.io/snapshots/YOUR_PROJECT_ID/strata.json
• Status should be 200 OK or 304 Not Modified
• Response should be a JSON object with variables, components, custom

Legacy Mode (syncUrl set):

• Look for 3 requests:
  • ${syncUrl}/variables → returns {}
  • ${syncUrl}/components → returns {}
  • ${syncUrl}/custom → returns {}
• All should return 200 OK

Console Debugging

Check for these messages:

• ✅ 🔄 Starting design system sync... → Sync is working
• ✅ 📊 Components available: Button, Navbar, Card → Components loaded
• ✅ 🎨 Variables available: colors, spacing, typography → Tokens loaded
• ❌ ❌ Sync failed: 401 → Token issue (see table above)
• ❌ ❌ Sync failed: 403 → CORS issue (see table above)

Programmatic Inspection

"use client";
import { useStrata } from "@strata-ds/core";

function DebugPanel() {
	const { designSystem, syncStatus, lastSynced, projectId, syncEnabled } =
		useStrata();

	return (
		<div style={{ padding: "1rem", background: "#f9fafb", borderRadius: 8 }}>
			<h3>🔍 Strata Debug Info</h3>
			<pre>
				{JSON.stringify(
					{
						syncStatus,
						syncEnabled,
						projectId,
						lastSynced: lastSynced?.toLocaleTimeString() || "Never",
						componentsLoaded: Object.keys(designSystem.components),
						variablesLoaded: Object.keys(designSystem.variables),
					},
					null,
					2,
				)}
			</pre>
		</div>
	);
}

Hooks Reference

| Hook / Property | Description | | :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | | useStrata() | Returns full context: designSystem, syncStatus, lastSynced, syncUrl, snapshotCdnBase, projectId, syncEnabled, forceSync. | | useComponents() | Returns ready-to-use React components by PascalCase name. | | useDynamicComponents() | Returns the raw component registry map. |

Customisation and Overrides

By default, all components are styled based on the latest tokens fetched from your Strata project. This ensures perfect design-to-code fidelity.

Local Overrides

Override any style locally using standard React props:

<Button
	style={{ backgroundColor: "#007bff", color: "white" }}
	className="my-custom-class"
>
	Custom styled button
</Button>

Dynamic Updates (Hot-Reloading)

@strata-ds/core intelligently handles design updates:

1. A designer makes a change in Strata (e.g., updates a colour token or modifies a component).
2. Strata generates a new checksum.
3. Your StrataProvider (via syncInterval) polls the syncUrl.
4. If the checksum has changed, the library fetches new design tokens and component configurations, and your app's components are dynamically restyled — without a page refresh.

Registry API

strataRegistry is the underlying singleton registry that stores all registered components.

import { strataRegistry } from "@strata-ds/core";

// Check if a component is registered
strataRegistry.hasComponent("Button");

// Get a component by name
const ButtonComponent = strataRegistry.getComponent("Button");

Component Factory

StrataComponentFactory creates React components from Strata component definitions.

import { StrataComponentFactory } from "@strata-ds/core";

const MyComponent = StrataComponentFactory.createComponent(
	"MyComponent",
	componentData,
	designSystem,
);

Key Features

• 🔁 Live sync with Strata backend
• 🧠 Token-driven styling
• 🧩 Dynamic component registry
• 🛠 Inline style overrides supported
• 📦 Installable via npm
• 📴 Offline-first fallback
• 🧪 Debug tools included (StrataDebug)

License

MIT © Charisol