Onboarding

Everything you need to get started with the Design Prototypes repo.

What Is This?

An AI-powered React + Vite app where you describe a feature idea and get back a working prototype, a Figma design, and a dev spec — all using real Encore design system components.

Two Prototype Modes

Quick (phases 1-2) uses @mui/material with sx for fast ideation. Dev-handoff (phase 3) uses @locus-taxy/encore-mui with strict component-props-only styling.

Quick Start

Clone the repo, run yarn install and yarn dev. Create a prototype with yarn create-prototype <name> "description" --quick or just describe what you want in Claude Code.

The AI Pipeline

Understand (domain context + brief) → Design & Build (Figma + code) → Review & Iterate (visual checks) → Publish (spec + Jira + Confluence).

Component Libraries

encore-mui for all MUI components + custom Encore components, icons, DataGrid, and date pickers. encore-ui-toolkit for maps, timelines, tables, and navigation.

Key Rules

No raw HTML, no third-party UI, no CSS files, no hardcoded colors, no HTTP requests. All data is mock data. All UI comes from MUI/Encore components. All styling via theme tokens.

Setup

Prerequisites

Node.js 20.18.0 (pinned via Volta)
Yarn 4.6.0 (Corepack)
Access to the @locus-taxy npm scope (GitHub Packages Registry)
Claude Code CLI (for AI-powered prototype generation)

Running Locally

          cd design-prototypes

          yarn install

          yarn dev # Starts at http://localhost:5173

Creating a Prototype

          # Quick prototype (ideation — @mui/material)

          yarn create-prototype order-tracking "Order tracking dashboard" --quick

          # Dev-handoff prototype (production — @locus-taxy/encore-mui)

          yarn create-prototype order-tracking "Order tracking dashboard"

Or simply describe what you want to build in Claude Code — the pipeline handles everything automatically.

Repo Structure

src/
  App.tsx                     # All routes and prototype registry
  components/                 # PrototypeShell, PasswordGate, MobileFrame
  theme/figma-theme.ts        # Design tokens and MUI theme
  providers/                  # MockProviders, ThemeContext
  mock-data/                  # Shared mock data (orders, vehicles, users...)
  prototypes/
    _template/                # Dev-handoff scaffold
    _template-quick/          # Quick prototype scaffold
    quick/                    # Quick prototypes (ideation)
    playground/               # AI-generated prototypes (DSU, NCM...)
    dashboard-example/        # Reference: dashboard patterns
    form-example/             # Reference: form patterns

.claude/skills/               # 23 custom Claude Code skills
docs/                         # Pattern guides (dashboard, mobile)
artifacts/                    # Project plan, specs, session logs
landing-page/                 # This site (design.locus.sh)
scripts/                      # create-prototype.sh
        

Prototype File Convention

Every prototype follows this structure:

src/prototypes/quick/my-feature/    # or playground/my-feature/
  MyFeaturePage.tsx    # Main page component (exported + routed)
  meta.ts              # Title, description, status, author, date, route
  components/          # Page-specific sub-components (optional)
  data.ts              # Page-specific mock data (optional)
        

Git Workflow

Default branch: master
Branch naming: feature/<name>, fix/<name>, or chore/<name>
Process: branch off master → commit → push → create PR → review → merge
Never commit directly to master — always use a feature branch + PR
Package manager: always yarn (never npm)

Key Resources

Prototypes design.locus.sh/prototypes DLS Documentation dls-doc.locus.sh Figma Component Library MUI Encore components Slack Channel #locus-dls-feedback

Full onboarding guide on GitHub