# ui-pack-maintain

Adopt this skill: https://proskills.md/skills/other/lisuiwen-ai-html-annotation-skills-ui-pack-maintain

Page: https://proskills.md/skills/other/lisuiwen-ai-html-annotation-skills-ui-pack-maintain
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/ui-pack-maintain/SKILL.md
size: 5143
upstream: https://github.com/lisuiwen/ai-html-annotation/blob/master/skills/ui-pack-maintain/SKILL.md

````text
---
name: ui-pack-maintain
description: Creates, extends, repairs, validates, versions, and publishes reusable UI Packs. Use when adding or changing UI Pack Foundations, Components, Patterns, Presets, design tokens, state adapters, manifests, or registry metadata, or when extracting a reusable visual system from screenshots, existing pages, or computed styles. Creating a Pack relies only on the self-contained contract plus user intent; maintenance may additionally read existing Packs. Do not use for generating business prototypes, editing production frontend code, installing packs for end users, or ordinary page styling.
---

# UI Pack Maintain

Self-contained authoring and publication workflow for UI Packs. This skill owns the pack
contract, schema version rules, registry format, validator, and release metadata. It does not
own consumer-side discovery, download, or prototype generation.

## Quick start

Create a Pack, then validate and resolve it:

```bash
node scripts/validate-pack.mjs --pack=<pack-directory> --strict
node scripts/resolve-pack.mjs --pack=<pack-directory> --entry=<id>[,<id>...]
```

Before publishing pack changes:

```bash
node scripts/generate-registry.mjs
node scripts/generate-registry.mjs --check
```

Landing paths, create/update steps, and the consumer resolver smoke test are in
[Pack authoring](references/pack-authoring.md).

## Responsibility split

| Owns `ui-pack-maintain` | Owns `html-prototype-build` |
|---|---|
| pack contract, `schemaVersion`, `validate-pack.mjs`, registry generation | pack lookup chain, `install-pack.mjs`, `deliver[]` copy-out |
| in-pack `resolve-pack.mjs` (`--pack=<dir> --entry=`) | consumer `resolve-pack.mjs` (`--list` / `--select`) |
| pack lifecycle: create → validate → version → publish | prototype generation |

## Workflow

1. Read `references/contract.md` for structure and responsibility boundaries.
   In **creation** mode, stop here for evidence. In **maintenance** mode,
   continue to step 2.
2. Read the target Pack's `PACK.md` and `manifest.json`, plus only the resource
   entries this task touches (maintenance only).
3. Classify the change as Pack creation, Foundation, Component, Pattern, Preset,
   registry/publication, or repair.
4. Read [Pack authoring](references/pack-authoring.md) and implement the smallest
   reusable change.
5. Update `manifest.json`, then run deterministic validation.
6. For a new Pack or substantial semantic change, run the isolated review in
   [Isolated semantic review](references/semantic-review.md).
7. Regenerate `registry.json` when publishing or changing downloadable metadata.
8. Apply only verified findings, then rerun validation and the resolver smoke test.

Evidence priority is documented in [Evidence authority](references/evidence.md).

Publication references:

- [Registry format](references/registry-format.md)
- [schemaVersion contract](references/schema-version.md)

## Hard boundaries

- Keep a UI Pack inside the directory passed as `--pack=`; this skill owns only
  the workflow, contract, registry format, resolver, and validator. It does not
  hard-code a consumer's pack install location.
- Keep the Foundation DOM-free; include only shared tokens and a document-level
  CSS baseline.
- Keep each Component as one leaf implementation with a local contract.
- Compose Components through Patterns without copying their implementations.
- Keep Presets business-fact-free.
- Keep state adapters to projecting passed local state only; never access
  `PrototypeViewers`, persist state, parse URLs, or register global event handlers.
- Treat `manifest.json` as the only machine-readable index and dependency source.
- Declare only required dependencies in `requires`; keep conditional capabilities
  in `optional`.
