Conventions

Layout

Every page is the same four boxes: PageFrame holds PageToolbar and PageBody, and PageBody holds PageContent. There is one vertical scroller per page, and it is PageContent. The toolbar is a sibling of the scroller, never inside it. Interior spacing is 20. The full contract, with the two page shapes and the measurements behind the tricky parts, is docs/LAYOUT.md. Read it before adding a page.

Copy

• Headings are Title Case; sentences are sentence case. The test is grammatical, not positional: an empty state's headline is a sentence.
• US spelling: program, color, organize.
• No em dashes or en dashes anywhere, code comments included. Use a comma, two sentences, or "to" in a range. The pre-push check greps for them.
• Feedback tones (success, error, warning, info) come from lib/alert-tones.ts. Toast when the work is finished; alert inline when the person has to act there.
• Full rules in docs/COPY.md.

Design System

• shadcn/ui, style base-vega, on Base UI (not Radix). Compose with render={<X />}; add nativeButton={false} when a Button renders a link.
• Never run npx shadcn add --overwrite or npx shadcn apply. Several components/ui files carry hand patches (sidebar, dialog, select, command, toast) and a test fails if they are lost.
• Inter is the only typeface. Teal #0F766E on warm neutrals. Tokens live in app/globals.css.
• Design-system lint rules run as warnings in ESLint until their count reaches zero.

Code

• TypeScript strict. No any without a comment saying why.
• Pure logic in its own file with a test beside it. Server-only modules import server-only.
• Every write is a server action that checks the role first. Never trust the screen.
• Comments explain why. The commit message explains what changed for a person, not which files moved.
• Secrets never appear in code, tests, logs or docs.

Commits and Branches

• Small commits on main, rebased onto the latest, pushed as a fast-forward. Never force-push main.
• Before pushing: npx tsc --noEmit, npm test, and the dash check on added lines.
• Commit messages describe the behavior change in plain English, with the ticket number.

Linear

The Impact Hub Houston team reads the workspace. Every issue and comment is written as if delivered to them directly: no commercial detail, no blaming anyone, defects describe the system and the fix, decisions state their reasoning. A ticket is closed with a comment that says how the feature works now and how it was checked.

Specs

specs/00 to 06 describe an earlier AWS design and carry a banner saying what is stale. specs/07 and 10 onward describe what is deployed. New specs follow the same ten-section shape as the existing ones.