[meta] Add desktop-theme agent skills, ./mach theme and related stylelint rules
Categories
(Developer Infrastructure :: AI for Development, task)
Tracking
(Not tracked)
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 fromdesktop-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,.xhtmlor script edit does not show after a reload, or a launch dies onMissing 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.jsonedit changedcontrastandcheck-hcm-colors: the contrast ratios and system-color pairs of a selector across statespixel-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-contrastvalue 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
- CSS Guidelines - where the forced-colors, chrome-versus-content and device-pixel material lands
- use-design-tokens rules - where the chrome
remnote lands
| Assignee | ||
Updated•2 months ago
|
| Comment hidden (obsolete) |
| Comment hidden (obsolete) |
| Assignee | ||
Updated•2 months ago
|
| Assignee | ||
Updated•2 months ago
|
| Assignee | ||
Updated•1 month ago
|
| Assignee | ||
Updated•1 month ago
|
| Assignee | ||
Updated•12 days ago
|
| Assignee | ||
Updated•12 days ago
|
Description
•