Add New Service Theme
Developmentadd-new-service-themeAdd New Service Theme is an Agent Skill for development published in the bbc/simorgh repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Adds a new World Service language/service theme to the SCSS modules theming system (ThemeProviderSCSSModules). Use this when asked to add or set up a theme for a new service.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/bbc/simorgh/blob/HEAD/.github/skills/add-new-service-theme/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/add-new-service-theme, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Skill: Add a New Service Theme (SCSS Modules)
Purpose
All existing World Service language themes have been migrated from Emotion CSS-in-JS to SCSS modules + CSS custom properties (ThemeProviderSCSSModules). This skill covers creating a theme for a new service using that same system going forward.
The Mundo theme is the best reference implementation to follow: src/app/components/ThemeProviderSCSSModules/themes/mundo/
When to Use
Use this skill when a new World Service language/service is being added and needs a theme set up under the SCSS modules theming system.
How the theming system works
For the Mundo theme, there is a directory including the main theme file itself: src/app/components/ThemeProviderSCSSModules/themes/mundo/mundo.ts; this file imports various SCSS files and relies on their side-effects to either import relevant resources or set CSS custom properties to apply runtime theme customisations.
The theme is made available to be dynamically imported in src/app/components/ThemeProviderSCSSModules/themes/loadableConfig.ts.
Steps
- Inspect the mundo theme as a guide:
src/app/components/ThemeProviderSCSSModules/themes/mundo/ - Create a new directory for the service under
src/app/components/ThemeProviderSCSSModules/themes/<service>/ - Create
palette.scssin that directory, mapping the service's palette tokens to CSS custom properties (usesrc/app/components/ThemeProviderSCSSModules/themes/mundo/palette.scssas a guide, importing from../../palette.scss) - Create the main
<service>.tstheme entrypoint, importing:- The appropriate font face SCSS files from
../../fontFaces/ - The appropriate font variant SCSS file from
../../fontVariants/ - The appropriate font script SCSS file from
../../fontScripts/ ./palette.scsswithThemeProviderfrom#app/components/ThemeProviderSCSSModules/withThemeProviderbrandSVGfrom../../chameleonLogos/<service>(see step 5)
- The appropriate font face SCSS files from
- Create the chameleon logo at
src/app/components/ThemeProviderSCSSModules/chameleonLogos/<service>.tsx— this step is easy to miss and must not be skipped - Register the theme in
loadableConfig.tsatsrc/app/components/ThemeProviderSCSSModules/themes/loadableConfig.ts, adding a new entry following the same pattern asmundo— this step is easy to miss and must not be skipped - Present this for feedback and iterate.
Checklist
Before considering a new service theme complete, verify all of the following:
-
themes/<service>/palette.scsscreated with correct CSS custom properties -
themes/<service>/<service>.tscreated, importing font faces, variants, script, palette, and brandSVG -
chameleonLogos/<service>.tsxcreated -
themes/loadableConfig.tsupdated to include the new service