npm package: @mikaelcarrara/substrata
Description: Framework-agnostic design tokens system
Author: Mikael Carrara
Latest version: 1.6.5
Deprecated: Pacote descontinuado: use @stratixlabs/core

# Substrata

Substrata is a framework-agnostic **design infrastructure** for tokens, schemas, and automation that transforms design decisions into **semantic contracts**. It serves as a stable foundation where design intelligence can run, enabling automation, consistency, and long-term resilience across any platform or tech stack.

Unlike a UI library that couples design to components, Substrata provides the low-level *definitions* (design tokens and their canonical graph) that drive the UI, ensuring design intent is preserved from design tools to production code—even as frameworks change.

**[Documentation](https://mikaelcarrara.github.io/substrata)**

---

## Philosophy

Substrata is guided by a core set of architectural principles: tokens are the atomic foundation of design; infrastructure must outlive frameworks; and a single source of truth prevents divergence. We design for durability and longevity, achieving consistency through architecture, not discipline. Our focus is on defining the foundation, not the final UI surfaces.

See our policies on [**Governance**](./GOVERNANCE.md) and [**Contributing**](./CONTRIBUTING.md).

---

## Architecture

Substrata is architected as a system of independent layers. Each layer encapsulates a distinct responsibility and can evolve autonomously, enabling long-term scalability, resilience, and architectural clarity.

1.  **Tokens**: Define design decisions as CSS Variables—colors, spacing, typography, and core primitives. They are semantic, stable, versionable, and platform-agnostic.
2.  **Base Styles**: Apply tokens to native HTML elements, establishing predictable defaults and consistent rendering without adding abstractions or components.
3.  **Components**: Optional reference patterns for consuming tokens in real interfaces. They demonstrate usage, not prescribe a UI library.

This layered approach ensures that the core design system remains decoupled from any specific implementation.

---

## W3C Alignment

Substrata implements the "Source of Truth" layer in the W3C reference architecture:

1.  **Definition**: Design intent defined in design tools (e.g., Figma).
2.  **Transformation**: Raw data processed into usable artifacts.
3.  **Source of Truth (Substrata)**: The detailed, versioned, and semantic definition of all tokens (CSS variables, JSON).
4.  **Consumption**: Applications (React, Vue, iOS, Android) consuming these tokens.

Read more in [W3C Alignment](./docs/w3c-alignment.html).

---

## Choose Your Path

Substrata is designed to be used in three distinct ways depending on your goal.

| Path | Goal | Installation | Tool |
| :--- | :--- | :--- | :--- |
| **1. Consumer** | Use default tokens in your app | `npm install @mikaelcarrara/substrata` | NPM |
| **2. Author** | Manage your own design system | `npx @mikaelcarrara/substrata init` | CLI (NPX) |
| **3. Contributor** | Modify Substrata core/docs | `git clone ...` | Git |

---

### Path 1: Consumer (Recommended)
Best for developers who want to use the official Substrata tokens (colors, spacing, etc.) in their project.

```bash
npm install @mikaelcarrara/substrata
```
*See [Getting Started](https://mikaelcarrara.github.io/substrata/getting-started) for importing CSS/JSON.*

### Path 2: Author & Automation
Best for architects building a custom design system using Substrata as the engine.

`init` scaffolds a **complete, production-ready** system:

**📦 Generated Structure:**
- `substrata.config.js` - Configuration file
- `src/tokens/` - **9 token files** (colors, spacing, typography, radius-and-borders, elevation, motion, opacity, breakpoints, semantic-aliases)
- `src/consumption/` - **3 framework examples** (Tailwind, styled-components, plain CSS)
- `scripts/` - Automation scripts (generate, validate, lint, breaking-change detection, token-aware code lint)
- `src/substrata.css` - Main entry point (imports all tokens)
- `src/base.css` - Typography reset and base styles

**📜 NPM Scripts Added:**
- `build:tokens` - Generate tokens.json from CSS
- `test:tokens` - Validate token structure
- `lint:tokens` - Check for hardcoded values
- `lint:code` - Enforce correct token usage in application code
- `detect:breaking` - Detect breaking changes between tokens.json versions

```bash
# Set up complete design system infrastructure
npx @mikaelcarrara/substrata init

# Generate tokens.json
npm run build:tokens

# Validate tokens (optional)
npm run test:tokens
```

Then import `src/substrata.css` in your app. Check `src/consumption/` for framework-specific integration examples.

*See [Authoring & Automation](https://mikaelcarrara.github.io/substrata/automation) for detailed guide.*

### Path 3: Contributor
Best for those who want to improve Substrata itself or host their own fork.

```bash
git clone https://github.com/mikaelcarrara/substrata.git
cd substrata
npm install
npm run build:tokens
```

### Manual Download

Clone or download from GitHub:

```bash
git clone https://github.com/mikaelcarrara/substrata.git
```

Or download directly and include in your project.

## Usage

Substrata is designed to be consumed, not imposed. You can use it in multiple ways:

### 1. Plain CSS
Import the full system or valid subsets from the package:
```css
/* Import everything */
@import "@mikaelcarrara/substrata/src/substrata.css";

/* Or just tokens */
@import "@mikaelcarrara/substrata/src/tokens/colors.css";
```

### 2. Tailwind CSS
Substrata feeds Tailwind. It does not replace it.
```css
@import "@mikaelcarrara/substrata/src/substrata.css";
@tailwind base;
@tailwind components;
@tailwind utilities;
```
*See the [Next.js + Tailwind Quickstart](https://mikaelcarrara.github.io/substrata/getting-started#quickstart-next-tailwind) for a full app example, and [Consumption Strategies](./docs/consumption.html) for `tailwind.config.js` mapping.*

### 3. JavaScript / TypeScript
Import tokens as a JSON object:
```js
import tokens from '@mikaelcarrara/substrata';

const Button = styled.button`
  padding: ${tokens.space[3].value} ${tokens.space[4].value};
  background: ${tokens.color.brand[500].value};
  border-radius: ${tokens.radius.md.value};
`;
```

---

## Documentation

Full documentation is available online. Key sections include [**Getting Started**](https://mikaelcarrara.github.io/substrata/getting-started), the [**Tokens Reference**](https://mikaelcarrara.github.io/substrata/tokens), [**Consumption Strategies**](https://mikaelcarrara.github.io/substrata/consumption), and guides on [**Automation & AI**](https://mikaelcarrara.github.io/substrata/automation).

---

## Naming Conventions

Tokens use kebab-case and semantic grouping:
- Colors: `neutral-100`, `brand-500`, `color-surface`, `color-text-primary`
- Spacing: `space-1` ... `space-6`
- Typography: `font-size-sm`, `font-weight-bold`, `line-height-normal`
- Radius/Borders: `radius-sm`, `border-width`
- Motion/Elevation/Opacity: `duration-sm`, `shadow-sm`, `opacity-80`
- Breakpoints: `breakpoint-sm`, `breakpoint-md`, `breakpoint-lg`

Semantic aliases (see `src/tokens/semantic-aliases.css`) map raw tokens to intended usage, e.g.:
- Surface: `color-surface`
- Brand: `color-brand-primary`, `color-brand-hover`
- Text: `color-text-primary`, `color-text-inverse`

These aliases help preserve intent across frameworks and refactors.

---

## Core Artifacts

Substrata's architecture is defined by a few key artifacts that enable its semantic power:

- **`tokens.json`**: The canonical source of truth, containing all design tokens in a structured, machine-readable format.
- **JSON Schema**: A strict schema for `tokens.json` that enables validation, IDE autocompletion, and automated CI checks.
- **`substrata.d.ts`**: TypeScript declarations for type-safe token consumption in modern development workflows.

See the [**ROADMAP.md**](./ROADMAP.md) and [**ARCHITECTURE.md**](./ARCHITECTURE.md) for more details on our architectural evolution.

---

## License

MIT © 2026 Mikael Carrara