UI redesign: implementation checklist

A backlog of cycles for building the redesign and its theme from the mockups. It is a planning input, not a Railspike artifact. Each cycle is marked with the process it uses (see below); Railspike cycles still go through Railspike's steps with an explicit approval at each gate, and may be reshaped during their own Step 1 or Step 2. Context and decisions are in next_steps.md.

Process per cycle

Decided by the user on 2026-10-26. The mockups and this checklist already cover much of Railspike's problem framing and requirements, so Railspike is kept where there are real unknowns or high stakes. Marking a cycle Direct is the user's explicit Railspike opt-out for that cycle under AGENTS.md.

For a Direct cycle:

• Work on its own branch (no direct merges to main).

• Use this checklist's items for the cycle as the spec; record any change of scope here rather than silently expanding it.

• Apply every check in Checks that apply to every cycle, and record UI verification in docs/plans/ui_copy_audit_checklist.md or a short note in this folder.

• Commit when the cycle's "Done when" is met. Direct cycles are not part of the railspike-effort study, which only collects Railspike cycles.

Sizing follows Railspike's rules for every cycle, Direct ones included: each is a releasable vertical slice (normal entry, end-to-end outcome, required recovery) that fits within a day or eight Step 3 stages. The item lists below are suggestions for Step 3 (or the spec, for Direct cycles), not approved plans.

Mockup references are relative to mockups/. Template paths are from plan_prompt.md.

Before the first cycle

• Decide the theme: Ma first; Living Sky optional and unscheduled (next_steps.md, 2026-10-26).

• Decide default versus opt-in: opt-in until ready; cycle T4 makes it the default.

• Decide fingerprint colors: deferred to cycle D4.

• Member preview: skipped, no regular members yet.

• Decide the six round 1 product proposals (2026-10-26; see next_steps.md, item 5).

Checks that apply to every cycle

Copy these into each Railspike cycle's Step 3 verification and Step 4 summary; Direct cycles apply them before committing.

• Rendered flow checked on phone and desktop in initial, loaded, empty, success, failure and expanded states (CONTRIBUTING.md, UI copy and verification).

• Page overflow checked with real content, long values and pagination.

• Every registered theme checked on the changed screens, not only Light and Dark (src/ForumRewrite/View/ThemeRegistry.php, docs/runbooks/theme_development_guide.md).

• Navigation changes mapped in public/assets/theme-nav-icons.css for Word97, Chicago and Midnight, including Tools buttons and subnavigation, and checked visually in each (AGENTS.md).

• Copy assertions in tests updated for removed or changed strings; copy cleanup recorded in docs/plans/ui_copy_audit_checklist.md.

• No new third-party dependency without approval under CONTRIBUTING.md.

• Theme hooks for the screen added (listed per cycle), inert in existing themes.

• Changed shared static assets go through the repository's existing asset fingerprinting (hashed copies such as browser_signing.<hash>.js exist in public/assets/).

• Any new motion animates only transform or opacity and stops under prefers-reduced-motion.

Phase 1: Base structure

Wording, arrangement and flow from round 1, theme-independent. Each cycle also adds its screen's theme hooks.

Cycle 1: ui_shell_navigation

Process: Railspike. Step 1 compares options: the phone tab bar is a new navigation surface, and moving rare destinations into the account menu has alternatives.

App shell and navigation. Mockup: shell.html. Templates: templates/layout.php, templates/partials/nav.php, templates/partials/theme_menu.php.

• Top bar with three destinations (Board, Users, Messages), one New post, and an account menu.

• Rare destinations (Tools, About, Invite, theme choice) move into the account menu.

• Phone bottom tab bar. Shipped in document order (New post not centered) and with About kept in the account menu rather than replacing Messages; see the Step 4 summary.

• Theme menu as swatches inside the account menu. The existing theme menu moved into the account menu; swatches were not built.

• Hooks: data-tab on navigation items, an empty aria-hidden sky layer as the first child of the app shell, an empty .site-brand__mark slot in the wordmark.

