AI FRONTEND OS (ai-frontend-orchestrator / aif)

Production-grade AI Frontend Orchestrator and Meta-Framework for React, Next.js, and TypeScript applications. Governs Figma-to-Code mapping, context token budgets, security boundaries, visual QA, design systems, and autonomous repair across Antigravity, Cursor, and Claude Code.

QUICK START (FIRST 5 MINUTES)

Note: aif is the official short CLI alias for ai-frontend. Both executables are functionally identical.

# 1. Global Installation
npm install -g ai-frontend-orchestrator@latest

# 2. System Diagnostic Pre-Flight Check
aif doctor

# 3. Adopt an Existing Repository (Creates .ai/ brain directory; zero source code edits)
aif adopt

# 4. Preview Resolved Design System (Read-Only Safety)
aif ds preview "Cross-platform fintech application for Web, iOS, and Android" --verbose

# 5. Build Canonical Product Design System
aif ds build "Cross-platform fintech application for Web, iOS, and Android"

SYSTEM ARCHITECTURE AND SYSTEM INVARIANTS

The orchestrator operates between the developer and AI coding agents as an authoritative governing layer:

Developer / Prompt / Figma ──► Orchestrator Engine ──► Precedence Law (L1-L8)
                                       │
                                       ▼
                       Canonical Design System Model (Profile)
                                       │
            ┌──────────────────────────┼──────────────────────────┐
            ▼                          ▼                          ▼
      Web Realization           iOS Realization         Android Realization
    (32px, 12-col grid)      (44pt HIG, SF Pro)       (48dp M3, Roboto/Sans)
                                       │
                                       ▼
                         Guardian & Validation Engine
                                       │
                                       ▼
                       Accepted Codebase Implementation

The 10 Core System Invariants

1. Single Source of Truth: The .ai/ directory acts as the unified project brain and canonical state store.
2. 8-Level Precedence Hierarchy Law: Enforces rule ordering: Security Constraints (Level 1) > Project Invariants (Level 2) > User Directives (Level 3) > Existing DS (Level 4) > Accessibility Standards (Level 5) > Product Conventions (Level 6) > Screenshot Reference (Level 7) > AI Preference (Level 8).
3. Read-Only Preview Invariant: aif ds preview shares 100% of the canonical builder pipeline but is strictly read-only and zero-mutation.
4. Atomic Rollback Guarantee: Every file surgery is snapshotted in memory before modification. Any failure triggers instant rollback.
5. Decoupled Design Meta-Framework: The engine provides schemas and rules, while interchangeable design profiles (apple_hig, material_3, brutalist_editorial, or custom synthesized) supply visual languages.
6. Multi-Domain Drift Guardian: Continuously audits code for raw hex colors, off-grid spacing, component drift, missing route states, and responsive viewports.
7. 27-Domain Typography Engine: Decouples display, heading h1-h6, UI control, numeric/financial tabular, metadata, link, and editorial roles.
8. Evidence-First Reporting: Every audit finding requires line-number empirical proof. Zero arbitrary quality scores.
9. Blast Radius Governance: Changes affecting >5 consumer routes automatically pause execution for developer review.
10. Zero Lock-In: Generates pure TypeScript, React, and CSS output. Projects can detach at any time.

PRIMARY SUBSYSTEMS AND CLI OPERATIONS

Design System Subsystem (aif ds)

• aif ds preview [prompt]: Read-only simulation of resolved design system specifications across 43 canonical sections.
• aif ds build [prompt]: Compiles design system model to .ai/design/system.json.
• aif ds inspect: Detailed structural inspection of foundations, tokens, components, and state matrices.
• aif ds audit: Evidence-based audit for raw hexes, spacing scale deviations, and unhandled states.
• aif ds fix: Synthesizes repair plans categorized by risk tiers (lowRisk, mediumRisk, highRisk).
• aif ds query [query]: Queries machine-readable component and platform contracts.
• aif ds status: Displays health score, token coverage, and drift indicators.
• aif ds export / aif ds import: Manages global registry publishing (~/.ai-frontend/design-systems/).

Project Audit and Discovery

• aif audit: Comprehensive project audit report covering health metrics and duplicate components.
• aif gaps: Identifies missing screens, missing route states, and broken transitions.
• aif flows: Reconstructs user flow graphs across all application routes.

Code Generation and Implementation

• aif implement [prompt|figmaUrl]: Generates governed UI components bound to active design tokens.
• aif review: Inspects pending change proposals for paused high-risk tasks.
• aif approve [taskId] / aif reject [taskId]: Governs high blast-radius task proposals.

DOCUMENTATION INDEX

• Commands Reference Guide: Complete catalog of all 59 CLI subcommands, aliases, and options.
• Architecture Specification: Technical specification of the 10-Layer Canonical Model, Precedence Law, and Engine-Profile decoupling.
• Greenfield Developer QA Guide: Functional testing guide for new project workflows.
• Brownfield Developer QA Guide: Functional testing guide for existing codebase adoption.

LICENSE

MIT License. Developed by the Google Deepmind Advanced Agentic Coding Team.