Skip to content
groundworkDocs

Set up a project

Start a new project with the whole kit, or add the design system to one you already have.

The whole kit

From an empty folder to a first feature. Run these once, in order.

  1. 1

    Create the app

    A Next.js app with TypeScript, Tailwind, ESLint and the App Router. kit init edits the files this creates, so pass the flags rather than relying on saved preferences.

    bunx create-next-app@latest your-app --ts --tailwind --eslint --app --use-bun --yes
  2. 2

    Run kit init

    Copies the house style into context/, installs the lifecycle skills, runs shadcn init against the registry, removes the leftover CSS that would override the theme, wires the lint rule, adds a check script, and locks what it installed.

    cd your-app && bunx @ja3dan/kit init next16-insforge
    your-app/
    • .claude/skills/
    • app/globals.css
    • context/
      • features/
        • README.md
      • code-standards.md
      • library-docs.md
      • progress.md
      • ui-registry.md
      • ui-rules.md
    • components.json
    • eslint.config.mjs
    • kit.lock.json
    • package.json
    Use the arrow keys to move. Right expands a folder, left collapses it or climbs to its parent. Home and End jump to the ends, and typing a letter jumps to the next name starting with it.
  3. 3

    Write the context

    Paste the kickoff prompts into any LLM chat, in order, and save each answer into context/. Each answer is the next prompt's input.

    your-app/
    • context/
      • project-overview.md
      • architecture.md
      • build-plan.md
    Use the arrow keys to move. Right expands a folder, left collapses it or climbs to its parent. Home and End jump to the ends, and typing a letter jumps to the next name starting with it.
    Read the prompts
  4. 4

    Check the project

    kit doctor and kit check pass straight away. bun run check fails on create-next-app's own home page, which uses raw palette colours: that is the lint rule working, and it passes once the first feature replaces the page.

    bunx @ja3dan/kit doctor
    required files, and the same outdated/missing info as sync status
    bunx @ja3dan/kit check
    scan locked files for raw colours and a theme missing required tokens
    bun run check
    typecheck and lint, including no-raw-colors
  5. 5

    Start the first feature

    In Claude Code, from the project. The feature skill opens a branch and a folder, and writes the spec with its done when criteria.

    /feature start 01
    Read the loop

Only the design system

shadcn does the install. Two things kit init would have done are yours to do by hand.

Before you start, in an app with its own styles

Search the codebase for the contract's token names (primary, accent, success and the rest). A name the app already uses for something else takes on the contract's meaning once the theme loads. Override it straight after the imports.
  1. 1

    Initialise on the contract

    Initialises a project on the token contract: installs @ja3dan/tokens and the lint plugin, wires the theme into global CSS, adds the @ja3dan registry to components.json. Run with shadcn init.

    bunx shadcn@latest init https://gw.jaedan.me/r/setup.json
  2. 2

    Remove the leftover CSS

    In a fresh create-next-app project, app/globals.css keeps its own colour variables, a dark media query copy and a body rule after the imports, and they override the theme. Keep the imports below and any --font-* lines; delete the rest.

    app/globals.css
    @import "tw-animate-css";@import "@ja3dan/tokens/theme.css";@import "@ja3dan/tokens/base.css";@import "@ja3dan/tokens/themes/neutral.css";
  3. 3

    Wire the lint rule

    The plugin is installed but does not run until the config names it. Add these two lines to eslint.config.mjs.

    eslint.config.mjs
    import ja3dan from "@ja3dan/eslint-plugin";// inside the config array:{ ...ja3dan.configs.recommended, files: ["app/**/*.{ts,tsx}", "components/**/*.{ts,tsx}"] },
  4. 4

    Add components

    Start with the button, which replaces shadcn's, then add any of the other 22.

    bunx shadcn@latest add @ja3dan/button --overwrite
    Browse the components

Keep it current

Installed components are yours to edit. The kit tells you when a newer version exists and merges it with your edits.

bunx @ja3dan/kit sync status
what's outdated, and what's been edited locally
bunx @ja3dan/kit sync update <item>
update one item on a branch: overwrite if unedited, 3-way merge if edited

Where to go next