Open Bug 2071608 Opened 2 months ago Updated 1 day ago

[meta] Add desktop-theme agent skills, ./mach theme and related stylelint rules

Categories

(Developer Infrastructure :: AI for Development, task)

task

Tracking

(Not tracked)

ASSIGNED

People

(Reporter: dao, Assigned: dao)

References

(Depends on 10 open bugs, Blocks 1 open bug)

Details

(Keywords: meta)

Attachments

(1 obsolete file)

This effort lands the tooling I have used locally for debugging Firefox front-end theming: six agent skills, a ./mach theme command for the scripts engineers run without an agent, and stylelint rules for the checks a stylesheet's text can decide. A good part of the skills' original bulk was knowledge about front-end architecture and Gecko behavior rather than instruction for an agent, so that lands as documentation on the CSS guidelines and design-token pages.

The skills

desktop-theme is the only skill with a description in permanent context. It triggers on Firefox::Theme and Toolkit::Themes bugs and on CSS work, and tells the agent which of the four subject skills to load. Those four and the probing skill are marked name-only, so their descriptions cost nothing until they load. The skills and their descriptions:

  • desktop-theme - A Firefox::Theme or Toolkit::Themes bug; investigating a CSS issue; writing/reviewing a CSS or design-token patch; taking before/after screenshots.
  • desktop-theme-colors - CSS issues, changes and reviews involving color - high contrast, forced colors, prefers-contrast, dark mode, system colors; a border, shadow, focus ring or icon that vanishes; states like hover/selected/focus that don't look distinct; a color right in chrome but wrong in an about: page or vice versa; a Firefox::Theme or Toolkit::Themes bug, even when the report already names the rule or token.
  • desktop-theme-layout - Front-end CSS and markup issues and changes that move, size or clip a box - overflow, scrollbars, centering, RTL, fractional scaling, font size, density, zoom, popovers, anchors; whether a change moves or resizes anything; a Firefox::Theme or Toolkit::Themes bug, even when the report already names the rule or token.
  • desktop-theme-tokens - Design tokens and CSS variables - picking one for a hard-coded value, *.tokens.json edits, Nova/Figma overrides, buildtokens, value-neutral diffs; one undefined or ineffective on a surface; finding the revision that changed a token's value; a Firefox::Theme or Toolkit::Themes bug, even when the report already names the rule or token.
  • desktop-theme-screenshots - Before/after screenshots for a bug or review; pixel-diffing a pair to prove a change visually neutral; shooting a hover or open-menu state; sampling a reporter's image; showing a hit area, focus target or stacking order.
  • desktop-probing (renamed from desktop-theme-probing, in review) - Use when measuring anything off a running Firefox (geometry, a computed style, media-query or pseudo-class state, a pref, window state, focus, a timing) through the devtools MCP, firefox-probe.py, a Marionette chrome-context probe or a scratch browser-chrome test; when writing or editing such a probe, even a small edit; when it needs --no-headless, xvfb-run, a headless compositor or the live desktop, or a headless run cannot see a value; when a chrome CSS, .xhtml or script edit does not show after a reload, or a launch dies on Missing chrome or resource URL; when a probe launch's state differs from a user's (remote-control stripes, an empty profile, about:blank); and before trusting a number a probe printed.

./mach theme

The skills' scripts that answer an engineer's own questions move out of the skills behind one mach command, so they run without an agent and changes to them go to the theme owners:

  • resolve-token: what a token resolves to per platform, theme and forced-colors state, and which resolved values a .tokens.json edit changed
  • contrast and check-hcm-colors: the contrast ratios and system-color pairs of a selector across states
  • pixel-diff: whether two screenshots differ

A later phase builds CI checks on the token and contrast tools, failing on a token that resolves to an invalid value or a cycle, and on chrome surfaces whose colors break the forced-colors system-color pairing or fall short on contrast, in each color scheme, theme and contrast mode.

Stylelint rules

The skills' rules that need no running browser move into stylelint-plugin-mozilla, so they apply to every contributor and the skill text shrinks to a pointer:

  • (forced-colors: active) never matches Windows chrome in high contrast, so a rule autofixes it to (forced-colors).
  • An override of a token with a forced-colors or prefers-contrast value hides that value, so a rule requires a guard that excludes the token's conditions, and autofixes it.

Rules that need the computed cascade or a live state stay in the skills.

Progress at a glance

Phase Goal Bug Status
1 Move the product knowledge into the tree bug 2071602, bug 2085331, bug 2090203 DONE
2 Port the skills into the tree bug 2071613 DONE
3 Move the skills' bug attachment script into the bug-filing skill bug 2090033 DONE
4 Add mach commands for the skills' scripts that engineers may want to run bug 2090042 DONE
5 Build CI checks on the token and contrast tools behind ./mach theme bug 2090765 IN REVIEW
6 Load the colors, layout and tokens skills for code review bug 2090683 DONE
7 Send agents to a theme skill before they edit a token file or theme CSS bug 2090689 IN REVIEW
8 firefox-desktop-frontend skill integration bug 2094544 IN REVIEW
9 Update CSS guidelines, and have the theme skills check the rules bug 2095051 IN REVIEW
10a Stylelint: Drop the tokens skill's advice to delete needless disables bug 2090682 DONE
10b Stylelint: Require the boolean forced-colors media query bug 2090680 IN REVIEW
10c Stylelint: Require a high contrast guard on design token overrides bug 2090679 IN REVIEW
10d Stylelint: Require a comment on !important Not filed yet PLANNED
10e Stylelint: Report rules nested under a pseudo-element, which never match Not filed yet PLANNED
10f Stylelint: Stop counting nested media queries toward the nesting depth limit Not filed yet PLANNED
10g Stylelint: Tell agents in the skills when to run ./mach lint bug 2094532 PLANNED
11 Compare screenshots across many surfaces and color modes on one page bug 2091312 IN PROGRESS
12 Remove Nova mentions once the pre-Nova code is gone Not filed yet PLANNED

References

Keywords: meta
Summary: Land the theme-debug skills in the tree and document the behaviour they measure → [meta] Add theme-debug skills and update related in-tree theme documentation
Depends on: 2071613
Assignee: nobody → dao+bmo
Status: NEW → ASSIGNED
See Also: → 2073795
Depends on: 2073795
See Also: 2073795 →
Summary: [meta] Add theme-debug skills and update related in-tree theme documentation → [meta] Add desktop-theme skills and update related in-tree theme documentation
Blocks: 2073795
No longer depends on: 2073795
Depends on: 2085056
See Also: → 2085325
See Also: → 2085326
See Also: 2085325 →
See Also: → 2085329
Depends on: 2085331
Depends on: 2090033
Depends on: 2090042
Depends on: 2090203
Depends on: 2090260
Depends on: 2090679
Depends on: 2090680
Depends on: 2090682
Depends on: 2090683
Summary: [meta] Add desktop-theme skills and update related in-tree theme documentation → [meta] Add the desktop-theme agent skills, ./mach theme and related stylelint rules
Depends on: 2090689
Summary: [meta] Add the desktop-theme agent skills, ./mach theme and related stylelint rules → [meta] Add desktop-theme agent skills, ./mach theme and related stylelint rules
Depends on: 2090765
Depends on: 2091312
Depends on: 2091974
Depends on: 2094532
Depends on: 2094544
Depends on: 2095051
You need to log in before you can comment on or make changes to this bug.

Attachment

General

Created:
Updated:
Size: