create-arrow-react-bootstrap

Scaffold a Vite + React project pre-configured with T-Mobile's Arrow Design System and an AI-powered design-to-code workflow.

Quick Start

npm create arrow-react-bootstrap my-project
cd my-project
npm install
npm run dev

Open http://localhost:5173 — you'll see the getting-started home screen with instructions for both workflows.

What's Included

| Feature | Details | |---|---| | React 19 + TypeScript + Vite | Production-ready stack | | arrow-react-bootstrap | All 65 Arrow/TDDS components as React wrappers | | Arrow CSS + fonts | Loaded in main.tsx via import 'arrow-react-bootstrap/styles' | | ArrowThemeProvider | Wraps the app — theme context is ready out of the box | | ArrowIcon component | Access to 670 Arrow icons by name | | File-based routing | Drop a page in src/pages/ — it routes automatically | | Getting-started page | Home screen with workflow instructions | | Pre-configured agent skills | arrow-react-figma-coder and a11y-tester (Claude Code) |

Project Structure

After scaffolding, your project looks like this:

my-project/
├── src/
│   ├── pages/
│   │   └── Home.tsx              # Getting-started page (replace or keep)
│   ├── components/
│   │   └── ArrowIcon.tsx         # 670-icon component
│   ├── App.tsx                   # Shell with auto-routing
│   ├── router.tsx                # File-based hash router
│   └── main.tsx                  # React root + ArrowThemeProvider + styles
├── public/
│   └── icons-data.json           # Icon registry (loaded once, cached)
├── .claude/
│   └── skills/
│       ├── arrow-react-figma-coder/  # Figma-to-code skill
│       └── a11y-tester/              # Accessibility audit skill
├── agent-team-workspace/               # Agent collaboration workspace (gitignored)
├── index.html
├── vite.config.ts
└── tsconfig.json

File-Based Routing

Pages are auto-discovered — no manual wiring needed. Create a PascalCase .tsx file in src/pages/ and it immediately appears as a route:

| File | Route | |---|---| | src/pages/Home.tsx | /#/ (default) | | src/pages/BillingOverview.tsx | /#/billing-overview | | src/pages/ContactForm.tsx | /#/contact-form | | src/pages/AccountSettings.tsx | /#/account-settings |

Created pages automatically appear in the "Pages built" list on the home screen.

Two Ways to Build Pages

1 — From a Figma Design

Take any Figma frame that uses Arrow components and turn it into a working React page.

Prerequisites: Figma MCP must be configured (see MCP Setup below).

Steps:

1. In Figma, select the frame you want to code
2. Right-click → Copy link to selection
3. Paste the link into a Claude Code prompt:

Code this design using the Arrow design system
https://figma.com/design/abc123/MyFile?node-id=1-4468

The arrow-react-figma-coder skill activates automatically. It runs a multi-agent team through 7 phases:

| Phase | Agent | What happens | |---|---|---| | 1 | Figma Agent | Reads the design, extracts component manifest | | 2 | Designer | Analyzes layout, creates section assignments | | 2.5 | Custom Component Developer | Builds any non-Arrow components (if needed) | | 3 | 3 Developers (parallel) | Code their assigned sections | | 4 | Accessibility Tester | WCAG 2.2 AA audit via axe-core | | 5 | QA Tester | Pixel-perfect visual comparison | | 6 | Critic | Final code, spec, design, and a11y review | | 7 | PM | Presents to you, handles feedback |

You get a pixel-perfect, accessible React page — no manual coding required.

2 — From a Description

No Figma file? Describe what you want and the agent builds it from scratch using Arrow components.

Build me an account overview page with a bill card,
a tab section for plan details and usage, and an FAQ
accordion at the bottom.

The agent searches the Arrow component library via the Arrow MCP, picks the best components for your description, and composes a complete page.

Available Components

All 65 Arrow components are available from arrow-react-bootstrap:

import {
  Accordion, AccordionButton, Avatar, BillCard, BroadbandFacts,
  Button, ButtonGroup, ButtonGroupHorizontal, ButtonStyledAsLink, ButtonTray,
  Checkbox, Chips, ColorSelector, CreditCardInput,
  DisclosureCard, DisclosureCardSecondary, DisclosureMenu,
  Divider, DotLoader, DropdownButton, FilterChip,
  FullPageInterruption, HybridBarChart, IconButton,
  Legend, Link, LinkStyledAsButton,
  List, ListItem, ListItemFilter, ListItemHsi, ListItemNavigation,
  ListItemTrailingIcon, Lists, Menu, MenuButton, MenuDropdown, Modal,
  NoticeBar, PaginationDot, PasswordField, ProgressBar, ProgressRing,
  PromoBanner, PromoLabel, PurchaseSummaryBar,
  RadioGroup, Search, SearchingInput, SectionHeader, Select, Snackbar,
  StatusLabel, StepIndicator, Stepper, StyledRadioGroup,
  Subnavigation, Table, Tabs, TextArea, TextField, TextingInput,
  Tidbit, Tile, Title, Toggle
} from 'arrow-react-bootstrap';

