Namespace model template for style design tokens.

design-token.model.json

{
    "unc": {
        "$description": "The root namespace for the Unified Naming Convention (UNC), providing a single, cohesive system for all frontend assets.",
        "tokens": {
            "$description": "Namespace for all design tokens, which act as the single source of truth for all stylistic properties like colors, spacing, and typography.",
            "primitive": {
                "$description": "Tier 1: These are the foundational, raw values of the design system. They are context-agnostic and named by a scale (e.g., numerical, t-shirt size). They should never be used directly in component styling.",
                "format": "[category]-[property]-[scale]",
                "example": {
                    "color-blue-400": {
                        "$value": "#4299E1"
                    },
                    "size-spacing-100": {
                        "$value": "0.25rem"
                    },
                    "font-weight-700": {
                        "$value": "700"
                    }
                }
            },
            "semantic": {
                "$description": "Tier 2: These alias tokens connect primitive values to a specific, meaningful purpose within the UI. This is the primary API for developers and enables features like theming.",
                "format": "[category].[element].[concept].[variant?].[state?]",
                "example": {
                    "color": {
                        "background": {
                            "action": {
                                "primary": {
                                    "default": {
                                        "$value": "{color-blue-500}"
                                    },
                                    "hover": {
                                        "$value": "{color-blue-600}"
                                    }
                                }
                            }
                        },
                        "text": {
                            "feedback": {
                                "error": {
                                    "$value": "{color-red-500}"
                                }
                            }
                        }
                    },
                    "spacing": {
                        "padding": {
                            "card": {
                                "default": {
                                    "$value": "{size-spacing-400}"
                                }
                            }
                        }
                    }
                }
            },
            "component": {
                "$description": "Tier 3: These tokens provide granular overrides for a single, specific component. They should be used sparingly to handle exceptions where a component must deviate from global semantic rules.",
                "format": "[component-name].[element?].[property].[variant?].[state?]",
                "example": {
                    "button": {
                        "border-radius": {
                            "default": {
                                "$value": "{size-border-radius-200}"
                            }
                        },
                        "background": {
                            "primary": {
                                "hover": {
                                    "$value": "{color-blue-700}"
                                }
                            }
                        }
                    },
                    "card": {
                        "box-shadow": {
                            "raised": {
                                "$value": "{shadow-300}"
                            }
                        }
                    }
                }
            }
        },
        "css": {
            "$description": "Namespace for CSS implementation, which is systematically derived from the design tokens and component architecture.",
            "variable": {
                "$description": "CSS Custom Properties are automatically generated from semantic and component tokens by a build tool. The 'unc-' prefix prevents collisions with third-party libraries.",
                "format": "--unc-[token-path-with-dashes]",
                "examples": [
                    "--unc-color-background-action-primary-default",
                    "--unc-spacing-padding-card-default",
                    "--unc-button-border-radius-default"
                ]
            },
            "class": {
                "$description": "A pragmatic, modern interpretation of BEM, designed for maximum clarity and debuggability in component-based architectures.",
                "block": {
                    "format": "unc-[component-name]",
                    "example": "unc-user-profile"
                },
                "element": {
                    "format": "unc-[component-name]__[element-name]",
                    "example": "unc-user-profile__avatar"
                },
                "modifier": {
                    "format": "...--[modifier-name]",
                    "example": "unc-user-profile--large"
                }
            },
            "state": {
                "$description": "Standalone state classes applied via JavaScript, based on the SMACSS/SUIT convention, to reflect dynamic UI states.",
                "format": "is-[state] or has-[state]",
                "examples": [
                    "is-loading",
                    "is-active",
                    "is-disabled",
                    "has-error"
                ]
            }
        },
        "javascript": {
            "$description": "Namespace for JavaScript, ensuring that component logic, state, and structure align seamlessly with the overall system.",
            "file": {
                "component": {
                    "format": "PascalCase.jsx",
                    "example": "UserProfileCard.jsx"
                },
                "utility": {
                    "format": "kebab-case.js",
                    "example": "date-formatting-helpers.js"
                }
            },
            "component": {
                "format": "PascalCase",
                "example": "UserProfileCard"
            },
            "variable": {
                "format": "camelCase",
                "example": "currentUser"
            },
            "constant": {
                "format": "UPPER_SNAKE_CASE",
                "example": "API_BASE_URL"
            },
            "state": {
                "format": "is[Property] or has[Property]",
                "example": "const [isLoading, setIsLoading] = useState(false);"
            },
            "function": {
                "eventHandler": {
                    "format": "handle[Element][Event]",
                    "example": "handleAvatarClick"
                },
                "utility": {
                    "format": "verb[Noun]",
                    "example": "calculateTotalPrice"
                }
            }
        },
        "i18n": {
            "$description": "Namespace for internationalization keys, structured semantically to mirror the component architecture, providing context and stability.",
            "componentKey": {
                "format": "[componentName].[elementName|context].[description]",
                "example": {
                    "userProfileCard": {
                        "header": {
                            "title": "User Profile"
                        },
                        "actions": {
                            "editLabel": "Edit Profile"
                        }
                    }
                }
            },
            "common": {
                "format": "common.[context].[description]",
                "example": {
                    "common": {
                        "actions": {
                            "save": "Save",
                            "cancel": "Cancel"
                        },
                        "feedback": {
                            "loading": "Loading..."
                        }
                    }
                }
            },
            "glossary": {
                "format": "glossary.[term]",
                "example": {
                    "glossary": {
                        "productName": "The UNC Platform",
                        "featureName": "Tokenization Engine"
                    }
                }
            }
        }
    }
}