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. 1Get the AG Design System on your computer. Ask engineering for access to the private GitHub repo, then clone it (recommended):

git clone https://github.com/skadlecek/AG-Design-System.git

After cloning, your REGISTRY_DIR is the registry folder inside the clone (e.g. ~/Projects/AG-Design-System/registry). It must contain .cursor/skills/, templates/app-shell/, and public/r/.

No GitHub access? Ask engineering for the offline kit zip (includes START_HERE.html at the top). Use the inner folder that contains the same paths as registry/ above.

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: Setup uses files on your machine. Run git pull inside your clone when engineering publishes changes. Repo: github.com/skadlecek/AG-Design-System.

Step 1, Bootstrap + Shell

With your project folder open in Cursor, one prompt creates your app, adds AG 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:

@ag-get-started @ag-vibe-start

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

REGISTRY_DIR: [paste path to …/AG-Design-System/registry from your clone; 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 AG 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

@ag-get-started

Bootstrap my AG app only, do NOT add the app shell.

REGISTRY_DIR: [paste path to …/AG-Design-System/registry from your clone; do NOT open this folder in Cursor]
MY_APP_DIR: [paste your project folder, the folder open in Cursor]

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

Option B, Fallback prompt

Bootstrap my AG app only, do NOT add the app shell.

My folders:
- REGISTRY_DIR: [paste path to …/AG-Design-System/registry from your clone; 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 ag-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 AG colors and styles using npm run dev:install in REGISTRY_DIR (port 3002)
4. Add AG fonts in src/app/layout.tsx
5. Stop the registry install server, start MY_APP_DIR on port 3000, confirm AG styling on the default Next.js page

Do NOT run ag-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 @ag-vibe-start if I want it.

To add the shell later, run @ag-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 AG app.

REGISTRY_DIR: [paste path to …/AG-Design-System/registry from your clone; 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 AG_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 AG_REGISTRY_URL="http://localhost:3000"
bash src/components/ag-shell/install-components.sh

Ask Cursor to update your root layout with AG 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')||'ag';document.documentElement.dataset.theme=ct;}catch(e){}})();`

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning data-theme="ag">
      <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 AG 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 AG styling on the default Next.js page, no /login or /dashboard yet

Something wrong? Paste this in Chat:

Something didn't work during AG Design System setup.

REGISTRY_DIR: [paste path to …/AG-Design-System/registry from your clone; 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 @ag-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