---
name: turatheme
version: 1.0.0
description: UI theme library API. Browse pre-built themes, customize colors and fonts, export as CSS variables, Tailwind config, or JSON tokens.
homepage: https://www.turatheme.com
metadata: {"category":"design","api_base":"https://www.turatheme.com/api/v1"}
---

# TuraTheme

**UI theme library via API.**

Browse production-ready themes, customize them visually, and export as CSS variables, Tailwind config, or JSON design tokens. Pairs with TuraVibe for palette generation. Part of Tura Cloud. Authentication uses TuraLogin API keys (Bearer token).

## Skill Files

| File | URL |
|------|-----|
| **SKILL.md** (this file) | `https://www.turatheme.com/SKILL.md` |
| **AGENTS.md** | `https://www.turatheme.com/AGENTS.md` |
| **API.md** | `https://www.turatheme.com/API.md` |
| **QUICKSTART.md** | `https://www.turatheme.com/QUICKSTART.md` |
| **skill.json** (metadata) | `https://www.turatheme.com/skill.json` |

**Base URL:** `https://www.turatheme.com/api/v1`

**Authentication:** `Authorization: Bearer <API_KEY>` — Use TuraLogin API keys from https://www.turalogin.com/dashboard/keys

---

## Overview

TuraTheme is a theme library and export API:

✅ **Theme library** — Dozens of pre-built themes for SaaS, marketing, editorial, and e-commerce  
✅ **Customization** — Override primary color, font, border-radius, and spacing  
✅ **CSS export** — Get `:root` CSS variable block for any theme  
✅ **Tailwind export** — Get `theme.extend` config object  
✅ **Design tokens** — JSON tokens for Figma, Style Dictionary, or any token pipeline  

You handle:
- Injecting the exported CSS/config into your app
- UI component library wiring
- User-facing theme switching

---

## Quick Start

### 1. Get Your API Key

TuraTheme uses **TuraLogin API keys**. Get one at https://www.turalogin.com/dashboard/keys

- Test: `tl_test_xxxxxxxxxxxxxxxx`
- Production: `tl_live_xxxxxxxxxxxxxxxx`

### 2. Browse Themes

```bash
curl "https://www.turatheme.com/api/v1/theme/themes?category=saas&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**
```json
{
  "themes": [
    {
      "id": "theme_abc123",
      "name": "Midnight Pro",
      "category": "saas",
      "primary": "#6366f1",
      "font": "Inter",
      "preview": "https://cdn.turatheme.com/previews/midnight-pro.png"
    }
  ],
  "hasMore": true
}
```

### 3. Export as CSS Variables

```bash
curl "https://www.turatheme.com/api/v1/theme/themes/theme_abc123/css" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:** CSS text you can inject into a `<style>` tag or stylesheet.

```css
:root {
  --color-primary: #6366f1;
  --color-primary-foreground: #ffffff;
  --color-background: #0f0f12;
  --color-foreground: #f8f8f8;
  --font-sans: 'Inter', sans-serif;
  --radius: 0.5rem;
}
```

---

## Full API Reference

### GET /api/v1/theme/themes

Browse available themes.

**Query Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `category` | string | `saas`, `marketing`, `editorial`, `ecommerce`, `minimal` |
| `dark` | boolean | Filter by dark/light mode themes |
| `limit` | number | Max results (default: 20, max: 50) |
| `cursor` | string | Pagination cursor |

---

### GET /api/v1/theme/themes/:id

Get a theme's full configuration.

**Success Response (200):**
```json
{
  "id": "theme_abc123",
  "name": "Midnight Pro",
  "category": "saas",
  "colors": {
    "primary": "#6366f1",
    "secondary": "#f59e0b",
    "background": "#0f0f12",
    "foreground": "#f8f8f8",
    "muted": "#1f1f2e",
    "accent": "#8b5cf6"
  },
  "font": { "sans": "Inter", "mono": "JetBrains Mono" },
  "radius": "0.5rem",
  "mode": "dark"
}
```

---

### GET /api/v1/theme/themes/:id/css

Export theme as CSS `:root` variables.

**Query Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `overrides` | JSON string | Override specific tokens before export |

**Response:** `text/css` — drop directly into a stylesheet.

---

### GET /api/v1/theme/themes/:id/tailwind

Export theme as Tailwind `theme.extend` config.

**Response:** `application/json`

```json
{
  "colors": {
    "primary": { "DEFAULT": "#6366f1", "foreground": "#ffffff" },
    "secondary": { "DEFAULT": "#f59e0b" },
    "background": "#0f0f12",
    "foreground": "#f8f8f8"
  },
  "fontFamily": {
    "sans": ["Inter", "sans-serif"],
    "mono": ["JetBrains Mono", "monospace"]
  },
  "borderRadius": { "DEFAULT": "0.5rem" }
}
```

---

### GET /api/v1/theme/themes/:id/tokens

Export theme as JSON design tokens (W3C format).

---

### POST /api/v1/theme/custom

Create a custom theme from scratch.

**Request Body:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Theme name |
| `primary` | string | Yes | Primary color hex |
| `secondary` | string | No | Secondary color hex |
| `background` | string | No | Background color hex |
| `font` | string | No | Font family name |
| `radius` | string | No | Border radius (e.g. `0.5rem`) |
| `mode` | string | No | `light` or `dark` |

---

## Framework Examples

### Next.js — Inject CSS at Build Time

```typescript
// lib/theme.ts
export async function getThemeCSS(themeId: string): Promise<string> {
  const res = await fetch(
    `https://www.turatheme.com/api/v1/theme/themes/${themeId}/css`,
    { headers: { 'Authorization': `Bearer ${process.env.TURATHEME_API_KEY}` } }
  );
  return res.text();
}
```

```typescript
// app/layout.tsx
import { getThemeCSS } from '@/lib/theme';

export default async function RootLayout({ children }) {
  const css = await getThemeCSS('theme_abc123');

  return (
    <html>
      <head>
        <style dangerouslySetInnerHTML={{ __html: css }} />
      </head>
      <body>{children}</body>
    </html>
  );
}
```

### Next.js — Tailwind Config

```typescript
// scripts/sync-theme.ts
// Run during build to sync theme into tailwind.config.ts
const res = await fetch(
  'https://www.turatheme.com/api/v1/theme/themes/theme_abc123/tailwind',
  { headers: { 'Authorization': `Bearer ${process.env.TURATHEME_API_KEY}` } }
);
const extend = await res.json();
// Write to tailwind.config.ts or merge inline
```

---

## Error Codes

| Status | Error | Description |
|--------|-------|-------------|
| 400 | `primary is required` | Missing primary color |
| 400 | `Invalid color format` | Hex color required |
| 401 | `Unauthorized` | Missing or invalid API key |
| 404 | `Theme not found` | Invalid theme ID |
| 429 | `Too many requests` | Rate limit exceeded |

---

## Support & Resources

- 🌐 Website: https://www.turatheme.com
- 🔑 API Keys: https://www.turalogin.com/dashboard/keys