Cross-Team Workflow Recommendations

Research and recommendations for efficient collaboration between Content Designers, UX Designers, Front-End Developers, and Back-End Developers.

Last Updated: 2026-01-14

---

Guiding Principles

All workflows should be:

• Agile - Changes in one source of truth should propagate quickly to downstream artifacts with minimal manual effort
• Low-friction - Teams can iterate independently without blocking each other
• Reversible - Easy to update, roll back, or refine as requirements evolve

The recommendations below prioritize automated syncing, single sources of truth, and schema-driven generation so that changes propagate downstream without manual re-work.

---

Actors and Current Tools

Actor	Responsibilities	Current Tools
Content Designers	Develop form content in multiple languages	Contentful
UX/Service Designers	Design visual form layouts, object modeling, service blueprints	Figma, service blueprints, OOUX/ORCA (under consideration)
Front-End Developers	Build accessible forms (USWDS), call APIs	React, Zodios clients
Back-End Developers	API architecture, data modeling	Graph data modeling, Domain-Driven Design, MuleSoft API-led connectivity, OpenAPI

---

Workflow 1: Content Designer → UX Designer

Goal

Content developed in Contentful should flow seamlessly into Figma designs.

Recommended Approach

Contentful to Figma Plugin

• Plugin: https://www.figma.com/community/plugin/789594601370719857/contentful-to-figma
• Contentful blog: https://www.contentful.com/blog/add-real-world-contentful-data-to-figma-designs/

Benefits

• Pull real content from Contentful directly into Figma
• See copy in context within form flows
• Generate multi-language design variants automatically
• Webhooks can auto-update Figma when content changes

Workflow Diagram

Contentful (source of truth for content)
    ↓ Figma plugin sync
Figma (designs with real content)

Status

• Evaluate Contentful to Figma plugin
• Test multi-language workflow
• Set up webhook for automatic updates

---

Workflow 2: UX Designer → Front-End Developer

Goal

Figma designs should translate efficiently to USWDS-compliant React code.

Recommended Approach

Design Tokens + USWDS Design Kit

Design Tokens

Use Tokens Studio as bridge between Figma and code:

• Tokens Studio: https://tokens.studio/
• GitHub plugin: https://github.com/tokens-studio/figma-plugin

Workflow:

Figma (design tokens via Tokens Studio)
    ↓ Git sync
GitHub repo (tokens.json - single source of truth)
    ↓ Style Dictionary / CI pipeline
CSS variables / Tailwind config / USWDS theme overrides

USWDS Figma Resources

Resource	Link
USWDS Design Kit Beta	https://www.figma.com/community/file/1440921849343185329/uswds-design-kit-beta
USWDS Design System	https://www.figma.com/community/file/1445773670714227313/uswds-design-system
USWDS (Truss version)	https://www.figma.com/community/file/836611771720754351/u-s-web-design-system-uswds

Code Generation Tools

Tool	Use Case	Link
Figma Dev Mode	Inspect designs, copy CSS	https://help.figma.com/hc/en-us/articles/15023124644247-Guide-to-Dev-Mode
Figma Code Connect	Link Figma components to React	https://github.com/figma/sds
Locofy	AI-powered Figma → React	https://www.locofy.ai/convert/figma-to-react
Figma Make	Natural language → React	https://www.figma.com/solutions/ai-react-generator/

Status

• Evaluate Tokens Studio for design token workflow
• Adopt USWDS Figma kit
• Set up Style Dictionary pipeline
• Evaluate code generation tools

---

Workflow 3: Form Layouts → API Data Models

Goal

Front-end form structures should align with back-end API schemas without manual translation.

Recommended Approach

OpenAPI/JSON Schema as Shared Contract

Option A: Schema-First (Recommended)

OpenAPI schemas become single source of truth for both frontend and backend:

OpenAPI Schema (safety-net-openapi)
    ↓                           ↓
Zodios clients              JSON Schema extraction
(backend types)                    ↓
                            react-jsonschema-form
                            (frontend forms)

Key Tools

Tool	Purpose	Link
react-jsonschema-form	Auto-generate forms from JSON Schema	https://github.com/rjsf-team/react-jsonschema-form
RJSF Playground	Test form generation	https://rjsf-team.github.io/react-jsonschema-form/
react-hook-form-jsonschema	Lighter alternative	https://github.com/vtex/react-hook-form-jsonschema
JSFE	Web component approach	https://github.com/json-schema-form-element/jsfe

UI Schema Separation

RJSF supports separating data schema from presentation:

