# Arrow React Bootstrap — Guidelines

`arrow-react-bootstrap` is a React 18 component library that wraps T-Mobile's **Arrow Design System (TDDS)**. Each export is a pure React component reproducing Arrow's exact compiled HTML — no Lit runtime, no Shadow DOM. Markup fidelity equals pixel-perfect fidelity.

> Future GitLab-scoped name: `@tmobile/arrow-react`. Brands: T-Mobile (default), Metro, Assurance.

## Read these in order

1. `setup.md` — install, style import, ArrowThemeProvider, peer deps.
2. `foundations/overview.md` — color, spacing, modes, icons, input styling.
3. `composition/` and `patterns.md` — multi-component layouts and form patterns.
4. `components/{slug}.md` — per-component prop tables and design notes (auto-generated from each component's `.types.ts`).
5. `icon-discovery.md` — icon catalog and naming conventions.

## Top-level rules

1. **Import from package root.** Every component, hook, type, and utility is a named export of `arrow-react-bootstrap`.
2. **Import styles once at the app entry point** with `import 'arrow-react-bootstrap/styles'`. Never re-import in components.
3. **Wrap the app in `ArrowThemeProvider`.** It owns `inverse` (dark surfaces) and `brand` ('tmobile' | 'metro' | 'assurance').
4. **CSS prefixes are reserved.** Use `tdds-` (component classes) and `tdds:` (utility classes) only via Arrow's stylesheet — never override or mint new ones.
5. **No inline styles for layout, color, type, or spacing.** Use Arrow utility classes (`tdds:row`, `tdds:col-*`, `tdds:pa-*`, `tdds:typeset-*`).
6. **No compound component syntax.** There is no `Accordion.Item` or `Tabs.Tab`. Pass typed arrays via `items`, `tabs`, `chips`, etc.
7. **Form inputs require `id`, `label`, and (usually) `name`.** Omitting them breaks accessibility.
8. **Icons are `ReactNode`.** Pass SVG elements to `icon`, `leadingIcon`, `closeIcon`. Never pass strings.
9. **Do not duplicate ARIA Arrow already manages** (e.g., `aria-expanded` on Accordion, `role` on NoticeBar variants).
10. **Use `inverse` for dark sections — never custom dark-mode CSS.** Set it on the provider or per-component.

## Routing

| Topic | File |
|-------|------|
| Install + provider + bundler | `setup.md` |
| Color tokens & decision tree | `foundations/color.md` |
| Spacing scale & utilities | `foundations/spacing.md` |
| Theme + brand + inverse | `foundations/modes.md` |
| Icon foundation | `foundations/icons.md` |
| Floating label inputs | `foundations/input_styling.md` |
| Icon catalog | `icon-discovery.md` |
| Composition recipes | `patterns.md`, `composition/` |
| Per-component API | `components/{slug}.md` |
