Skip to content

Latest commit

 

History

History
532 lines (429 loc) · 26 KB

File metadata and controls

532 lines (429 loc) · 26 KB

Visual Design UX Optimization Plan — Airtable Benchmark Analysis

Author: ObjectStack Core Team
Created: 2026-02-16
Status: 📋 Active Planning
Based On: Airtable Interface Designer (2025–2026), existing gap analysis
Scope: Evaluate Spec UI / Data / Studio classification, identify optimization opportunities, propose improvements


Table of Contents


1. Executive Summary

This document is a comprehensive evaluation of ObjectStack's visual design tool UX compared to Airtable's Interface Designer. It serves three purposes:

  1. Benchmark Analysis — Map Airtable's zero-code builder UX patterns to ObjectStack's protocol schemas
  2. Coverage Audit — Identify what the Spec already covers vs. what's missing, and fix outdated roadmap entries
  3. Optimization Plan — Define concrete schema enhancements and Studio UX improvements

Key Findings

Finding Impact
Phase B & C schema work is largely complete — Interactive elements, blank layout, sharing, embedding are all implemented in spec but roadmaps are outdated Roadmap sync required
Studio lacks a "Data Studio" concept — No unified visual data exploration experience combining views, charts, and inline editing New protocol needed
Design-time preview is not modeled — No previewAs or live preview protocol exists Schema gap
Interface Builder protocol is minimal — Only snap/zoom/palette defined; missing undo/redo state, selection model, clipboard, multi-select Enhancement needed
Template ecosystem is unmodeled — No interface/page template schema for reuse and marketplace New protocol needed
ObjectStack exceeds Airtable in 15+ areas but the builder UX needs to make these capabilities discoverable UX alignment

2. Airtable Visual Design Tool UX Benchmark

2.1 Core UX Principles

Airtable's Interface Designer follows six core UX principles that ObjectStack should internalize:

# Principle Airtable Implementation ObjectStack Alignment
1 Data-first composition Every element is bound to a data source (table + view + filter) ElementDataSourceSchema per component
2 Progressive disclosure Simple defaults → advanced options on demand 🟡 Schemas have defaults but Studio UX doesn't implement progressive panels
3 Zero-code building Drag-and-drop, no configuration files 🟡 PageBuilderConfigSchema exists but Studio runtime not built
4 Role-specific surfaces Same data, different pages per stakeholder AppSchema with requiredPermissions
5 Shareable artifacts Apps are independently shareable/embeddable SharingConfigSchema + EmbedConfigSchema on AppSchema
6 Record-centric workflow Review, approve, and edit records inline RecordReviewConfigSchema

2.2 Design Tool Capabilities

Capability Airtable ObjectStack Spec ObjectStack Studio Gap
Drag-and-drop element placement BlankPageLayoutSchema ❌ Not built Studio runtime gap
Element palette with categories ElementPaletteItemSchema ❌ Not built Studio runtime gap
Canvas snap-to-grid CanvasSnapSettingsSchema ❌ Not built Studio runtime gap
Canvas zoom/pan CanvasZoomSettingsSchema ❌ Not built Studio runtime gap
Layer ordering panel PageBuilderConfigSchema.showLayerPanel ❌ Not built Studio runtime gap
Property inspector panel PageBuilderConfigSchema.showPropertyPanel ❌ Not built Studio runtime gap
Undo/redo (multi-step) 🟡 undoLimit only ❌ Not built Schema + runtime gap
Multi-select elements Schema + runtime gap
Copy/paste elements Schema + runtime gap
Alignment tools (center, distribute) Schema + runtime gap
Live data preview Schema + runtime gap
Preview as different user Schema gap
Page template gallery Schema gap
Responsive preview modes ResponsiveConfigSchema ❌ Not built Studio runtime gap

2.3 Data Studio Concept

Airtable's "Data Studio" experience is the seamless blend of:

  • Data views (grid, kanban, calendar, gallery, timeline) with inline editing
  • Charts & metrics embedded alongside data
  • Quick filters and grouping that apply across elements
  • Cross-table references with linked record expansion
  • Aggregation bars showing counts/sums at column footers

This is fundamentally different from a "Dashboard" (read-only KPI display) or a "Form" (data entry). It's an interactive data workspace where users simultaneously explore, filter, visualize, and edit data.

ObjectStack Gap: The spec has DashboardSchema (KPI display), ListViewSchema (data table), and FormViewSchema (data entry) as separate concepts. There is no unified "Data Studio" surface that combines interactive data views with embedded analytics in a single workspace.


3. Current Spec Coverage Evaluation

