TrackItPilot Developer Docs
This is TrackItPilot's design system and frontend developer documentation — an
in-repo Markdown reference for the tokens, tip-* components, and composed screen
patterns that make up app/frontend. It is kept in sync with the
code, not a one-time snapshot: every time the frontend's tokens, components, or
patterns change, the matching doc changes in the same commit (see
CONTRIBUTING.md).
The developer PaaS portal (
developer.trackitpilot.com— third-party API keys, usage, Stripe billing for/v1/parse-do,/v1/port-status,/v1/driver-check-call) is a separate, not-yet-built surface also planned to live underapp/developer-doc/; seedoc/prd.md§6 for that spec. This README currently indexes the design-system documentation only.
Stack
app/frontend is Angular 22 — standalone components (no NgModules), OnPush change
detection, Angular Signals for reactive state, Tailwind CSS v4 (@theme mapped onto the
same design tokens components use), and @lucide/angular for icons. See
app/frontend/README.md for the runnable stack (build/test
commands) and current scaffolding status.
Where to start
| Doc | What's in it |
|---|---|
| design-system/README.md | Design-system overview, principles, full component index |
| design-system/tokens.md | Colors, typography, spacing/radii, shadows/effects, motion tokens — real names + values |
| design-system/conventions.md | Component conventions: standalone + OnPush + signals, tip-* selectors, token-only styling, icons, testing, file layout |
| design-system/components/ | One doc per tip-* component — selector, API table, usage, notes |
| design-system/patterns/settings.md | Two-pane admin Settings pattern (Shopify App Home aligned) |
| design-system/patterns/auth.md | Split-screen login/sign-up pattern |
| design-system/patterns/dashboard.md | Home, Orders, Order Details screen patterns |
| CONTRIBUTING.md | The contract: how a component/pattern/token change keeps these docs current |
Component index
| Component | Selector | One-liner | Doc |
|---|---|---|---|
| Icon | tip-icon |
Lucide icon wrapper by kebab-case name | icon.md |
| Button | tip-button |
Primary action control, 4 variants × 3 sizes | button.md |
| Badge | tip-badge |
Tone-driven status pill | badge.md |
| Card | tip-card |
Base panel surface, 4 variants + accent border | card.md |
| Avatar / Avatar Group | tip-avatar / tip-avatar-group |
Identity chip with status dot; overlapping stack | avatar.md |
| Skeleton | tip-skeleton |
Shimmering loading placeholder | skeleton.md |
| Input | tip-input |
Text field, icon + pill/rounded shape | input.md |
| Select | tip-select |
Native-backed dropdown filter | select.md |
| Checkbox | tip-checkbox |
Row/select-all control w/ indeterminate | checkbox.md |
| Radio | tip-radio |
Single circular radio (caller owns the group) | radio.md |
| Stat Card | tip-stat-card |
KPI tile — value, rows, progress, footnote | stat-card.md |
| Progress Bar | tip-progress-bar |
Single or multi-segment fill track | progress-bar.md |
| Nav Item | tip-nav-item |
Sidebar nav row, active + badge | nav-item.md |
| Nav List | tip-nav-list / tip-nav-list-item |
Bordered "interstitial nav" drill-down rows | nav-list.md |
| Activity Item | tip-activity-item |
Toned timeline/stream card | activity-item.md |
| Empty State | tip-empty-state |
"Nothing here yet" block + CTA slot | empty-state.md |
| Menu / Menu Item | tip-menu / tip-menu-item |
Popover menu with nested submenu flyouts | menu.md |
| Modal | tip-modal |
Centered overlay dialog, parent-controlled open |
modal.md |
| Toast | tip-toast-host (+ ToastService) |
App-wide toast queue | toast.md |
| Save Bar | tip-save-bar |
Sticky unsaved-changes bar | save-bar.md |
How this evolves
There is no separate design-doc review cadence — the rule is simple: a PR that adds or
changes a tip-* component, introduces a new screen pattern, or edits a design token
updates the matching file here in the same PR. CONTRIBUTING.md spells
out the exact contract per change type. Treat drift between this documentation and
app/frontend/src as a bug.