# JSON Schema (shared with backend)
Application:
  properties:
    status:
      type: string
      enum: [draft, submitted, approved]

# UI Schema (frontend presentation only)
Application:
  status:
    ui:widget: "radio"
    ui:options:
      inline: true

Integration with Existing OpenAPI Schemas

OpenAPI 3.1 is a superset of JSON Schema draft 2020-12. The schemas in openapi/components/ can be:

1. Extracted as standalone JSON Schema files
2. Used directly by react-jsonschema-form
3. Validated against the same rules as API requests

Status

• Prototype react-jsonschema-form with existing schemas
• Create JSON Schema extraction script
• Define UI Schema conventions
• Test form ↔ API data roundtrip

---

Workflow 4: UX Object Modeling → API Data Models

Goal

UX object models (from OOUX/ORCA or service blueprints) should align with backend graph data models and API schemas, establishing a shared vocabulary across teams.

Why This Matters

All three disciplines center on objects/entities:

Discipline	Term	Focus
OOUX/ORCA	Objects	User mental models
Service Design	Touchpoints, Actors	Service interactions
Graph Data Modeling	Nodes + Relationships	Data relationships
API Design	Resources/Schemas	Business domain

Aligning early prevents costly translation errors and rework.

Recommended Approach

Shared Visual Modeling with Hackolade

Hackolade bridges UX and backend by providing:

• Visual graph modeling (supports Neo4j)
• Export to OpenAPI (JSON/YAML)
• Polyglot output - same model targets multiple formats

OOUX/ORCA Tooling

OOUX is methodology-focused, using collaborative tools:

Tool	Use Case	Link
Miro ORCA Template	Object mapping workshops	https://miro.com/templates/ooux-orca-process/
Figma ORCA Template	Object map documentation	https://www.figma.com/community/file/1184428250626254821/orca-object-map-template-ooux
OOUX Resources	Methodology guides	https://ooux.com/resources/quickstart

Key artifacts:

• Object Map - Visual representation of system objects and relationships
• Object Guide - Detailed documentation of each object's attributes and CTAs

MuleSoft API-Led Connectivity

Backend uses MuleSoft's tiered API architecture:

┌─────────────────────────────────────────────────────────────┐
│                    Experience APIs                           │
│         (per application, tailored to client needs)          │
└─────────────────────────────┬───────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│                     Process APIs                             │
│           (orchestration, business logic)                    │
└─────────────────────────────┬───────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│                     System APIs                              │
│        (direct integration with backend systems)             │
└─────────────────────────────────────────────────────────────┘

All API tiers use OpenAPI specifications designed in MuleSoft Anypoint Design Center.

Bridging Tool: Hackolade

Feature	Benefit	Link
Visual graph modeling	UX + Backend collaborate on same model	https://hackolade.com/
Neo4j support	Native graph database modeling	https://hackolade.com/help/Neo4j.html
OpenAPI export	Generate API specs from graph model	https://hackolade.com/help/OpenAPI.html
Polyglot models	One model, multiple outputs	https://hackolade.com/help/LeverageaPolyglotdatamodel.html

Proposed Workflow

OOUX Object Map / Service Blueprint (UX artifacts)
    ↓ Collaborative workshop
Hackolade Graph Model (shared visual model)
    ↓ Export
OpenAPI Specifications
    ↓ Import
MuleSoft Anypoint Design Center
    ↓ Implement
System APIs → Process APIs → Experience APIs

Establishing Ubiquitous Language

To align teams, conduct a vocabulary alignment workshop:

1. UX presents Object Map with proposed object names
2. Backend presents graph model entities
3. Teams align on shared terminology
4. Document in a glossary that maps UX terms ↔ API resource names

This follows Domain-Driven Design principles - a shared language reduces miscommunication.

Status

• Evaluate OOUX/ORCA methodology for UX team
• Evaluate Hackolade for shared visual modeling
• Define vocabulary alignment process
• Prototype: OOUX Object Map → Hackolade → OpenAPI pipeline
• Document MuleSoft API tier conventions

---

Proposed Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                            SOURCES OF TRUTH                              │
├───────────────┬───────────────┬─────────────────┬───────────────────────┤
│  Contentful   │ OOUX/Service  │  Figma/Tokens   │   Hackolade Graph     │
│  (content)    │ Blueprints    │  Studio (UI)    │   Model (data)        │
└───────┬───────┴───────┬───────┴────────┬────────┴───────────┬───────────┘
        │               │                │                    │
        │               └────────────────┼────────────────────┘
        │                       ▼        │        ▼
        │              Vocabulary        │    OpenAPI Schemas
        │              Alignment         │         │
        ▼                                ▼         ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                          GENERATED ARTIFACTS                             │
