BMI Licensing + Affiliate Products

AI-Native Design + Development
Operating Model

A clear framework for how design, AI tooling, and development collaborate across multiple product areas. This document defines engagement levels, process flows, design system strategy, and the roadmap for scaling these practices.

Status: v1.1 — Active Products: Licensing Center, Affiliate Portal, Publisher Portal Last updated: April 2026 Team: 2 FTE + 4 Enspirit contractors
00

Team

Two BMI full-time employees set direction and own stakeholder relationships. Four Enspirit contractors own execution, research, and design system development. Manish (UXE) joined from Enspirit and owns the full Tonic engineering layer.

BMI Full-Time
K
Kelsey
UX Head — Nashville
Stakeholder relations, strategic direction, design team lead
J
Joey
Design Systems Designer — Seattle
Tonic component design, Figma library, design system governance
Enspirit Contractors
T
Tejas
UX Lead — Licensing + Design System
End-to-end UX for Licensing Center; design system strategy
P
Palak
UX Researcher + Licensing UX, Sublead
Research planning, usability studies, secondary design lead for Licensing
B
Bansi
UX Designer — Licensing
Screen-level design execution for Licensing Center flows
M
Manish
UX Engineer — Design Systems
Owns @bmi/tonic, Storybook, theme sync pipeline, Figma Code Connect, CI/versioning
01

Engagement Tiers

The team operates at three distinct levels depending on the product area, stakeholder relationship, and available bandwidth. Each tier has a different ownership model, delivery cadence, and set of expected outputs.

Embedded

Deep Ownership

Full design and UX ownership of specific products. End-to-end involvement from research through QA, with active participation in sprint ceremonies.

  • Licensing Center Portal
  • Payments Screen
  • License Renewal Flows
Strategic Partner

Direction + Governance

Guiding product and design direction at a high level. Setting standards, reviewing critical decisions, and managing design system governance.

  • Affiliate Portal
  • Tonic Design System
  • RevenueIQ (Licensing team)
Advisory + AI

Lightweight Contribution

Enabling teams via AI-assisted design, automation, and targeted UX contributions. Lower design overhead, higher leverage per hour invested.

  • Onboarding flows
  • Catalog redesigns
  • Publisher Portal

Transition principle: Products ideally move from Advisory toward Embedded over time as confidence, data, and relationships develop. The AI tier is not a permanent holding area -- it is a deliberate entry point.

02

End-to-End Process Flow

This flow applies primarily to Embedded and Strategic Partner products. AI touchpoints (highlighted in blue) are integrated throughout, not bolted on at the end. DESIGN.md lives at the repo root and gives every AI agent instant Tonic context without manual token pasting.

📋
PM Input
Requirements + acceptance criteria
📌
Backlog
Prioritized by impact + effort
✦
Design
Figma + Tonic variables
🤖
AI Review
Token audit, a11y, doc gen
🔍
Stakeholder Review
Design + PM sign-off
⚙
Dev Handoff
Dev Mode + Code Connect
⚡
AI Code Gen
AI + codebase context
⬡
Build
React + MUI + Tonic
✓
QA + A11y
Manual + automated
↑
Ship
Deploy + FullStory
FullStory analytics feed back into PM input, closing the loop
AI-assisted step
Human-led step

Current gap: The Dev Handoff step currently relies on Figma Dev Mode inspection without Code Connect. Developers are manually rebuilding MUI components from specs rather than pulling from a live component library. Closing this is Manish's first priority as UXE.

03

Research

Research is not a separate workstream that precedes design. It runs in parallel with every phase and feeds directly into design decisions, AI context, and Confluence documentation. Palak owns all research execution and acts as sublead on Licensing UX design.

Embedded tier

Full research cycle

Discovery interviews, usability testing, synthesis, and Confluence documentation. Research actively shapes the design brief before any UI work begins.

Strategic Partner tier

Targeted studies

Focused usability sessions or expert reviews on specific flows. Research informs decisions rather than driving the full design process.

Advisory + AI tier

AI-synthesized signals

FullStory behavioral data analyzed with AI tools. No moderated research investment. Findings inform lightweight UX recommendations.

