# RJ DTC Admin design system

The design system for the RJ DTC admin, the "Fine Worsted · Satin Lapel" direction Frank approved. It is built for the front-end team turning the 64 approved surfaces into the Next.js 15, Tailwind 3.4 and shadcn/ui (new-york) admin in `rj-dtc` `apps/admin`. Every value on these pages is generated from `phase-2/kit/tokens.css` at build time, so the docs cannot drift from the kit.

**Kit v3** · Next.js 15 · Tailwind 3.4 · shadcn/ui new-york · Archivo · IBM Plex Sans · IBM Plex Mono

## Start here

### Principles

- **Calm.** A light, white canvas and one RJ midnight-navy accent (#0E1729) on the sidebar and the primary action. Status colour is for status only.
- **Quiet.** Hairlines, soft 6px corners, small shadows and short, crisp motion. Nothing glows except the faint sidebar light, and no button ever does.
- **One primary per screen.** Each screen has one filled navy button for the thing you came to do. Everything else steps down.
- **Ranked actions.** Primary, then secondary (outlined), tertiary (text), ghost, then the two danger forms. Labels say what happens: "Publish to brands", "Save draft".
- **Fabric does the visual work.** Cloth photography and garment thumbnails on the studio ground carry the colour. The interface stays out of their way.
- **Two dedicated compositions.** Desktop (1440) and phone (390) are separate layouts on separate URLs, sharing tokens and data. On a phone, tables become lists and sheets become bottom sheets.

### How to use these docs

- **Foundations** holds every token: colour (with the shadcn HSL mapping and contrast), type, spacing, layout, radius, elevation, gradients, motion, focus, icons and z-index. Each value has a copy button.
- **Components** has one page per component: anatomy, variants, every state, exact specs, motion and accessibility, content rules, the shadcn/Radix equivalent, a suggested React props interface, a live specimen and the surfaces that use it.
- **Patterns** shows how components combine into screens: the HQ and brand shells, ranked actions, tables, forms, overlays, the status vocabulary, empty / loading / error / not-wired, toasts, page help, phone patterns and the voice.
- **Implementation** is the Next.js 15 + Tailwind 3.4 + shadcn/ui setup: the drop-in `tailwind.config.ts`, the `globals.css` variable block, `components.json`, font loading with `next/font`, server vs client components, the kit.js behaviours to rebuild, and the gotchas found during the build.
- **Surfaces** links all 64 approved pages, desktop and phone, grouped as in `PAGE-MAP.md`.
- Search with **/** on desktop, or the menu button on a phone. Every page has a dedicated phone version: use the **Phone page** link, or open the same URL on a phone.

### Files in the hand-off folder

All paths are relative to `projects/pina/brands/brand-005-rj-dtc-admin/`.

| File | What it is |
|---|---|
| `PAGE-MAP.md` | The integration checklist: one row per admin URL → the surface to copy → the components it uses. Start here when you build. |
| `PROPOSALS.md` | Everything the designs add beyond today's admin, tagged UI-only, needs-backend or needs-a-decision. The 10 decisions for Frank are at the top. |
| `phase-2/kit/tokens.css` | The source of truth for every value. Ship it as-is. |
| `phase-4/tokens.json` | The same tokens in W3C design-tokens format. |
| `phase-4/implementation-files/` | Generated `tailwind.config.ts` (3.4), `globals.css` block and `components.json` for `apps/admin`. |
| `phase-4/DESIGN-SYSTEM.md` | This whole site as one markdown file, for repo docs. |

### Version and changelog

This is **Kit v3** of the kit. The full log is `phase-2/kit/KIT-CHANGELOG.md`.

| Pass | What changed |
|---|---|
| Round 2 kit: integration pass changelog | **Client:** brand-005-rj-dtc-admin (RJ DTC Admin) · **Direction:** Fine Worsted · Satin Lapel, Archivo at normal width · **Pass:** 2026-10-11, after all ten families landed. |
| v2 · Round 4 page promotion (2026-10-11) | **Pass:** after all 64 Round 4 page folders landed (68 routes). Every page `NOTES.md` "CONTRACT GAPS / Kit gaps" section was read. Anything raised by two or more page teams, plus the shell fixes every team hit, moved into the shared layer. Every value is the one the approved pages already use, so the pages look exactly as approved. New specimen family: `families/page-primitives/` (desktop + `m/`), card 11 on the hub. |
| v3 · Named literals (2026-10-12) | **Pass:** the Foundations audit (`phase-4/docs/foundations/audit/`) found literal values with no token: 69 kinds on the surfaces and 101 in `base.css` and the family CSS. This pass gives the visual ones a name. **Every new token holds the exact value it replaces, so nothing renders differently.** Proof: six surfaces (dashboard, global-store, global-store-editor, orders, support-thread, website) and nine families, ful |

### Surfaces

Live: desktop `/pages/<slug>/`, phone `/pages/<slug>/m/` on the hand-off host.

**HQ** (RJ HQ shell · super admin)

- Global Store · `/super/global-store` · `/pages/global-store/` · `/pages/global-store/m/`
- Global Store product editor · `/super/global-store/new` · `/pages/global-store-editor/` · `/pages/global-store-editor/m/`
- Cloth library · `/super/cloths` · `/pages/super-cloths/` · `/pages/super-cloths/m/`
- Brands · `/super/brands` · `/pages/super-brands/` · `/pages/super-brands/m/`
- API Access · `/super/api-access` · `/pages/super-api-access/` · `/pages/super-api-access/m/`
- Connect MCP client · `/super/mcp-connect` · `/pages/super-mcp-connect/` · `/pages/super-mcp-connect/m/`
- Users & access (HQ) · `/settings/users` · `/pages/hq-settings-users/` · `/pages/hq-settings-users/m/`
- Audit log (HQ) · `/settings/audit-log` · `/pages/hq-settings-audit-log/` · `/pages/hq-settings-audit-log/m/`

**Store** (Brand shell · Store)

- Dashboard · `/` · `/pages/dashboard/` · `/pages/dashboard/m/`
- Orders · `/orders` · `/pages/orders/` · `/pages/orders/m/`
- Order detail · `/orders/[id]` · `/pages/order-detail/` · `/pages/order-detail/m/`
- Production kanban · `/orders/kanban` · `/pages/orders-kanban/` · `/pages/orders-kanban/m/`
- Envelope audit · `/orders/envelopes/[id]` · `/pages/order-envelope/` · `/pages/order-envelope/m/`
- Customers · `/customers` · `/pages/customers/` · `/pages/customers/m/`
- Customer detail · `/customers/[id]` · `/pages/customer-detail/` · `/pages/customer-detail/m/`
- Funnel · `/analytics/funnel` · `/pages/analytics-funnel/` · `/pages/analytics-funnel/m/`
- Revenue · `/analytics/revenue` · `/pages/analytics-revenue/` · `/pages/analytics-revenue/m/`
- System status · `/analytics/system-status` · `/pages/analytics-system-status/` · `/pages/analytics-system-status/m/`
- Campaigns · `/campaigns` · `/pages/campaigns/` · `/pages/campaigns/m/`
- Campaign detail · `/campaigns/[id]` · `/pages/campaign-detail/` · `/pages/campaign-detail/m/`
- Email broadcasts · `/campaigns/email` · `/pages/campaigns-email/` · `/pages/campaigns-email/m/`
- Inbox · `/support` · `/pages/support/` · `/pages/support/m/`
- Ticket thread · `/support/[id]` · `/pages/support-thread/` · `/pages/support-thread/m/`
- Support templates · `/support/templates` · `/pages/support-templates/` · `/pages/support-templates/m/`
- Support categories · `/support/categories` · `/pages/support-categories/` · `/pages/support-categories/m/`
- AI training pairs · `/support/training-pairs` · `/pages/support-training-pairs/` · `/pages/support-training-pairs/m/`

**Products** (Brand shell · Products)

- Global Store (brand) · `/global-store` · `/pages/brand-global-store/` · `/pages/brand-global-store/m/`
- My Products · `/products` · `/pages/products/` · `/pages/products/m/`
- Create product · `/create-product` · `/pages/create-product/` · `/pages/create-product/m/`
- Product prices · `/products/[offerId]/prices` · `/pages/product-prices/` · `/pages/product-prices/m/`
- Pricing · `/pricing` · `/pages/pricing/` · `/pages/pricing/m/`
- Variant pricing · `/pricing/[variant_id]` · `/pages/pricing-variant/` · `/pages/pricing-variant/m/`
- Bulk price import · `/pricing/bulk` · `/pages/pricing-bulk/` · `/pages/pricing-bulk/m/`
- Design pricing · `/design-pricing` · `/pages/design-pricing/` · `/pages/design-pricing/m/`
- Variants · `/variants` · `/pages/variants/` · `/pages/variants/m/`
- Variant · `/variants/[id]` · `/pages/variant-detail/` · `/pages/variant-detail/m/`
- New SKU · `/variants/new` · `/pages/variant-new/` · `/pages/variant-new/m/`
- Groups · `/variants/groups` · `/pages/variant-groups/` · `/pages/variant-groups/m/`

**Website** (Brand shell · Website)

- Website · `/website` · `/pages/website/` · `/pages/website/m/`
- Menu & sections · `/website/menu` · `/pages/website-menu/` · `/pages/website-menu/m/`
- Content · `/content/[[...slug]]` · `/pages/content-frame/` · `/pages/content-frame/m/`
- Releases · `/releases` · `/pages/releases/` · `/pages/releases/m/`

**Selling, needs attention and settings** (Brand shell · Selling · Needs attention · Settings)

- How customers buy · `/selling` · `/pages/selling/` · `/pages/selling/m/`
- Contact channels · `/selling/contact-channels` · `/pages/selling-contact-channels/` · `/pages/selling-contact-channels/m/`
- ERP retry queue · `/orders/retry-erp` · `/pages/orders-retry-erp/` · `/pages/orders-retry-erp/m/`
- Sync & OOS · `/variants/sync` · `/pages/variants-sync/` · `/pages/variants-sync/m/`
- Brand · `/settings/brand` · `/pages/settings-brand/` · `/pages/settings-brand/m/`
- Brands · `/settings/brands` · `/pages/settings-brands/` · `/pages/settings-brands/m/`
- Brand detail · `/settings/brands/[brand_id]` · `/pages/settings-brand-detail/` · `/pages/settings-brand-detail/m/`
- Create a brand · `/settings/brands/new` · `/pages/settings-brand-new/` · `/pages/settings-brand-new/m/`
- Users & access · `/settings/users` · `/pages/settings-users/` · `/pages/settings-users/m/`
- API keys · `/settings/api-keys` · `/pages/settings-api-keys/` · `/pages/settings-api-keys/m/`
- Audit log · `/settings/audit-log` · `/pages/settings-audit-log/` · `/pages/settings-audit-log/m/`
- Rules · `/settings/rules` · `/pages/settings-rules/` · `/pages/settings-rules/m/`
- Profile · `/settings/profile` · `/pages/settings-profile/` · `/pages/settings-profile/m/`

**Off the menu** (Brand shell · URL only, no menu item)

- Appointments · `/appointments` · `/pages/appointments/` · `/pages/appointments/m/`
- Fit review · `/fit-review` · `/pages/fit-review/` · `/pages/fit-review/m/`
- Fit review detail · `/fit-review/[id]` · `/pages/fit-review-detail/` · `/pages/fit-review-detail/m/`
- Tailor Roster · `/tailors` · `/pages/tailors/` · `/pages/tailors/m/`
- Tailor detail · `/tailors/[id]` · `/pages/tailor-detail/` · `/pages/tailor-detail/m/`
- Connected apps · `/connected-apps` · `/pages/connected-apps/` · `/pages/connected-apps/m/`
- Founder · `/founder` · `/pages/founder/` · `/pages/founder/m/`
- Refund-gate queue · `/founder/refund-requests` · `/pages/founder-refund-requests/` · `/pages/founder-refund-requests/m/`

**Sign in** (No shell)

- Sign in · `/sign-in` · `/pages/sign-in/` · `/pages/sign-in/m/`