3.1 UI Protocol Coverage

Schema File Schemas Tests Airtable Parity Status
view.zod.ts ListView, FormView, ViewSharing ✅ Exceeds (6 form types, 3-level grouping) Stable
page.zod.ts PageSchema, 16 types, BlankLayout, RecordReview, Variables ✅ Full parity Stable
component.zod.ts 30 component types, 12 prop schemas ✅ Full parity Stable
sharing.zod.ts SharingConfig, EmbedConfig ✅ Full parity Stable
app.zod.ts AppSchema, NavigationItem, sharing, embed ✅ Full parity Stable
dashboard.zod.ts DashboardSchema, widgets ✅ Exceeds Stable
chart.zod.ts 45+ chart types ✅ Exceeds (45 vs 4) Stable
report.zod.ts Tabular, Summary, Matrix, Joined ✅ Exceeds Stable
action.zod.ts URL, Script, Flow, API ✅ Parity Stable
theme.zod.ts Full design system ✅ Exceeds Stable
responsive.zod.ts 6 breakpoints, visibility rules ✅ Exceeds Stable
animation.zod.ts Page/component transitions ✅ Exceeds Stable
dnd.zod.ts Full DnD protocol ✅ Exceeds Stable
keyboard.zod.ts Full keyboard nav ✅ Exceeds Stable
touch.zod.ts Gesture support ✅ Exceeds Stable
offline.zod.ts Cache + sync ✅ Exceeds Stable
i18n.zod.ts Full i18n ✅ Exceeds Stable
notification.zod.ts Toast, snackbar, banner ✅ Exceeds Stable
widget.zod.ts Custom widgets ✅ Exceeds Stable

UI Protocol Score: 20/20 schema files, all tested, full Airtable parity achieved.

3.2 Data Protocol Coverage

Schema File Relevance to Visual Design Status
object.zod.ts Object definitions power all visual tools ✅ Complete
field.zod.ts Field types drive form widgets, column renderers ✅ Complete (44+ types)
query.zod.ts Query AST powers data views, filters, aggregations ✅ Complete
filter.zod.ts Filter criteria for views, record pickers ✅ Complete
validation.zod.ts Form validation rules ✅ Complete
dataset.zod.ts Seed data for previews ✅ Complete
analytics.zod.ts Cube dimensions/measures for charts ✅ Complete

Data Protocol Score: All schemas supporting visual design are complete.

3.3 Studio Protocol Coverage

Schema File Purpose Status
plugin.zod.ts Studio plugin extension model ✅ Complete
object-designer.zod.ts Visual field editor, ER diagram, relationship mapper ✅ Complete (46 tests)
interface-builder.zod.ts Canvas snap/zoom, element palette ✅ Basic — needs enhancement

Studio Protocol Score: 3/3 files exist but interface-builder needs expansion.

3.4 Classification Assessment

Current classification across src/ subdirectories:

Directory Domain Files Assessment
src/ui/ Presentation & Interaction 20 ✅ Well-organized, comprehensive
src/data/ Data Model & Query 14 ✅ Well-organized, comprehensive
src/studio/ IDE Visual Editors 3 🟡 Needs expansion for visual builder protocols
src/automation/ Business Logic 8 ✅ Well-organized
src/ai/ AI & Intelligence 12 ✅ Well-organized
src/api/ API Contracts 20 ✅ Well-organized
src/system/ Runtime Config 22 ✅ Well-organized
src/security/ Access Control 5 ✅ Well-organized
src/identity/ User & Org 4 ✅ Well-organized
src/integration/ External Connections 7 ✅ Well-organized
src/kernel/ Plugin System 18 ✅ Well-organized
src/cloud/ Marketplace 4 ✅ Well-organized
src/contracts/ Service Interfaces 5 ✅ Well-organized
src/qa/ Testing 3 ✅ Well-organized
src/shared/ Common Utilities 3 ✅ Well-organized

Classification Verdict: The UI / Data / Studio three-tier classification is sound. The main issue is that Studio protocol only has 3 files while it should be the primary hub for visual builder specs. Recommend expanding src/studio/ with additional protocols rather than restructuring directories.


4. Gap Identification & Prioritized Improvements

4.1 Already Implemented (Roadmap Sync Needed)

These items are already implemented in spec schemas but roadmaps still show them as pending:

