``` Format: **`{screen}.{section}.{thing}`**, English, kebab-case, dot-separated. - Required on: buttons - input fields - links - table rows - tabs - result boxes - status boxes - error messages. - **Do not change an existing value without a real reason** — tests and notes referencing it break along with it. - Never use a framework's random auto-generated `id` (`el-8f3a`) as a reference — it changes on every render. ### Important state must live in the URL Users must be able to **copy the link, send it to someone else, and have it open to the same view**, and the browser back button must work. | Must be on the URL | Example | |---|---| | Which screen/tab is open | `?tab=round3` | | The selected item | `?id=RC-2026-001` | | Filters, search terms, sort order | `?status=waiting&q=สมชาย&sort=-created_at` | | Which page number | `?page=2` | - In-page state changes should use a technique that **doesn't reload the page**, but the URL must still update to match (see section 13). - Opening a URL with parameters directly must restore that exact state, not bounce back to defaults. - **Never put secrets or personal data in the URL** (passwords, ID numbers, tokens) — it persists in browser history and server logs. --- ## 12. The whole-app shell Screens don't float independently — every screen shares one shell, or the user feels lost. ``` ┌──────────────────────────────────┐ │ Top bar (navbar) system name - menu - user │ <- always present, never disappears, never reloads ├──────────────────────────────────┤ │ │ │ Content (main) │ <- the only part that changes per screen │ │ ├──────────────────────────────────┤ │ Bottom bar (footer) company name - version │ <- optional; drop it if there's nothing to put there └──────────────────────────────────┘ ``` **The navbar must carry a readable system name — but do not ask for it up front.** Same reasoning as the brand question in section 1d: before the user has seen anything, "what should we call it?" gets "ไม่รู้ แล้วแต่เลย" and costs a question for nothing. - **At level 1**, derive a sensible name from what the work is about and mark it as provisional, e.g. `ระบบบันทึกสต็อกวัตถุดิบ (ชื่อชั่วคราว)`. Say once that the name is a placeholder and can be changed any time. - **Ask for the real name only at the level 2 brand moment**, folded into the same question as the logo/colour one — one turn, not two. - If the user names it themselves at any point, use it immediately and stop treating it as provisional. - Never leave `{system-name}` literally in place, and never leave it blank — the user will think the system is broken. ### Two things that make the top bar "look inconsistent" even though it's the same code **1. Always reserve space for the scrollbar** A short-content page has no scrollbar; a long-content page does — a scrollbar takes up roughly 15px of width. This means **the two top bars shift by different amounts**, and switching between pages makes the menu visibly jump. The eye catches that something's off but can't say what. ```css html { scrollbar-gutter: stable; } ``` Set this once, in the shared stylesheet — it fixes the whole system. **Never fix it by hiding the scrollbar.** **2. Always show which page you're on** The current page's menu item must be visibly more prominent than the others (darker color + bold + `aria-current="page"`). If every menu item looks identical, the user has no idea where they are in the system. And **never use color alone** as the signal — pair it with font weight or an underline too (section 2). ### Mobile top bar — choose based on menu count | Number of top-level destinations | Use | Why | |---|---|---| | 5 or fewer | **Bottom tab bar, fixed to the screen edge** | Thumb-reachable, always visible, one tap to switch | | More than 5 | **Hamburger button opening a side drawer** | Fits more items without crowding the screen | Never use a hamburger when there are only 3 menu items — hiding things that should be visible reduces engagement for no reason. An open drawer must be closable via its X button, tapping the dimmed area outside it, and the Esc key. --- ## 12b. Only the content region scrolls — the frame stays put The page itself must never be the scroll container. If the whole document scrolls, the top bar and the footer scroll away with the content, the browser's own scrollbar runs the full height of the window, and the user loses the frame they navigate by. ``` +-----------------------------+ | HEADER | fixed — never scrolls +-----------------------------+ | |^|| | CONTENT |||| this region scrolls, and only this region | |v|| +-----------------------------+ | FOOTER | fixed — never scrolls +-----------------------------+ ``` ```css .app-shell { height: 100dvh; display: flex; flex-direction: column; overflow: hidden; } .app-header, .app-footer { flex: none; } .app-main { flex: 1; min-height: 0; overflow-y: auto; overscroll-behavior: contain; } ``` > **`min-height: 0` is load-bearing — do not remove it.** A flex child defaults to `min-height: auto`, > which refuses to shrink below its content. Without it the middle region grows to fit its content, the > shell overflows, and the layout silently degrades back into a normal scrolling page that merely looks > correct until the content gets long. This is the single most common way a fixed layout breaks. **Two layout modes, chosen by what the page is:** | Page type | Mode | |---|---| | Table, list, dashboard — the frame matters and the data is long | Fixed viewport, as above | | Form, composer, document — the user works top to bottom | Let the whole page scroll normally | Do not force a form into a fixed frame. A long form in a 60%-height scroll box is worse than a page that scrolls. - `100dvh`, not `100vh` — on mobile the browser chrome eats the difference and the footer ends up off-screen. - `overflow: hidden` on the shell is what stops the document itself from scrolling. - `overscroll-behavior: contain` stops a scroll that reaches the end of the content from dragging the page behind it. - A fixed footer must not cover content: the scrolling region already ends above it, so no bottom padding hack is needed. - The mobile bottom tab bar (section 12) is part of the fixed frame, not part of the scrolling region. **The same three-part structure applies to any bounded box that can overflow** — dialogs, drawers, side panels, pickers, long filter lists. Header and footer stay, the middle scrolls, and that box's scroll must not leak into the page behind it. --- ## 12c. Dialogs **Structure is always header / scrolling body / fixed footer**, per section 12b. The action buttons must stay visible no matter how long the content is — a user should never have to scroll to find the confirm button. **Size is fixed and chosen up front, not grown from the content.** A dialog that resizes as its content loads jumps under the cursor. The size scale pairs a width with a height, so the frame is stable regardless of content: | Size | Width | Height | Use for | |---|---|---|---| | `sm` | 448px | 60dvh | Confirmations, single-field prompts | | `md` | 512px | 70dvh | Ordinary forms | | `lg` | 672px | 75dvh | Forms with several columns | | `xl` | 896px | 80dvh | Detail views, side-by-side comparison | | `2xl` | 1024px | 85dvh | A table inside a dialog | - Width is `min(, calc(100vw - 32px))` so it never exceeds the viewport. - Height never exceeds `85dvh`; the body scrolls, the dialog frame never does. - **Pick a size from the scale.** An ad-hoc `max-width: 1100px` is how a set of dialogs stops looking like a set. - Below 640px viewport width a dialog becomes full-screen — a centred box on a phone wastes the screen. - Close via the X button, Escape, and clicking the backdrop. A dialog with unsaved changes asks before closing. - Focus moves into the dialog on open and returns to the trigger on close. Tab stays trapped inside while open. ## 12d. Confirming something destructive Match the friction to the damage. Too much friction on a trivial action trains people to click through everything without reading, which is worse than no confirmation at all. | How bad if it happens by mistake | What is required | |---|---| | Reversible, affects one item | A plain confirm dialog. Say what will happen in one sentence. | | Hard to reverse, or affects many items | A **checkbox** the user must tick, whose label states the actual consequence. The confirm button stays disabled until it is ticked. | | Irreversible, or touches real customer data | The user must **type the exact name of the thing** into a field before the confirm button enables. | ``` ลบผู้สมัคร 24 คนที่ค้างเกิน 90 วัน [ ] เข้าใจแล้วว่าข้อมูลคะแนนและความเห็นของผู้ตรวจทั้งหมดจะหายถาวร กู้คืนไม่ได้ พิมพ์คำว่า ลบผู้สมัคร 24 คน เพื่อยืนยัน [____________________________] [ ยกเลิก ] [ ลบถาวร ] ``` - The confirm button says what it does — `ลบถาวร`, not `ตกลง`. `ยกเลิก` sits on the left and is the default focus. - The checkbox label must state the consequence, never just "ฉันเข้าใจ". - The string to type is the item's real name or count, shown right above the field so it can be read and typed. - **Never pre-tick the checkbox and never pre-fill the field.** --- ## 12e. Telling the user what happened Every action the user takes must produce visible feedback. Silence reads as "it didn't work" and makes people click twice. But the feedback has to match the message — a toast is the wrong place for something the user must act on, because it disappears. | What happened | Show it as | |---|---| | A field is invalid | **Inline, under that field.** Never a toast — the user cannot tell which field a toast is about. | | Their action succeeded and needs no response | **Toast**, auto-dismiss after 3 seconds | | Their action failed and they must do something | **Inline banner in the content area**, stays until resolved | | Loading the screen failed | **In place of the content** (section 6), with a retry button | | They must decide before anything continues | **Dialog** (section 12c) | ### Toast rules - Bottom-right on desktop. On mobile, **above** the bottom tab bar, not over it. - Success auto-dismisses after 3 seconds. **An error toast does not auto-dismiss** — it stays until dismissed. - At most 3 at once; beyond that, replace rather than stack a wall of them. - **A toast is confirmation, never the only evidence.** The screen itself must already show the change — the row appears, the number updates, the status flips. If the toast is the only proof anything happened, the screen is wrong. - **Never put anything the user needs later in a toast** — an ID, a code, an error detail they must report. It vanishes and cannot be recovered. - Announce it to screen readers (`role="status"` for success, `role="alert"` for errors). - Write what happened, not that something happened: `บันทึกใบสมัครแล้ว` — not `สำเร็จ`. ### Prefer undo over asking first For anything **reversible**, do it immediately and offer an undo in the toast, rather than blocking with a confirm dialog: ``` ย้ายผู้สมัคร 3 คนไปรอบ 2 แล้ว [ ยกเลิกการย้าย ] ``` This is faster for the common case (the user meant it) and safer for the rare one (they get it back with one click). Reserve the confirm dialogs in section 12d for things that genuinely cannot be undone. A confirm dialog on a reversible action is friction that trains people to click through without reading. The undo must stay available for at least 8 seconds — longer than a normal toast, because the user has to notice the mistake first. --- ## 13. Loading and skeletons — never make it feel like an F5 refresh ### What reloads, what stays put | Part | On first open | On button click / page change | |---|---|---| | Top bar - bottom bar - menu | Appears instantly, **no skeleton, no spinner** | **Never flickers, never disappears** — stays put | | Content (main) | Skeleton per the rules below | Only this part changes | **The principle:** the shell comes from local values already in hand — it isn't waiting on anything, so there's no reason to show a loading state for it. Only the content is actually waiting on data — show a loading state there only. **Never show a blank white screen and reload everything on every button click** — the user will feel like they hit F5, and lose their reading position. A click should only change the content; the top bar stays, and scroll position is preserved if the content is still the same set. > Acceptable exception: navigating **between separate screens** in a prototype built as separate files counts as a page change. > But set the background color in the CSS at the very top of the file, so there's no flash of white during the switch. ### Skeleton rules The rule depends on whether this is the **first sight** of the screen or a return to it. | Situation | What to show | |---|---| | **First open of a screen in this session** — nothing on screen yet | **Always show the skeleton, and hold it for at least 500ms**, even if the data was instant | | Returning to a screen whose data is already in hand | **No skeleton.** Show the content immediately | | Re-fetching while rows are already visible (filter or page changed) | Keep the rows, dim them, float a small loading pill (section 9) | - **The 500ms floor on first open is deliberate — never optimise it away.** With local mock data everything resolves instantly, so without a floor the screen snaps from blank to full and the eye cannot follow it. The floor is what makes the screen feel like it loaded rather than flickered. - **Never show a skeleton on a return visit.** The data is already there; a skeleton is pure delay. - A skeleton that appears for 100ms and vanishes reads as a glitch — that is what the floor prevents. - The skeleton **must match the real shape** — same row count, column count, and heights — so content doesn't jump once loading finishes. - **No spinner centered on the page** as the primary approach — reserve spinners for a button that's actively working (e.g. saving). - On first open with no data yet -> skeleton first, then the "no data" state per section 6. ### Splash screen **The default is: no splash screen.** It's dead time the user gets nothing back for. Only add one when there's a genuine startup step that takes longer than 1.5 seconds (e.g. checking user permissions, loading initial config), and: - Show only the system name and mark, on the app's background color. - **Disappear the instant it's ready — no artificial delay.** Never exceed 2 seconds under any circumstance. - Never use it as ad space or for a long animation. --- ## 14. Checklist before calling a screen done - [ ] Opens at 375px with nothing overflowing the edge - [ ] Has one clearly dominant primary button per screen - [ ] All 5 states present (section 6) - [ ] All Thai on screen, buttons written as outcome verbs - [ ] Numbers use tabular-nums and thousands separators - [ ] Tab key reaches everything, focus is visible - [ ] No redundant information the user already knows - [ ] Everything clickable/editable has a `data-testid` per the format in 11c - [ ] Important state lives in the URL - copying the link and reopening it shows the same view - browser back works - [ ] **Actually seen it rendered** (opened it / screenshotted it) — not verified from code alone ### How much to check, and when — spend the effort where things actually break Checking costs time. Checking everything at every level makes the work crawl; checking nothing ships broken work. **Spend the budget on mobile and on the main path — that is where breakage actually happens.** | Situation | Check this much | Do NOT do this | |---|---|---| | Level 1-3 finished | **One representative screen**, viewed in the browser at 375 and at 1280 | Do not look at every screen. Screenshots taken to inspect are scratch — do not keep them in `screenshots/`; only level 4 keeps files there. | | An edit was requested | **Only the screen that changed** | Do not re-check screens you did not touch | | **Level 4** | **Every screen on the main path**, at 375 and at 1280, screenshots saved into `screenshots/` | Do not skip 375 — it is the width that breaks. Do not screenshot screens that are not on the main path. | | Nothing changed since the last check | Skip it entirely | Do not re-verify just to look thorough | Rules that keep this honest: - **375 is never optional at level 4.** Desktop-only evidence is not evidence — mobile is where layout actually fails. - If some screens were deliberately not checked, **say which ones and why** in the level report. Silence reads as "all of them were checked". - If the environment cannot open a browser, **say plainly that visual verification was not possible**, list what the user must look at themselves, and do not write "tested" anywhere. - A screen that has never been viewed at any width cannot be part of a level that is declared passed. ### Visually verify at 1280x800 — look at the render and answer every item Code can't catch these — you must look at the rendered page. **Any "no" answer = not done.** - [ ] Content is balanced across the whole screen — **the bottom half isn't empty for no reason** (11b) - [ ] Short content is centered, not huddled in the top-left corner - [ ] The app shell's top bar is present — not a floating heading on an empty page (section 12) - [ ] The input area and the result area are visually distinct, not merged into one box - [ ] Before any button is pressed, no result has appeared yet - [ ] External-facing screens have no link or menu leading to the internal side - [ ] Strip the system's name and it still reads as this specific business, not a generic template (section 1c) ### Then repeat at 375x812 - [ ] No horizontal scrolling - tables become cards - [ ] Mobile menu matches the destination-count rule (section 12), thumb-reachable - [ ] The top bar doesn't eat so much space that content has barely any room left --- # HANDOFF PROTOCOL — the contract for passing work between "owner" and "developer" > This is the heart of the whole system. Every skill in this pipeline exists to make this two-way handoff smooth. --- ## The problem this solves **The old way:** the owner has a picture in their head -> can't describe it well -> waits on UX/UI design -> waits on a dev to build a prototype -> sees it, it's not right -> loops back. Weeks lost. **The new way:** the owner can vibe it themselves, see it working within the hour, edit it themselves. But the **backend** (database, API, security, going live) still needs a developer. So this system doesn't remove the developer — it makes **the line clear**, and **standardizes what crosses that line**. --- ## Where the responsibility line sits | Owner side (can do it themselves) | Developer side (must be handed off) | |---|---| | Look, button placement, colors, copy | Connecting a real database | | Screen order, usage flow | API / integrating with other systems | | Sample (mock) data | Login and user permissions | | Business rules ("turn red if over 30 days") | Security - real customer data | | Trying out adding/moving/removing a button | Going live (deploy) - backups | **Hard rule:** the owner can edit anything **visible** - the dev owns everything **invisible**. --- ## Direction 1 — Owner -> Developer Invoked via the `/app-send` skill. The output is a zipped **Handoff Package**. ``` handoff-{project-name}-{YYYY-MM-DD}.zip ├── README-สำหรับนักพัฒนา.md <- read this first — summarizes what to do next ├── HISTORY.md <- the decision trail: what changed, why, who asked ├── prototype/ <- what the owner built │ ├── index.html <- viewer only: device-frame shell for browsing screens, not the product │ ├── screens.json <- screen list + order (present once the shell layout is used, 2+ screens) │ ├── screens/ <- the actual designed screens — this is what the dev builds on │ ├── shared/ <- style.css / layout.js / ui.js — shared look and behaviour used by every screen │ ├── data/mock-data.json <- sample data — the dev builds the real schema from this │ ├── LEVEL.md <- which level was reached, approved by whom and when │ ├── screenshots/ <- 375px and 1280px evidence from level-4 testing │ ├── README.md <- how to open the prototype (see condition 5 below) │ └── เปิดดู.command <- double-click to open in a browser automatically (macOS) ├── SPEC.md <- what's needed, written in plain language ├── DATA.md <- data used: what fields, sample values ├── RULES.md <- every business rule (conditions, calculations, permissions) ├── TODO-DEV.md <- the backend work list for the dev, each item with a reason └── OPEN-QUESTIONS.md <- what's still unclear/unconfirmed (never filled in with a guess) ``` `screens.json`, `screens/`, and `shared/` only exist when the prototype used the shell layout (2+ screens, per `PROJECT-STRUCTURE.md` section 3) — a single-screen prototype has no shell and `index.html` alone is the product. **Conditions before sending (incomplete = not ready to send):** 1. The prototype opens and shows the real thing, not just a description of it. 2. Every item in `TODO-DEV.md` states **why it needs a dev** (what the owner specifically can't do themselves and why). 3. `OPEN-QUESTIONS.md` contains only genuinely unknown items — never filled in with a guessed answer. Every item must be traceable to the actual conversation with the owner: something the owner explicitly said they didn't know, or a decision that came up and was left unsettled. If the assistant believes something important was never raised at all, it does not belong in `OPEN-QUESTIONS.md` — it goes in a separate, clearly-labelled section headed `ข้อเสนอให้พิจารณา (ยังไม่เคยคุยกัน)`, so the developer can tell a genuine open question from an assistant-invented suggestion at a glance. 4. No real customer data, passwords, or keys of any kind are anywhere in the package. 5. `prototype/README.md` must instruct opening the prototype through a local server, or by double-clicking `เปิดดู.command` — it must never tell the developer to open `prototype/index.html` (or any screen file) directly by double-clicking the HTML. From level 3 onward the prototype loads `data/mock-data.json` via `fetch()`, which browsers block under `file://`, so opening the file directly renders a blank screen with no explanation. --- ## Direction 2 — Developer -> Owner Invoked via the `/handback-to-owner` skill. The output is a zipped **Return Kit**. ``` return-{project-name}-{YYYY-MM-DD}.zip ├── README-สำหรับเจ้าของงาน.md <- plain language, no dev jargon: what was done, what can still be edited ├── app/ <- what remains editable, marked แก้ได้:/ห้ามแก้: in the code ├── รายงานตรวจสอบ.md <- findings from /security-review + /bug-hunt (plain language) ├── แก้ตรงไหนได้บ้าง.md <- self-edit guide: which line has the color, text, buttons └── CHANGELOG.md <- what the dev changed from the original, and why ``` **Marking rule for code in the returned package** — so the owner feels safe editing it: ```html