Interface Intelligence

Important

Portfolio Disclaimer

This project was conceived, designed, implemented, and deployed by me as a rapid AI-assisted product build.

"Built in a single session" means the project was completed over approximately 20 iterative commits using Claude Code as a development assistant, with me directing the product strategy, UX, architecture, workflow design, implementation decisions, testing approach, and deployment.

AI was used as a coding and implementation accelerator, similar to how modern engineering teams use AI development tools. The product concept, workflow design, user experience, design system strategy, technical architecture, and final implementation decisions were mine.

This project is intended to demonstrate how I work in an AI-first environment and how I design and build AI-powered products from concept to production.

Is it ready to be use as a design system co-pilot that helps users find patterns, understand constraints, and move from idea to implementation faster.

I designed, built, and deployed this product in a single session — from idea → architecture → UI → API → production.

AI-powered design system co-pilot. Build components, validate consistency, and generate documentation -- all grounded in your actual design system.

Author: Mirabelle Doiron

Domain: interface-intelligence.ai

The Problem

Design systems exist in Figma, in code, and in documentation - but AI tools ignore all of it. When teams use AI to generate UI, the output uses generic colors, arbitrary spacing, and misses accessibility requirements. The result: inconsistency, redundant work, and broken compliance.

Interface Intelligence makes AI system-aware. Instead of "generate a modal," you get "generate a modal using our tokens, following our patterns, meeting our WCAG level." Every output references your actual token names, explains why it chose them, and flags accessibility requirements.

That's the exact gap GrowthX fills for their clients - they build the experience layer around AI agents. This product demonstrates that job.

Context

Portfolio piece for the GrowthX AI Design Engineer application. Demonstrates designing and building the experience layer around an AI agent - the exact role. Uses Output.ai workflow patterns. Built and deployed in a single session.

Concept

Teams connect their tokens and components, then use guided workflows to build components, validate consistency, and generate documentation - all grounded in their actual system. The AI doesn't generate from scratch. It generates within a system.

Tech Stack

Next.js 15 (App Router)
React 19 + TypeScript
Tailwind CSS v4 + shadcn/ui
Claude API via @anthropic-ai/sdk
Output.ai workflow patterns (LiquidJS prompt templates, Zod schemas)
localStorage for persistence
Mock fallback for no-API-key viewers
Deployed to Vercel

Architecture

[Browser] -> [Next.js Frontend] -> [API Routes] -> [Claude API]
                                        |
                              mirrors Output.ai workflow
                              patterns: .prompt structure,
                              structured Zod schemas,
                              per-step execution

Screens

1. System Dashboard (/)

Design tokens overview with color swatches
List of connected components with variant counts
System health stats (token count, component count, WCAG target)
Quick-launch buttons for the 3 workflows

2. Build Flow (/build)

Step-by-step guided input: component type, context, constraints
System tokens visible as reference panel
Output: component structure, recommended tokens, API design, a11y notes
Each output section is a card with copy actions
Explains WHY each decision was made (reasoning panel)

3. Validate Flow (/validate)

Paste code snippet or describe a component
Output: alignment score (0-100), violations, suggestions, alternative patterns
Severity badges (error/warning/info)
Actionable suggestions referencing system tokens

4. Docs Generator (/docs)

Select a component from system
Generate: usage docs, do/don't guidelines, a11y notes, code examples
Copy entire doc or individual sections

Built on Output.ai

This project is built on the workflow patterns from Output.ai, GrowthX's open-source AI workflow framework.

What Output.ai provides

Output.ai organizes AI prompts as version-controlled files instead of hardcoding them in application code. Each workflow is a self-contained folder with a .prompt file (instructions for the AI) and a workflow.ts file (typed schemas for input and output validation). This is the same structure GrowthX uses in production when building AI agents for clients like Lovable, Airbyte, and Augment.

How this project uses it

The /workflows directory follows Output.ai's convention:

