Local Design System Sync Workflow

This guide covers how to sync components from juniro-design to the web portals locally for development and testing.

Overview

The design system sync copies components, styles, utilities, and types from juniro-design (source of truth) to the web application repositories.

juniro-design (source)
       ↓
   sync scripts
       ↓
├── juniro-web-public
├── juniro-web-parents
├── juniro-web-providers
└── juniro-web-admin

Quick Reference

Command	What it does
./sync-smart.sh	Sync all portals with validation (default)
./sync-smart.sh --mode=quick	Fast sync, no validation
./sync-smart.sh --mode=full	Sync + validation + E2E tests
./sync-smart.sh --portal=public	Sync only the public portal

Scripts Location

All sync scripts are in juniro-infra/scripts/:

Script	Target Portal
sync-smart.sh	Recommended - Wrapper with validation
sync-local-public.sh	juniro-web-public
sync-local-parents.sh	juniro-web-parents
sync-local-providers.sh	juniro-web-providers
sync-local-admin.sh	juniro-web-admin

Sync Modes

Quick Mode (--mode=quick)

When to use: Rapid iteration during development when you just want to test a visual change.

./sync-smart.sh --mode=quick --portal=public

• ✅ Fastest
• ⚠️ No validation - might sync broken code
• ⚠️ Skips pre/post checks

Validate Mode (--mode=validate) - Default

When to use: Normal development workflow. Recommended for most cases.

./sync-smart.sh --portal=parents
# or explicitly:
./sync-smart.sh --mode=validate --portal=parents

• ✅ Pre-sync: Builds juniro-design, runs lint & tests
• ✅ Post-sync: Lints the target portal
• ✅ Catches errors before they propagate
• ⚠️ Doesn't run E2E tests

Full Mode (--mode=full)

When to use: Before creating a PR or after major changes.

./sync-smart.sh --mode=full

• ✅ All validation checks
• ✅ Runs Playwright E2E tests
• ⚠️ Slower (E2E tests take time)
• ✅ Most thorough validation

What Gets Synced

Source (juniro-design)	Destination (portal)
src/components/ui/shared-core/	src/components/design-system/components/shared-core/
src/components/ui/shared-customer/	src/components/design-system/components/shared-customer/
src/components/ui/public/	src/components/design-system/components/public/ (public portal only)
src/components/ui/parent-portal/	src/components/design-system/components/parent-portal/ (parents only)
src/components/ui/provider-portal/	src/components/design-system/components/provider-portal/ (providers only)
src/components/ui/admin-portal/	src/components/design-system/components/admin-portal/ (admin only)
src/styles/globals.css	src/components/design-system/styles/globals.css
src/utils/	src/components/design-system/utils/
src/mocks/	src/mocks/
src/types/	src/types/
src/tokens/	src/tokens/

What's Excluded

• *.stories.tsx - Storybook files
• *.test.tsx, *.test.ts - Test files
• mocks/ directories within components
• docs/ directories within components

Import Path Transformations

The sync scripts automatically transform import paths:

Before (juniro-design)	After (portal)
@/components/ui/	@/components/design-system/components/
@/utils/shared-customer	@/components/design-system/utils/shared-customer
@/hooks/shared-customer	@/components/design-system/hooks/shared-customer

Recommended Workflow

Daily Development

# 1. Make changes in juniro-design
cd juniro-design
# ... edit components ...

# 2. Verify in Storybook
bun run storybook:customer

# 3. Sync to portal with validation
cd ../juniro-infra/scripts
./sync-smart.sh --portal=parents

# 4. Test in portal
cd ../../juniro-web-parents
bun run dev

Before Creating a PR

# Full validation with E2E tests
./sync-smart.sh --mode=full

# Or for a specific portal
./sync-smart.sh --mode=full --portal=public

When You Just Need Speed

# Quick sync (skip all checks)
./sync-smart.sh --mode=quick --portal=public

Validation Flow

┌─────────────────────────────────────────────────────────────┐
│                    PRE-SYNC CHECKS                          │
├─────────────────────────────────────────────────────────────┤
│  1. TypeScript build (juniro-design)                        │
│  2. ESLint check                                            │
│  3. Vitest tests                                            │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                       SYNC                                  │
├─────────────────────────────────────────────────────────────┤
│  • Clean target directories                                 │
│  • Copy components (excluding stories/tests)                │
│  • Copy styles, utils, types, tokens, mocks                 │
│  • Transform import paths                                   │
│  • Apply compatibility fixes                                │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                  POST-SYNC CHECKS                           │
├─────────────────────────────────────────────────────────────┤
│  1. Portal build verification                               │
│  2. ESLint check                                            │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                 E2E TESTS (full mode only)                  │
├─────────────────────────────────────────────────────────────┤
│  • Playwright tests for portal                              │
│  • Accessibility checks (axe-core)                          │
│  • Dark mode verification                                   │
│  • Responsive tests                                         │
└─────────────────────────────────────────────────────────────┘

Troubleshooting

Sync fails with TypeScript errors

# Check what's broken in juniro-design first
cd juniro-design
bun run build

# Fix the errors, then sync again

Portal won't build after sync

Check for:

1. Missing dependencies (component uses something not synced)
2. Import path issues (check the transformation rules)
3. API changes (component signature changed)

# Run lint to find issues
cd juniro-web-parents
bun run lint

E2E tests fail

# Run E2E tests directly with debug output
cd juniro-infra/e2e
npx playwright test --project=parents --headed --debug

I need to skip validation

Use --mode=quick but understand the risks:

./sync-smart.sh --mode=quick --portal=public

Or skip specific checks:

./sync-smart.sh --skip-pre --portal=public   # Skip pre-sync checks
./sync-smart.sh --skip-post --portal=public  # Skip post-sync checks

Integration with AI Agents

The sync workflow integrates with our AI agents:

When	Agent	Purpose
Before sync	@design-audit	Verify design system compliance
Before sync	@ship-check	Quick quality gate
After sync	@a11y-audit	Accessibility verification
Before PR	@verifier	Prove work is complete

Example workflow with agents:

# 1. In juniro-design, run design audit
# @design-audit (in Cursor)

# 2. If audit passes, sync
./sync-smart.sh --mode=validate --portal=parents

# 3. Test locally, then before PR:
./sync-smart.sh --mode=full

# 4. Run @ship-check on the portal
# @ship-check (in Cursor)

CI/CD vs Local Sync

Aspect	Local Sync	CI/CD Sync (GitHub)
Speed	Fast (~30s)	Slower (~2-3 min)
Triggers	Manual	Push to main
Validation	Configurable	Full checks
Use case	Development	Production

Rule: Local sync for development, CI/CD handles production deployments.

Related Documentation

• Agent Registry - AI agent documentation
• Ship Check Guidelines - Quality gate criteria
• Component Status - Component inventory
• Contributing Guidelines - How to contribute

---

Appendix: Script Options Reference

sync-smart.sh

Usage: ./sync-smart.sh [options]

Options:
  --portal=<portal>  Target portal: public, parents, providers, admin, all
                     Default: all
  
  --mode=<mode>      Sync mode: quick, validate, full
                     Default: validate
  
  --skip-pre         Skip pre-sync checks (build/lint in juniro-design)
  
  --skip-post        Skip post-sync checks (lint in target portal)
  
  --help, -h         Show help message

Individual sync scripts

The individual scripts (sync-local-public.sh, etc.) don't have options - they run a fixed sync process with build verification at the end.

# Run directly (no options)
./sync-local-public.sh