New Tab Widget Scaffold

New Tab Widget Scaffold

Widgets live in browser/extensions/newtab/content-src/components/Widgets/.

Workflow

Step 1 — Gather requirements

Ask the user to run the requirements script first:

python3 .claude/skills/newtab-widget-scaffold/scripts/gather_requirements.py

The script asks all required questions and prints a widget spec summary. Wait for the user to paste that summary before proceeding.

Step 2 — Plan

Enter plan mode. Using the spec and the example in references/ExampleWidget/, propose the full list of files to create/modify before writing anything. Read references/notes.md for non-obvious requirements and gotchas.

Files touched by every widget:

1. ActivityStream.sys.mjs — register prefs (do this first, then run ./mach build faster before proceeding)
2. Widgets/{Name}/{Name}.jsx — new widget component
3. Widgets/{Name}/_{Name}.scss — widget styles
4. Widgets/Widgets.jsx — import, enabled logic, null guard, JSX render
5. Widgets/_Widgets.scss — add CSS class to :has() selector
6. content-src/styles/activity-stream.scss — add @import
7. stylelint-rollouts.config.js (repo root) — add the new widget's SCSS path in alphabetical order alongside the other widget entries
8. Base.jsx, CustomizeMenu.jsx, ContentSection.jsx — Customize panel toggle
9. browser/locales/en-US/browser/newtab/newtab.ftl — FTL strings

Additional files if the spec requires them:

• common/Actions.mjs + common/Reducers.sys.mjs — only if Redux state is needed

Step 3 — Scaffold

After plan approval, implement all files end-to-end without stopping between edits. Do not pause to summarize progress or ask for confirmation mid-scaffold. Work through every file in the plan in sequence, replicating the patterns in references/ExampleWidget/ and substituting values from the spec.

Only stop if you hit a genuine blocker (e.g. a file doesn't exist where expected, or the codebase structure differs from what the plan assumed). In that case, explain what you found and what decision is needed before continuing.

Step 4 — Follow-up

Remind the user:

• Add any remaining Fluent strings for context menu items and widget body labels
• Run ./mach lint

Then explain how to enable the widget:

Option A — about:config

Set both of these to true:

• browser.newtabpage.activity-stream.widgets.{widgetKey}.enabled
• browser.newtabpage.activity-stream.widgets.system.{widgetKey}.enabled

Option B — Nimbus trainhop

1. Install Nimbus devtools
2. Choose "Feature configuration enrollment" on the left side
3. Opt into an experiment for newtabTrainhop with:

{
  "type": "widgets",
  "payload": {
    "enabled": true,
    "{widgetKey}Enabled": true
  }
}