Package Naming

This document defines the authoritative package naming system used by Gerbtrace for imported and curated package libraries. It combines KiCad KLC naming structure with internal stability and lookup requirements.

Scope

These rules apply to:

• Built-in package libraries under public/packages/libraries/*
• THT built-in libraries under public/packages/tht-libraries/*
• Parser outputs from the CAD library ingestion pipeline
• Name matching in the package lookup logic

Core naming principles

1. Uppercase canonical names — canonical names are uppercase. Use - and _ only (no spaces).
2. Structured head + fields — head encodes package family and pin-count semantics. Tail fields encode dimensions, pitch, and modifiers.
3. No invented families — reuse industry/KiCad family tokens. Do not create project-specific package family prefixes.
4. Be specific when ambiguity is likely — QFN/DFN/LGA families should include body dimensions and pitch when available.
5. Canonical key stability — once a package name is published, avoid renaming. If renamed, maintain compatibility through aliases.

Canonical grammar

<PKG>-<PINCOUNT>[-<SPECIAL>]_<FIELD>_<FIELD>...

Head section

• <PKG> — package family token (e.g., SOIC, QFN, DFN, DIP, TO, SOT)
• <PINCOUNT> — primary pin count
• Optional additional head tokens:
  • Non-standard numbering (e.g., MSOP-12-16)
  • Special pad-count tokens: -1EP, -1SH, -1MP

Tail fields

Underscore-separated, KLC-style parameter fields:

• Body dimensions: 3.9X9.9MM, 5X5MM, 4X4X1.1MM
• Pitch: P1.27MM, P0.5MM
• Exposed pad: EP3.3X3.3MM
• Width/lead span: W7.62MM
• Options: SOCKET, HANDSOLDERING, THERMALVIAS, TOPTENTED

SO family canonicalization

The canonical family token is SOIC. All SO variants normalize to it:

• SO-8 becomes SOIC-8
• SOP-8 becomes SOIC-8
• SOIC-08 becomes SOIC-8

This avoids split inventories between SO-* and SOIC-*.

Parser normalization

The parser applies deterministic normalization in this order:

1. Trim and uppercase
2. Normalize separators
3. Family normalization for SO variants (SO/SOP to SOIC)
4. Build KLC-style head and underscore-tail structure
5. Compact known option phrases:
   • THERMAL-VIAS becomes THERMALVIAS
   • TOP-TENTED becomes TOPTENTED
   • HAND-SOLDERING becomes HANDSOLDERING

Alias and lookup compatibility

Canonical names are strict. Lookup remains permissive.

Common equivalent inputs

These all resolve to the same canonical target:

• SOIC-8, SOIC8, SO-8, SO8, SOP-8
• R0603, C0603, L0603, 0603

Safeguards

• Aliases must not collide with another package's canonical key.
• Duplicate or ambiguous aliases are removed during migration checks.
• Prefer deterministic pattern-based normalization over large ad-hoc alias lists.

Family-specific recommendations

Chip passives

• Canonical: bare size code when truly generic (0402, 0603, 0805)
• Prefix-specific variants (R0603, C0603) map via aliases

Gullwing ICs

• SOIC-16_3.9X9.9MM_P1.27MM
• TSSOP-20_4.4X6.5MM_P0.65MM
• SSOP-28_5.3X10.2MM_P0.65MM

No-lead ICs

• QFN-32-1EP_5X5MM_P0.5MM_EP3.3X3.3MM
• DFN-8_2X3MM_P0.5MM
• LGA-14_2X2MM

THT IC families

• DIP-8_W7.62MM
• DIP-14_W7.62MM_SOCKET
• TO-220-5_VERTICAL

Examples: before and after normalization

Migration and change management

When changing naming logic:

1. Update parser normalization rules.
2. Regenerate package outputs and manifests.
3. Run tree checks for collisions and alias conflicts.
4. Ensure lookup compatibility remains intact.

pnpm run libraries:parse
pnpm run packages:manifest
pnpm run packages:check
pnpm run libraries:parse:tht
pnpm run packages:tht:manifest

References

• KiCad KLC F2.1 — General footprint naming conventions
• KiCad KLC F2.2 — Footprint naming field prefixes
• KiCad KLC F2.4 — Footprint naming for non-standard pin numbering
• KiCad KLC F3.4 — SMD IC package naming conventions
• KiCad KLC F3.5 — THT IC package naming conventions