Data Model and Database

Data Model & Database

Architecture Overview

Unity-Theme uses a singleton + event-driven architecture. The Theme class is a partial class singleton that manages the color palette and notifies binders when colors or themes change.

Data Hierarchy

Theme (singleton)
├── colors: List<ColorDataRef>          ← Named color slots (GUID + name)
│   ├── ColorDataRef { guid, name: "Primary" }
│   ├── ColorDataRef { guid, name: "Secondary" }
│   └── ...
├── themes: List<ThemeData>             ← Named themes, each with color values
│   ├── ThemeData "Light"
│   │   ├── ColorData { guid, colorHex: "#6750A4FF" }  ← matches "Primary"
│   │   ├── ColorData { guid, colorHex: "#625A71FF" }  ← matches "Secondary"
│   │   └── ...
│   └── ThemeData "Dark"
│       ├── ColorData { guid, colorHex: "#D0BCFFFF" }  ← matches "Primary"
│       ├── ColorData { guid, colorHex: "#CCBCE8FF" }  ← matches "Secondary"
│       └── ...
├── currentThemeIndex: int
└── debugLevel: DebugLevel

GUID-Based Binding

Colors are referenced by GUID, not by name. This means:

• Renaming a color does not break any binder references
• Binders store a colorGuid string that maps to a ColorDataRef
• Each theme has a ColorData entry with the same GUID but potentially different hex values
• GUIDs are generated automatically when colors are added

This is a key design decision — it allows you to freely rename colors in the editor without worrying about broken references across your scenes and prefabs.

Database File

The theme database is stored as JSON at:

Assets/Resources/Unity-Theme-Database.json

This file is loaded at runtime via Resources.Load. It should be committed to version control.

Database Structure

{
    "debugLevel": 1,
    "currentThemeIndex": 1,
    "colors": [
        { "guid": "c1a53828-...", "name": "Primary" },
        { "guid": "9e099043-...", "name": "Primary Text" },
        { "guid": "d56cc8cb-...", "name": "Primary Container" }
    ],
    "themes": [
        {
            "guid": "a1aa6e11-...",
            "expanded": true,
            "themeName": "Light",
            "colors": [
                { "guid": "c1a53828-...", "colorHex": "#6750A4FF" },
                { "guid": "9e099043-...", "colorHex": "#FFFFFFFF" },
                { "guid": "d56cc8cb-...", "colorHex": "#EADBFFFF" }
            ]
        },
        {
            "guid": "828eccfe-...",
            "expanded": false,
            "themeName": "Dark",
            "colors": [
                { "guid": "c1a53828-...", "colorHex": "#D0BCFFFF" },
                { "guid": "9e099043-...", "colorHex": "#381E72FF" },
                { "guid": "d56cc8cb-...", "colorHex": "#4F378BFF" }
            ]
        }
    ]
}

Field Reference

Field	Type	Description
debugLevel	int	Logging verbosity (see Debug Levels)
currentThemeIndex	int	Index of the active theme in the themes array
colors	array	Color reference list — each entry has guid and name
themes	array	Theme list — each has guid, themeName, expanded, and colors
themes[].colors	array	Per-theme color values — each has guid (matching a color ref) and colorHex

Color Hex Format

Colors are stored as 8-character hex strings with alpha: #RRGGBBAA (e.g., #6750A4FF).

Default Database

The included default database contains 23 Material Design 3 colors across Light and Dark themes:

Color Name	Light	Dark
Primary	#6750A4	#D0BCFF
Primary Text	#FFFFFF	#381E72
Primary Container	#EADBFF	#4F378B
Primary Container Text	#21005D	#EADBFF
Secondary	#625A71	#CCBCE8
Secondary Text	#FFFFFF	#332D41
Secondary Container	#E8DEF8	#4A4458
Secondary Container Text	#1D192B	#E8DEF8
Tertiary	#7D5260	#EFBCD1
Tertiary Text	#FFFFFF	#492539
Tertiary Container	#FFD8E4	#633740
Tertiary Container Text	#31061D	#FFD8E4
Error	#B5251D	#F2B8B5
Error Text	#FFFFFF	#602319
Error Container	#F9DDDC	#8C1D18
Error Container Text	#410E0B	#F9DDDC
Background	#FFF9FC	#1C1B1F
Background Text	#1C1B1F	#E6E1E5
Surface	#FFF9FC	#1C1B1F
Surface Text	#1C1B1F	#E6E1E5
Outline	#79747E	#938F99
Surface-Variant	#E7E1EC	#49454F
Surface-Variant Text	#49454F	#CAC4D0

Save Mechanism

The database is saved automatically in the Unity Editor when changes are made through the editor window. At runtime, the database is read-only — changes made via the C# API persist only for the session.

See Also

• C# API Reference — Programmatic access to the data model
• Migration from v2 — Migrating from the old .asset format