# Build standard
An assistant building on Harakumo follows this standard without being asked, so nobody has to request a tab icon, a password eye button, a phone layout or a terms page on every project. The connector tells assistants to read it first; get_build_standard returns it with the extras for the kind of app being built.
## How to work
- 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").
- Plan before code: list the pages, the data (tables and fields), the roles (visitor, user, admin), and which Harakumo services each part uses. Show the plan in a few lines.
- 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.
- 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.
- After every deploy, run check_launch 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 (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 . A missing tab icon is the most common miss: never ship without one, and check it shows in the browser tab.
- A unique, descriptive 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 (refund, cancel, ban, mark as done). Destructive actions ask to confirm.
- 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.
## 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.
- Validate every input on the server. Check permissions on the server for every read and write. Parameterized SQL only.
- 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.
| Kind | Adds |
| --- | --- |
| Online store (store) | Product list with search, category filters and pagination; Product page with images, price, stock and Add to cart; Cart and checkout |
| SaaS product (saas) | Landing with pricing; Onboarding after sign up (first useful result in a minute); The app itself |
| Booking or services business (booking) | Services with prices and durations; Pick a date and an open time slot; Book and pay (or pay later) |
| School or education (education) | Public site: about the school, admissions, contact, notices; Student and parent portal: timetable, attendance, results, fees; Teacher portal: classes, attendance, marks |
| Portfolio or marketing site (portfolio) | Home with a clear headline and call to action; Work or services with case studies; About |
| Community, content or social app (community) | Feed with infinite scroll; Post page with comments; Create and edit post |
| AI-powered app (ai-app) | The main AI screen with streaming answers and a stop button; History of past chats or results; Usage and limits for the signed-in user |
| Internal tool or dashboard (internal-tool) | Overview with the key numbers; A table page per record type with search, filters, pagination and CSV export; Detail and edit forms |
## 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 README is written.