workflows/
  component-builder/
    build.prompt        # YAML frontmatter + Liquid template
    workflow.ts         # Zod input/output schemas
  system-validator/
    validate.prompt
    workflow.ts
  docs-generator/
    docs.prompt
    workflow.ts

Each .prompt file has two parts:

YAML frontmatter at the top: which model to use, temperature, max tokens
Liquid template below: the actual AI instructions with {{ placeholders }} for variables

What happens when you click "Generate Component Spec"

The app reads build.prompt from the workflows directory
The prompt engine parses the YAML config (model, temperature)
LiquidJS fills in {{ system_name }} with "Mirabelle Design System"
LiquidJS fills in {{ token_groups }} with all mirabelle-ds-* token values
LiquidJS fills in {{ component_type }} with "Button" or "Card" or whatever was selected
The rendered prompt is sent to Claude via the Anthropic SDK
Claude responds with code that references the actual design system tokens
The response is validated and returned to the browser

The prompt engine (src/lib/prompt-engine.ts) handles steps 1-5. It mirrors the same loading pipeline that @outputai/llm uses internally: read file, parse YAML, render Liquid, extract system/user prompt pairs.

What would change in production

In a production Output.ai deployment, these same workflow folders would gain:

Temporal orchestration for durable execution with retry and replay
Step caching so completed LLM calls are not repeated on re-runs
Tracing with token counts, costs, and latency per step
Evals for automated output quality scoring

The workflow structure, prompt files, and schemas are identical. The orchestration layer changes.

See Output.ai on GitHub for the full framework documentation.

Key UX Decisions

Guided flows, not blank prompts -- progressive disclosure, step-by-step
System-aware outputs -- references actual tokens, not generic advice
Transparent reasoning -- every output explains which rules applied
Accessible from day one -- keyboard nav, focus management, aria-live for async
Meaningful loading states -- "Analyzing token structure..." not "Loading..."
Reduced motion support -- respects prefers-reduced-motion

Getting Started

npm install
npm run dev

Open http://localhost:3000

Testing the Workflows

Build Component (/build)

Select a component type (e.g. Button)
Enter a usage context (e.g. "settings dashboard for SaaS")
Optionally add constraints and select WCAG level
Click Generate Component Spec
Results show: component structure, recommended tokens, API design, accessibility notes
Each section has a "Why" button showing the AI's reasoning

Validate Code (/validate)

Click Load sample to populate with example code, or paste your own
Click Validate Against System
Results show: alignment score (0-100), issues by severity, and suggestions

Generate Docs (/docs)

Select a component from the Mirabelle Design System
Click Generate Documentation
Results show: overview, usage examples, do/don't guidelines, accessibility notes, complete code example

Run History (/history)

All workflow runs are saved to localStorage
View past results and delete old runs

AI Configuration

The app works in two modes:

Mock mode (default): Without an API key, all workflows return high-quality mock data with a simulated 2-second delay. This is how portfolio reviewers will experience the app.

Live mode: Add your Anthropic API key to .env.local:

ANTHROPIC_API_KEY=sk-ant-...

Restart the dev server. Workflows will call Claude and generate results grounded in the Mirabelle Design System tokens.

Implementation Order

Phase 0: Scaffold

create-next-app, shadcn init, install deps

Phase 1: Foundation

Types (tokens, components, workflow schemas)
Mock design tokens + sample system data
localStorage store
Prompt templates (3 workflows)
Utility functions

Phase 2: API Routes

/api/build, /api/validate, /api/docs
Claude integration with mock fallback

Phase 3: Shared Components

App shell / nav
Token display panel
Section card (collapsible with copy + reasoning)
Severity badge
Loading states with contextual messages

Phase 4: Pages

Dashboard (system overview + workflow launchers)
Build flow (guided wizard + results)
Validate flow (input + report)
Docs generator (select + output)

Phase 5: Theme + Polish

Mirabelle Design System tokens as app theme
Focus rings, aria-live regions
Responsive breakpoints

Phase 6: Deploy

