OpenParable
Skip to content
← Back to skills

Add New Service Theme

Development
add-new-service-theme

Add 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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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

  1. Inspect the mundo theme as a guide: src/app/components/ThemeProviderSCSSModules/themes/mundo/
  2. Create a new directory for the service under src/app/components/ThemeProviderSCSSModules/themes/<service>/
  3. Create palette.scss in that directory, mapping the service's palette tokens to CSS custom properties (use src/app/components/ThemeProviderSCSSModules/themes/mundo/palette.scss as a guide, importing from ../../palette.scss)
  4. Create the main <service>.ts theme 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.scss
    • withThemeProvider from #app/components/ThemeProviderSCSSModules/withThemeProvider
    • brandSVG from ../../chameleonLogos/<service> (see step 5)
  5. Create the chameleon logo at src/app/components/ThemeProviderSCSSModules/chameleonLogos/<service>.tsx — this step is easy to miss and must not be skipped
  6. Register the theme in loadableConfig.ts at src/app/components/ThemeProviderSCSSModules/themes/loadableConfig.ts, adding a new entry following the same pattern as mundo — this step is easy to miss and must not be skipped
  7. Present this for feedback and iterate.

Checklist

Before considering a new service theme complete, verify all of the following:

  • themes/<service>/palette.scss created with correct CSS custom properties
  • themes/<service>/<service>.ts created, importing font faces, variants, script, palette, and brandSVG
  • chameleonLogos/<service>.tsx created
  • themes/loadableConfig.ts updated to include the new service