Build and tooling scripts

scripts/ is the engine layer for builds and verification. Most of the commands in package.json are thin wrappers around these scripts; running a script directly lets you add arguments for debugging.

Script overview

Script	Command wrapper	Responsibility
`build-styles.mjs`	`pnpm build:styles`	Compiles share scss → `dist/theme/` + `dist/styles/`
`sync-exports.mjs`	`pnpm sync:exports` (included in `pnpm build`)	Generates `package.json`’s exports from the source directory structure
`verify-dts.mjs`	`pnpm verify:dts`	Output dts consistent with source types
`verify-styles.mjs`	`pnpm verify:styles`	The six scss checks (see Verification system)
`verify-theme-contrast.mjs`	`pnpm verify:theme`	Theme AA 4.5:1 contrast gate
`check-version-sync.mjs`	`pnpm verify:versions`	Each UI library’s dependency range covers share’s current version
`gen-docs-data.mjs`	`pnpm docs:data`	Parses tokens / icons / class names → `docs/src/data/*.json`
`push-release.mjs`	`pnpm release:push`	Pushes master + the tag to GitHub, triggering archival
`release-notes.mjs`	—	Generates release notes
`extract-from-plus.mjs`	`pnpm extract`	A one-shot script: extracted the shared layer from the plus repo (historical use)
`normalize-styles.mjs`	—	Style normalization (a historical one-shot)
`patch-var-fallbacks.mjs`	—	Batch-patched `var()` fallback values (a historical one-shot)

sync-exports.mjs — the exports-key generator

This is the script most likely to cause trouble.

@lh-ui/share’s package.json has 77 exports keys (subpaths like ./core/button/*), all generated by this script scanning the directory structure of src/ and styles/.

Flow: vite build writes the output to disk → sync:exports scans the es/ directory structure → rewrites the exports / files fields of package.json.

Why it matters:

Add src/core/foo/bar.ts, and it is immediately available during dev (which goes through the source alias), but the npm side has no matching exports key — downstream pnpm up then hits MODULE_NOT_FOUND.
Before a release you must run the full pnpm build (including sync:exports); running only build:dts is not enough.

Note that it modifies package.json: afterwards git diff shows the exports changes — this is normal and should be committed.

build-styles.mjs — style artifacts

Compiles the SCSS sources in styles/ into css:

dist/
├── theme/
│   ├── index.css          # theme tokens (light)
│   └── index-dark.css     # dark overrides
└── styles/
    └── index.css          # full aggregation (tokens + all components)

It also generates the styles/index.scss full aggregation file (by scanning styles/*/index.scss), and verify:styles item 4 checks its consistency — do not hand-edit this file.

Each UI library has its own build-styles.mjs (the plus version scans packages/components, the vue2 version scans src/components); components without a share style source are silently skipped — so share must contain the matching scss, otherwise that component has no styles on one of the ports.

gen-docs-data.mjs — docs data generation

pnpm docs:data

Parses four sources → docs/src/data/*.json:

Output	Source	Contents
`tokens.json`	`var.scss` + `var-dark.scss` + `variables.scss`	185 light + 118 dark + 183 SCSS variables, grouped by semantic domain
`icons.json`	`src/.../icon/svgs.ts`	the 37 built-in icons
`classes.json`	`styles/*/index.scss`	58 component BEM class-name lists

Count assertions: a mismatch between the parsed counts and the expectations (185 / 118 / 183 / 37 / 58) throws directly. This is the first line of defense against “a token was deleted by mistake / a component was deleted by mistake”.

Idempotent: run it freely; it only rewrites the json when the content changed. After changing tokens or class names, run it once to refresh the docs data.

push-release.mjs — release push

pnpm release:push

Run after pnpm release (npm publish + local tag creation):

Push master to github-lhgb
Push this version’s tag to github-lhgb
Trigger .github/workflows/release.yml: pulls the published tarball from npm → creates the GitHub Release (attaching lh-ui-share-<version>.tgz) → pushes the tag to Gitee and calls the Gitee API to create a release

Push to GitHub only — never push tags to Gitee manually — Gitee’s tags / releases are handled uniformly by release.yml, and double-writing would conflict.

verify-theme-contrast.mjs — the contrast gate

Reads the es/ output (so pnpm build must run first) and uses getRelativeLuminance / getContrastRatio — exported from src/theme/themes/index.ts — to compute the WCAG contrast of every “text / background” pair; anything below 4.5:1 fails.

To debug a single color scheme, call these two functions directly in node instead of running the full gate.

The historical one-shot scripts

Script	Notes
`extract-from-plus.mjs`	Extracted the shared layer from lh-ui-plus when this repo was created. Kept as a record; no longer run — share is now the single source (red line 2).
`normalize-styles.mjs`	Early style normalization (unifying how tokens are referenced). Its job is done.
`patch-var-fallbacks.mjs`	Batch-added fallback values to `var(--lh-)`. This was the migration tool before verify:styles item 2 (var fallback) went live — new code must write the fallback by hand; do not rely on this script to cover it*.

The docs site is not an npm artifact

package.json’s files: ["es", "lib", "dist", "styles"] does not include docs/. The docs site is built by pnpm docs:build into docs/dist/ and deployed manually to the family nginx (the contract lives in lh-ui/docs/部署/nginx-lhui.conf.md, another repo). See Release process.

Command reference — the pnpm command corresponding to each script
Verification system — what each verify script checks
Release process — push-release and CI archival
Package entry and subpaths — the 77 keys generated by sync-exports