Item Schema Location Roadmap Status Action
Interactive elements (element:button, element:filter, element:form, element:record_picker) component.zod.ts L176-221 ❌ Phase B pending ✅ Mark complete
ElementButtonPropsSchema, ElementFilterPropsSchema, ElementFormPropsSchema, ElementRecordPickerPropsSchema component.zod.ts L176-221 ❌ Phase B pending ✅ Mark complete
BlankPageLayoutSchema for free-form canvas page.zod.ts L123-128 ❌ Phase B pending ✅ Mark complete
PageVariableSchema with record_id type and source binding page.zod.ts L98-104 ❌ Phase B pending ✅ Mark complete
SharingConfigSchema (public link, password, domain, expiration) sharing.zod.ts L19-29 ❌ Phase C pending ✅ Mark complete
EmbedConfigSchema (iframe, origins, responsive) sharing.zod.ts L36-45 ❌ Phase C pending ✅ Mark complete
sharing and embed on AppSchema app.zod.ts ❌ Phase C pending ✅ Mark complete
PageBuilderConfigSchema (snap, zoom, palette, layers) page-builder.zod.ts L55-63 ❌ Phase B pending ✅ Mark complete

Impact: 10 roadmap items need status update from pending → complete.

4.2 Remaining Gaps (P0 Critical)

# Gap Description Proposed Solution
G1 Design-time preview No previewAs schema for impersonating another user/role during design Add PreviewConfigSchema to studio/interface-builder.zod.ts
G2 Builder selection model No schema for multi-select, clipboard, alignment tools in the canvas builder Enhance PageBuilderConfigSchema
G3 JSON Schema generation Still pending from Phase A — needed for non-TS ecosystem support Tooling task (not a schema gap)

4.3 Enhancement Opportunities (P1 High)

# Enhancement Description Proposed Location
E1 Data Studio protocol Unified interactive data workspace combining views + charts + filters studio/data-studio.zod.ts (new)
E2 Template protocol Page templates for reuse and marketplace studio/template.zod.ts (new)
E3 Builder history state Undo/redo action stack with action types and serializable state Enhance page-builder.zod.ts
E4 Live preview protocol Schema for live data preview configuration in builders Enhance interface-builder.zod.ts

4.4 Future Vision (P2 Medium)

# Vision Description Timeline
V1 Collaborative editing CRDT-based real-time multi-user interface building v4.1+
V2 AI-assisted design Natural language → interface generation ("create a kanban board for tasks") v4.1+
V3 Page analytics Page views, element interactions, user engagement tracking v4.1+
V4 A/B testing Page variants with traffic splitting and conversion tracking v5.0+
V5 Mobile builder Touch-optimized interface builder for tablet devices v5.0+

5. Schema Enhancement Proposals

5.1 Page Builder Protocol Enhancement

Enhance studio/interface-builder.zod.ts with builder state management:

// Proposed additions to interface-builder.zod.ts

/** Selection model for multi-element operations */
export const BuilderSelectionSchema = z.object({
  selectedIds: z.array(z.string()).describe('Currently selected element IDs'),
  mode: z.enum(['single', 'multi', 'marquee']).default('single'),
});

/** Clipboard state for copy/paste */
export const BuilderClipboardSchema = z.object({
  items: z.array(z.object({
    type: z.string().describe('Component type'),
    properties: z.record(z.string(), z.unknown()),
    layout: BlankPageLayoutItemSchema.optional(),
  })).describe('Clipboard contents'),
  source: z.enum(['copy', 'cut']).describe('How items were placed on clipboard'),
});

/** Alignment tools configuration */
export const AlignmentToolsSchema = z.object({
  snapToElements: z.boolean().default(true).describe('Snap to other element edges'),
  showDistributionGuides: z.boolean().default(true).describe('Show equal spacing guides'),
  alignActions: z.enum([
    'align_left', 'align_center', 'align_right',
    'align_top', 'align_middle', 'align_bottom',
    'distribute_horizontal', 'distribute_vertical',
  ]).describe('Available alignment operations'),
});

/** Builder history entry for undo/redo */
export const BuilderHistoryEntrySchema = z.object({
  action: z.enum([
    'add_element', 'remove_element', 'move_element', 'resize_element',
    'update_properties', 'reorder_layers', 'paste', 'align',
  ]).describe('Action type'),
  timestamp: z.number().describe('Unix timestamp'),
  before: z.unknown().describe('State before action'),
  after: z.unknown().describe('State after action'),
});

/** Live preview configuration */
export const LivePreviewConfigSchema = z.object({
  enabled: z.boolean().default(true).describe('Enable live data preview'),
  sampleDataLimit: z.number().int().min(1).default(10),
  refreshInterval: z.number().int().min(0).default(0).describe('Auto-refresh in seconds (0 = manual)'),
  previewAs: z.object({
    userId: z.string().optional().describe('Preview as specific user'),
    role: z.string().optional().describe('Preview as specific role'),
    permissions: z.array(z.string()).optional().describe('Override permissions for preview'),
  }).optional().describe('User impersonation for design-time preview'),
});

