--- name: First Vibe-Coded App slug: first-vibe-coded-app url: "https://dontmakeitugly.com/packs/first-vibe-coded-app" install: npx dontmakeitugly init first-vibe-coded-app designMd: "https://dontmakeitugly.com/packs/first-vibe-coded-app/DESIGN.md" manifest: "https://dontmakeitugly.com/packs/first-vibe-coded-app.json" audience: beginner stack: - react - nextjs - tailwind resources: - godly - tweakcn - checklist-design - autoanimate - v0 - radix-colors - vercel-web-interface-guidelines - playwright-mcp createdAt: "2026-09-04" --- # First Vibe-Coded App Defaults that are hard to get wrong, for people who have never built software before. - Audience: No design background needed - Stack: React, Next.js, Tailwind CSS - Install: `npx dontmakeitugly init first-vibe-coded-app` ## What this pack is A contract for your first app: warm off-white pages, one teal, soft corners, one friendly typeface in five sizes. Nothing here needs design knowledge. The agent reads the file, uses only what is in it, and runs a check that tells it what to fix in plain language. ## How to use it Install the pack before you ask for a single screen. Then build with v0 or your agent, use tweakcn if you are on shadcn, and paste a Checklist Design list into your prompt so the empty state and the focus ring don't get forgotten. Auto Animate is the one motion library you need. When something looks off, run the check and hand the report to the agent. ## What `init` puts in your repo - `DESIGN.md`: the visual contract below. Tokens in the front matter, reasoning in the prose. - `dmiu.config.json`: which routes the design check screenshots and how strict it is. - `.dmiu/references/README.md`: the reference screens and what to take from each. - A block in `AGENTS.md` (and `CLAUDE.md` if you have one) telling the agent to read the contract first and run the check before finishing. ## Reference screens - [Godly](https://godly.website): What good looks like. You don't need to copy any of it; you need to have seen it before you describe what you want. Look at: how much empty space there is, how few colours each site uses. Preview: https://dontmakeitugly.com/previews/godly.jpg - [tweakcn](https://tweakcn.com): A theme editor for shadcn apps. Ten minutes here does more than an afternoon of prompting. Look at: how one radius and one accent change the whole feel. Preview: https://dontmakeitugly.com/previews/tweakcn.jpg - [Checklist Design](https://www.checklist.design): What every screen should include. Paste a checklist into your prompt so the agent stops forgetting things. Look at: the form and empty-state checklists. Preview: https://dontmakeitugly.com/previews/checklist-design.jpg ## Resources, in order 1. [Godly](https://dontmakeitugly.com/resources/godly.md) — Astronomically good web design inspiration, hand-picked. Agent: Limited. 2. [tweakcn](https://dontmakeitugly.com/resources/tweakcn.md) — A visual theme editor that makes a shadcn/ui app stop looking like every other shadcn/ui app. Agent: Good. 3. [Checklist Design](https://dontmakeitugly.com/resources/checklist-design.md) — Checklists of what every common screen and component should include. Agent: Good. 4. [AutoAnimate](https://dontmakeitugly.com/resources/autoanimate.md) — One line of code that animates list changes for you. Agent: Excellent. Install: `npm install @formkit/auto-animate` 5. [v0](https://dontmakeitugly.com/resources/v0.md) — Vercel's generative UI tool: describe a screen, get a shadcn/ui implementation. Agent: Good. 6. [Radix Colors](https://dontmakeitugly.com/resources/radix-colors.md) — Colour scales designed for real UI, with light and dark modes that actually match. Agent: Excellent. Install: `npm install @radix-ui/colors` 7. [Web Interface Guidelines](https://dontmakeitugly.com/resources/vercel-web-interface-guidelines.md) — A concise, agent-readable checklist of what a well-built web interface must get right. Agent: Excellent. 8. [Playwright MCP](https://dontmakeitugly.com/resources/playwright-mcp.md) — Give your agent a browser so it can see and test what it built. Agent: Excellent. Install: `claude mcp add playwright -- npx @playwright/mcp@latest` ## Related collections - [Best resources for first-time vibe coders](https://dontmakeitugly.com/collections/first-time-vibe-coders.md) ## The contract (DESIGN.md) ```markdown --- version: alpha name: First Vibe-Coded App description: Safe, good-looking defaults for someone building their first app with an agent. Nothing here needs a design vocabulary. colors: paper: "#f8f7f4" surface: "#ffffff" surface-2: "#efede8" ink: "#17181a" ink-2: "#55575c" ink-3: "#7d8087" line: "#e3e1dc" line-strong: "#c9c6bf" primary: "#0f766e" primary-soft: "#e6f4f2" on-primary: "#ffffff" success: "#15803d" success-soft: "#ecfdf3" error: "#b42318" error-soft: "#fef3f2" typography: title: fontFamily: DM Sans fontSize: 32px fontWeight: 600 lineHeight: 1.15 letterSpacing: -0.02em heading: fontFamily: DM Sans fontSize: 20px fontWeight: 600 lineHeight: 1.3 body: fontFamily: DM Sans fontSize: 16px fontWeight: 400 lineHeight: 1.6 small: fontFamily: DM Sans fontSize: 14px fontWeight: 400 lineHeight: 1.5 label: fontFamily: DM Sans fontSize: 14px fontWeight: 500 lineHeight: 1.4 mono: fontFamily: DM Mono fontSize: 14px fontWeight: 400 lineHeight: 1.5 rounded: sm: 6px md: 8px lg: 12px full: 9999px spacing: base: 4px xs: 4px sm: 8px md: 16px lg: 24px xl: 32px 2xl: 48px 3xl: 64px gutter: 16px measure: 640px components: button-primary: backgroundColor: "{colors.primary}" textColor: "{colors.on-primary}" typography: "{typography.label}" rounded: "{rounded.md}" padding: "{spacing.md}" height: 40px button-secondary: backgroundColor: "{colors.surface}" textColor: "{colors.ink}" typography: "{typography.label}" rounded: "{rounded.md}" padding: "{spacing.md}" height: 40px card: backgroundColor: "{colors.surface}" textColor: "{colors.ink}" rounded: "{rounded.lg}" padding: "{spacing.lg}" input: backgroundColor: "{colors.surface}" textColor: "{colors.ink}" typography: "{typography.body}" rounded: "{rounded.md}" padding: "{spacing.sm}" height: 40px badge: backgroundColor: "{colors.primary-soft}" textColor: "{colors.primary}" typography: "{typography.small}" rounded: "{rounded.full}" padding: "{spacing.xs}" list-item: backgroundColor: "{colors.surface}" textColor: "{colors.ink}" padding: "{spacing.md}" rounded: "{rounded.md}" --- # First Vibe-Coded App ## Overview You are building something for the first time and you do not want it to look like a demo. This contract gives you a look that is hard to get wrong: warm off-white pages, dark grey text, one teal for buttons and links, soft corners, a friendly typeface. It is deliberately plain. Plain and consistent beats interesting and messy every time. Everything in this file is a default. Change a value only when you have a reason you can say out loud. ## Colors Five greys, one colour, two statuses. Learn what each is for and you will never need to pick a colour again. - **Paper (#f8f7f4):** the page background. Not pure white, so white cards stand out a little. - **Surface (#ffffff):** cards, forms, dialogs. Surface 2 (#efede8) is for things that sit back, like a sidebar or a disabled state. - **Ink (#17181a):** headings and body text. Ink 2 for less important text. Ink 3 for hints and placeholders. Never lighter than ink 3 for anything someone has to read. - **Line (#e3e1dc):** borders. All of them. - **Primary (#0f766e):** teal. The main button, links, the active tab, the focus ring. One teal thing per screen is ideal; two is fine; a screen that is mostly teal is wrong. - **Success and Error:** messages after the user does something. Not for decoration. ## Typography One typeface, DM Sans, in five sizes. A second one, DM Mono, only for code or IDs. - Page title 32px semibold. Section heading 20px semibold. Body 16px. Small text 14px. Buttons and form labels 14px medium. - Line height is generous (1.6 on body). Text blocks stop at 640px wide. - Do not add a third size between these. If something feels like it needs one, change its colour to ink 2 instead. ## Layout Everything sits on a 4px grid: 8 between related things, 16 inside cards and between form fields, 24 between groups, 48 between sections. Page padding is 16px on mobile and 24px on desktop. The content column is at most 1040px wide and centred. Put things in a single column until you have a reason for two. Mobile first: if it works at 390px wide, it will work everywhere. ## Elevation & Depth Flat with one exception. Cards are white on paper with a line border and no shadow. Dialogs and dropdowns get one soft shadow because they float above the page. No gradients, no glow, no glass. ## Shapes Softly rounded: 6px on badges and small controls, 8px on buttons and inputs, 12px on cards. Pills only for badges and avatars. Keep the same radius on every button. ## Components - **Buttons:** 40px tall. Primary is teal with white text. Secondary is white with a line border. One primary button per screen. - **Inputs:** 40px tall, white, line border, teal ring on focus. Label above in label style, help or error text below in small. - **Cards:** white, line border, 12px radius, 24px padding, a heading and some body text. Not a card inside a card. - **Lists:** rows with 16px padding and a hairline between them. Use Auto Animate so adding and removing rows feels smooth. - **Badges:** pill, teal-soft background, teal text, small size. - **Empty state:** one sentence saying what will appear here and one button to make it appear. - **Navigation:** a top bar with the app name on the left and at most four links. Active link in teal. ## Do's and Don'ts - Do use only DM Sans and DM Mono. If a font you did not choose shows up, remove it. - Do use only the colours in this file. When you want a new one, use ink 2 or surface 2 instead. - Do keep text readable: 4.5:1 contrast, 16px body, never grey-on-grey. - Do respect `prefers-reduced-motion`: animations turn off when the user asks. - Don't use gradients, purple, glow effects or glass. These are the tells of a generated app. - Don't centre everything. Left-align text and let the layout breathe. - Don't add icons to every button and heading. Icons go where they carry meaning. - Don't ask the agent to "make it pop". Ask it to check this file. ``` ## Agent instructions (added to AGENTS.md) ```markdown ## Design contract (First Vibe-Coded App) This project uses a DESIGN.md contract from Don't Make It Ugly. Before writing or changing any UI: 1. Read `DESIGN.md`. Use only its fonts, colours, spacing scale and radii. If something you need isn't there, ask before inventing it. 2. Read `.dmiu/references/README.md` for the reference screens and what to take from each. 3. When you finish a UI change, start the dev server and run `npx dontmakeitugly check`. Read `.dmiu/report.md` and fix every error before you say you're done. 4. Never edit `DESIGN.md` to make a check pass. Change the code. Curated resources for this pack (each page says how an agent can use it): - Godly: https://dontmakeitugly.com/resources/godly.md - tweakcn: https://dontmakeitugly.com/resources/tweakcn.md - Checklist Design: https://dontmakeitugly.com/resources/checklist-design.md - AutoAnimate: https://dontmakeitugly.com/resources/autoanimate.md - v0: https://dontmakeitugly.com/resources/v0.md - Radix Colors: https://dontmakeitugly.com/resources/radix-colors.md - Web Interface Guidelines: https://dontmakeitugly.com/resources/vercel-web-interface-guidelines.md - Playwright MCP: https://dontmakeitugly.com/resources/playwright-mcp.md ``` ## The check After building, run `npx dontmakeitugly check` with the dev server running. It screenshots / at desktop and mobile widths and fails on fonts outside the contract, colours off the palette (tolerance 8), WCAG AA contrast failures, purple/blue gradients, animation that ignores reduced motion, and screenshot drift. The report lands in `.dmiu/report.md`.