Overview
Framework-agnostic UI specification format for design systems
Introduction
Coral is a specification format for describing UI components in a framework-agnostic way. Define your component structure, styling, variants, interactivity, and responsive behavior in a portable JSON format that can be transformed into various output formats.
Why Coral?
- Framework Agnostic - Define once, generate for React, Vue, HTML, or any framework
- Design System Ready - Built-in support for variants, tokens, and composition
- Type Safe - Full TypeScript support with Zod validation
- Tool Friendly - JSON format works with any tool or language
Key Features
Component Variants
CVA-style variant definitions with per-node style responses:
{
"componentVariants": {
"axes": [
{ "name": "intent", "values": ["primary", "secondary"], "default": "primary" },
{ "name": "size", "values": ["sm", "md", "lg"], "default": "md" }
]
},
"variantStyles": {
"intent": {
"primary": { "backgroundColor": "#007bff" },
"secondary": { "backgroundColor": "#6c757d" }
}
}
}Package System
Organize your design system with coral.config.json:
coral init my-design-system
coral add component Button
coral validate
coral build --target typesComponent Composition
Embed components within components:
{
"type": "COMPONENT_INSTANCE",
"$component": { "ref": "./button/button.coral.json" },
"propBindings": { "intent": "primary" }
}Typed Props & Events
Full type definitions for component APIs:
{
"props": {
"label": { "type": "string", "required": true },
"disabled": { "type": "boolean", "default": false }
},
"events": {
"onClick": { "parameters": [{ "name": "event", "type": "React.MouseEvent" }] }
}
}Quick Start
Getting Started
Learn how to use Coral Libraries in your project
Component Variants
Create flexible, multi-variant components
Component Composition
Embed components within components
Package System
Organize and distribute design systems
Packages
| Package | Description | Documentation |
|---|---|---|
| @reallygoodwork/coral-core | Core types, schemas, CLI, and utilities | Core Package Docs |
| @reallygoodwork/coral-to-react | Generate React components from Coral specs | Coral to React Docs |
| @reallygoodwork/coral-to-html | Generate HTML from Coral specs | Coral to HTML Docs |
| @reallygoodwork/react-to-coral | Parse React components to Coral specs | React to Coral Docs |
| @reallygoodwork/coral-tw2css | Convert Tailwind classes to CSS | Tailwind to CSS Docs |
| @reallygoodwork/style-to-tailwind | Convert CSS styles to Tailwind classes | Style to Tailwind Docs |
Example
Here's a complete button component with variants, props, and events:
{
"$schema": "https://coral.design/schema.json",
"name": "Button",
"elementType": "button",
"$meta": {
"name": "Button",
"version": "1.0.0",
"status": "stable"
},
"componentVariants": {
"axes": [
{ "name": "intent", "values": ["primary", "secondary", "destructive"], "default": "primary" },
{ "name": "size", "values": ["sm", "md", "lg"], "default": "md" }
]
},
"props": {
"label": { "type": "string", "required": true }
},
"events": {
"onClick": { "description": "Button click handler" }
},
"styles": {
"display": "inline-flex",
"borderRadius": "6px",
"fontWeight": "500"
},
"variantStyles": {
"intent": {
"primary": { "backgroundColor": "#007bff", "color": "#fff" },
"secondary": { "backgroundColor": "#6c757d", "color": "#fff" },
"destructive": { "backgroundColor": "#dc3545", "color": "#fff" }
},
"size": {
"sm": { "padding": "4px 8px", "fontSize": "12px" },
"md": { "padding": "8px 16px", "fontSize": "14px" },
"lg": { "padding": "12px 24px", "fontSize": "16px" }
}
},
"textContent": { "$prop": "label" }
}Documentation Structure
Coral documentation is organized into two main sections:
Concept Guides (/docs/guides/)
In-depth explanations of core concepts with examples:
- Getting Started - Installation, quick examples, and workflow
- Component Variants - Creating flexible, multi-variant components
- Component Composition - Embedding components within components
- Props & Events - Defining typed component APIs
- Package System - Organizing and distributing design systems
- LLM Usage - Using Coral with AI assistants and LLMs
API Documentation (/docs/packages/)
Reference documentation for packages and APIs:
- Core Package - Core utilities, schemas, CLI, and APIs
- Transform Packages - Packages for converting between formats
Tip: Start with the Getting Started guide to learn concepts, then refer to API documentation for specific implementation details.