5.2 Design-Time Preview Protocol

// Proposed: additions to studio/interface-builder.zod.ts

/** Design-time preview configuration */
export const DesignPreviewSchema = z.object({
  mode: z.enum(['design', 'preview', 'live']).default('design'),
  viewport: z.enum(['desktop', 'tablet', 'mobile']).default('desktop'),
  previewAs: z.object({
    userId: z.string().optional(),
    role: z.string().optional(),
    locale: z.string().optional(),
  }).optional(),
  showBoundaries: z.boolean().default(true).describe('Show element boundaries in design mode'),
  showDataBindings: z.boolean().default(false).describe('Show data binding indicators'),
});

5.3 Data Studio Protocol

A new protocol for the unified interactive data workspace:

// Proposed: studio/data-studio.zod.ts

/** Data Studio Configuration */
export const DataStudioConfigSchema = z.object({
  /** Default view mode when opening data */
  defaultView: z.enum(['grid', 'kanban', 'calendar', 'gallery', 'timeline', 'chart'])
    .default('grid'),
  
  /** Inline editing behavior */
  inlineEditing: z.object({
    enabled: z.boolean().default(true),
    singleClick: z.boolean().default(false).describe('Single click to edit (vs double-click)'),
    autoSave: z.boolean().default(true).describe('Auto-save on blur'),
    expandedRow: z.boolean().default(true).describe('Allow expand row to full record detail'),
  }).optional(),
  
  /** Embedded analytics sidebar */
  analytics: z.object({
    enabled: z.boolean().default(true),
    position: z.enum(['right', 'bottom']).default('right'),
    defaultCharts: z.array(z.string()).optional().describe('Pre-configured chart IDs'),
    showAggregationBar: z.boolean().default(true).describe('Show column footer with aggregations'),
  }).optional(),
  
  /** Quick filter bar */
  filterBar: z.object({
    enabled: z.boolean().default(true),
    position: z.enum(['top', 'left']).default('top'),
    savedFilters: z.boolean().default(true).describe('Allow saving filter presets'),
    globalFilter: z.boolean().default(true).describe('Cross-view global filter'),
  }).optional(),
  
  /** View switcher tabs */
  viewSwitcher: z.object({
    enabled: z.boolean().default(true),
    position: z.enum(['top', 'left']).default('top'),
    allowCreate: z.boolean().default(true).describe('Allow creating new views'),
    allowRename: z.boolean().default(true),
  }).optional(),
});

5.4 Template & Marketplace Protocol

// Proposed: studio/template.zod.ts

/** Interface Template */
export const InterfaceTemplateSchema = z.object({
  name: z.string().regex(/^[a-z_][a-z0-9_]*$/),
  label: z.string(),
  description: z.string().optional(),
  category: z.enum([
    'crm', 'project', 'hr', 'inventory', 'support',
    'marketing', 'finance', 'operations', 'custom',
  ]),
  thumbnail: z.string().optional().describe('Preview image URL'),
  interface: InterfaceSchema.describe('Template interface definition'),
  requiredObjects: z.array(z.string()).optional()
    .describe('Object names that must exist for this template'),
  variables: z.array(z.object({
    name: z.string(),
    label: z.string(),
    type: z.enum(['string', 'object_name', 'field_name']),
    description: z.string().optional(),
  })).optional().describe('Template variables that must be provided on instantiation'),
});

6. Studio Visual Builder UX Alignment Plan

6.1 Airtable UX Parity Matrix

UX Pattern Airtable ObjectStack Target Priority
Click element → Property panel ✅ Right sidebar Same — showPropertyPanel config exists P0
Drag from palette → Canvas ✅ Left palette Same — ElementPaletteItemSchema exists P0
Snap to grid with guides Same — CanvasSnapSettingsSchema exists P0
Multi-select with Shift/Cmd Add BuilderSelectionSchema P1
Copy/paste elements Add BuilderClipboardSchema P1
Alignment tools Add AlignmentToolsSchema P1
Undo/redo with history Enhance BuilderHistoryEntrySchema P1
Preview in different viewports Add DesignPreviewSchema.viewport P1
Preview as different user Add DesignPreviewSchema.previewAs P1
Template gallery Add InterfaceTemplateSchema P2
AI-assisted layout ObjectStack advantage — AI agent integration P2

6.2 Progressive Disclosure Strategy