Icons

The scaffolded project ships with an ArrowIcon component that renders any of the 670 Arrow icons by name. Icons load once from /icons-data.json and are cached globally.

import { ArrowIcon } from '../components/ArrowIcon';

// Decorative icon (most common)
<ArrowIcon name="chevron-right-outlined" />

// Meaningful icon with accessible label
<ArrowIcon name="info-circle-outlined" ariaLabel="Information" />

// Custom size (default is 20px)
<ArrowIcon name="close-outlined" size={24} />

To find an icon name, search public/icons-data.json for keywords like "chevron", "close", "check", "account".

Common icon names:

| Name | Use case | |---|---| | chevron-right-outlined | Trailing icon for tertiary buttons | | chevron-down-outlined / chevron-up-outlined | Expand/collapse | | info-circle-outlined | Info tidbits | | close-outlined | Close/dismiss | | check-circle-filled | Success states | | warning-outlined | Warning states | | account-outlined | User/profile |

Writing Pages Manually

If you prefer to write pages yourself instead of using the AI workflow:

// src/pages/BillingOverview.tsx
import { BillCard, Tabs, Accordion, Divider, SectionHeader } from 'arrow-react-bootstrap';
import { ArrowIcon } from '../components/ArrowIcon';

export default function BillingOverview() {
  return (
    <div className="tdds:container-md tdds:pt-5 tdds:pb-5 tdds:pl-2 tdds:pr-2">
      <h1 className="tdds:text-title-1">Billing Overview</h1>

      <BillCard
        amount="$85.00"
        dueDate="Dec 15"
        status="current"
      />

      <Divider />

      <SectionHeader heading="h2" label="Plan Details" />

      <Tabs
        ariaLabel="Billing tabs"
        tabs={[
          { id: 'details', label: 'Plan Details', content: <p>Plan content here</p> },
          { id: 'usage', label: 'Usage', content: <p>Usage content here</p> },
        ]}
      />
    </div>
  );
}

The page appears at /#/billing-overview automatically. No editing App.tsx or router.tsx.

Layout Utilities

Arrow utility classes use a tdds: prefix:

| Class | Effect | |---|---| | tdds:container-md | Centered content container (medium width) | | tdds:pt-5, tdds:pb-5 | Top/bottom padding (5 = ~3rem) | | tdds:pl-2, tdds:pr-2 | Side padding | | tdds:mt-3, tdds:mb-3 | Top/bottom margin | | tdds:d-flex | display: flex | | tdds:text-title-1 | Title-1 typography style | | tdds:text-body | Body typography style |

Rules

The project uses Arrow CSS exclusively — no Tailwind, no custom CSS files:

1. All components from arrow-react-bootstrap — never write raw tdds-* HTML markup
2. No inline style attributes — use Arrow utility classes (tdds:*) or component props
3. No custom CSS files — Arrow CSS handles all component styling
4. ArrowThemeProvider and styles are in main.tsx — do not import them again in pages
5. Pages go in src/pages/ — they are auto-routed, no manual wiring needed

MCP Setup

The arrow-react-figma-coder skill requires MCP servers to be configured in Claude Code. Run these commands once:

# Figma MCP (Required for Figma workflow)
claude mcp add figma --transport http https://mcp.figma.com/mcp

# Playwright MCP (Required — headless for background browser testing)
claude mcp add playwright -- npx @playwright/mcp@latest --headless

# Arrow MCP (Recommended — enables component search by description)
claude mcp add --transport stdio --scope user official-arrow-mcp -- npx -y @tmobile/arrow-mcp@latest

# MagentaA11y MCP (Recommended — accessibility guidance)
claude mcp add magentaa11y-mcp -- npx -y magentaa11y-mcp

Without Figma MCP, only the description-based workflow is available. Without Playwright MCP, accessibility and QA testing phases are skipped.

Agent Skills

The scaffolded project includes two Claude Code skills in .claude/skills/:

arrow-react-figma-coder

Converts Figma designs to React pages using arrow-react-bootstrap. Runs a team of 8 specialized agents through 7 mandatory phases including design analysis, parallel development, WCAG 2.2 AA accessibility testing, pixel-perfect visual QA, and a final critic review.

Activate by pasting a Figma URL into any prompt. No slash command needed — the skill detects Figma URLs automatically.

a11y-tester

Standalone WCAG 2.2 AA audit. Runs axe-core via Playwright against any page in the app and reports issues by severity (Critical → High → Medium → Low).

/a11y-tester http://localhost:5173/#/billing-overview

Commands

| Command | What it does | |---|---| | npm run dev | Start Vite dev server at http://localhost:5173 | | npm run build | Production build | | npm run preview | Preview the production build |