Process Overview

Our development process ensures that what's designed is what gets built. Work flows through three distinct stages with clear deliverables and responsibilities at each step.

Workflow Stages

flowchart LR
    UX[UX Discovery] --> Figma[Figma Design] --> dApp[dApp Implementation]
    
    style UX fill:#e3f2fd
    style Figma fill:#fff3e0
    style dApp fill:#e8f5e9

Each stage builds on the previous one, ensuring alignment from concept to code.

UX Discovery

The UX stage establishes the foundation for everything that follows. Clear requirements at this stage prevent costly changes later.

Required Deliverables

Goal and Scope

MUST define:

Business objective - What problem are we solving?
Target user - Who is this for?
Success metrics - How do we measure success?
Constraints - Technical, timeline, or resource limitations

Example:

Goal: Enable users to browse and filter their land parcels efficiently
Target: Land owners with 10+ parcels
Success: 80% of users can find a specific parcel in under 10 seconds
Constraints: Must work on mobile; no backend changes allowed

Interaction Flows

MUST map end-to-end user journeys:

All use cases - Primary and secondary user paths
Edge cases - Empty states, first-time users, errors
Alternate paths - Different ways to accomplish goals
Visual aids - Wireframes or flow diagrams when helpful

Example:

Primary Flow:
1. User clicks "My Land"
2. System loads parcels
3. User applies filter
4. Results update immediately

Edge Cases:
- User has no parcels → Show empty state with CTA
- Filter returns no results → Show "no results" message
- Loading takes >2s → Show skeleton loaders

UI States

SHOULD specify all component states:

Idle - Default state
Loading - Data fetching or processing
Error - Failed operations
Empty - No data available
Success - Successful operations
Disabled - Unavailable actions

SHOULD outline error recovery:

What happens when an error occurs?
How can users retry or resolve it?
What information do users need?

Analytics Tracking

MUST agree on tracking at this stage:

Events - What actions to track
Properties - What data to capture
User properties - Relevant user attributes
Conversion goals - Key success metrics

Example:

Events:
- parcel_filter_applied { filter_type, filter_value }
- parcel_selected { parcel_id, source }
- parcel_transfer_initiated { parcel_id }

Properties:
- user_parcel_count
- filter_used (boolean)
- time_to_result (ms)

Recommended Deliverables

Accessibility Intent

SHOULD describe:

Keyboard flows - Tab order and shortcuts
Focus order - Logical focus progression
Screen reader labels - ARIA labels and descriptions
Alternative content - Text for images, icons, graphs

Example:

Keyboard Navigation:
- Tab: Navigate through filters
- Enter: Apply selected filter
- Escape: Close filter dropdown
- Arrow keys: Navigate filter options

Screen Reader:
- "Filter by: Owner address. Type to search or select from list"
- "3 parcels found matching your filters"

Accessibility Readability

SHOULD ensure:

Color contrast - Minimum WCAG AA ratios
- Normal text: 4.5:1
- Large text (18pt+): 3:1
- UI components: 3:1
Text sizing - Readable at default sizes
Interactive targets - Minimum 44×44px touch targets

UI Interactive Elements

SHOULD define states for all interactive elements:

Enabled - Default interactive state
Disabled - Non-interactive state
Hover - Mouse over (desktop)
Pressed/Active - During interaction
Focus - Keyboard focus state

SHOULD specify user feedback:

Visual changes on interaction
Loading indicators
Success/error messages
Haptic feedback (mobile)

Figma Design

Designers MUST start from our Figma library, which mirrors Material UI components and uses the Decentraland theme defined in UI2.

Special colors, sizes, or styles SHOULD NOT be used. Exceptions may exist but MUST be justified in the spec and approved during review.

Required Standards

Use Decentraland Figma Library

MUST use MUI components when an equivalent exists:

Check MUI component library first
Use Decentraland variants and styles
Don't create custom versions of existing components

If a required UI element doesn't exist:

Check if it can be composed from existing components
If not, propose a custom component (see Custom Components)
Document the rationale in the spec
Get approval during design review

