TapMaker UI Theme Studio

Last updated: 2026-06-11

This is a bound TapTap Maker project for building a runnable UI Theme Editor. The editor lets designers and players tune TapMaker UI theme tokens, preview the result on real UI widgets, and export a Lua theme file usable by TapMaker.

Project Binding

• Maker project id: adba8d65-92f1-400e-9ca7-526344b350a8
• Maker page: https://maker.taptap.cn/app/adba8d65-92f1-400e-9ca7-526344b350a8
• Preview URL: https://adba8d65-92f1-400e-9ca7-526344b350a8.games.tapapps.cn/
• Current main commit after the last successful Maker build: 7972ede

Agent Rules

Read AGENTS.md first. Important project-specific rules:

• Do not edit urhox-libs/; it is a reference copy. Runtime uses the engine-bundled library.
• Business code for this project lives under scripts/.
• Build and submit with Maker MCP maker_build_current_directory.
• Do not use normal git push, branches, PRs, or GitHub workflow for this Maker project.
• Leave unrelated local changes alone. At the time of writing, tools/install-skills.sh may be locally modified and should not be submitted unless the user explicitly asks.

Current App Structure

• scripts/main.lua Main Theme Studio UI. It builds the editor shell, the preview grid, the right-side component editor, color picker panel, export panel, scroll locking, and preset switching.

• scripts/theme_studio/ThemeState.lua Theme state, default tokens, presets, component lists, component edit schemas, export order.

• scripts/theme_studio/ThemeBuilder.lua Converts editor state into a runtime UI theme via Theme.ExtendTheme(...).

• scripts/theme_studio/ThemeExporter.lua Serializes the current state into Lua code.

Current Feature State

The editor currently supports:

• Dark, neutral editor chrome independent from the theme being edited.
• Left panel for global theme tokens: name, preset selection, fonts, colors, radius, component defaults.
• Center preview panel for the theme being edited.
• Right panel for selected component tokens.
• Color editor with visual color picker.
• Lua export via Theme.ExtendTheme(...).
• Scroll lock/anchor logic to avoid panels jumping when clicking controls.
• Presets:
  • Default Light
  • DefaultDarkTheme
  • AstroonTheme
  • BrawlForgeTheme
  • PixelForgeTheme

Important behavior:

• Default Light uses DefaultTaptapTheme as the base.
• Non-default presets use Theme.defaultTheme / core base, then apply their preset overrides. This avoids inheriting unwanted DefaultTaptap styles.
• Preview overlays are scoped to the preview theme so modal/popover/drawer examples use the edited theme, not the editor theme.
• The editor shell itself should not change when the preview theme changes.

Component Coverage

The preview currently lists 50 UI exports from urhox-libs/UI/init.lua:

Panel, Label, SafeAreaView, ScrollView, SimpleGrid, Button, TextField, Checkbox, Toggle, Slider, Dropdown, DatePicker, TimePicker, ColorPicker, Calendar, Divider, Skeleton, Rating, RichText, Spine, Tabs, Pagination, Breadcrumb, Menu, Stepper, ProgressBar, Card, Alert, Badge, Chip, Avatar, Toast, Tooltip, Popover, Timeline, Accordion, List, Table, Tree, FileUpload, Carousel, Modal, Drawer, VirtualList, DragDropContext, ItemSlot, InventoryManager, SkillTree, ChatWindow, ItemTooltip.

Notes:

• InventoryManager is a data model, not a visual widget, so the preview card shows an inventory-grid use case.
• ItemTooltip is a global overlay singleton, not a normal UI.ItemTooltip {} widget, so the preview card simulates its rendered tooltip appearance.
• VERSION, Style, Theme, Input, serializers, inspector, and other utility exports are intentionally not shown as editable visual components.

Validation

Useful local checks:

/opt/homebrew/bin/lua-language-server --check=. --check_format=pretty --checklevel=Error --logpath=.tmp/lua-ls-check

Recent validation:

• LuaLS check passed after the P2 component coverage update.
• Maker remote build succeeded after commit 7972ede.
• Preview page opened and showed the Theme Studio UI.

Maker Build

Use Maker MCP only. Typical call:

maker_build_current_directory(
  target_dir = "/Users/kiro/Library/Mobile Documents/com~apple~CloudDocs/Vibe Codeing Project/TapTapMaker",
  files = { "scripts/main.lua", "scripts/theme_studio/ThemeState.lua", ... },
  message = "Short commit message",
  scriptsPath = "scripts",
  entry = "main.lua",
  timeout_ms = 600000
)

If the Maker MCP tool is not exposed in the current AI session, restart/check the Maker MCP session instead of falling back to ordinary Git push.

Performance Notes

On 2026-06-11, the user's Mac was overheating because 17 orphaned taptap-maker __maker-proxy Node processes were left running, consuming about 960% CPU total. They were cleaned up by killing only proxy processes whose parent process id was 1.

Diagnostic command:

ps -axo pid,ppid,pcpu,command | awk '/taptap-maker __maker-proxy/ {print $1, $2, $3}'

Safe cleanup for old orphan proxies:

ps -axo pid,ppid,command | awk '/taptap-maker __maker-proxy/ && $2 == 1 {print $1}' | xargs -r kill

This does not change project files or remote Maker state. It can interrupt only stale local proxy connections. A future Maker build will start a fresh proxy when needed.

The app itself is also somewhat heavy because the preview renders 50 component cards at once, including advanced components. If the page remains CPU-heavy after cleaning proxies, optimize this next:

• Render only visible preview cards.
• Add component category tabs or sections so advanced widgets are not always live.
• Replace continuously animated preview widgets with static mock previews.
• Reduce layout warning noise from the large wrapped component grid.

Known Issues / Risks

• scripts/main.lua is about 2950 lines and should be split soon.
• scripts/theme_studio/ThemeState.lua is about 2130 lines and should also be split by presets/schema/state helpers.
• The preview grid may emit layout overflow warnings. These are not Lua runtime errors, but they add noise and should be cleaned up during performance work.
• Advanced components are previewed lightly; not every runtime behavior is represented.
• Font path changes are exported, but live font-registration behavior should be reviewed if adding user-imported fonts.

Suggested Next Steps

1. Performance pass: Add category filtering or virtualized/lazy rendering for the center preview grid.

2. Refactor pass: Split main.lua into focused modules such as editor shell, preview cards, right panel editors, color editor, export panel, scroll state.

3. Theme fidelity pass: Compare each preset against its source style and correct any remaining contrast or sizing mismatches.

4. Editor UX pass: Simplify the left color editing workflow, group related color tokens, and avoid overwhelming users with every low-level token at once.

5. Import pass: Add import support for existing TapMaker theme Lua files such as DefaultTaptap.lua or custom exported files.

Handoff Checklist For Another Agent

Before making changes:

1. Read AGENTS.md.
2. Read this README.
3. Inspect git status --short.
4. Do not touch urhox-libs/.
5. Keep changes scoped to scripts/ unless the user explicitly asks for docs or tooling changes.
6. Run LuaLS before building.
7. Build with Maker MCP maker_build_current_directory.
8. Check the preview URL and browser/runtime logs after build.