Creating WebADM Web Applications Themes with Claude Code

Introduction

This guide explains how to use Claude to build a theme in your organization's branding for the
WebADM end-user Web applications (SelfDesk, SelfReg, PwReset, OpenID, Helpdesk or custom apps).

Claude never connects to your WebADM server. You give it the theme specification, a base theme and your brand assets. Claude returns a finished theme folder, and you install and test it yourself.

The reference specification ships with every WebADM installation:
/opt/webadm/lib/htdocs/themes/README.md. Claude follows it to the letter.

What is a theme?

A theme is a single folder in /opt/webadm/lib/htdocs/themes/<name>/:

<name>/
    theme.css     all styles, with the --wa-* design tokens at the top (required)
    theme.js      theme options only, e.g. action tiles (required)
    fonts.css     font faces, including Font Awesome 4.7 (required)
    theme.svg     36x27 preview for the footer theme menu (required)
    images/       logo, background.svg and other assets (optional)

Main rules of the specification:

• A theme contains only files in its own folder. It never changes the WebADM frameworks, the shared scripts, the applications, the built-in themes (classic, modern, techno) or conf/. The only exceptions are the webapp_themes setting and an optional custom_css file.
• A theme never uses selectors that target one application, page or language.
• A theme defines every --wa-* design token and includes the functional rules from section 7.4 of the specification.
• Product updates do not replace lib/htdocs/themes custom themes.

What to give Claude

To collect the files, copy them from your WebADM server to your workstation, for example:

scp root@<webadm>:/opt/webadm/lib/htdocs/themes/README.md ./theme-input/
scp -r root@<webadm>:/opt/webadm/lib/htdocs/themes/modern ./theme-input/

Which Claude to use

• Claude Code (recommended). Start it in an empty working folder that contains the files above. Claude writes the complete theme folder there, ready to copy to the server.
• Claude.ai. Attach the files to the conversation. Claude returns the theme files to download. Because theme.css is large, ask for one file at a time if needed.

The prompt

Fill in this template and give it to Claude together with the files from section 2:

Create a new WebADM WebApps theme named <name> for <Organization>.
Follow the attached theme specification (README.md) exactly and change nothing outside the
theme folder. Start from a copy of the attached <modern|techno> theme.

Brand:
- logo: <attached file>
- colors: primary <#hex>, accent <#hex>, other brand colors <#hex> (or: sample them from the logo)
- font: <font name and attached files, or keep the default fonts>
- <light|dark> theme
- logo shown <top left on the page, above the card | only in the card header>
- background: <plain | subtle shapes using the brand colors>
- corner radius: <e.g. 4px fields / 8px card>

Check WCAG contrast (4.5:1 for text, 3:1 for icons, field borders and focus rings), create the theme.svg preview.

Tips:

• Attach the logo image. Claude can then sample the exact brand colors from it.
• Describe the look you want in plain words, for example "corporate and sober" or "a colored stripe on top of the card".
• Ask for changes in the same conversation, for example "make the main button darker" or "hide the logo on mobile".

What Claude does

1. Reads the specification and the base theme, then lists the tokens and components it will change.

2. Works out the brand palette. It checks the contrast of each color against the theme surfaces. A color that is too light for text on white, such as a bright yellow, is used only for decoration, and any text on it uses a dark brand color.

3. Builds the theme:

   • the --wa-* design tokens (primary, accent, states, surfaces, borders, radius, shadows),
     plus private variables with the theme's own prefix (for example --acme-*),
   • brand details, for example a colored stripe on top of the card and portals, a mark before the application title, or the logo above the card (hidden on small screens),
   • images/background.svg built the way the specification requires: a solid base rectangle, no mask, no filter and no full-size pattern,
   • the theme.svg preview, the theme.js options and a short README.

4. Reviews the result against the acceptance checklist in section 10 of the specification:
   every token defined, the functional rules present, the focus visible, the forced-colors and
   reduced-motion blocks present, and the small-screen layout.

5. Gives you the folder and the installation steps.

Claude can't load your WebADM pages, so the visual testing in section 7 is up to you. Send
Claude screenshots of anything you want changed.

Installing the theme

Copy the folder to a your server(s) in :

/opt/webadm/lib/htdocs/themes/

Apply the permissions :

chown -R root:root /opt/webadm/lib/htdocs/themes/<theme_name> 

On SELinux systems, also restore the file contexts with
restorecon -R /opt/webadm/lib/htdocs/themes/<theme_name>.

In /opt/webadm/conf/webadm.conf file, you must declare your theme in the following setting :

# WebApps themes: classic, modern, techno or any theme installed in lib/htdocs/themes.
# Configure with a comma-separated list. The first theme listed is the default one.
# With more than one theme, users can choose theme in the footer of the WebApps.
# Without this setting, modern theme is used by default.
#webapp_themes "modern,techno,classic"

webapp_themes "<theme_name>"

Then restart WebADM and your theme should be enforced

/opt/webadm/bin/webadm restart

Testing the theme

To try the theme without changing the configuration, open an application (for example
https://<webadm>/webapps/selfdesk/) and choose the theme in the footer theme menu. The choice
is stored in a cookie for that application, in your browser only.

Checklist (based on section 10 of the specification):

• [ ] Login pages of SelfDesk, SelfReg, PwReset and OpenID, and their pages after login: menu,
  action tiles, tables, switches, radio buttons, statuses
• [ ] An error page (for example a wrong password) and a standalone error frame (for example a disabled application)
• [ ] Another language, selected in the footer
• [ ] Desktop width, 600px, and a phone (Chrome DevTools device toolbar)
• [ ] Keyboard: Tab through every widget. The focus is always visible, and the menus open with Enter and close with Escape.
• [ ] DevTools Rendering tab: forced-colors: active and prefers-reduced-motion: reduce
• [ ] Safari: the background stays correct after switching tabs and resizing the window
• [ ] Both portals (/webapps/ and /websrvs/), with the theme set in webapp_themes
• [ ] No errors in the browser console

To report a problem, send Claude a screenshot and a short description, for example "the action tiles are too wide on mobile".

Common issues

Rendering Examples

This section provides examples of the rendered output to illustrate how the content is displayed.