Colors

MUST match Figma color styles to UI2 theme names:

import { dclColors } from 'decentraland-ui2';

// Figma "Rarity / Unique" → Code
dclColors.rarity.unique

// Figma "Primary / Main" → Code
theme.palette.primary.main

// Figma "Text / Secondary" → Code
theme.palette.text.secondary

Source of truth: colors.ts

Typography

MUST use defined variants:

Available variants:

h1, h2, h3, h4, h5, h6 - Headings
subtitle1, subtitle2 - Subheadings
body1, body2 - Body text
button - Button text
caption - Captions
overline - Overline text

References:

Example mapping:

Figma "H1" → <Typography variant="h1">
Figma "Body 1" → <Typography variant="body1">
Figma "Caption" → <Typography variant="caption">

Breakpoints

MUST design for these breakpoints:

Name	Width	Typical Device
`xs`	768px	Mobile
`sm`	991px	Tablet
`md`	1024px	Small Desktop
`lg`	1280px	Desktop
`xl`	1500px	Large Desktop

Source: index.ts

Best practices:

Design mobile-first (start at xs)
Show key breakpoints in Figma frames
Document responsive behavior
Test at viewport edges (767px, 768px, etc.)

Border Radius and Palettes

MUST use theme-defined values:

Don't introduce new border radius values
Don't create new palette roles
Exceptions require spec justification and approval

Theme values:

theme.shape.borderRadius // Default radius
theme.palette.primary    // Primary colors
theme.palette.secondary  // Secondary colors
theme.palette.error      // Error colors
theme.palette.text       // Text colors
theme.palette.background // Background colors
theme.palette.divider    // Divider colors

Color Schemes

If the screen supports multiple color schemes:

MUST provide:

Which scheme applies (see colorSchemes.ts)
Light mode preview
Dark mode preview
Documentation on switching schemes in Storybook

Example:

Supported Schemes: Light, Dark
Default: System preference
Toggle: Settings menu → Appearance
Storybook: Use "Theme" control in toolbar

Component Selection

SHOULD reuse prepared components:

Check MUI first - Does MUI have this component?
Check UI2 - Is there a Decentraland variant?
Compose if possible - Can you combine existing components?
Custom as last resort - Follow Custom Components process

dApp Implementation

Developers implement designs using UI2 components and following our Styling & Theming standards.

Implementation Checklist

Start with UI2 component if available
Use MUI component with Decentraland theme if no UI2 equivalent
Follow Styling & Theming standards
Implement all states from UX spec
Add analytics tracking as specified
Test at all breakpoints
Verify keyboard navigation
Check color contrast
Test with screen reader
Handle loading and error states
Add to Storybook if it's a reusable component

Component Implementation Flow

1. Check UI2 for component
   ↓
2. Found? → Use it
   ↓
3. Not found? → Check MUI
   ↓
4. Found in MUI? → Use with Decentraland theme
   ↓
5. Need customization? → See Custom Components guide
   ↓
6. Implement following Styling standards
   ↓
7. Add to Storybook (if reusable)

Quality Gates

Before marking implementation complete:

Visual match - Matches Figma pixel-perfect at key breakpoints
Theme compliance - All values from UI2 theme
States implemented - All UX-specified states work
Accessibility - Keyboard nav, focus states, ARIA labels
Analytics - Events fire as specified
Responsive - Works at all breakpoints
Performance - No unnecessary re-renders
Tests - Component tests pass
Storybook - Stories added (if reusable)
Code review - Approved by maintainers

Handoff Best Practices

From UX to Design

Clear requirements document
User flows with annotations
State diagrams for complex interactions
Analytics event specifications

From Design to Development

Figma file with dev mode enabled
Component specifications
Responsive behavior notes
Color and typography token mapping
Accessibility annotations
Link to UX requirements

During Implementation

Regular check-ins between designer and developer
Early feedback on technical constraints
Iterative reviews at key milestones
Final review before merging

Next Steps

Learn about Custom Components for creating new components
Review Styling & Theming for implementation details
See Migration Guide if working with UI1 components