@stratixlabs/core 1.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikael Carrara
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# 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 for semantic design governance, 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 independently, 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 @stratixlabs/core` | NPM |
+| **2. Author** | Manage your own design system | `npx @stratixlabs/core 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 @stratixlabs/core
+```
+*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 @stratixlabs/core 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 "@stratixlabs/core/substrata.css";
+
+/* Or just tokens */
+@import "@stratixlabs/core/src/tokens/colors.css";
+```
+
+### 2. Tailwind CSS
+Substrata feeds Tailwind. It does not replace it.
+```css
+@import "@stratixlabs/core/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 '@stratixlabs/core';
+
+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**](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.
+
+---
+
+## Tooling & Scripts
+
+- [detect-breaking-changes.js](file:///c:/Users/Usuario/Desktop/substrata/scripts/detect-breaking-changes.js)
+  - What it does: Detects when tokens are removed or renamed
+  - Foundation: Basic validation, table stakes
+
+- [figma-sync.js](file:///c:/Users/Usuario/Desktop/substrata/scripts/figma-sync.js)
+  - What it does: Pull/push tokens to/from Figma
+  - Foundation: The design ↔ code bridge you want standard
+
+- [generate-dts-from-tokens.js](file:///c:/Users/Usuario/Desktop/substrata/scripts/generate-dts-from-tokens.js)
+  - What it does: Generates TypeScript definitions
+  - Why core: Basic DX expected in modern libraries
+
+- [generate-tokens.js](file:///c:/Users/Usuario/Desktop/substrata/scripts/generate-tokens.js)
+  - What it does: CSS → tokens.json
+  - Foundation: Fundamental build pipeline
+
+- [lint-code.js](file:///c:/Users/Usuario/Desktop/substrata/scripts/lint-code.js)
+  - What it does: Detects hardcoded values in code
+  - Foundation: Basic linting is expected
+
+- [lint-hardcoded.js](file:///c:/Users/Usuario/Desktop/substrata/scripts/lint-hardcoded.js)
+  - What it does: Similar, detects hardcoded values
+  - Foundation: Basic quality tooling
+
+- [tokens-to-css.js](file:///c:/Users/Usuario/Desktop/substrata/scripts/tokens-to-css.js)
+  - What it does: tokens.json → CSS variables
+  - Foundation: The bidirectional loop you promised
+
+- [validate-tokens.js](file:///c:/Users/Usuario/Desktop/substrata/scripts/validate-tokens.js)
+  - What it does: Validates tokens.json against schema
+  - Foundation: Validation is fundamental
+
+---
+
+### Usage Snippets
+
+```bash
+npm run detect:breaking
+npm run sync:figma
+FIGMA_SYNC_DIRECTION=push npm run sync:figma
+FIGMA_TOKEN=... FIGMA_FILE_KEY=... npx @stratixlabs/core figma apply-preview
+npm run build:types
+npm run build:tokens
+npm run lint:code
+npm run lint:tokens
+npm run build:css-from-tokens
+npm run test:tokens
+```
+
+---
+
+## License
+
+MIT © 2026 Mikael Carrara