---
name: build-with-a-framework
description: The scaffold that is known to build, and the @acuvo/ui component kit (Button, Card, Dialog, Input, Tabs) already vendored into it
when: Before npm install or any create-* command, before writing ANY button, card, dialog, input or tab, or when the answer is React/Vue/Svelte/Vite
---
# Building with a framework
You have a real machine: `npm install` works, a build step works, and its output
is what ships. This scaffold is **known to work** — measured live: install 11.9s,
`vite build` 2.0s, exit 0 both.
## ⭐ Do not re-derive the scaffold. Write `src/App.jsx` and copy the rest.
Re-deriving `package.json`, `vite.config.js`, `index.html` and `main.jsx` on
every build spends tokens on a solved problem and fails in tedious ways. **These
four are correct and free.** The part that is the request is `src/App.jsx`.
`package.json`
```json
{
"name": "app",
"private": true,
"type": "module",
"scripts": { "build": "vite build" },
"dependencies": {
"react": "18.3.1", "react-dom": "18.3.1",
"@radix-ui/react-dialog": "1.1.23", "@radix-ui/react-tabs": "1.1.21", "@radix-ui/react-slot": "1.3.3"
},
"devDependencies": { "vite": "5.4.0", "@vitejs/plugin-react": "4.3.1" }
}
```
`vite.config.js`
```js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { fileURLToPath } from 'node:url';
export default defineConfig({
plugins: [react()],
base: './',
resolve: { alias: { '@acuvo/ui': fileURLToPath(new URL('./src/ui', import.meta.url)) } },
});
```
`index.html`
```html
App
```
`src/main.jsx`
```js
import './system.css'; // ⚠️ FIRST. It is the base layer your own CSS overrides.
import React from 'react';
import { createRoot } from 'react-dom/client';
import App from './App.jsx';
createRoot(document.getElementById('root')).render();
```
### What the preview bundle resolves from npm — and nothing else
The preview and the published page bundle your tree on the server with `react`,
`react-dom` and **`motion/react`** (framer-motion 12, MIT). For animation:
`import { motion, AnimatePresence } from 'motion/react'`, then
``. Any other npm
import is refused by name and the page goes blank — not GSAP (licence), lodash,
axios or a UI kit; `fetch` and CSS are there.
Then:
```
npm install --no-audit --no-fund && npm run build
```
## ⭐⭐ The component kit is already in the project. Do not rebuild it.
`src/ui/` is vendored into every React scaffold and aliased to `@acuvo/ui`. It is
**your** source — read it, change it — and it renders the **same `ax-` classes**
every page gets, so a component here and a hand-written element are one element.
```jsx
import { Button, Card, CardHeader, CardTitle, CardDescription, CardBody, CardFooter,
Field, Input, Label, Tabs, TabsList, TabsTrigger, TabsContent,
Dialog, DialogTrigger, DialogContent, DialogTitle, DialogDescription,
DialogFooter, DialogClose } from '@acuvo/ui';
Book a jobPick a time and we will confirm it by email.
```
**What the kit adds is behaviour, not styling** — the design system already does
the styling:
- `Button` — `variant` **primary | quiet | danger** (the system's three; no size
prop, no `secondary`/`ghost`), `asChild` to style your own element.
- `Field` — generates the ids, so the label points at its input and a screen
reader reads the error with it. Never hand-wire `htmlFor`.
- `Dialog` — real focus trap, Escape, scroll lock, background made inert.
**Never hand-roll a modal beside this one.**
- `Tabs` — roving tabIndex and arrow keys, per the WAI-ARIA tablist contract.
⚠️ **Do not restyle it with hard-coded colours.** It is written in design tokens
and repaints itself to this build's palette. Compose instead — pass `className`.
### The three shapes worth copying
```jsx
// FORM
setEmail(e.target.value)} />
// TABLE — the kit has none on purpose: a table is markup, not behaviour.
// ⚠️ Wrap it AND let its parents shrink: a grid/flex child defaults to
// min-width:auto, so the wrapper cannot scroll and the PAGE scrolls sideways.
// Put min-width:0 on any grid/flex ancestor.
, never
, and
// tabIndex on the scroller or no keyboard can scroll it (axe:
// scrollable-region-focusable). All three measured on real builds.
Job
Status
{jobs.map((j) => (
{j.title}
{j.status}
))}
// DIALOG — actions in DialogFooter, primary last. A bare button in a dialog stretches.
```
`ax-grid` is already `repeat(auto-fit,minmax(16rem,1fr))` — no media queries for
a card grid.
⚠️ **It ships nothing you do not import** — the three portal rules ride in on the
barrel, and everything else is already in `system.css`.
## ⚠️⚠️ NEVER run a bare `create-*` command. It prompts, and you have no tty.
`npm create vite@latest` and `npx create-next-app` are **interactive**. Run
without every answer supplied they sit at a prompt nobody can type into, and the
first sign is a command that times out with no output — which then gets debugged
as a network problem. Supply the flags, or write the four files above:
```
npm create vite@latest app -- --template react-ts # note the bare --
npx create-next-app@latest app --ts --app --tailwind --eslint \
--no-src-dir --import-alias "@/*" --use-npm --yes
```
## Swapping the framework — only the plugin and the entry change
| stack | dependency | dev plugin | entry |
|---|---|---|---|
| React | `react`, `react-dom` | `@vitejs/plugin-react` | `createRoot(el).render()` |
| Vue 3 | `vue` | `@vitejs/plugin-vue` | `createApp(App).mount('#app')` |
| Svelte | `svelte` | `@sveltejs/vite-plugin-svelte` | `new App({ target: el })` |
| vanilla | — | — | `