Customize a Module's Screens
Take over how a Module's pages look and behave on screen while its logic keeps getting updates.
Every feature Module is split in two. Its core holds the logic: rules, data, permissions, the hooks that load and save. Its UI layer holds the screens: what each page draws. Customizing a Module's screens makes the UI layer yours to edit and leaves the core on updates. You get the layout you want and keep the Module's fixes.
Try the theme first
Colours, corners, control sizes, density and fonts are theme tokens, and the app's theme file
overrides them on every screen, the Modules' included. Stardeck never changes that file. If the
change you want is a look, it belongs there, with no Module customized. See your app's
AGENTS.md § "Theme and branding".
Customize
Your coding agent calls customize_module_ui on your org's MCP server. In the
dashboard, open the app's Settings → Modules, then Customize screens in the Module's actions
menu. Only Modules whose screens are separate from their logic offer it.
From then on:
- The Module's screen folders, and the screens of its enhancements, are your app's. Edits there no longer count as changes to Stardeck.
- The Module's core stays Stardeck's, and the editing tools still refuse it.
- Screen tests sit beside the screens, so they become yours too. Rework a screen and update its tests with it. The core's tests stay Stardeck's and keep running.
Your screens call the Module's core through the hooks in its client/ folder, exported from its
index.ts, and through the loaders in server/ui.ts, never by fetching its endpoints themselves.
That way a fix in the core reaches your screens too.
What an update does
An update merges into your screens instead of replacing them. Keep your markup, styling and layout, and take the update's new props, fixes and behavior. New behavior arrives as new hooks in the core; wire them into your screens rather than writing your own. A new screen the update adds arrives in Stardeck's look; restyle it to match. The update gives your agent the list of customized files it also changed, the hooks it added and removed, and the new screen files.
A release that removes or renames a hook is a major version, and its changelog tells your agent what replaces it.
Undo
Return screens to Stardeck's version in the same menu, or undo_customize_module_ui, gives the screens
back to Stardeck. The next update puts back Stardeck's version of every screen file and
deletes the files you added there, so your screen edits are lost. The core is not affected.
Customize or detach
| Customize screens | Stop updates for this Module | |
|---|---|---|
| What becomes yours | The screens | The whole Module, logic and screens |
| Updates | Keep coming, merged into your screens | Stop for that Module, for good |
| Undo | Yes | No |
Detach only when you must change a Module's logic. Modules that use a detached one keep updating
and can break against your copy; the detach warning lists them. Agents use detach_module for one
Module and detach_app to stop updates for the whole app. Both show a preview first.
The rules your agent follows are in your app's AGENTS.md § "Core and UI layer".
Next steps
Updates
What to check in your customized screens after an update