skill

Make a Wiki Component Page

Public Made by Adom

by adom

Create a wiki component page the RIGHT way. Pages are keyed manufacturer-mpn and scoped to ONE DATASHEET, so a datasheet covering six voltages and three packages is ONE page covering all of them, never six pages. Two manufacturers publishing the same MPN are two pages, because their limits genuinely differ. Renders through a hand-built readme.html on the Adom theme tokens with a fixed ten-section shape (identity, at a glance, specifications, symbol+footprint viewers, pin map, variants, assets, i

skillwikicomponentdatasheetfamilympnmanufacturerkicadedapublishdedupreadme-htmlprovenance
Overview Files Skills Discover Packages Releases Dependencies Issues1 Breadcrumbs Pull Requests Activity
adom-component-page / SKILL.md
Download

name: adom-component-page description: Create a wiki component page the RIGHT way. Pages are keyed manufacturer-mpn and scoped to ONE DATASHEET, so a datasheet covering six voltages and three packages is ONE page covering all of them, never six pages. Renders through a hand-built readme.html on the Adom theme tokens, with the LAN7800 / AMS1117 section shape. Anything not available yet gets a "not available, open a pull request" placeholder rather than being silently dropped. Use when publishing a part to the Adom wiki, adding a component to a board or circuit library, deciding whether a variant deserves its own page, resolving an LCSC/JLC code to an MPN, deduping against an existing page, or correcting a page published under the wrong name. Trigger words: make a component page, publish this part, component page for, add component to library, wiki component by MPN, component family page, which variants go on one page, LCSC to MPN, fix component page name, split a component page by manufacturer. metadata: type: skill

Making wiki component pages

The three rules

  1. Slug is <manufacturer>-<mpn>. ams-ams1117, umw-ams1117, microchip-lan7800.
  2. One page per DATASHEET. The datasheet draws the family boundary. Every variant inside it belongs on that one page. Two manufacturers with two datasheets for the same MPN are two pages.
  3. readme.html is the page. Hand-built, on the Adom theme tokens, following the section shape in §5. README.md is shadowed by it and exists only as a text fallback.

Reference pages that are the standard, both worth opening before you build: adom/microchip-lan7800 and adom/ams-ams1117.

Companion skills: wiki-component (the page TYPE and its native viewers), adom-theme (the colour tokens, load it, do not guess hexes), adom-hardware-component-publish (hero images, 3D composites, the push loop).

1. Decide the page boundary BEFORE anything else

This is the step people get wrong, and it is expensive to undo. Ask one question:

Which datasheet describes this part?

That datasheet is the page. Everything it covers goes on that page.

The datasheet covers You create
Six fixed voltages and three packages One page with all six and all three
Two temperature grades and two package codes One page, grades and codes in the variants section
One part only One page
The same MPN, but a different manufacturer published it A second page. Different silicon, different limits.

Do NOT create a per-variant page

ams1117-3-3 and ams1117-1-2 were separate pages before this rule existed. Both were wrong: one datasheet covers the whole voltage range, so one page should have. Splitting a datasheet family into per-variant pages means the electrical tables get copied N times, drift N ways, and no page has the full ordering picture.

Before creating anything, check whether the part is a variant of a family you should be adding to instead:

  • Read the datasheet's ordering-information table. If your MPN is one row of it, the page is the whole table.
  • Search the wiki for the base part, not just your exact MPN (§3).
  • If a family page exists, add the variant to it and stop. Do not create a sibling.

DO split when the manufacturers differ

The counter-case is real. AMS1117 is second-sourced: Advanced Monolithic Systems carries 2.85 V and not 1.2 V, UMW carries 1.2 V and not 2.85 V, and they differ on input maximum (15 V vs 18 V), current limit (0.9 to 1.5 A vs 2.1 to 2.5 A) and thermal shutdown (165 vs 150 C). One page could not hold both without a vendor caveat on every number, which is exactly what gets misread. Two datasheets, two pages, each pure, each linking to the other.

The tell: if you find yourself writing "(AMS)" and "(UMW)" after individual numbers, you needed two pages.

2. Slug and title

Slug is <manufacturer>-<mpn>, lowercased, every run of non-alphanumeric characters collapsed to a single -:

Manufacturer MPN Slug
Advanced Monolithic Systems AMS1117 ams-ams1117
UMW (Youtai Semiconductor) AMS1117 umw-ams1117
Microchip Technology LAN7800 microchip-lan7800
Samsung CL05B104KO5NNNC samsung-cl05b104ko5nnnc

Use the manufacturer's common short name, not its legal name: ti, st, nxp, microchip, samsung, yageo, bosch, ams, umw. The registry lowercases slugs on publish, so capitalisation in page.json is not preserved.

Why the manufacturer prefix: a bare MPN cannot express the AMS1117 case, where one part number has two manufacturers, two datasheets and two sets of limits. Prefixing makes the collision impossible and makes the owner of the numbers obvious in the URL.

Title is <what it is> <MFR> - <MPN>, function first so the wiki grid is readable:

1 A Low-Dropout Regulator AMS - AMS1117
1 A Low-Dropout Regulator UMW - AMS1117
SuperSpeed USB 3.1 to Gigabit Ethernet Controller Microchip - LAN7800

Keep the function phrase short enough to scan. It is what tells a reader what the chip does before they click.

3. Dedup pre-flight (always, before creating)

A page may already exist under any owner, under the new convention or the legacy bare-MPN one.

MPN=ams1117; MFR=ams
adom-wiki discover search --query "$MPN"                      # any owner, any slug shape
curl -s -o /dev/null -w "%{http_code}\n" \
  https://wiki.adom.inc/api/pages/adom/$MFR-$MPN              # 200 = new-convention page exists
curl -s -o /dev/null -w "%{http_code}\n" \
  https://wiki.adom.inc/api/pages/adom/$MPN                   # 200 = legacy bare-MPN page exists

Also search the base part, not just your variant: searching ams1117 finds ams1117-3-3, which tells you a family page is what you need.

Outcomes:

  • A correct family page exists -> add your variant to it, republish, stop.
  • A legacy bare-MPN page exists -> see §8.
  • Per-variant pages exist -> build the family page, then deprecate them (§8).
  • Nothing exists -> continue.

chip-fetcher and chip-fetcher-lite are wiki-first, so they are the fastest way to find an existing page. Ask the user which to use (see the routing note in memory) before running the heavy one.

4. Build the CAD

Do not hand-author geometry you can pull from a real library.

Footprints and 3D, in preference order:

  1. KiCad's own official library on the user's machine. This is the best source: real land patterns, matching STEP, clean provenance. Via adom-desktop:

    adom-desktop --ai-thread "<thread>" desktop_list_files \
  '{"path":"C:\\Program Files\\KiCad\\10.0\\share\\kicad\\footprints\\Package_TO_SOT_SMD.pretty","glob":"SOT-223*"}'
adom-desktop --ai-thread "<thread>" pull_file \
  '{"filePaths":["...\\SOT-223-3_TabPin2.kicad_mod","...\\3dmodels\\Package_TO_SOT_SMD.3dshapes\\SOT-223.step"],"destDir":"/tmp"}'

    Pick the land pattern that matches the datasheet's pin function, not just the package name. The AMS1117 tab is VOUT, which is pin 2, so SOT-223-3_TabPin2 is correct and plain SOT-223 is not. Getting this wrong leaves the tab (the heat path) floating.

  2. The part's own vendor CAD (chip-fetcher).

  3. Generated from the datasheet drawing, last resort, and say so in provenance.

Renaming a pulled footprint means changing BOTH:

(footprint "AMS1117_SOT-223"          <- the node name
(property "Value" "AMS1117_SOT-223"   <- the wiki's native viewer displays THIS

Renaming only the first leaves the old library name showing on the page.

Symbol: adom-symbol create from a JSON of {symbolName, manufacturer, package, description, datasheetUrl, designatorPrefix, footprint, pins:[{number,name,type,side}]}. side accepts left/right/bottom. Unknown fields are silently ignored, so you cannot discover the schema by probing errors.

Canonical JSON and viewers:

step2glb convert part.step --out part.glb
adom-lbr import-kicad --sym part.kicad_sym --fp part.kicad_mod --mpn "<MPN>" --out part.adom-lbr.json
adom-symbol    embed --file part.kicad_sym --out viewer-symbol.html
adom-footprint embed --file part.kicad_mod --out /tmp/raw.html
python3 scripts/inject_layers.py /tmp/raw.html part.kicad_mod fp-<pkg>.html   # see below
python3 scripts/build_switcher.py <dir> <vendor> viewer-footprints.html       # multi-package

adom-footprint 1.0.20 ships the fab, silk and courtyard layer groups EMPTY (both embed and render), so the component outline is invisible and you get floating pads with no body. scripts/inject_layers.py parses the .kicad_mod graphics and fills them, and widens the viewBox (which is computed from copper only, so courtyards clip). Tracked as adom/adom-footprint#2. Drop the workaround once that lands.

Do NOT ship generated Fusion .lbr or Altium .IntLib/.SchLib/.PcbLib. They are generated rather than hand-verified and the Altium symbol encoder has produced wrong geometry before. Ship the placeholder from §6 instead. Generated-but-unchecked CAD on a public page is worse than a gap, because a reader assumes it was verified.

5. Build readme.html

Start from templates/readme.html. It carries the Adom studio-dark tokens and the full section skeleton.

Section order (the LAN7800 / AMS1117 shape)

# Section Contents
1 Identity header <h1> MPN, manufacturer, gradient badge, one-paragraph summary, meta chips (package / pins / key ratings)
2 At a glance Six stat cards, the numbers someone picks the part on
3 Specifications Label to value rows, every headline electrical figure
4 Symbol and footprint Two iframes: viewer-symbol.html, and viewer-footprints.html with a package switcher when there is more than one package
5 Pin map Every pin, grouped by function into coloured cards
6 Component variants Order-code decoder plus a card per package, and a table of every orderable variant
7 Assets CAD download table, with §6 placeholders for anything missing
8 Implementation Boards on the wiki that use the part, and sibling pages
9 Datasheet Embedded PDF iframe plus a download link
10 Provenance The real source of every number and every file

Add sections when the part earns them (thermal-design tables, application notes, internal structure). Do not drop sections because the data was inconvenient to find: use a placeholder.

Hard rules

  • Colours come from the adom-theme skill, studio-dark column. Load it, do not guess. --green / --red / --yellow are SEMANTIC (success / destructive / warning) and must not be used as categorical colours. For a pin-map legend needing many hues, derive a ramp across the three non-semantic brand hues (teal #00b8b1, blue #64abff, purple #8c6bf7) plus neutrals.

  • Fonts: Satoshi for prose, "JetBrains Mono" for code and part numbers.

  • No em-dashes, no en-dashes, no emoji. House prose rule, and adom-wiki pkg publish lints for it.

    prose-lint README.md readme.html
grep -c -e '&mdash;' -e '&ndash;' readme.html     # prose-lint CANNOT see these

    prose-lint matches the literal — and – characters and not their HTML entities, so a readme.html written with &mdash; passes clean while the rendered page is full of em-dashes. Grep for the entities yourself until adom/prose-lint#1 lands. Substitutions that read well: a dash introducing an elaboration becomes a colon, or a period plus a capital when what follows is an independent clause; a bare dash in a table cell becomes n/a; a numeric range 1.5 &ndash; 2.5 becomes 1.5 to 2.5.

  • Every number is attributable. If it is not in the datasheet, either cite where it came from in Provenance or leave it out.

  • Keep the postMessage height-reporting script at the bottom of the template. The wiki sizes the readme iframe from it.

Iframe URLs are absolute and contain the slug

src="https://wiki.adom.inc/api/v1/pages/adom/<slug>/files/viewer-symbol.html"

Get the slug wrong here and the viewers are silently blank on the live page. Check them after publishing.

6. Placeholders: never silently drop something

If a file or a fact is not available yet, say so on the page and invite a PR. A missing row reads as "this part has no Altium library". A placeholder reads as "nobody has contributed one yet", which is true and actionable.

In the Assets table:

<tr><td class=tool style="color:#484f58">Fusion 360 / EAGLE</td>
    <td class=na>Not available yet. <a href="https://wiki.adom.inc/adom/<slug>/pulls">Open a pull request</a> to add it.</td></tr>

with

.na{color:var(--text-3);font-style:italic}

Same pattern for a package with no footprint, a variant with no verified limits, a missing datasheet. State what is missing, why if you know, and how to contribute it. Then say the same thing in Provenance, because that is where a careful reader checks.

7. Publish (both layers, in order)

adom-wiki pkg publish --org adom --public --include-media     # registry + first-publish hero
adom-wiki repo push adom/<slug> -m "<message>" --files page.json README.md readme.html <cad...> \
  viewer-symbol.html viewer-footprints.html docs/<datasheet>.pdf screenshots/hero.png
  • pkg publish writes the registry layer (manifest, dependency graph, install payload). The dependency graph comes from here, never from a repo push.
  • repo push writes the page repo (the Files tab, and what the page renders from).
  • --include-media is only needed on a brand-new page's first publish, to materialise the hero. Drop it after, or the hero rides every install tarball.
  • Rate limit is 10 publishes per minute.

Then verify on the live page, not just locally:

curl -s -o /dev/null -w "%{http_code}\n" https://wiki.adom.inc/api/v1/pages/adom/<slug>/files/readme.html

and screenshot it. A live page whose srcdoc iframes are large needs about 5 s after networkidle2 before puppeteer paints them, so a blank capture is usually timing rather than a real fault. Compare live against local by character count, not bytes (multibyte glyphs like µ and Ω make byte counts differ on identical files).

8. Fixing a page that has the wrong shape

A legacy bare-MPN page

Older pages are keyed on the bare MPN (cl05b104ko5nnnc). They are not broken and there are a lot of them. Do not mass-rename. When you touch one:

  1. Create or update the <mfr>-<mpn> page.
  2. Repoint any library or board dependency at the new slug and republish it (registry layer).
  3. Deprecate the old page (below).

Per-variant pages that should be one family

Build the family page, repoint dependents, then deprecate each variant page.

Deprecating so the page LOOKS deprecated, not just so the registry knows

There is no page-level deprecated field in the API. A banner in the readme alone is invisible: it renders far below the fold and the header looks like any live page. The visible signal is a convention. Do all of it:

  1. title -> [DEPRECATED] <old title> → <replacement-slug>. Use a real →, and pass ensure_ascii=False when writing page.json with json.dumps or it becomes \u2192.
  2. tags -> deprecated FIRST, then alias, then the replacement slug(s). The tag chip is what the UI renders.
  3. brief -> lead with "DEPRECATED. Use ...".
  4. hero -> replace it. It is the largest header element and the gallery-card image.
  5. adom-wiki pkg deprecate <owner>/<slug>@<version> for every published version. It requires an explicit version and there is no whole-package form.
  6. A banner at the top of readme.html for people who scroll.

Then repo push page.json and pkg publish, because the title and brief live in both layers.

Canonical example to copy: adom/adom-layout-viewer.

Use adom-wiki page delete (soft) only when the page has no useful history. Deprecating and leaving it readable is usually better.

9. Linking into a library

A library is a page tagged library whose dependencies are the component pages, owner-qualified:

"dependencies": {
  "adom/samsung-cl05b104ko5nnnc": "^1.0.0",
  "adom/mps-mp2393gtl-z": "^1.0.0"
}

Republish the library through pkg publish so the registry graph updates. A board depends on the library, and Nucleus expands board -> library -> components so each part becomes clickable.

10. Batch flows

adom-design-blocks/src/make-components.mjs <sch> <pcb> <outDir> <modelsDir> walks a KiCad circuit, finds every unique placed part, resolves LCSC to MPN and writes one bundle per part.

It predates this skill and emits bare-MPN slugs and no readme.html. When using it, treat its output as raw CAD only: apply §1 (are several of these parts one datasheet family?), §2 (re-slug), and §5 (build the page) before publishing. Publishing its output directly is how a board import scatters twenty thin per-variant pages across the wiki.

Files in this skill

Path What
templates/readme.html The section skeleton with Adom theme tokens
templates/page.json Manifest skeleton with the component block
scripts/inject_layers.py Fills the empty fab/silk/courtyard groups in an adom-footprint embed
scripts/build_switcher.py Wraps N footprint embeds into one package switcher
reference/worked-example.md The AMS1117 build end to end, every command in order