• Icon themes: tab bar and account menu icons mapped for Word97, Chicago and Midnight.

• Done when: every page uses the new shell in every theme, with no lost destination. Done 2026-10-27, merged to main (5ac1432de).

• Follow-up (2026-10-28, ui_tab_bar_scroll_away): on phones the tab bar slides away while scrolling down and returns on scroll up, at either page end, on focus and while the account menu is open, after the user reported that floating bars cover content and cannot be dismissed. Real-iPhone feel pending.

Cycle 2: ui_board_list

Process: Direct.

Mockup: board.html. Templates: pages/board.php, partials/thread_card.php. Depends on cycle 1.

• Denser thread rows with separate filter (All / Liked) and sort (Newest / Oldest / Top) controls.

• Pinned threads grouped above Latest.

• Designed empty state for Liked.

• "Show older threads" pager.

• "(unapproved)" restyled as a "Pending" chip, still shown to everyone (decided 2026-10-26).

• Hooks: pinned-list class and an empty .like-mark slot on Liked are in; --person waits for cycle D4, since no avatar or person color exists yet (decided 2026-10-27).

• Done when: browsing, filtering, sorting and paging work in all themes.

Built 2026-10-27 on feat/ui-board-list as a boardCard presentation choice list selected only by ZenMemes; Chouse and MIT Rap Club keep the card board, QDB its quote board. Decisions and limits:

• Paging uses the shared native-link pagination (docs/reference/pagination.md): 50 latest threads per page, pinned threads on the first page only, "Show older threads" / "Newer threads" links, and First page after an expired or foreign position. It does not load more into the same list.

• Sort is a native <details> menu ("Newest ▾"); filter links and sort items keep .nav-link[data-nav-key], so the icon themes' existing icons apply with no new mapping.

• The board's own "New Post" link is gone (the shell has New post), matching ae0ab8859 on ui/remove-board-new-post.

• Rows have no avatars. Excerpts are plain text and skip image references; the quick-compose row is unchanged (composers are cycle 6).

• The flag-gated thread density toggle is not shown on the list board, which is already the dense view; it stays on tag pages and the card boards.

• Unchanged: the offline reader's own board rendering, and pending-post insertion after the composer.

• Verification: BoardListTest (paging both ways, pinned placement, recovery, empty Liked, sort menu, Pending chip, image excerpts, other sites unchanged); one full suite run (1594 run, failures limited to five that also fail on main plus three board tests since updated and passing); guest JavaScript on/off matrix at 1280px and 390px; all 13 themes plus Auto with the sort menu open on desktop and phone; board_compose_focus, listing_query_dialog, nav_active_theme_styles, feature_flags_toolbar, standard_activity_pagination pass. signed_reactions failed once and passed on rerun; compose_layout_stability also fails on main. Signed-in viewers and a real Pending author were checked through server-rendered tests, not in a browser.

Cycle 3: ui_thread_reply_dock

Process: Railspike, no Step 1.

Mockup: thread.html. Templates: pages/thread.php, partials/thread_root_card.php, partials/post_card.php, partials/reply_form.php. Depends on cycle 1.

• Reply box docked to the bottom of the viewport, fixing the reported off-screen textarea.

