00 · Why This Exists
The gap between intent and output.
In ProgressThis page documents a project under active development. Nothing described here has shipped to production. All claims are architectural, not performance-based.
Every design system eventually confronts the same structural failure: a designer specifies intent in one environment, and that intent is re-interpreted by engineers, by component libraries, by framework conventions, and by runtime conditions in ways that are neither tracked nor governed. The output diverges from the intent. The divergence accumulates.
The conventional response is process: more documentation, more design review, closer handoff. These interventions reduce the divergence at a given moment. They do not eliminate the structural gap that produces it. The gap is not a communication problem. It is a compilation problem.
A compiler has a precise job: take an input expressed in one formal language and transform it, deterministically, into an output in another. When the input violates the grammar, the compiler reports the violation — it does not silently accept it and produce undefined behavior. Design-to-implementation pipelines do not behave this way. They accept ambiguous inputs. They silently resolve violations. They produce outputs related to — but not determined by — the designer’s intent.
Structural Premise
The gap between design intent and shipped UI is not a handoff problem. It is the absence of a formal grammar layer that governs what intent means and rejects specifications that cannot be deterministically compiled to output.
01 · Core Structural Problem
What breaks without a grammar layer.
The absence of a formal grammar layer between design and deployment produces four compounding failure classes. Each appears solvable at the surface. None is.
F1
Intent Ambiguity
Specifications that describe visual outcomes without governing the constraints that produce them. "The button should feel lighter" is not compilable. Ambiguity is not resolved at handoff — it is silently accepted and arbitrarily resolved at build time.
F2
Constraint Drift
Design tokens and component constraints defined once and then drifting independently in code, in Figma, and in documentation. No single authoritative source. Divergence is discovered at integration time, not at definition time.
F3
Contract Opacity
Component contracts — the rules governing which properties may be composed with which others, which variant combinations are valid — are held in undocumented engineering knowledge. They cannot be validated before build time.
F4
Silent Acceptance
Without a validator, specifications that violate component contracts are accepted silently and resolved arbitrarily at build time. The violation is never reported. The output diverges from intent with no audit trail.
What This Is Not
This is not a design system. It is not a component library. It is infrastructure that governs the transformation from specification to output — the layer those other things rest on, but that none of them provide.
02 · What I’m Building
Four platform primitives.
In ProgressThe primitives below are in active design and early implementation. API surfaces are not final. Behavior described is intended, not shipped.
The platform infrastructure is organized into four primitives. Each is independently definable. Each depends only on the primitives below it in the stack. Together they form the compilation pipeline from designer intent to deployed UI output.
P1
Invariant Grammar Layer
A formal specification language for design intent. Defines what properties may be specified, what value ranges are valid, and what relationships between properties are permitted. The grammar is the source of truth — not Figma, not code, not documentation.
In Progress
P2
Constraint Validator
Validates incoming specifications against the grammar. Produces structured violation reports with severity classification, source location, and resolution guidance. Halts on error-class violations before compilation.
Design Phase
P3
Component Contract Resolver
Maps validated specifications to component contracts. Produces a resolved intermediate representation — not final code, but a deterministic component graph. Surfaces ContractError for unresolvable specifications.
Specified
P4
Compiled UI Output
Transforms the resolved component graph into deployable output. The transformation is deterministic. Output targets are configurable: React, tokens-only, static markup. Version-locked to the grammar version at compile time.
Not Started
03 · Compilation Flow Diagram
From designer intent to output.
The diagram below traces how a design specification moves through the grammar layer, constraint validation, contract resolution, and compilation into a deployed UI artifact. Each step either passes the specification forward or produces a structured report and halts.
Fig 3.A — Compilation Pipeline · Input to Output
Compilation path
Input
Designer Intent
Formal specification in grammar syntax. Properties, constraints, variant selectors, relationship declarations.
↓
Layer 01
Invariant Grammar Layer
Grammar parse. Syntax validation. Property range check. Relationship rule evaluation.
↓
Layer 02
Constraint Validator
Cross-property constraint evaluation. Token resolution. Variant compatibility check. Violation report or pass-through.
↓
Layer 03
Component Contract Resolver
Maps validated spec to component graph. Resolves variant, props, layout. Produces intermediate representation.
↓
Output
Compiled UI Output
Deterministic output from resolved graph. Same input always produces same output. Target: React / tokens / markup.
Rejection paths
Grammar Rejection
Specification uses undefined property, invalid value range, or disallowed relationship. Grammar parser rejects. Structured syntax error returned. Compilation halts.
→ SyntaxViolation { severity: error }
Constraint Violation
Syntactically valid but constrained property combination detected. Validator reports violation with location, severity, and resolution hint. Halts on error-class violations.
→ ConstraintReport { type, loc, hint }
Contract Mismatch
Validated specification cannot resolve to a valid component graph. Component contract does not support the requested variant or property combination.
→ ContractError { component, reason }
Design Principle
A compilation pipeline that silently resolves ambiguity is not a compiler. It is a best-guess interpreter. This platform halts on error-class violations rather than producing undefined output. The violation report is the deliverable, not the fallback.
04 · Platform Architecture Stack
System to output.
The second diagram traces the architectural layers of the platform from the design surface through the grammar engine and compiler, through the runtime validator, to frontend output. The architecture stack describes the layers that make compilation possible — not just the path a single specification takes through the pipeline.
Fig 4.A — Platform Architecture · Layer Stack
Platform layers
Surface
Design Surface
Where specifications are authored. Grammar-native syntax only — not free-form prose, not Figma properties.
↓
Engine
Grammar Engine
Parses and validates against the Invariant Grammar. Maintains grammar version. Tracks specification history. Surfaces violations to authoring surface.
↓
Compile
Compiler
Takes validated specs and resolved graphs. Produces deterministic output artifacts. Version-locked to grammar version at compile time.
↓
Validate
Runtime Validator
Post-compilation layer. Checks compiled output matches resolved graph. Detects regressions before deployment.
↓
Output
Frontend Output
Deployable artifact. React components, tokens, or static markup. Semantically equivalent to the validated specification.
Layer responsibilities
Design Surface
Specification authorship. Grammar-native input only.
Grammar Engine
Grammar definition, versioning, parse, syntax validation, relationship rules.
Compiler
Specification-to-graph transformation. Deterministic resolution. Contract evaluation.
Runtime Validator
Output verification. Regression detection. Semantic equivalence check.
Frontend Output
Deployment artifact. No specification logic at this layer.
Every compilation is tagged with the grammar version active at compile time. A specification compiled against grammar v1.2 will not be silently recompiled against grammar v1.4 after a grammar update. Grammar changes are auditable events.
// Compilation manifest — attached to every output artifact
compilation: {
grammar_version: "1.4.0",
specification_hash: "sha256:4a9f...",
resolved_contracts: [Button.primary, Input.default],
violations: [], // empty = passed validation
compiled_at: "2026-02-25T10:44:00Z"
}
05 · What It Solves
Structural problems. Structural responses.
Each of the four failure classes from Section 01 has a corresponding structural response within the platform. Each failure maps to a specific layer and a specific mechanism.
Failure 01 → P1
Intent Ambiguity → Grammar Layer
Specifications that cannot be expressed in the grammar cannot be authored. Ambiguity is not resolved at handoff — it is rejected at authorship. The grammar defines what intent may specify, and specifications outside that definition do not exist as valid inputs.
Failure 02 → P1 + P2
Constraint Drift → Grammar + Validator
The grammar is the single authoritative source for constraint definitions. Figma configurations, code implementations, and documentation are all downstream of the grammar — not parallel sources. Drift is a grammar version mismatch, and version mismatches are auditable events.
Failure 03 → P3
Contract Opacity → Contract Resolver
Component contracts are machine-readable definitions in the resolver, not undocumented engineering knowledge. Any specification requesting a component combination that violates its contract is rejected with a structured ContractError — not silently accepted.
Failure 04 → P2 + P4
Silent Acceptance → Validator + Compiler
The constraint validator halts on error-class violations before compilation. The runtime validator checks compiled output against the resolved graph before deployment. There is no path from invalid specification to deployed output that does not produce a structured report.
06 · Low Fidelity Interfaces
Layout blocks, not final UI.
In ProgressThese wireframes represent structural layout decisions, not visual design. They are low-fidelity by intent. Final interface design has not begun.
Wireframe 1 — Grammar Definition Panel
The grammar definition panel is the authoring surface where grammar rules, property definitions, and constraint relationships are declared. It is used by platform maintainers, not end users. It is not a design tool. It is an infrastructure configuration interface.
Grammar Definition PanelLo-Fi Grammar › Properties › spacing
Valid Range
0 – space.16 (exclusive upper)
Constraint Rules
RULE 1spacing.inner must be ≤ spacing.outer when both defined
RULE 2spacing.vertical may not exceed container.height × 0.25
RULE 3spacing.gap requires display: flex or display: grid on parent
+ Add Constraint Rule
Wireframe 2 — Constraint Violation Report
The violation report is the output surface of the constraint validator. It is displayed when a specification fails validation — before compilation. It presents structured violations with severity, source location, the violated rule, and resolution guidance.
Constraint Violation ReportLo-Fi Grammar v1.4.0 · Spec: nav-header-v3
Errorspacing.inner exceeds spacing.outer
spacing.inner: space.12 · spacing.outer: space.8
Rule: spacing.inner must be ≤ spacing.outer when both defined
Resolution: reduce spacing.inner to space.8 or below
nav-header-v3:14
ErrorUndefined token reference
color: brand.accent-secondary — not defined in grammar v1.4.0
Rule: all token references must resolve to a defined token
Resolution: use color.accent or define brand.accent-secondary in grammar
nav-header-v3:22
Warningfont-weight outside recommended range
font-weight: 350 — valid but below recommended minimum (400)
Advisory: may produce inconsistent rendering across platforms
nav-header-v3:31
InfoGrammar migration available
Property display.type renamed to layout.mode in grammar v1.5.0
Current usage compiles in v1.4.0 but requires migration before v1.5 upgrade
grammar migration
View in Specification
Export Report
Suppress Warnings
Wireframe 3 — Compilation Result Preview
The compilation result preview shows the output of a successful compilation: the resolved component graph, the output tokens, and the deployment status. It is the audit view of what was produced — not the output artifact itself.
Compilation Result PreviewLo-Fi Compilation passed · All constraints satisfied
spec hash: 4a9f2c · graph hash: 8d3e1a
NavHeader
variant: primary
layout: flex.row
spacing: space.8
→ LogoSlot [required]
→ NavItems [required]
→ ActionSlot [optional]
--nav-spacing: 32px
--nav-color-bg: #111110
--nav-color-fg: #f4f3f0
--nav-font-size: 14px
--nav-font-weight: 500
--nav-height: 56px
Output Artifact Preview — React Component
07 · Roadmap
What is built, building, and defined.
In ProgressRoadmap phases reflect current work status. Nothing below Phase 1 is shipped. Dates are not provided — this project does not operate on a fixed calendar.
Phase 01
Grammar Specification
Define the property set, value types, valid ranges, and relationship rules of the Invariant Grammar. Establish versioning model. Define the grammar parse contract — what a grammar-compliant specification looks like in its raw form.
In Progress
Phase 02
Constraint Validator
Build the constraint validation layer. Implement cross-property constraint rules. Define the ConstraintReport structure. Build the severity classification model and the halt-on-error logic.
Not Started
Phase 03
Component Contract Resolver
Define component contracts as machine-readable specifications. Build the resolver that maps validated specifications to component graphs. Implement ContractError for unresolvable specifications.
Specified
Phase 04
Compiler + Runtime Validator
Build the compilation step from resolved graph to output artifact. Implement output targets: React, tokens-only, static markup. Build the runtime validator that verifies compiled output before deployment.
Not Started
Phase 05
Authoring Surface
Build the grammar definition panel and specification authoring surface. These are infrastructure configuration tools, not design tools. Define integration points for downstream tooling.
Not Started
08 · Closing
Governance precedes automation.
The impulse in platform infrastructure is to automate first. Build the compiler, trust the output, ship faster. The grammar layer slows this down deliberately. It requires that every transformation be governed by a rule that was explicitly declared, versioned, and validated before the transformation occurs.
This is not a constraint on automation. It is the condition under which automation is safe. A compiler without a grammar is a text transformer. The grammar layer is what makes the rest of the pipeline deterministic — and determinism is what makes the output trustworthy enough to deploy without manual review at every step.
This project is not finished. The grammar specification is in progress. The validator and resolver are specified but not built. The compiler and authoring surface have not started. This page records where that work stands.
Closing Position
Governance precedes automation. A pipeline that transforms without governing what it accepts is not a compiler — it is a procedure. The grammar layer is what makes the distinction.
This page documents a platform infrastructure project currently under development within the Invariant Design Language system. Nothing described here is shipped or production-ready. All architectural descriptions represent intended behavior, not observed behavior. Grammar specifications, API surfaces, and component contracts are subject to change. · IDL-COMP-001 · v0.4