Methods Discovery + Usability
Discovery interviews
Semi-structured interviews with licensees (restaurants, bars, hotels, retail) to understand mental models, top tasks, and pain points before any design work begins. Palak moderates. AI drafts the discussion guide from a problem description.
Usability testing
Moderated sessions on prototypes via UserTesting.com (piloted, pending tooling approval). HTML prototypes built with AI are used directly as test stimuli -- they are closer to production fidelity than Figma prototypes for interaction-heavy flows.
Methods Behavioral Analytics
FullStory
Session recordings and behavioral heatmaps reveal where licensees stall, abandon, or repeat actions. Palak reviews recordings and identifies patterns. AI synthesizes observations into structured findings with frequency and severity rankings.
Post-launch instrumentation
Every significant design change requires a defined instrumentation plan before release: what events to track, what success looks like at 30 and 90 days, and what would trigger a follow-up study. This is currently an open gap to close.
AI Role AI in Research
What AI handles
Research plan drafting, discussion guide writing, raw note synthesis into structured themes, competitive pattern analysis, and Confluence research page generation. Palak reviews and approves all outputs -- AI drafts, researcher decides.
Research as AI context
Palak's research summaries (1--2 pages per product area) become part of the AI context stack. Pasting a research summary into any design or UX writing conversation grounds AI output in actual user behavior rather than generic assumptions.
Ownership Palak
Research deliverables
Research plan, discussion guide, synthesis doc, Confluence research page, user archetypes, and design implications ranked by frequency. All deliverables are drafted with AI and approved by Palak before sharing with the broader team.
Research repository (later)
Long-term vision: a centralized repository of all research studies with an AI-assisted querying layer so anyone can ask "what do we know about how licensees think about their balance?" and get a synthesis across all past studies.
04

Design Process in Detail

Seven phases from first research touch to shipped documentation. Each phase shows who leads, what the team does, and what Claude handles. Blue lanes are AI-assisted.

Phase 01 Discovery + Research
Understanding the problem before designing anything. Feeds the design brief and the Claude context stack.
PPalak TTejas
Team does
  • Align with PM on research goals before touching Figma
  • Conduct and moderate user interviews
  • Review FullStory recordings for behavioral patterns
  • Decide which findings are signal vs. noise
Claude does
  • Research plan + discussion guide from a problem description
  • Synthesis doc from raw notes -- themes, quotes, patterns
  • Competitive analysis on comparable flows
  • Confluence research page ready to review and publish
Outputs Research plan Discussion guide Synthesis doc Confluence page
Phase 02 Define + Frame
Translating research and PM requirements into a design brief and IA before opening Figma.
TTejas PPalak
Team does
  • Review PM requirements against research findings, surface contradictions
  • Define information architecture and page structure
  • Map user flows including all edge cases
  • Sign off on the brief with PM before Figma opens
Claude does
  • Design brief from a Jira description or PM conversation
  • IA options with trade-offs -- team picks, Claude does not decide
  • Edge case inventory -- every state, empty condition, and error
  • Stress-test the proposed flow against the design principles
Outputs Design brief IA + flow diagram Edge case inventory PM sign-off
Phase 03 Design in Figma
Building UI with Tonic components. Claude works around Figma, not inside it -- generating copy, auditing tokens, catching missing states.
TTejas BBansi JJoey
Team does
  • Assemble Tonic components into layouts, make visual hierarchy calls
  • Review and approve all Claude-generated copy
  • Decide which design direction to pursue when options are surfaced
  • Validate interactions feel right via prototype and gut check
Claude does
  • All microcopy upfront -- every label, placeholder, error, empty state, tooltip for every state before design starts
  • Token audit from screenshots or exported specs against Tonic files
  • Missing states checklist -- loading, empty, error, disabled, hover, success
  • A11y review -- contrast ratios, touch targets, focus order, ARIA labels
Outputs Figma frames (all states) Microcopy set Token audit A11y checklist
Phase 04 Prototype + Validate
HTML and React prototypes for usability testing and stakeholder review. Faster than Figma for interaction-heavy flows. Established pattern from RevenueIQ.
TTejas PPalak MManish
Team does
  • Specify what the prototype needs to prove
  • Give directional prompts to iterate ("try inline edit instead of modal")
  • Palak runs usability sessions using the live HTML prototype as stimulus
  • Manish integrates scaffolded React directly into the codebase
Claude does
  • HTML prototype with exact Tonic tokens and IBM Plex Sans applied
  • All states in one file with a switchable state bar
  • React component scaffold using MUI + Tonic theme structure
  • Iterates on directional prompts without re-speccing
Outputs HTML prototype (all states) React scaffold Usability test results
Phase 05 Dev Handoff
Closing the gap between Figma and code. Code Connect (Manish) is the end state. Claude fills the gap until it is live.
TTejas MManish
Team does
  • Annotate Figma frames with interaction and behavior notes
  • Review generated specs before sharing with developers
  • Manish writes and commits Figma Code Connect mapping files
Claude does
  • Props documentation -- names, types, defaults, Tonic token mappings
  • Handoff spec -- states, transitions, responsive behavior, a11y requirements
  • Code Connect mapping file generated from component structure (Manish reviews)
  • Answers dev questions from the design brief without pinging Tejas
Outputs Props documentation Handoff spec Code Connect file Jira annotations
Phase 06 QA + Review
Validating implementation against design intent. Token compliance is non-negotiable and checked at PR level, not just at QA.
MManish TTejas
Team does
  • Visual QA against Figma designs in staging environment
  • Interaction QA -- states, transitions, edge cases
  • Final copy approval
  • Manish runs Chromatic visual regression snapshots
Claude does
  • Token compliance scan -- flags every hardcoded hex value in component source
  • Copy diff -- compares implementation against approved copy spec
  • A11y audit from rendered HTML: ARIA, contrast, focus order
  • QA checklist -- every testable state and behavior from the design spec
Outputs Token compliance report Copy diff A11y audit Chromatic snapshots QA sign-off
Phase 07 Documentation
The phase that always gets skipped. Claude removes almost all the friction -- the team's job is review and publish, not write from scratch.
JJoey TTejas MManish
Team does
  • Review and approve all Claude-generated docs before publishing
  • Add nuance that only comes from being in the room
  • Maintain accuracy as components and patterns evolve
Claude does
  • Confluence component pages -- usage, do/don't, token reference, Storybook link
  • Storybook .stories.tsx files -- all variants and states, Manish refines
  • ADRs -- context, options, decision, rationale from a conversation summary
  • Release notes from merged PRs and Jira tickets
Outputs Confluence pages Storybook stories ADRs Release notes
05

Design System Strategy

Tonic is built on MUI/Material UI with IBM Plex Sans as the primary typeface. The strategy balances using the MUI base library (which dev teams already understand) with meaningful customization that expresses BMI's brand identity -- without over-engineering a bespoke system from scratch.

Layer 01 Foundation
Base component library
MUI provides the structural and behavioral foundation. Inputs, buttons, tables, dialogs, data grids. Teams use these out-of-the-box rather than rebuilding.
@mui/material @mui/x-data-grid @emotion/react
Ownership
MUI upstream. BMI team owns theme customization and token mapping only. No forking base components unless strictly necessary.
Layer 02 Tonic Theme
Token-based customization
Tonic wraps MUI via a custom theme object. Figma Variables (light + dark mode) are the source of truth. Tokens sync to the MUI theme via the Figma Variables REST API, replacing the discontinued MUI Sync plugin.
@bmi/tonic Figma Variables REST API IBM Plex Sans IBM Plex Mono
Light mode primary
All product surfaces use light mode tokens extensively. Dark mode tokens are defined but applied selectively (e.g., RevenueIQ map layer, RevenueIQ admin panel).
Layer 03 Rules Engine
Consistency without rigidity
A lightweight set of usage rules governs when and how components are applied -- without requiring a fully bespoke component for every use case. Rules are documented in Confluence and enforced via Storybook + ESLint token linting.
Storybook 8 Chromatic ESLint token rules
Non-negotiable rule
No off-token hex values in production code. Every color must trace to a named Tonic token. Token compliance is part of the PR review checklist.
Layer 04 Toolchain
In execution
Versioned monorepo using Turborepo + Changesets. Storybook 8 on Chromatic for visual regression. Figma Code Connect mapping Figma components to live code. DESIGN.md at the repo root as the AI agent context file.
Turborepo Changesets Figma Code Connect DESIGN.md
Manish owns this layer
Manish (UXE, Enspirit) is responsible for the component library, Storybook, theme sync pipeline, Code Connect mappings, and CI/versioning. This frees Tejas and Joey to stay in Figma.
06

Now / Next / Later Roadmap

Sequenced by dependency and impact. "Now" items are either in progress or blocked only by budget/approvals. "Next" items require foundational work from "Now." "Later" items are directionally correct but not yet specced.

Now In progress
  • DESIGN.md Done
    Tonic context file at the repo root. All AI agents read this before generating components. Eliminates manual token pasting per conversation.
  • UX Engineer hire Done
    Manish (Enspirit) is now embedded as UXE. Owns @bmi/tonic, Storybook, theme sync pipeline, Code Connect, and CI/versioning.
  • Licensing Center payments redesign
    Option 3 approach finalized. Inline-editable amount field with quick-fill chips.
  • Tonic token audit + light mode cleanup
    Ensure all product surfaces map to named tokens. No off-token hex values.
  • Brand voice + tone guidelines
    Required foundation before scaling AI-driven content outputs.
  • Confluence structure + documentation
    Single source of truth for process, components, and usage rules.
  • GitHub read-only access for design team
    Enable AI-assisted codebase exploration without blocking dev workflows.
Next 3-6 months
  • Versioned monorepo
    Turborepo + Changesets. Semantic versioning and automated changelogs for @bmi/tonic. Manish leads execution.
  • Figma Code Connect rollout
    Map Figma components to live MUI/Tonic code. Eliminate manual spec translation.
  • Figma Variables REST API sync
    Automated token sync pipeline replacing the discontinued MUI Sync plugin.
  • Storybook 8 + Chromatic
    Visual regression testing and component documentation as part of CI.
  • AI code generation workflow
    Structured prompt templates for AI to generate Tonic-compliant React components from Figma specs.
  • UserTesting.com unmoderated research
    Pending tooling approval. Piloted. First studies target licensee self-service flows.
Later 6+ months
  • Research repository + AI querying
    Centralized research repository with an AI-assisted layer for synthesis across studies and products.
  • Design governance tooling
    Evaluate Tenet or similar for design system documentation, rules, and audit trail.
  • Affiliate Portal self-service expansion
    Extend the single-scroll, no-hidden-tabs paradigm established in Licensing Center to affiliate-facing flows.
07

Challenges + Mitigations

These are the known friction points in standing up this operating model. Each has a proposed mitigation -- these should be tracked as explicit work items, not assumptions.

Challenge
Git / DevOps gap. Most designers and PMs have limited familiarity with GitHub, branching, or codebases. Asking them to read source code directly creates friction and errors.
Mitigation
Grant read-only GitHub access and establish an AI-assisted exploration workflow. Designers and PMs interact with the codebase through AI rather than raw file inspection. Document 3-5 high-value prompt templates for common questions (e.g., "what props does this component accept?").
Challenge
No clear source of truth. Figma files, the live codebase, and unreleased features exist in separate silos with no synchronization mechanism. Developers hand-inspect specs; Figma drifts from production.
Mitigation
Establish Figma Variables as the canonical token source, synced to the MUI theme via the Variables REST API. Code Connect closes the loop from the component side. DESIGN.md at the repo root gives any AI agent instant, structured Tonic context without requiring manual token pasting. Until the full sync pipeline is live, a lightweight "token delta" review step is added to each sprint's design review.
Challenge
Developer resistance. Some developers prefer out-of-the-box MUI components and are skeptical of additional customization layers, tooling overhead, or design-system-driven workflows.
Mitigation
Show, do not tell. Deliver one working reference implementation (a Tonic-compliant component with Code Connect, Storybook story, and Figma mapping) before asking for buy-in. Let the DX argument make itself. Frame Tonic as a constraint layer on top of MUI -- not a replacement.
Challenge
Missing brand voice and tone. As AI-assisted content generation scales, the absence of voice guidelines means outputs are inconsistent, generic, or off-brand without a human catching it.
Mitigation
Treat voice and tone as a pre-condition for AI content workflows. Deliver a lightweight V1 guide (audience, register, vocabulary, anti-patterns) before any AI-generated copy reaches production. This guide becomes a system prompt input for all AI content tooling.
08

GitHub + AI Access Model

Designers and PMs should be able to extract meaningful insights from the codebase without needing to read raw TypeScript or navigate file structures manually. The model below uses AI as an interpreter layer between the team and the repository.

Designers
01
Read-only GitHub access to frontend repos. No write access or branching required.
02
AI + codebase context to answer questions like: "Does this component accept a disabled state?", "What tokens are used here?", "How is this API response structured?"
03
Figma Dev Mode (with Code Connect active) to inspect the live component mapping without leaving Figma.
04
Storybook on Chromatic as a browsable component reference with states, props, and usage notes. Manish owns this -- it is being built now.
Product Managers
01
Read-only GitHub access to track open PRs, understand what is actually in a release, and validate feature flags.
02
AI + ticket context to synthesize Jira history and GitHub PRs for release notes, stakeholder summaries, or gap analysis.
03
FullStory + AI to extract behavioral insights and frame them for product planning without needing analyst support.
04
Confluence as the structured home for specs, decisions, and cross-team alignment. Linked bidirectionally from Jira tickets.
09

Documentation in Confluence

Everything in this document should have a persistent home in Confluence, structured for cross-team discoverability. The recommended structure below maps to the sections above.

Space Design + Product
Top-level structure
Operating Model (this doc) / Design System / Product Areas / Research / Decisions
Ownership
Design lead maintains structure. Each product area has a designated PM owner for that area's pages.
Page Tonic Design System
Required pages
Token reference (light + dark) / Component usage rules / Token compliance checklist / DESIGN.md (AI agent context file) / Storybook link / Figma library link
Update cadence
Updated on every Tonic release. Minimum quarterly review. Changes flagged in #design Slack channel.
Page Process + Workflow
Required pages
End-to-end process flow / Dev handoff checklist / AI tool usage guide / GitHub access instructions / PR review criteria
Audience
Onboarding new designers, developers, and PMs. Should answer "how do we work together?" in under 10 minutes of reading.
Page Decisions + ADRs
Architecture Decision Records
Every significant technical or design system decision should have a lightweight ADR: context, options considered, decision made, and rationale. Prevents relitigating closed questions.
Starting point
ADR-001: MUI Sync plugin deprecated -- Figma Variables REST API adopted. ADR-002: Single-scroll over tabbed navigation in licensee portal. ADR-003: DESIGN.md format adopted as AI agent context file at repo root.