├───────────────┬─────────────────┬───────────────────────────────────────┤
│ Figma designs │  CSS/Tailwind   │  Zodios clients + JSON Schema         │
│ (with content)│  tokens         │  for forms                            │
└───────┬───────┴────────┬────────┴───────────────────┬───────────────────┘
        │                │                            │
        └────────────────┴────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         REACT APPLICATION                                │
│  - USWDS components styled with design tokens                           │
│  - Forms generated from JSON Schema (RJSF)                              │
│  - API calls via Zodios (typed from same schema)                        │
│  - Content pulled from Contentful at runtime                            │
└─────────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                    MULESOFT API-LED CONNECTIVITY                         │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                  │
│  │ Experience  │ ←→ │   Process   │ ←→ │   System    │                  │
│  │    APIs     │    │    APIs     │    │    APIs     │                  │
│  └─────────────┘    └─────────────┘    └─────────────┘                  │
└─────────────────────────────────────────────────────────────────────────┘

---

Quick Wins

Immediate Actions

1. Install Contentful to Figma plugin
2. Adopt official USWDS Figma kit
3. Prototype react-jsonschema-form with Application schema
4. Evaluate Tokens Studio
5. Introduce OOUX/ORCA concepts to UX/Service Design team

Medium-Term

• Set up design token pipeline (Tokens Studio → Git → Style Dictionary)
• Create JSON Schema extraction from OpenAPI
• Define UI Schema conventions for forms
• Evaluate Hackolade for shared UX/Backend modeling
• Conduct vocabulary alignment workshop (UX + Backend)

Long-Term

• Automated content sync (Contentful webhooks)
• Full schema-driven form generation
• Design-to-code pipeline with Figma Code Connect
• Integrated pipeline: OOUX → Hackolade → OpenAPI → MuleSoft

---

Research Sources

Contentful + Figma

• https://www.contentful.com/blog/add-real-world-contentful-data-to-figma-designs/
• https://contentfultofigma.com/blog/integrating-contentful-and-figma-6-strategies-for-success/

Design Tokens

• https://tokens.studio/
• https://medium.com/@jdposada/design-tokens-architecture-7544c9a8f33a
• https://smallstep.com/blog/halving-ui-dev-time-figma-token-studio/

Figma to Code

• https://www.figma.com/blog/schema-2025-design-systems-recap/
• https://github.com/figma/sds

Schema-Driven Forms

• https://rjsf-team.github.io/react-jsonschema-form/docs/
• https://medium.com/quadcode-life/fully-typed-forms-based-on-api-schema-with-react-hook-form-openapi-typescript-and-yup-validation-93ba1321368b
• https://github.com/json-schema-form-element/jsfe

OOUX/ORCA

• https://ooux.com/resources/quickstart
• https://alistapart.com/article/object-oriented-ux/
• https://adobe.design/stories/leading-design/why-ux-designers-should-create-object-maps-and-how-to-start
• https://miro.com/templates/ooux-orca-process/

Graph Data Modeling + API Design

• https://hackolade.com/
• https://hackolade.com/help/OpenAPI.html
• https://hackolade.com/help/LeverageaPolyglotdatamodel.html
• https://medium.com/@shalin.garg/apis-using-domain-driven-design-a7ecf7bb11fb

MuleSoft

• https://docs.mulesoft.com/neo4j-connector/latest/
• https://blogs.mulesoft.com/dev-guides/open-api-raml-better-together/
• https://developer.mulesoft.com/tutorials-and-howtos/quick-start/designing-your-first-api/

---

Decision Records

Significant workflow decisions are documented as Architectural Decision Records (ADRs) in the adr/ folder. Use the template at templates/adr-template.md. Files are named NNNN-short-title.md (e.g., 0001-use-openapi-as-shared-contract.md).

---

Open Questions

1. How should multi-language content flow from Contentful through forms?
2. What's the right granularity for design tokens (USWDS defaults vs custom)?
3. Should form validation use Zod schemas directly or JSON Schema?
4. How to handle form fields that don't map directly to API fields?
5. How to integrate service blueprint artifacts with OOUX object models?
6. What's the right cadence for vocabulary alignment sessions between UX and Backend?
7. Should Hackolade be the single source of truth, or maintain separate UX/Backend models that sync?
8. How should Experience APIs differ from Process APIs in schema design?

---

Notes

Add ongoing notes and decisions here as the workflow evolves.