Build standard

How to work

• Decide the platform first. This standard is for websites; an iPhone or Android app follows the Mobile Build Standard (get_build_standard with platform 'mobile'). When the person says only "app", ask: "A website, a phone app, or both?"
• Understand first: who uses the app, what they do in it, and what the owner must manage. Ask at most three short questions when something essential is unclear; otherwise state your assumptions and go on.
• Create the tab icon first, before any page: it is the item assistants forget most (see "Identity").
• Roadmap before code: write the project's Roadmap first. A goal of 1-3 sentences (who it is for, what it does, where it is going) and 8-20 items written as outcomes ("Customers can book a time slot"), each with 2-4 "Done when" checks in its detail, covering the pages, the data (tables and fields), the roles (visitor, user, admin) and the Harakumo services each part uses. Show it as Now / Next / Later in about 10 lines and ask once; on yes, call set_roadmap_goal and add_roadmap_items (approved: true). Without an answer, add them as ideas and keep building: naming the items you finish with ships on the deploy is the go-ahead for those, and the person reviews the rest. Then call get_roadmap before each piece of work, and name what each deploy finishes with ships ("R4"), so the item is marked done when the deploy is live.
• Set up the backend in one call with setup_app_backend (the kind of app decides whether it needs a database, storage and sign-in), then read every setting from the environment variables it stores.
• Build every item of this standard without being asked. The person should never have to request a tab icon, an eye button, a phone layout, pagination or a terms page.
• If the app has users, orders, bookings or content, call suggest_agents and propose the agents that fit (a shopping or booking assistant, a support helper, a report someone asks for…); create the ones the person picks with create_suggested_agents. An agent can also run on a schedule (a cron line in UTC, at most every 10 minutes, set on the agent in the dashboard's Agents tab or with update_agent and schedule), so a daily report or a reminder the day before is a scheduled agent's job; functions have no scheduled runs yet and run only when something calls them. When no blueprint fits, design the agent yourself with create_agent (instructions, the fewest tools that do the job, what starts it, its purpose), test it with run_agent, read its steps with get_agent and improve it with update_agent.
• Propose what the app clearly needs and was not asked for (an admin dashboard for an app with users or orders, email receipts for an app that takes payments), then build it.
• Start from get_starter_files for the tab icon, sign-in pages, footer and legal pages, instead of writing them from memory.
• Working on an app made earlier from the starter files (it has their AGENTS.md or app/api/auth/[action]/route.js)? An app keeps the copy it was given, so first apply each fix in get_starter_files' updates list that the app still needs; each one says how to tell an old copy.
• Write the project docs (see "Project docs in Nucleus") when you create the project, and update them in the same deploy as every major change. Never wait to be asked.
• After every deploy, run check_launch (with testSignIn when the app has accounts) and fix every "must" it lists.
• Before saying it is done, walk the Done checklist at the end of this standard and fix every miss.

Identity: tab icon, titles and sharing

• A tab icon on every page, created first: icon.svg (scales everywhere), favicon.ico (32×32) for old browsers, apple-touch-icon.png (180×180) for phones, and a web manifest with 192×192 and 512×512 icons. Link them in the shared <head> (or the framework's icon convention, like app/icon.svg in Next.js) so no page is left out. No logo given? Make a clean mark from the app's initial on the brand color, for example <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><rect width="64" height="64" rx="14" fill="#4F46E5"/><text x="32" y="44" font-family="system-ui,sans-serif" font-size="36" font-weight="700" fill="#fff" text-anchor="middle">F</text></svg>. A missing tab icon is the most common miss: never ship without one, and check it shows in the browser tab.
• A unique, descriptive <title> and meta description on every page ("Orders · Fruitly", not "App").
• Link previews: og:title, og:description and a 1200×630 og:image, so a shared link shows a card.
• A theme-color meta tag matching the brand color.

Design and icons

• One icon set for the whole app, consistent in stroke and size (for example Lucide, Heroicons or Phosphor). Never emoji as icons, never mixed sets, never clip-art.
• Design tokens: a small palette (one brand color, neutrals, success, warning, danger), one or two fonts, a spacing scale. No one-off colors.
• Clear hierarchy: one main action per screen, readable line length, generous spacing, consistent buttons.
• Text contrast of at least 4.5:1. Visible focus rings. Every image has alt text; every icon-only button has an aria-label.
• Respect the system's light or dark mode when the app has a dashboard.

Motion: a landing page that feels alive

Motion makes a landing page feel crafted. Use it with intent: to guide the eye, show how the product works and reward interaction. Never as decoration that slows the page down.

• Hero: one signature moment on load, such as the headline and product visual arriving in a short stagger (300–600 ms), an animated product demo, or a subtle moving gradient or illustration behind the headline.
• Scroll: sections and cards fade and rise in as they enter view (once, not on every scroll), numbers count up, and a feature walkthrough can pin and step through as the visitor scrolls.
• Micro-interactions: buttons and cards respond on hover and press (a lift, a shadow or a color shift in 150–200 ms), links underline smoothly, and form success has a small check animation.
• Product visuals: show the app working (an animated screenshot, a short looping clip or a Lottie illustration) rather than a static picture where possible.
• Easing: ease-out for things entering, ease-in for leaving, never linear for UI. Keep durations short; nothing blocks reading or clicking.
• Performance: animate transform and opacity only (never width, height or top), lazy-start animations below the fold, and keep the page fast (Largest Contentful Paint under 2.5 s). Start with CSS transitions, the Web Animations API or IntersectionObserver; reach for a library (GSAP, Motion, Lottie) only for scroll sequences or complex timelines.
• Respect prefers-reduced-motion: with it on, show the end state with no movement. Nothing flashes more than three times a second.
• Dashboards and admin pages stay calm: quick transitions and skeletons, no showpiece motion.

Every screen size, from the first build

• Phone (375 px), tablet (768 px) and desktop (1280 px and up) are built together, never as a later pass. The person should never have to ask for a mobile version.
• No sideways scrolling at any width. Navigation collapses into a menu button on phones. Wide tables become stacked cards or scroll inside their own box.
• Tap targets at least 44×44 px. Inputs use the right type (email, tel, number) so phones show the right keyboard.
• Check the layout at phone width before calling a page done.

Lists, loading and performance

• Any list that can grow past about 20 items is paginated without being asked: numbered pages for tables and admin lists, "Load more" or infinite scroll for feeds and galleries. Fetch one page at a time from the server (LIMIT and a cursor or offset), never everything at once.
• Search, filter and sort run on the server for large data, and are kept in the URL so a refreshed or shared link shows the same view.
• Every screen that loads data has three states designed: loading (skeleton placeholders the size of the content, so nothing jumps), empty (a friendly line and the next action, like "No orders yet. Share your store link."), and error (what went wrong and a Try again button). Never a blank screen.
• Images: the right size for where they show, modern formats, lazy-loaded below the fold. Uploads go straight to storage with signed URLs.
• Buttons show progress while they work and cannot be double-submitted.

Pages every public app has

• Home (landing): what it is, who it is for, the main action, and proof (features, screenshots or testimonials the owner provides; never invented customers or numbers).
• About, Contact (a form that sends with Harakumo Mail, plus an email address), Privacy Policy and Terms of Service.
• A footer on every public page: links to About, Contact, Privacy and Terms, the copyright line with the current year, and social links when given.
• A designed 404 page with a way back home, and a friendly error page.
• Privacy and Terms are starting templates written for this app (what data it collects, which services process it, how to ask for deletion), with a visible note that the owner should review them for their country. They are not legal advice.

Sign-in and accounts

Use a Harakumo auth pool for every app with accounts: it already handles hashing, codes and tokens.

• Sign up asks only for what the app needs. Default: full name, email, password and confirm password. Add a username only when users see each other (communities, profiles); add phone only when the app texts or calls.
• Every password field has a show/hide eye button (an icon button with aria-label "Show password" / "Hide password"). Confirm password must match before submit, with the message under the field.
• A password strength hint and the rule stated up front (for example "At least 8 characters"). Correct autocomplete attributes: name, email, new-password, current-password, one-time-code.
• Log in, Forgot password (email a code), Reset password, and email verification. After a reset, say so on the login page.
• Errors are specific and kind ("That email already has an account. Log in instead?"), next to the field, and never reveal whether an email exists on the forgot-password screen.
• Signed-in users get an account page: change name, email and password, sign out, and delete their account.
• Pages that need sign-in redirect to login and back again afterwards.

Admin dashboard

Propose and build one whenever the app has users, orders, bookings, posts or any data the owner must manage. Do not wait to be asked.

• Behind sign-in, for an admin role only, checked on the server for every request (not only by hiding links).
• An overview: the few numbers that matter for this app (new users, orders, revenue, bookings) for today, 7 days and 30 days, with a simple chart.
• A page per thing the owner manages (users, orders, products, bookings, messages) as a paginated, searchable table with filters, a detail view, and the actions the owner needs (cancel, ban, mark as done). Destructive actions ask to confirm.
• Refunds are made by the owner in the Harakumo dashboard (the project's Payments page), never by the app: the API refuses them to app keys (403 payouts_require_owner). Show each payment's refund status and link the owner there instead of building a Refund button.
• Settings the owner changes without code (business name, contact email, prices) stored in the database.
• An activity log of admin actions for anything that changes money or accounts.

Forms and feedback

• Labels above inputs (never placeholder-only), required fields marked, validation on blur and on submit, messages next to the field.
• Success is confirmed (a toast or a clear next screen). Every destructive action asks first and says what will be lost.
• Times shown in the viewer's time zone, money with its currency, numbers formatted for the locale.

Project docs in Nucleus

Every project has a private Nucleus repo, its code home, and every deploy_files upload is saved there as a commit (a deploy from a GitHub repository is not). The person reads the project in Nucleus: its code, its history, its Roadmap and these documents. Write them when the project is created, from what you are actually building, and keep them true after every major change (a new page, table, service, role or flow), in the same deploy, without being asked. They are kept out of the public site, and deploys that leave them out keep them.

docs/ROADMAP.md is the one you never write: Harakumo writes it into every commit from the project's Roadmap, and replaces any copy you send. Keep the Roadmap itself current instead, with get_roadmap, add_roadmap_items, update_roadmap_items and ships on each deploy.

• README.md: What the app is, who it is for, how to run it locally, how to deploy it, and where everything lives.
• docs/ARCHITECTURE.md: The parts of the system and how they talk: pages, API routes or functions, database tables, storage, sign-in, payments and outside services, with at least one diagram as a mermaid block (a flowchart of the parts, a sequence diagram of the main request).
• docs/SYSTEM-DESIGN.md: The data model (every table and its fields), the main flows step by step, roles and permissions, limits, failure handling, security and how it scales.
• docs/ROADMAP.md: Harakumo writes it from the project's Roadmap (the goal, every item and what is done) into every commit, once the Roadmap has a goal or an item. Assistants never write it: change the Roadmap itself, in Nucleus or through the roadmap tools.
• docs/DECISIONS.md: One short entry per real decision: the date, what was decided, the options weighed and why.
• docs/presentation.html: A single-file HTML slide deck about the project (16:9, 1280×720 scaled to fit, keyboard and click navigation, a progress bar). Slides: title, the problem, the solution, how it works with an architecture diagram in inline SVG, the tech stack, status and next steps. CSS design tokens in :root, one clear point per slide, motion only where it explains. No external scripts.

Engineering

• The API key lives on the server only, in an environment variable (Harakumo project env vars). The browser gets signed URLs, checkout links or the auth pool's publishable id, never the key.
• Payments: Harakumo checkout takes one-off card payments in US dollars, with no subscriptions yet. It fits physical goods and real-world services (orders, bookings, deposits, fees) and digital goods sold on the web. Inside an App Store or Google Play app, digital goods (credits, premium features, subscriptions) need the store's own billing. Refunds are the owner's, in the Harakumo dashboard.
• Validate every input on the server. Check permissions on the server for every read and write. Parameterized SQL only.
• Check an email address in one pass with a length limit (at most 254 characters, one @, a dot after it), never with a regular expression that can backtrack: one long, hand-made input must not hold a public route busy.
• A clear structure: pages, components, server routes and data access kept apart; no file that does everything.
• Database: a schema with migrations, indexes for what lists sort and filter by, created_at and updated_at on every table.
• Tests for the money, sign-in and permission paths at least. Run them before deploying.
• A README: what the app is, how to run it, its environment variables and how to deploy.
• Errors are logged with enough detail to debug; people see a friendly message.

Kinds of app

Each kind adds its own pages, data, services and admin dashboard. An assistant asks for one with get_build_standard.

Done checklist

• Tab icon shows in the browser tab (svg, ico, apple-touch-icon, manifest); page titles on every page; a link preview card.
• The landing page has purposeful motion (hero, scroll reveals, hover states) and stays still with reduced motion on.
• Works at 375, 768 and 1280 px with no sideways scroll.
• Every list that can grow is paginated; loading, empty and error states exist.
• Home, About, Contact, Privacy, Terms, 404, and a footer linking them.
• Password fields have the eye button; sign up has confirm password; forgot and reset password work.
• An admin dashboard exists if the app has users or data to manage, and its checks run on the server.
• No API key or secret in browser code; inputs validated on the server.
• One icon set, no emoji icons, consistent colors and spacing.
• Tests for money, sign-in and permissions pass.
• The project docs in Nucleus are written and match what was built: README, architecture with diagrams, system design, decisions and the slide deck.
• The Roadmap is current: every item that shipped was named in a deploy (ships "R4") and shows Done, and what is left is in Next up, Later or Ideas to review.

Update the email check in an app from an older starter kit

The sign-in route that older starter kits wrote into apps checks email addresses with a pattern that can take seconds on one long, made-up address. It is a public route, so anyone can send one, and many of them can slow the whole app. Starter files made now have the fixed check.

To see whether your app has the old one, open the file app/api/auth/[action]/route.js in it. If it has a line that starts const EMAIL = /^ and checks the address with EMAIL.test(email), delete that line, add the function below, change EMAIL.test(email) to isEmail(email), and deploy the app again. The AI assistant that works on your code can make the change: ask it to update the email check in that file to the one in the Harakumo build standard.

// An email address, checked in one pass and at most 254 characters.
function isEmail(v) {
  if (v.length > 254) return false;
  const at = v.indexOf('@');
  if (at < 1 || at !== v.lastIndexOf('@') || /\s/.test(v)) return false;
  const dot = v.indexOf('.', at + 2);
  return dot !== -1 && dot < v.length - 1;
}

// Where the route checks the address:
if (!isEmail(email)) return fail('Enter a valid email address.');