Git repo, push to GitHub
Vercel deploy

Project Structure

src/
  app/
    page.tsx              # Dashboard -- system overview + workflow launchers
    build/page.tsx        # Build workflow -- guided component generation
    validate/page.tsx     # Validate workflow -- code analysis
    docs/page.tsx         # Docs workflow -- documentation generation
    history/page.tsx      # Run history
    api/build/route.ts    # Build API -- loads .prompt, calls Claude
    api/validate/route.ts # Validate API
    api/docs/route.ts     # Docs API
  components/
    app-shell.tsx         # Navigation shell
    section-card.tsx      # Collapsible result card with copy + reasoning
    token-panel.tsx       # Design token reference panel
    code-block.tsx        # Copyable code display
    severity-badge.tsx    # Error/warning/info badges
    loading-states.tsx    # Skeleton loading with contextual messages
  lib/
    types.ts              # TypeScript types for all workflows
    sample-system.ts      # Mirabelle Design System tokens + components
    store.ts              # localStorage persistence
    prompt-engine.ts      # .prompt file loader (YAML + Liquid)
    mock-results.ts       # Mock data for no-API-key mode
    hooks.ts              # useReducedMotion hook
workflows/
  component-builder/
    build.prompt          # YAML frontmatter + Liquid template
    workflow.ts           # Zod schemas
  system-validator/
    validate.prompt
    workflow.ts
  docs-generator/
    docs.prompt
    workflow.ts

Accessibility Testing

90 automated tests across 4 test suites covering WCAG compliance, keyboard navigation, and screen reader support.

npm test                # Run all 90 tests
npm run test:a11y       # WCAG axe scans + aria attribute tests
npm run test:keyboard   # Keyboard navigation and activation
npm run test:sr         # Screen reader landmarks, labels, announcements

What the tests verify

WCAG Compliance (jest-axe)

Automated axe scans on every page and interactive component
No WCAG 2.1 AA violations in any rendered state

Aria Attributes

All collapsible sections have aria-expanded
Radio groups have role="radiogroup" with aria-label
Each selectable chip has role="radio" with aria-checked
Copy buttons have descriptive aria-label per section
Loading states use role="status" with aria-label

Keyboard Navigation

All interactive elements reachable via Tab
Enter and Space activate radio selections and buttons
Focus-visible ring classes present on all interactive elements
Textarea fields are focusable and editable via keyboard

Screen Reader Support

Every page has a level 1 heading
Decorative icons have aria-hidden="true"
Form labels are programmatically associated with inputs
Loading state includes sr-only announcement text
No buttons use generic labels ("click here", "submit")
Severity badges use text labels, not color alone

Verification

Run npm test to verify all 90 accessibility tests pass
Run npm run dev, test all 3 workflows with mock data
Test with real Claude API key
Deploy to Vercel, verify production build

Deploy

npm run build
vercel --prod

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
public		public
src		src
workflows		workflows
.gitignore		.gitignore
ARTICLE.md		ARTICLE.md
README.md		README.md
components.json		components.json
eslint.config.mjs		eslint.config.mjs
jest.config.ts		jest.config.ts
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tokens.css		tokens.css
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Interface Intelligence

The Problem

Context

Concept

Tech Stack

Architecture

Screens

1. System Dashboard (/)

2. Build Flow (/build)

3. Validate Flow (/validate)

4. Docs Generator (/docs)

Built on Output.ai

What Output.ai provides

How this project uses it

What happens when you click "Generate Component Spec"

What would change in production

Key UX Decisions

Getting Started

Testing the Workflows

Build Component (/build)

Validate Code (/validate)

Generate Docs (/docs)

Run History (/history)

AI Configuration

Implementation Order

Phase 0: Scaffold

Phase 1: Foundation

Phase 2: API Routes

Phase 3: Shared Components

Phase 4: Pages

Phase 5: Theme + Polish

Phase 6: Deploy

Project Structure

Accessibility Testing

What the tests verify

Verification

Deploy

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages