# Install Protokit

Protokit is a prototype kit for coding agents: a themed component registry, design tokens with a WCAG AA
gate, and rules that keep a prototype inside what the kit ships. There are two kits on one set of tokens:

- **Mobile** (`apps/mobile`): Expo, React Native, NativeWind, react-native-reusables. Phone prototypes.
- **Web** (`apps/web`): Next.js, Tailwind 4, shadcn/ui. Dashboards, marketing pages, AI product interfaces.

If the person did not say which, ask: "a phone app, a web app, or both?"

## 1. Pick the path

> **Not yet:** paths A and B copy one kit out of the repo, and that kit installs `@itshendri/kit-tokens`
> from npm, which is not published yet, so `npm install` fails. Until it is, use path E (clone the repo)
> and work in `apps/mobile` or `apps/web`.

**A. New mobile prototype**

```bash
npx giget@latest gh:itsHendri/protokit/apps/mobile <project-name>
cd <project-name> && npm install
npm run ios        # or: npm run web
```

**B. New web prototype**

```bash
npx giget@latest gh:itsHendri/protokit/apps/web <project-name>
cd <project-name> && npm install
npm run dev        # http://localhost:3100
```

**C. Add kit components to an existing Expo app** that already uses react-native-reusables:

1. Add the registry to `components.json`:
   `"registries": { "@kit-native": "https://protokit-docs.empty-math-d572.workers.dev/r/native/{name}.json" }`
2. `npx shadcn@latest add @kit-native/theme @kit-native/lib-theme-context`, wrap the root
   layout in `<KitThemeProvider>`, then add components: `npx shadcn@latest add @kit-native/list-row`.
3. When shadcn asks to overwrite a react-native-reusables file (`text.tsx`, `button.tsx`, …), answer yes or
   pass `--overwrite`: kit components expect the kit's refined versions.
4. `npx expo install --fix` so Expo packages match the project's SDK.

**D. Add kit components to an existing Next.js app** that already uses shadcn/ui (Tailwind 4):

1. Add the registry to `components.json`:
   `"registries": { "@kit": "https://protokit-docs.empty-math-d572.workers.dev/r/web/{name}.json" }`
2. `npx shadcn@latest add @kit/theme` for the kit's colours and radius, then components:
   `npx shadcn@latest add @kit/data-table`. Components the kit did not change are plain shadcn
   items (`npx shadcn@latest add dialog`).
3. When shadcn asks to overwrite `button.tsx`, `badge.tsx` or `slider.tsx`, answer yes: the kit's versions
   fix colour contrast that kit components rely on.

**E. Mobile and web on one brand**: `git clone https://github.com/itsHendri/protokit.git`, `npm install` at the root, and work in
`apps/mobile` and `apps/web`. `apps/mobile/tokens/tokens.json` is the one brand file; `npm run tokens:sync`
copies it to the web kit.

## 2. Read before writing UI

In the kit you are working in:

- `AGENTS.md`: stack, commands, how a prototype is laid out (its own folder under `app/`), gotchas.
- `DESIGN_SYSTEM.md`: tokens, the component registry, patterns, anti-patterns, the hallucination guard.
- `llms.txt` in the project, or https://protokit-docs.empty-math-d572.workers.dev/llms.txt: every component with its API.
- The sample apps are the worked examples, the same products in both kits. Native: `app/shop`, `app/habits`,
  `app/northwind`. Web: `app/shop`, `app/habits`, and Northwind as `app/dashboard`, `app/landing`, `app/assistant`. Remove them with `npm run eject-samples` once you have copied their shape.

## 3. Rules (both kits)

- Build screens only from registry components, by their exact names. If something is missing, stop, say
  so in one line, and add it with the `add-component` skill. Never invent a component.
- Style with semantic classes only (`bg-card`, `text-muted-foreground`, `bg-primary/15`). No hex, no
  Tailwind palette colours, no inline colour styles.
- One primary action per screen. Content is flat; shadows only on what you can press or what floats.
- Mock data lives beside the prototype (`components/<slug>/data.ts`). Never call real APIs.
- Check every screen in light and dark. Run the `qc-pass` skill before saying "done".

**Mobile only:** text through `<Text variant>`, icons through `<Icon as={…} />` (lucide). Buttons hold
`<Text>`/`<Icon>`. Prefer a kit pattern over a new flow: screen skeleton, multi-step flow as one route,
`SuccessScreen`, `StickyBottomBar`.

**Web only:** a prototype's `layout.tsx` holds its frame (`AppShell` for an app, a plain header and footer
for a marketing page). Lucide icons from `lucide-react`, links as `<Button asChild><Link/></Button>`. Design
at 375px and 1280px. In an AI interface, ask with an `ApprovalCard` before anything irreversible.

## 4. Re-brand

Edit `tokens/tokens.json` (brand ramp, semantic colours, radius) and run `npm run tokens:build`. The build
refuses any palette where a fill and its text, or muted text on a surface, falls below 4.5:1, and names the
pairing.