> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fskin.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Skins

> Skins define your app's color scheme. Publish one from the dashboard and every connected Flutter app updates instantly — no restart required.

A **skin** is a named set of color tokens that maps to Flutter's `ColorScheme`. When you publish a skin, the FSkin backend pushes the change to all connected app instances via SSE. Apps update in real time — no restart, no re-fetch, no App Store release.

## Creating a Skin

<Steps>
  <Step title="Open your project">
    Navigate to **Projects**, select the project you want to add a skin to, then click **+ Create Skin**.
  </Step>

  <Step title="Name your skin">
    Give the skin a descriptive name — for example `default`, `dark_pro`, or `summer_2026`.
  </Step>

  <Step title="Configure the colors">
    Fill in the color tokens using hex values. FSkin follows the Material color scheme structure:

    | Token          | Description                   |
    | -------------- | ----------------------------- |
    | `primary`      | Main brand color              |
    | `secondary`    | Accent / secondary color      |
    | `background`   | Page background               |
    | `surface`      | Card and container background |
    | `error`        | Error state color             |
    | `onPrimary`    | Text and icons on primary     |
    | `onSecondary`  | Text and icons on secondary   |
    | `onBackground` | Text and icons on background  |
    | `onSurface`    | Text and icons on surface     |
    | `onError`      | Text and icons on error       |
    | `brightness`   | `light` or `dark`             |
  </Step>

  <Step title="Save the skin">
    Click **Save**. The skin is saved as a draft and won't affect your app until you publish it.
  </Step>
</Steps>

<Tip>
  Use the **Clone** action on any existing skin to create a variant without starting from scratch. Useful for creating a dark version of your default skin.
</Tip>

## Publishing a Skin

Publishing makes a skin the **active** skin for the project and immediately pushes the update to all connected Flutter apps.

1. Open the project where the skin is saved and click **Publish** next to the project name.
2. Review the color tokens
3. Click **Publish**
4. Confirm the dialog

<Warning>
  Only one skin can be active per project at a time. Publishing a new skin automatically deactivates the previously active one.
</Warning>

### What happens when you publish

```
You click Publish
        ↓
Skin is marked active in the database
        ↓
FSkin backend detects the change via Supabase Realtime
        ↓
Backend broadcasts SSE event to all connected Flutter apps
        ↓
flutter_skin re-fetches the active skin
        ↓
App re-renders with new colors — no restart needed
```

<Note>
  The update reaches connected apps in approximately **1–2 seconds** after you click Publish. Apps that are backgrounded or closed will receive the new skin on next launch via the normal fetch.
</Note>

## Skin JSON Format

Under the hood, FSkin serves skins as a JSON file. This is what the backend delivers to the Flutter package:

```json theme={null}
{
  "name": "default",
  "version": 1,
  "colors": {
    "primary": "#6C63FF",
    "secondary": "#FF6584",
    "background": "#FFFFFF",
    "surface": "#F9F9FB",
    "error": "#EF4444",
    "onPrimary": "#FFFFFF",
    "onSecondary": "#000000",
    "onBackground": "#0D0D0D",
    "onSurface": "#1C1B1F",
    "onError": "#FFFFFF",
    "brightness": "light"
  }
}
```

<Note>
  The current alpha supports **color tokens only**. Typography, spacing, border radii, elevation, and animation tokens are planned for upcoming releases.
</Note>