Following Airtable's UX philosophy, the Studio builder should implement progressive disclosure:

Level 1 — Simple Mode (Default)

  • Pre-configured page templates (Dashboard, Grid, Form, Kanban)
  • Single-click element addition
  • Auto-layout with sensible defaults
  • No visible grid/snap configuration

Level 2 — Advanced Mode (Toggle)

  • Free-form blank canvas with grid
  • Manual element positioning
  • Layer ordering panel
  • Custom snap grid size

Level 3 — Expert Mode (Settings)

  • Full property inspector with all schema fields
  • Raw JSON/TypeScript editing
  • Custom element development
  • API binding configuration

6.3 Builder Experience Phases

Phase 1: Core Builder (v3.3 — Q4 2026)

  • Implement drag-and-drop canvas using BlankPageLayoutSchema
  • Element palette with all 12 component types
  • Property panel for selected element
  • Grid snap and alignment guides
  • Undo/redo (50 steps)

Phase 2: Data-Aware Builder (v4.0 — Q1 2027)

  • Live data preview in elements
  • previewAs user impersonation
  • Data source binding UI (visual ElementDataSourceSchema editor)
  • Responsive viewport switcher

Phase 3: Collaborative Builder (v4.1 — Q2 2027)

  • Real-time collaborative editing
  • Template gallery and instantiation
  • Version history (draft → published → archived)
  • AI-assisted layout suggestions

7. Updated Implementation Roadmap

Phase B Status Update (v3.3)

All spec schema work for Phase B is complete. Remaining work is Studio runtime:

Item Spec Status Studio Runtime Status
Interactive elements (button, filter, form, record_picker) ✅ Complete ❌ Pending
Element prop schemas ✅ Complete ❌ Pending
BlankPageLayoutSchema ✅ Complete ❌ Pending
PageVariableSchema integration ✅ Complete ❌ Pending
PageBuilderConfigSchema ✅ Complete ❌ Pending
Studio Page Builder UI N/A ❌ Pending

Phase C Status Update (v4.0)

Most spec schema work for Phase C is also complete:

Item Spec Status Runtime Status
SharingConfigSchema ✅ Complete ❌ Pending
EmbedConfigSchema ✅ Complete ❌ Pending
sharing and embed on AppSchema ✅ Complete ❌ Pending
sharing on FormViewSchema ✅ Complete ❌ Pending
Share link generation (runtime) N/A ❌ Pending
Embed code generation (runtime) N/A ❌ Pending
previewAs option ❌ Not in spec ❌ Pending
Security audit N/A ❌ Pending

New Optimization Items (Added by This Plan)

Version Item Type Priority
v3.3 Enhance PageBuilderConfigSchema (selection, clipboard, alignment, history) Spec P1
v3.3 Add DesignPreviewSchema (viewport, previewAs, boundaries) Spec P1
v4.0 Add DataStudioConfigSchema (inline editing, analytics sidebar, filter bar) Spec P1
v4.0 Add PageTemplateSchema (template marketplace) Spec P2
v4.1 Collaborative editing protocol (CRDT, presence, attribution) Spec P2
v4.1 Page analytics protocol (page views, interactions) Spec P2

8. Decision Log

# Decision Rationale Date
1 Keep UI / Data / Studio classification — do not restructure Classification is sound. Expand Studio with new files instead. 2026-02-16
2 Mark Phase B + C spec items as complete and update roadmaps Interactive elements, blank layout, sharing, embedding are all implemented. Roadmaps must reflect reality. 2026-02-16
3 Enhance PageBuilderConfigSchema rather than create new file Builder state management (selection, clipboard, history) belongs in the existing builder protocol. 2026-02-16
4 Add DataStudioConfigSchema as new file in studio/ Data Studio is a distinct concept from Dashboard (read-only) or ListView (single view). It deserves its own protocol. 2026-02-16
5 Add DesignPreviewSchema to interface-builder.zod.ts Preview configuration is builder-specific and belongs with other builder settings. 2026-02-16
6 Defer collaborative editing and AI-assisted design to v4.1+ These require significant runtime infrastructure (CRDT, AI service) not yet available. 2026-02-16

Related Documents

Document Location
Airtable Interface Gap Analysis docs/design/airtable-interface-gap-analysis.md
Main Roadmap ROADMAP.md
Studio Roadmap apps/studio/ROADMAP.md
Enterprise Assessment docs/ENTERPRISE_ASSESSMENT.md
DX Roadmap docs/DX_ROADMAP.md

Last Updated: 2026-02-16
Author: ObjectStack Core Team
Status: 📋 Active Planning — Ready for Implementation