map-controls
Skill0 starsChanged 2 months agoMITView on GitHub
Style MapLibre's control stack without fighting it - the specificity trap that silently ignores your CSS, currentColor glyphs, and why the library's own baked-image buttons need dark-mode treatment yours do not. Use when adding a custom map control, or when control CSS "does nothing".
1 other project uses a version of this.
Adopted by
Most recently taken up by
- ComplianceAsCode/contenttheir own version, first seen Oct 8, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- ComplianceAsCode/content★ 2.8ksame name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository15 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- app-adoptSkill
- app-contributeSkill
- app-startSkill
- app-upgradeSkill
- app-verifySkill
- map-cameraSkill
- map-popupsSkill
- repo-maintainSkill
- ui-bootSkill
- ui-furnitureSkill
- ui-iconsSkill
- ui-stowSkill
- ui-themeSkill
- ui-windowSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 36
Every glyph in app/js/icons.js is stroked with currentColor and carries no fill.
- Very specific: line 91
Every custom button goes through makeControl in app/js/ui/control-stack.js.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Map control icons
MapLibre's control API is small: an object with onAdd returning an element. Easy to add, easy
to make look foreign. Three things decide whether a custom control reads as native.
1. The specificity trap
MapLibre styles its buttons through .maplibregl-ctrl-group button: a class plus a type, which
beats a single class. So this silently does nothing:
.sgs-ctrl-btn { width: 30px; } /* loses */Two ways out. Match the specificity:
.maplibregl-ctrl-group.sgs-ctrl button.sgs-ctrl-btn { width: var(--sgs-ctrl-size); }or reach for !important. Matching is better: it stays readable, it keeps working when
MapLibre adds a state class, and it does not train the next person to reach for !important
first. This is one of the few places where !important is a legitimate answer rather than a
smell, which is exactly why it should still be the second choice.
The symptom when you get this wrong is not an error. It is CSS that appears to be ignored, and half an hour in devtools.
2. Let the glyph inherit color
Every glyph in app/js/icons.js is stroked with currentColor and carries no fill. One
declaration then colours the whole stack, in every theme and every state:
.maplibregl-ctrl-group.sgs-ctrl button.sgs-ctrl-btn { color: var(--sgs-fg-dim); }
.maplibregl-ctrl-group.sgs-ctrl button.sgs-ctrl-btn:hover { color: var(--sgs-fg); }MapLibre's OWN zoom, compass, and geolocate buttons do not have this property — their glyphs
are background images baked in one fixed colour, which reads as a different visual family next
to currentColor glyphs, and in dark mode stays black unless inverted. Do not reach for an
invert filter to fix this. app/js/ui/control-glyphs.js (adoptControlGlyphs()) replaces
the baked artwork with this app's own glyph inside the same <span> MapLibre already renders,
so the whole stack becomes one family with one set of colour rules and dark mode needs nothing
special at all:
map.addControl(new maplibregl.NavigationControl(), 'top-right');
// ...every control that should get this treatment...
adoptControlGlyphs(); // call once, after every control for this session is mountedThe reset itself is INLINE, in control-glyphs.js, not a stylesheet rule — this is the
one place in the app that deliberately breaks rule 1's own advice. It was a stylesheet rule
first, and it half worked: MapLibre writes its icon rules at several different specificities,
so a single rule caught the zoom buttons and silently missed the compass and geolocate, whose
baked artwork went on rendering UNDERNEATH the adopted svg — a glyph with a phantom extra bar
through it, and npm run icons reporting 22.5px of ink in a 17px box, which is what actually
found it. An inline style beats every stylesheet rule without !important's side effect of
stopping the next person reasoning about the cascade, and it sits two lines from the thing it
undoes instead of in a file that has to be found. See app/css/components/map-controls.css
for what's left in the stylesheet once the reset itself moved out: only state colour, which
the cascade genuinely is the right tool for.
State colour has to carry every state the control has
Geolocate has three, and MapLibre already tracks them: -background means it is watching your
position while the camera is free, and -active means it is watching AND the camera is locked
to you. Painting both the same accent made "I know where you are" and "I am following you"
look identical, so the button could not answer the question a reader presses it to ask.
The fix is in the art, not in a second control. The glyph is a ring around a dot, so it can say
both things at once: the dot paints from its own custom property (--sgs-locate-dot), the ring
from color. The DOT alone lights up on -background, the WHOLE glyph on -active, reading
outward from the centre in the direction the behaviour grows.
Error is the exception and stays whole-glyph in both states: a half-lit error would be read as a degree of success.
Before styling an adopted control, list the classes MapLibre actually toggles on it. A state the framework distinguishes and the stylesheet flattens is information thrown away in the one place the reader was looking for it.
3. One shell, many buttons
Every custom button goes through makeControl in app/js/ui/control-stack.js. One place
decides sizing, padding and the focus ring, so a second control cannot drift from the first.
Adding a control is a spec, not a class:
map.addControl(makeControl([{ glyph: 'info', title: 'About', onClick: () => {} }]), 'top-right');Checklist
- Container wears
maplibregl-ctrl maplibregl-ctrl-group. - Button built through
makeControl, not by hand. - Glyph from
icons.js, strokedcurrentColor, no fill. titleANDaria-label, saying the same thing.- Rules that must beat MapLibre's are written at matching specificity, not
!important. - Adopting one of MapLibre's own controls (zoom, compass, geolocate)? Use
adoptControlGlyphs(), never an invert filter, and never a stylesheet reset — inline only, right where the glyph is injected. - Run
npm run icons. A new control is a new glyph, and it will not be the right size by accident. Seeui-icons.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

