KiCad users usually notice silkscreen-to-mask clearance late: the board looks fine in the editor, then the fab preview clips reference text, polarity marks, or pin 1 indicators away from exposed pads. That is not just a cosmetic nuisance. If the silkscreen disappears near small passives, fine-pitch ICs, or connector pads, assembly operators lose the markings they rely on during first article inspection and manual rework. The broader PCB silkscreen rules used in fabrication and service work still apply here, but KiCad exposes the problem at the footprint and plot-setting level.
This guide explains what the KiCad silkscreen to mask clearance check is really warning about, where the conflict usually comes from, and how to fix it without creating a different manufacturing problem in Gerbers.
What the KiCad warning actually means
The warning appears when a silkscreen object sits too close to an opening in the solder mask. In production, the fab often clips legend ink away from exposed copper so ink does not land on solderable pads. That means KiCad may show a complete outline or reference designator while the manufactured board receives a shortened version, a broken shape, or no legend in that area at all.
In practice, the risk is highest around QFN corners, dense resistor networks, fine-pitch connectors, LED polarity marks, and test pads placed near assembly labels. A board can still pass electrical checks while becoming harder to assemble, inspect, or repair because the useful marks were the first thing the fab removed.
Why this problem shows up so often in real layouts
Most silkscreen-to-mask conflicts are not caused by one wrong setting. They come from the stack of decisions below acting together:
- A footprint library was drawn with tight body outlines or oversized polarity marks.
- Solder mask expansion is larger than the designer expected, especially on fine-pitch parts.
- Reference text was moved after routing, when the free area around pads was already gone.
- Fab legend capability is tighter on paper than it is in repeatable volume production.
- The board uses small packages where even a 0.15 mm shift changes whether a mark survives clipping.
KiCad can only flag the geometry conflict. It cannot decide whether your chosen fab will clip the legend, whether a lost pin 1 marker creates AOI confusion, or whether the board will later need bench rework by someone who did not design it.
Start with the footprint, not the global rule
If the same warning repeats across many placements of one package, the footprint is usually the right place to fix it. Shrinking a silkscreen outline segment, moving a polarity dot, or breaking the body outline away from pad edges is safer than globally relaxing clearance until the warnings disappear.
This matters most for reusable libraries. A footprint that passes once on a prototype can still become a manufacturing nuisance when the same package is reused on a denser board, on a panelized design, or with a different mask expansion rule. Fixing the source footprint keeps the error from multiplying through the next project.
A practical clearance workflow that holds up in fabrication
Treat the check as a small DFM review, not just a DRC cleanup task. A practical workflow is:
- Identify whether the conflict is on body outline, reference text, polarity marking, or pin 1 marking.
- Check whether the exposed mask opening comes from pad size, local mask expansion, or a footprint courtyard drawn too aggressively.
- Ask whether the silkscreen element is needed during assembly or only decorative.
- Fix the footprint or local text placement first.
- Replot Gerbers and inspect the silkscreen layer with solder mask openings visible before signing off.
For many fabs, a conservative starting point is to keep at least about 0.15 mm to 0.20 mm between silkscreen and mask openings, then verify against the fabricator’s published legend capability. On small packages, line width matters too. A theoretically legal gap can still disappear after clipping if the line itself is already near the fab’s minimum printable width.
When it is safe to clip the legend and when it is not
Not every warning deserves the same response. Losing a short body outline segment on a two-pin resistor may be acceptable. Losing the only pin 1 marker on a QFN, the polarity mark on an LED array, or the orientation cue for a connector is not the same class of issue.
The better question is not “Can the fab clip this?” but “If the fab clips this, what manufacturing or service task becomes harder?” If the missing legend affects placement verification, rework orientation, ICT fixture labeling, or field repair, the mark should be redesigned rather than sacrificed.
KiCad-specific places to check before you regenerate Gerbers
Before exporting files again, inspect the places in KiCad where this warning is commonly introduced:
- Footprint silkscreen primitives on
F.SilkSnear pads or exposed thermal pads. - Reference designator placement after interactive routing or copper pour updates.
- Pad solder mask clearance settings in the footprint or board rules.
- Plot settings that clip silkscreen against solder mask during Gerber generation.
If you only fix the text placement but leave a polarity triangle or body outline too close to the pads, the warning may return on the next ECO. If you only relax the DRC threshold, you may ship a board whose legend looks complete in KiCad but is partially removed by the fabricator.
How this affects yield, inspection, and later repair
Silkscreen clarity affects more than appearance. During first article inspection, technicians often confirm orientation using a mix of centroid data, assembly drawings, and whatever survives on the board itself. When the board legend is weak, every manual verification step takes longer. That slows NPI work and increases the chance of orientation escapes on similar-looking parts.
Field repair is where bad legend decisions become expensive. If a regulator, connector, or jumper location is no longer easy to identify once conformal coating, flux residue, or heat discoloration shows up, the board may need extra schematic review before a simple rework can begin. That is wasted time created by a preventable layout detail.
A better rule of thumb for dense boards
On dense layouts, keep essential legend information sparse and intentional. Preserve pin 1, polarity, reference IDs for hand-worked parts, and service-relevant labels. Let decorative body outlines shrink or break where needed. That approach usually survives fabrication better than trying to keep a full package outline around every component.
If the board is headed to volume SMT assembly, review the result alongside other manufacturability checks such as stencil access, fiducial visibility, test-point reachability, and component spacing. Silkscreen conflicts rarely appear alone on crowded designs, which is why they are worth checking together with surface-mount PCB layout decisions that affect yield, inspection, and rework.
Conclusion
The KiCad silkscreen to mask clearance warning is useful because it points to a real manufacturing compromise: the marks you want on the board are too close to the copper you need to solder. The best fix is usually a footprint or placement change that preserves assembly-critical legend, not a global rule change that simply hides the warning. When you verify the result in Gerbers and think about assembly and rework at the same time, the warning becomes a DFM checkpoint instead of a nuisance.
What is a safe silkscreen to solder mask clearance in KiCad?
There is no single universal number because fabricators differ, but many designers start around 0.15 mm to 0.20 mm and then confirm against the board house’s legend and mask capability. On very small packages, line width and mask expansion matter just as much as the nominal clearance value.
Should I relax the KiCad rule just to remove the warning?
Usually no. If the warning is tied to essential marks such as pin 1 or polarity, relaxing the rule can hide a real manufacturing problem. Fix the footprint, text placement, or local geometry first, then decide whether a remaining warning is acceptable.
Why does the silkscreen look fine in KiCad but disappear in Gerbers or fabrication output?
Because fabrication output often clips legend away from solder mask openings to keep ink off solderable areas. KiCad can display the original geometry, but the plotted or manufactured result may remove the portion that overlaps the keepout around exposed pads.
Which silkscreen elements should be protected first on a dense PCB?
Protect pin 1 marks, polarity indicators, connector orientation cues, and any labels needed for first article inspection or bench rework. Decorative body outlines are usually lower priority and can be shortened when space is tight.
