Getting Started

Step 0, Save the kit & open your project

Do this once before Bootstrap + Shell. You work in your project folder in Cursor. The design system stays on disk as a reference kit, you do not open it as your workspace.

1. 1Save the Project North Star kit on your computer. Your team or engineering provides this (zip, shared drive, or USB). Unzip if needed. You should see index.html and a Project North Star folder at the top level.

Your REGISTRY_DIR is the registry folder inside the kit (e.g. ~/Projects/Project North Star/registry). It must contain .cursor/skills/, templates/app-shell/, and public/r/.

2. 2Open Cursor on your computer.
3. 3File → Open Folder → create or choose your project folder (e.g. Desktop/my-product). It can be empty, Step 1 builds your app here. Do not open the design system folder.
4. 4Open Chat: View → Chat (or press Cmd + L on Mac, Ctrl + L on Windows).

Updates: Ask engineering for an updated kit when new components or setup steps are published.

Step 1, Bootstrap + Shell

With your project folder open in Cursor, one prompt creates your app, adds NS colors and fonts, then adds login, sidebar, dashboard, and sample charts. Paste both folder paths from Step 0.

• A sign-in page (demo only, replace before launch)
• A dashboard with sidebar, top bar, and sample charts
• A checklist file (INSTALL.md) inside your app for remaining steps

Option A, Recommended, use the skills

In Chat, mention both skills (or paste the paths below if @ does not find them) and send:

@ns-get-started @ns-vibe-start

I want to start a new North Star product with the full app shell.

REGISTRY_DIR: [paste path to …/Project North Star/registry from your kit; do NOT open this folder in Cursor]
MY_APP_DIR: [paste your project folder, the folder open in Cursor]

Read skills from REGISTRY_DIR/.cursor/skills/ and run bootstrap, then the app shell.

Cursor runs commands in both folders using the paths you provide. Approve each step when asked.

Optional, Bootstrap only (no shell)

Use this only if you want NS colors and fonts on a blank app and will build your own layout, no login page, sidebar, or dashboard.

Option A, Use the bootstrap skill only

@ns-get-started

Bootstrap my North Star app only, do NOT add the app shell.

REGISTRY_DIR: [paste path to …/Project North Star/registry from your kit; do NOT open this folder in Cursor]
MY_APP_DIR: [paste your project folder, the folder open in Cursor]

Read ns-get-started from REGISTRY_DIR/.cursor/skills/. Stop after bootstrap, no scaffold:shell, no /login, no /dashboard.

Option B, Fallback prompt

Bootstrap my North Star app only, do NOT add the app shell.

My folders:
- REGISTRY_DIR: [paste path to …/Project North Star/registry from your kit; do NOT open this folder in Cursor]
- MY_APP_DIR: [paste the project folder I already opened in Cursor]

Bootstrap only:
1. Read and follow ONLY ns-get-started from REGISTRY_DIR/.cursor/skills/
2. Create the app (create-next-app + shadcn init) in MY_APP_DIR if it does not exist yet
3. Add NS colors and styles using npm run dev:install in REGISTRY_DIR (port 3002)
4. Add North Star fonts in src/app/layout.tsx
5. Stop the registry install server, start MY_APP_DIR on port 3000, confirm North Star styling on the default Next.js page

Do NOT run ns-vibe-start. Do NOT run scaffold:shell or install-components.sh. Do NOT add ThemeProvider, /login, or /dashboard.

Do NOT open Simple Browser for the registry. If a preview opens showing Getting Started or component docs, tell me that is the design system site, not my app.
Ask me to approve each step. STOP when bootstrap is complete and tell me how to add the shell later with @ns-vibe-start if I want it.

To add the shell later, run @ns-vibe-start in a new Chat message.

Optional, Finish or redo shell

Use this if Bootstrap + Shell did not finish, you chose bootstrap-only, or you scaffolded the shell manually. With your app folder open in Cursor, paste this prompt (replace paths):

Continue app shell setup for my North Star app.

REGISTRY_DIR: [paste path to …/Project North Star/registry from your kit; do NOT open this folder in Cursor]
MY_APP_DIR: [paste app folder path]

The app already has scaffold files from npm run scaffold:shell.
1) Start npm run dev:install in REGISTRY_DIR (port 3002, background, do NOT open Simple Browser for the registry)
2) Run install-components.sh from MY_APP_DIR with NS_REGISTRY_URL=http://localhost:3002
3) Stop the registry install server, wire ThemeProvider in src/app/layout.tsx
4) Start npm run dev in MY_APP_DIR on port 3000 and verify /login and /dashboard

If Cursor opens Getting Started or component docs in a preview, tell me that is the design system site, not my app.

Manual fallback, only if you prefer commands over Chat:

cd "REGISTRY_DIR"
npm run dev

cd "MY_APP_DIR"
export NS_REGISTRY_URL="http://localhost:3000"
bash src/components/ag-shell/install-components.sh

Ask Cursor to update your root layout with the North Star ThemeProvider, or paste:

import { ThemeProvider } from "@/components/ag-shell/theme-provider"
import Script from "next/script"
import "./globals.css"

const themeInitScript = `(function(){try{var t=localStorage.getItem('colorMode');var d=t==='dark'||(t==='system'&&window.matchMedia('(prefers-color-scheme: dark)').matches);document.documentElement.classList.toggle('dark',d);document.documentElement.classList.toggle('light',!d);var ct=localStorage.getItem('colorTheme')||'ns-pro';document.documentElement.dataset.theme=ct;}catch(e){}})();`

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning data-theme="ns-pro">
      <body>
        <Script id="theme-init" strategy="beforeInteractive" dangerouslySetInnerHTML={{ __html: themeInitScript }} />
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  )
}

Step 2, Check that it worked

After Bootstrap + Shell (Step 1):

• Your app opens on http://localhost:3000, not the design system docs site
• /login shows a sign-in page with North Star styling
• /dashboard shows a sidebar, top bar, and sample charts

If you used bootstrap only (optional path):

• Your app opens on http://localhost:3000 with North Star styling on the default Next.js page, no /login or /dashboard yet

Something wrong? Paste this in Chat:

Something didn't work during Project North Star setup.

REGISTRY_DIR: [paste path to …/Project North Star/registry from your kit; do NOT open this folder in Cursor]
MY_APP_DIR: [paste your app folder path]

Walk me through troubleshooting using src/components/ag-shell/INSTALL.md in my app.
Explain fixes in plain language and ask before running commands.

Step 3, What's next

• Keep using @ns-vibe-start when building pages and adding components
• Browse components on the design system site and ask Cursor to add what you need
• Demo login accepts any email and password, replace with real sign-in before launch
• Your app has a checklist at src/components/ag-shell/INSTALL.md after the shell is scaffolded