• Tag-only posts (#pin, #pinned) shown as one-line activity entries instead of empty cards.

• Consecutive posts by one person joined into one block.

• Agent status shown in place ("Writing a reply…"), and agent failures explained without a Retry that cannot work.

• Hooks: data-sky (original poster) on the page, --person on posts and replies.

• Done when: reading, liking, replying and the agent states work on phone without the keyboard hiding the reply box.

Cycle 4: ui_account_states

Process: Railspike, no Step 1.

Mockup: account.html. Template: pages/account_key.php.

• Three clear states: guest, set up and waiting for approval, approved.

• ~~"Not backed up" warning at the top until a backup exists.~~ Replaced 2026-10-28: keys are cheap and the user is the name, so there is no warning; the Save row shows the date of the last saved copy.

• Back up as a sheet with passphrase and format choice (text file or Starfield image), now "Save a copy of this key".

• Advanced key controls (keys, linking, storage) moved behind Advanced.

• Record the last backup date in the browser (shown as "Saved {date}" on the Save row).

• Hooks: data-tone on rows, a starfield slot and night class on the account card, data-sky on the page.

Built 2026-10-28 on feat/ui-account-states for all sites; see the Step 4 summary.

• Done when: a member can see their state, back up, restore and reach advanced controls in all themes.

Cycle 5: ui_first_post_identity

Process: Railspike. Step 1 compares options for when and where keys are generated.

Mockups: compose-thread.html, account.html. Templates: pages/compose_thread.php, partials/thread_compose_form.php, pages/account_key.php, plus the browser signing scripts. Depends on cycle 4.

• Name chosen inline (composer and account page); no window.prompt or window.confirm.

• ~~Key generation starts when the composer or account page opens, so Post only signs and sends.~~ Revised in Step 1: the key is made in the browser ahead of time, but the server learns it with the first post, reply or Like (one registration, about 0.2 s locally on a ZenMemes-sized copy). G2, the server accepting the key with the first action itself, is the follow-up.

• A visible state while the key is created ("Creating your account…"), with recovery if it fails.

• Done when: a new visitor can write and publish a first post with no browser dialogs and no long wait after pressing Post.

Built 2026-10-28 on feat/ui-first-post-identity for all sites (not merged); see the Step 4 summary. Readers no longer register keys. The real-iPhone check on ZenMemes is pending with the user.

Cycle 6: ui_composers

Process: Direct.

Mockups: compose-thread.html, compose-reply.html. Templates: pages/compose_thread.php, pages/compose_reply.php. Depends on cycle 5.

• One shared composer component: title, body, tools.

• Reply composer as the no-JavaScript fallback with parent context.

• Done when: new threads and replies post from both pages, with and without JavaScript.

Built 2026-10-28 on feat/ui-composers:

• partials/composer.php is the one composer. thread_compose_form.php and reply_form.php set its options and include it, so every composer on every site renders there: New post, reply page, board quick compose, thread inline reply, QDB add, and Forte's new post dialog and reply panel.

• Order: Title ("Title — or we’ll use your first line", full New post only), body, a tools row (# tags and Event disclosures, which work without JavaScript), the "Post as" row, then Post and the ··· menu.

• Wording from the mockups: New post / Post / Post reply; ··· menu: Post anonymously or Reply anonymously, Save to Outbox, Remove timestamps (QDB), Discard draft.

• Reply page: "Reply to {name}" with the parent as a quote, "author · date · in {thread title}". Long parents are clamped to four lines, with Show more linking to the post. A missing parent says "That post was removed or isn’t in this thread. Reply to the thread instead."

• Scope notes, deviations from the mockups, deferred:

  • Attach image stays in the ··· menu, not the tools row. It appears only once the browser knows the viewer may attach images, so in a toolbar it would shift the page after first paint; compose_layout_stability caught this.

  • The ··· menu stays beside Post, not in the tools row, so the phone keyboard panel keeps its layout.

  • Deferred: the phone header bar with Cancel/Post, the event card and tag chips (the existing fields are kept inside the tool disclosures), the offline "Save" mode, and "Keep draft / Discard" on Cancel.

Cycle 7: ui_profile_users

Process: Direct.

Mockups: profile.html, users.html. Templates: pages/profile.php, pages/username.php, pages/users.php.

• One person page with a Message button; keys listed as identities.

• Searchable compact member list with pending approvals beside it.

• Hooks: the banner slot (.starfield.banner with data-seed) is in; --person waits for cycle D4, as in cycle 2, since no person color exists yet.

• Done when: finding a member, opening their profile and messaging or approving them works in all themes.

Built 2026-10-28 on feat/ui-profile-users:

• Users: "Members | Waiting" tabs. Members is a compact list with one row per person ("N threads · M posts", an Agent chip), a search field and an Activity/Name sort; both work on the list already on the page and are hidden without JavaScript.

• Waiting (/users/pending): it used to redirect approved members to User Access. It now shows the waiting list itself, with the same Approve buttons, beside Members, and the count updates in place after an approval. It stays approved-members-only (403 otherwise), so the Waiting tab, with its count, is rendered only for approved members; visitors without cookies get the static copy, which has no tabs, and other viewers see just "Users" (user request, 2026-10-28: don't show a tab people can't open). The empty state reads "No one is waiting."

• Person page (/user/{name}): the heading shows the name, "N threads · M posts" and an Approved (or Automated reply agent) chip. Message opens /messages/conversation/{name}, which replaces the embedded send-only form; your own page shows "Edit in Account" instead. Threads | Replies is a tab pair, and each key is listed under Identities ("Approved by …"), linking to its key page. "Manage access" shows for operators only; it replaces the "User Access" link and the "Approved by: …" line.

• Built from existing components (fixed after review; see the debug log): the tabs are the board's All | Liked filter (.board-filter); member rows and Identities are Account's grouped rows (.account-group / .account-row); the person heading is Account's card (.account-card, .account-id); threads use partials/thread_row.php, and replies use the same row markup. These pages load account.css and thread-list.css; the only CSS of their own is page layout in site.css.

• Kept as is: the key page (/profiles/{slug}) keeps the presentation accepted on 2026-10-27 in profile_public_details: no name link, and Approval details beside Approved/Not approved. That decision is newer than the mockup.

• Deferred: approving with a 5-second Undo before publishing (a proposal in the mockup that changes approval behavior), showing each waiting person's first post in their row, avatars, and the agent page's empty-state wording.

Cycle 8: ui_messages

Process: Railspike, no Step 1.

Mockups: messages.html, conversation.html. Templates: pages/private_messages.php, partials/private_message_list.php, pages/private_message_conversation.php, partials/private_message_composer.php.

• Conversation list with two panes on desktop and an explanation for members not yet approved.

• Bubbles, a plain-language encryption line, and per-message failure recovery (verify, confirm, retry).

• Previews decrypt progressively, with a per-row "Couldn't decrypt preview" and Retry.

• Hooks: --person on the conversation, a starfield slot on the first-message screen, a hook on incoming messages for the decrypt effect.

• Done when: reading, sending and recovering from each failure work on phone and desktop.

Cycle 9: ui_tools_launcher

Process: Direct.

Mockup: tools.html. Templates: pages/tools.php, partials/tools_nav.php.

• Tools grouped by who uses them (Your device, Reading, Community, Operator), each listed once.

• Hooks: a stable data-tone key per tool in src/ForumRewrite/Tools/ToolsPageSupport.php, data-shape on group headings.

• Icon themes: Tools launcher buttons and subnavigation mapped in theme-nav-icons.css.

• Done when: every tool is reachable once, in all themes.

Phase 2: Theme hooks

There is no separate cycle. Hooks ship with the base cycle for their screen (listed above). Before Phase 3, confirm the full set exists:

• Sky layer in the app shell (decorative, aria-hidden).

• data-tab, data-tone, data-shape, data-sky, data-person / --person.

• Avatar data-cut and --av-rot from a hash of the name (or fingerprint, per decision 3).

• Starfield slots with data-seed: profile banner, account card, identity thumbnails, first-message screen, backup format choice.

• Empty .mark slot in the wordmark; .hud caption slots on account cards.

Phase 3: The theme

Ma was chosen (2026-10-26) and ships opt-in. Living Sky (T3) is optional and unscheduled.

Cycle T1: ma_theme_day

Process: Railspike.

Ma in light mode. Step 1 decides how a theme with a day and a night look is registered (one auto theme that follows the system, or separate "Ma" and "Ma Night" entries), given ThemeRegistry's one-mode-per-theme entries.

• Register the theme in src/ForumRewrite/View/ThemeRegistry.php and update tests/ThemeRegistryTest.php.

• public/assets/theme-ma.css, adapted from mockups/zen/ma.css to the real templates.

• Paper surfaces and grain, the mincho serif stack (system fonts only), vermilion accent.

• Ando light shaft, Turrell light field in the page's person color, teamLab petals.

• Ensō-face logo and seal; Fukuda loaders and the empty-Liked face.

• Tanaka avatars (flat circles with a per-name cut); shapes on navigation and Tools groups.

• Flow-field generator as first-party JavaScript (from mockups/mockup.js), drawn once per element, for the account card, profile banner and identity thumbnails.

• Profile skyspace banner with the person's flow field and the slow dusk glow.

• Contrast verified against the values in visual_direction_notes.md (muted text 4.7:1 or better, tool glyphs 3:1 or better).

• Done when: Ma can be chosen from the theme menu and every redesigned screen renders correctly in it on phone and desktop.

Cycle T2: ma_theme_night

Process: Railspike, no Step 1.

Ma's cyberpunk dark mode. Depends on T1.

• Night tokens; neon logo and seal with a one-time flicker (no more than 3 flashes a second; none under reduced motion).

• Rain in place of petals, still following the community pulse once cycle D1 exists; neon light shaft.

• Flow fields as neon on the account card and banner.

• ID-chip account cards with captions of real key data; "Signatures verified" only after verification succeeds.

• Decrypt scramble on incoming messages, hooked into the real decryption step; screen readers get the final text; skipped under reduced motion.

• Glitch only on short failure labels; long error text gets a split neon edge.

• Holographic agent; monospace system font for times, counts and fingerprints.

• Done when: night mode renders every redesigned screen with the night contrast values met (cyan 12.6:1, neon 5.4:1, muted text 5.7:1 or better).

Cycle T3 (optional, unscheduled): living_sky_theme

Process: decide when scheduled.

• Register and build theme-living-sky.css from mockups/zen/zen.css.

• Measure frosted-glass cost on a low-end phone; fall back to solid surfaces under prefers-reduced-transparency or on low-end devices.

• Done when: Living Sky is selectable and scrolls smoothly on the test phone.

Cycle T4: ma_theme_default

Process: Direct.

Only when we decide Ma is ready to become the default (decision 2: opt-in until then).

• Make the chosen theme the default for ZenMemes; keep the previous default selectable.

• Check Auto, legacy aliases and other sites' permitted theme lists.

• Done when: new visitors get the new theme and existing choices are preserved.

Phase 4: Features that need data

Each needs its own product decision before its cycle starts.

Cycle D1: community_pulse

Process: Railspike, no Step 1.

• One cached count of posts in the last 24 hours, mapped to data-pulse (quiet / steady / busy) on the app shell.

• Prefer existing read-model queries; if a schema change is needed, follow the read-model rules in CONTRIBUTING.md.

Cycle D2: profile_constellation

Process: Railspike, no Step 1.

• Per-identity post and like counts drive the profile artwork (one star per post, brighter for liked posts), capped.

• Likely a read-model schema change: bump ReadModelMetadata::SCHEMA_VERSION, update docs/specs/read_model_schema_v1.md, add the rebuild regression test, and verify ./v3 rebuild.

Cycle D3: post_seals

Process: Railspike, no Step 1. Step 2 must state the security rule: a seal appears only after verification succeeds.

• A seal per author key, generated from the key (not the per-post signature).

• Shown only after the post's signature verifies; never a placeholder seal.

• Generator keeps lookalike seals apart, including for color-blind users.

Cycle D4 (deferred): fingerprint_colors

Process: decide when scheduled.

• Person colors and avatar cuts derived from the key fingerprint instead of the name.

• Decide what happens when a person changes keys.

Not yet planned

Decided against or deferred on 2026-10-26: Unlike (not implemented), Undo after Approve (skipped), offline message queue (deferred), hiding Tools groups the viewer cannot use (deferred), fingerprint colors (cycle D4, deferred).

From the graded idea list in visual_direction_notes.md, still unbuilt even as mockups: time-of-day sky (A4), planet flight between screens (A5), kintsugi for edits and resends (B3), the closing ensō for reply progress (B1), riso meme thumbnails (B6, risky), and bolder titles for busy threads (B7, needs font approval). Add a cycle here if any is chosen.