- Patterns and Presets must not select internal components directly.
- Do not implement consumer download flows here; point users to
  `html-prototype-build` [Pack install](../html-prototype-build/references/pack-install.md).

## Deterministic validation

```bash
node scripts/validate-pack.mjs --pack=<pack-directory> --strict
```

The validator enforces [the pack contract](references/contract.md), including pack-local
`vendor` / `runtime` / `assets` and `manifest.delivery`. Fix every error before semantic
review. Warnings must be resolved or explicitly reported as evidence gaps.

It cannot judge whether a component boundary is useful or whether visual evidence
is sufficient; delegate those questions to the semantic reviewer.

## Resolver smoke test

```bash
node scripts/resolve-pack.mjs --pack=<pack-directory> --entry=<id>[,<id>...] [--optional=<id>[,<id>...]]
```

This covers in-pack `requires`/`uses` closures only. After validation, also run the
consumer resolver check in [Pack authoring](references/pack-authoring.md#resolver-smoke-tests).
Cross-pack references are out of scope and must be reported as a `ponytail:` evidence gap.

## Completion report

Report:

- changed Pack entries
- evidence used
- provisional decisions and missing evidence
- validator and resolver test results
- registry regeneration status
- unresolved independent-review findings
````

## File: README.md
upstream: https://github.com/lisuiwen/ai-html-annotation/blob/master/README.md

````text
# AI HTML Annotation

[中文](README.zh-CN.md)

[![skills.sh](https://skills.sh/b/Lisuiwen/ai-html-annotation)](https://skills.sh/Lisuiwen/ai-html-annotation)

> Agent Skill for native HTML prototypes with real-DOM annotations — for Claude Code, Codex, Cursor, and other coding agents.

**The page is the deliverable, not just a picture of one.** Build from a UI pack, annotate on the live DOM, copy feedback to an AI, and ship clean multi-state screenshots.

Experimental 0.x · zero npm dependencies · MIT · [Changelog](CHANGELOG.md)

## Why it exists

Chat comments never hit an element, screenshot-based HTML drifts, and spec / chat / source stay disconnected. The [product guide](docs/guide.md) covers why that fails, four jobs on the loop, and the numbered workflow.

```text
generate HTML from a UI pack
        │
        ▼
     Viewer
        │
        ├── Mark → Copy for AI   (optional)
        ├── Direct Edit          (optional)
        ├── Inspector            (optional)
        └── Sketch board         (optional clipboard image)
        │
        ▼
   scenarios
```

Mark, Direct Edit, and Inspector are parallel options after Viewer, not a required sequence.

## See it first

Walkthrough video: [media/hero-main.mp4](media/hero-main.mp4) (GitHub may not autoplay — open the file).

### Review the page the way a PM would

Formal annotations sit on the real DOM. Add, edit, or browse them, switch page states, and follow SVG connectors to the matching modules — same page, not a separate spec.

![Formal notes on the live page: browse annotations and switch scenarios](media/viewer.gif)

### Pin a problem and copy it to the AI

Hold `Ctrl` (macOS: `⌘`) and click an element to drop a removable review pin. Then `Copy all → For AI` exports selectors plus element HTML.

![Pin feedback on a real element and copy selector + HTML snapshot for the agent](media/mark.gif)

### Tweak style or copy on the live page

Author Tools → **edit**. Hold `Ctrl` (macOS: `⌘`), change copy or styles (for example a background color), and save. The editor UI stays in the authoring session; it is not injected into the deliverable.

![Change copy or styles on the page and write them back to source](media/direct-edit.gif)

### Lock the thing that looks wrong and jump to source

Hold `Alt + Shift`, hover to see the selector, click to open that location in your local IDE.

![Lock an element and jump from the page to its source](media/inspector.gif)

### Deliver clean multi-state screenshots

Multi-state screenshots hide the annotation rail, connectors, and Author Tools. Formal HTML can still show Viewer; the PNGs are the product page only.

![Notes rail versus product-only output for the same mobile page](media/scenarios-mobile.gif)

### Generate from a UI pack so pages stay visually consistent

Installable visual systems — tokens, components, patterns — not bundled inside the Skill. Official packs: `admin-desktop` (desktop admin) and `mobile-vant` (phone-width H5). Customize or author a pack with the `ui-pack-maintain` skill when the official simulation is the wrong visual language. Details: [UI packs](docs/ui-packs.md).

## Fit / not fit

**Fit** when you need to:

- turn UI materials into openable HTML quickly;
- review on the real page and copy precise feedback to an AI;
- iterate structure, copy, and state while keeping reproducible screenshots;
- keep admin, config, or interaction prototypes visually stable across tasks.

**Not a fit** as a production component library, a Figma replacement, a third-party design-system implementation, or a general frontend scaffold / production code generator.

## Install

skills.sh is the default. Then install a UI pack (`admin-desktop` for desktop, `mobile-vant` for phone) and open Author Tools — steps in [5-minute quickstart](docs/quickstart.md).

```bash
npx skills add https://github.com/Lisuiwen/ai-html-annotation --skill html-prototype-build
```

Open [`examples/minimal-notes-system/prototype.html`](examples/minimal-notes-system) (desktop sample in this repo).

Claude Code marketplace is secondary: `/plugin marketplace add Lisuiwen/ai-html-annotation` then `/plugin install ai-html-annotation@lisuiwen-agent-skills`. Pack authors also install `ui-pack-maintain`.

## Examples

- Default walkthrough: [`examples/minimal-notes-system`](examples/minimal-notes-system) (admin desktop).
- Alternate: [`examples/mobile-work-order`](examples/mobile-work-order) (mobile H5, `mobile-vant`).

## Where to go next

- [Product guide](docs/guide.md) — why it fails, four scenarios, capabilities, numbered steps
- [Quickstart](docs/quickstart.md) · [UI packs](docs/ui-packs.md) · [Comparison](docs/comparison.md) · [FAQ](docs/faq.md)
- [Docs index](docs/README.md)
- Skill overview → [html-prototype-build README](skills/html-prototype-build/README.md) ([中文](skills/html-prototype-build/README.zh-CN.md))

Skill references, UI pack contracts, and addon docs are in English.

## For agents

Local Author Tools, pack install, and screenshot commands: [Local authoring](skills/html-prototype-build/references/local-authoring.md), [Pack install](skills/html-prototype-build/references/pack-install.md), [Screenshots](skills/html-prototype-build/references/screenshots.md). Agent routing: [SKILL.md](skills/html-prototype-build/SKILL.md).

## Distribution layout

```text
.claude-plugin/marketplace.json  Claude Code marketplace catalog
.html-prototype/packs/           Official UI packs
skills/html-prototype-build/     Prototype build Agent Skill
skills/ui-pack-maintain/         UI pack authoring Agent Skill
examples/                        Runnable samples
media/                           README demo assets
docs/                            Product docs
```

## Security

- Author Tools bind to `127.0.0.1` only. Do not run authoring or screenshots against untrusted HTML.
- Author writes require same-origin localhost JSON. Keep the Skill-root `.env` local for IDE selection; never commit it.
- Direct Edit and Mark load only in the authoring session. Direct Edit writes style/copy through localhost; Mark stores pins in page-scoped `localStorage` and may copy to the clipboard. Neither is injected into source HTML.
- Do not put real credentials, production data, personal information, or unauthorized brand assets in prototypes.

## Contributing

Experimental 0.x; APIs and layout may change. See [`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md) and [`.github/CODE_OF_CONDUCT.md`](.github/CODE_OF_CONDUCT.md). Report vulnerabilities privately per [`.github/SECURITY.md`](.github/SECURITY.md).

UI packs are original native-HTML visual simulations. They do not bundle third-party design-system code; vendored libraries (for example Apache ECharts in `admin-desktop`) ship inside the pack and are listed in [NOTICE](NOTICE).

## License

[MIT](LICENSE). Third-party attribution is in [NOTICE](NOTICE) (html-mark credit and Apache ECharts).
````
