# UI Thorough > Full UI development workflow from specs to auditing. Use for new apps or major features. Use when this capability is needed. - Skill: `tomevault-io/ui-thorough` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/ui-thorough` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/ui-thorough/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/ui-thorough --- # UI Thorough Complete workflow for ui-engine apps: requirements → design → code → audit → simplify. ## On Skill Load **IMMEDIATELY invoke `/ui-basics` using the Skill tool before doing anything else.** It covers the mental model, bindings, object model, and patterns. Without it, standard web patterns will lead you astray. --- # Workflow Follow these steps in order. ## Step 0: Consolidate Existing Checkpoints **Check for existing checkpoints from `/ui-fast` prototyping:** ```bash {cmd} checkpoint list ``` If checkpoints exist (output is not "No checkpoints for "): 1. **Thoroughly explore what was done:** Use `checkpoint diff 10` to see the full diff from earliest to current. Use `checkpoint diff N` for specific checkpoints. The checkpoint messages (from `list`) provide context for each change. 2. **Update BOTH requirements.md AND design.md:** - Read current `requirements.md` and `design.md` - Update `requirements.md` first — add any new features that were prototyped - Update `design.md` to match — add data model fields, methods, viewdef changes - Use the diff output to ensure nothing is missed - **Both files must be updated** — the design must stay in sync with requirements 3. **Simplify the checkpointed code:** Run the code-simplifier agent on the app's Lua code: ``` Task tool with subagent_type="code-simplifier" prompt: "Simplify the code in {ui_dir}/apps//app.lua" ``` 4. **Record as fast code gaps:** Since checkpoint work is rapid prototyping ("quick and dirty"), add a summary to `TESTING.md` under `## Gaps` with a `### Fast Code` subsection: Add a `### Fast Code` subsection under `## Gaps` in `TESTING.md` listing the methods/features added via checkpoints that may need review. This flags the code for later cleanup while preserving the feature. 5. **Clear checkpoints:** ```bash {cmd} checkpoint clear ``` This ensures prototyping work is captured in the design before proceeding. ## Step 1: Create Progress Steps (IMMEDIATELY) **Run BEFORE reading any files.** The user is watching — without this, the build looks frozen. Steps: `{'Read requirements', 'Requirements', 'Design', 'Write code', 'Write viewdefs', 'Link and audit', 'Simplify', 'Set baseline'}` Use `mcp:createTodos(STEPS, APP)` with the steps list and app name. The listed steps above all have matching entries in `UI_STEP_DEFS` (`apps/mcp/app.lua`) for tailored progress messages; new labels work but get generic ones. Also create Claude Code tasks (see MCP Methods in `/ui-basics`). **Progress pattern:** At each step transition, call `mcp:startTodoStep(N)` and update Claude Code tasks. At the end, call `mcp:completeTodos()`. ## Step 2: Requirements - Read `{ui_dir}/apps//requirements.md` (create with prose if missing) - Read `TESTING.md` if it exists — note Known Issues - Update requirements if the task requires changes - Ensure requirements are complete and unambiguous before designing ## Step 3: Design - Check `{ui_dir}/patterns/` for reusable patterns - Write `{ui_dir}/apps//icon.html` with an emoji, ``, or `` - Write `{ui_dir}/apps//design.md`: - **Intent**: What the UI accomplishes - **Layout**: ASCII wireframe showing structure - **Data Model**: Tables of types, fields, descriptions - **Methods**: Actions each type performs - **ViewDefs**: Template files needed - **Events**: JSON examples with **complete handling instructions** ## Step 4: Write Code Write `{ui_dir}/apps//app.lua` — Lua classes and logic. **Write code BEFORE viewdefs** — viewdefs may reference types that must exist first. ## Step 5: Write Viewdefs - `viewdefs/.DEFAULT.html` — HTML templates - `viewdefs/.list-item.html` — List item templates (if needed) ## Step 6: Link and Audit ```bash {cmd} linkapp add {cmd} audit {cmd} theme audit ``` The audit tool checks Lua code and viewdefs for common violations. Also do **AI-based checks**: - Compare design.md against requirements.md - Compare implementation against design.md **Fix violations:** 1. Dead methods NOT in design.md → Delete from `app.lua` 2. Dead methods IN design.md → Record in `TESTING.md` under `## Gaps` 3. Other violations → Fix in code 4. Warnings (external methods) → OK to ignore **Clear Empty Gaps:** If there were gaps and they are all gone now, leave the `## Gaps` section empty, do not leave a comment. ## Step 7: Simplify Use the `code-simplifier` agent: ``` Task tool with subagent_type="code-simplifier" prompt: "Simplify the code in {ui_dir}/apps//app.lua" ``` ## Step 8: Set Baseline Commit the audited code to the local branch and set a clean baseline for future `/ui-fast` iterations: ```bash {cmd} checkpoint local "thorough: " {cmd} checkpoint baseline ``` The `local` commit preserves audited code on a permanent branch that survives baseline resets. The `baseline` clears trunk for fresh `/ui-fast` checkpoints. ## Step 9: Complete ```bash {cmd} run "mcp:completeTodos()" {cmd} run "mcp:appUpdated('APP_NAME')" {cmd} run "mcp:addAgentMessage('Done - built APP_NAME')" ``` --- # Examples See `{ui_dir}/apps/app-console` for complete examples: - `requirements.md` — Requirements spec - `design.md` — Design spec --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/zot) — claim your Tome and manage your conversions.