The Espalier Codex: Architecture & Engineering Guides

A design system is more than a library of components; it is a shared mental model for solving spatial and cognitive problems. The Espalier system provides a rigorous "trellis"—a supportive framework of technical standards—that allows our products to grow with both elegance and structural integrity.

These guides are authored for engineers and designers who prioritize Technical Defensibility, Perceptual Accuracy, and Modular Scalability.

Start Here

New to Espalier? These two guides will get you up and running and help you understand what to expect:

• Getting Started — Installation, root setup, your first component, and a simple form.
• Browser Support — Minimum browser versions, required polyfills, and support policy.
• Styling Reference — Every CSS custom property: theme-level tokens, per-component overrides, and VS Code integration.
• Tokens & Variants — How to choose between theme fields, semantic tokens, component props, and variant without breaking coherence.
• Font Picker — Setting up font assets, configuring the picker, and keeping the catalog current.
• Caveats — Detailed per-feature compatibility rationale and known limitations.
• AI Development — Guardrails, prompt fragments, and contract testing for AI-assisted development in projects that consume Espalier.

The Architecture Pillars

Explore our core philosophies and implementation standards across four key domains:

1. Perceptual Color Engine

Move beyond the "hardware-centric" legacy of RGB and Hex. This section details our transition to OKLCH and the APCA accessibility standard, treating color as a functional, biologically-aware API.

• Key Sub-pages: OKLCH Notation, Accessibility & APCA.

2. Architecture of Reading

We utilize fluid interpolation via clamp() and mathematical modular scales to ensure that $95\mathrm{\%}$ of our interface—the text—is high-performing and accessible on every device.

• Key Sub-pages: Fluid Fundamentals, Modular Scale.

3. Layout Governance

Establishing the Division of Labor between CSS Grid and Flexbox. We embrace Intrinsic Design, allowing components to respond to the space they occupy via Container Queries rather than coarse viewport breakpoints.

• Key Sub-pages: Orchestrating Macro Layouts, Micro Alignment, Container Queries.

4. Documentation as Infrastructure

In Espalier, documentation is the implementation. We utilize automated build pipelines to transform source-code metadata into interactive, live-testing environments.

• Key Sub-pages: Authoring Components, Build Pipeline.

How to Use These Guides

From a Startup Strategist's perspective, these documents serve as the Source of Truth for technical onboarding and code review.

1. Reference Before Implementation: Before authoring a new component, consult the Layout and Typography guides to identify the correct tokens and orchestration patterns.
2. Audit via the Codex: During code reviews, use these guides as the "Constitution." If a pull request introduces "magic numbers" or sRGB-based colors, it should be pruned to align with our perceptual standards.
3. Onboard AI Agents: For contributors using Claude or Copilot, point them to the copilot-instructions.md file in the repository root to ensure AI-generated code respects the Espalier architecture.

Strategy: The ROI of a Disciplined System

Investing in these standards delivers measurable business value:

• Velocity: Standardized patterns and automated docs reduce component integration time by up to $40\mathrm{\%}$ .
• Resilience: Proportional layouts and perceptually uniform colors eliminate the need for constant device-specific maintenance.
• Inclusion: Building with APCA and fluid type allows us to reach the $16\mathrm{\%}$ of the global population living with disabilities—a market valued at $13 trillion.