Getting Started

Recursica is a token-locked design system built specifically for digital product agencies. By establishing a strict, 1:1 token contract between Figma variables and React code, Recursica guarantees absolute brand fidelity and design consistency across all surfaces of your application.

This guide will walk you through installing the adapter, setting up the provider, and importing components into your project.

1. Install Dependencies

The primary React adapter is @recursica/mantine-adapter, which wraps and binds standard Mantine components to the Recursica tokens. To install it along with its peer dependencies, run the following command in your terminal:

npm install @recursica/mantine-adapter @mantine/core @mantine/hooks @mantine/dates dayjs @emotion/react @emotion/styled

2. Configure Theme and Styles

To apply the design tokens globally, you must import the core Mantine styles, the Recursica adapter stylesheet, and wrap your application in Mantine’s provider.

Add the following configuration to your main entry file (e.g., main.jsx or index.tsx):

import React from 'react';
import { createRoot } from 'react-dom/client';
import { MantineProvider } from '@mantine/core';

// Core Mantine styling
import '@mantine/core/styles.css';

// Recursica design system overrides and token bindings
import '@recursica/mantine-adapter/style.css';

import App from './App';

const container = document.getElementById('root');
const root = createRoot(container);

root.render(
  <MantineProvider defaultColorScheme="light">
    <App />
  </MantineProvider>
);

3. Consume Adapter Components

With the provider configured, you can import and render token-locked components directly from @recursica/mantine-adapter. These components restrict styling properties to the variables allowed by your theme, keeping your layouts perfectly aligned with the design spec.

import React from 'react';
import { Button, TextField, Switch } from '@recursica/mantine-adapter';

export default function ContactForm() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 16, maxWidth: 360 }}>
      <h3>Send a message</h3>
      <TextField 
        label="Email Address" 
        placeholder="hello@agency.com" 
        required 
      />
      <Switch 
        label="Subscribe to updates" 
        defaultChecked 
      />
      <Button 
        variant="solid" 
        onClick={() => alert('Submitted!')}
      >
        Submit
      </Button>
    </div>
  );
}

4. Theme Forge Integration

Recursica is built on customizable token architecture. Designers can modify variables such as brand colors, typeface family, spacing scales, and border radii using the Theme Forge.

To integrate a customized theme:

1. Design your palette and styling tokens in Theme Forge.
2. Export the theme package (.zip or .css).
3. Preview the theme instantly on this documentation site by clicking Import Theme in the top navigation bar and dropping your file.
4. Download the custom variables CSS file and import it into your application root to apply the styling changes project-wide without editing single components.