amicro-universal-frontend-style 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 1.1.0 — 2026-08-31
+
+- Reworked the Skill entrypoint to fit the Yao Library context budget and tightened route exclusions.
+- Moved Skill IR out of the always-loaded `agents/` directory.
+- Added reproducible standard-library tests, trigger-routing evals, and six recorded-fixture Output Lab cases covering file-backed, near-neighbor, and boundary behavior.
+- Added npm runtime packaging with explicit file allowlists, Python cache exclusions, and CLI entrypoints.
+- Fixed uninstall planning so managed-file symlinks are blocked before path resolution and cannot delete their targets under `--force`.
+- Fixed Python 3.11 Markdown rendering compatibility by moving pipe escaping outside the f-string expression.
+- Fixed the browser preview copy feedback after asynchronous clipboard access and added an explicit input `id`/`name`.
+- Removed references to absent companion archives, browser suites, and generated release reports.
+- Preserved missing human review and production telemetry as explicit evidence gaps.
+
+## 1.0.1 — 2026-08-30
+
+- Moved non-essential CSS animation and transition declarations under `prefers-reduced-motion: no-preference` and added an exact emergency stop for reduced motion.
+- Fixed 320px horizontal overflow, narrow toolbar/nav wrapping, RTL switch positioning, and logical sizing.
+- Reworked text/icon swap examples so each control exposes one accessible name and selection state is reflected with ARIA.
+- Enforced target-scoped `--output` paths for inspection and verification, including absolute path, parent traversal, and symlink escape rejection.
+- Added safe install/update/uninstall lifecycle with `.amicro-install.json`, hashes, drift detection, atomic writes, dry-run, and explicit force semantics.
+- Changed the light muted token to `#6f6f6f` and added semantic contrast checks.
+- Made `amicro-tokens.json` the canonical 66-variable source and generated CSS/TypeScript artifacts deterministically.
+- Added conservative animation-context verification, deliberately unsafe regression fixtures, and self-scoped React/Vue/Svelte examples.
+- Added 19 standard-library unit tests and a 10-check Chromium smoke suite covering 320/360/768/1440px, reduced motion, accessible names, focus, RTL, and console errors.
+- Split runtime, source/evidence, and five host-layout adapter distributions.
+- Removed unsupported world-class/adoption claims; independent human blind review and production telemetry remain missing evidence.
+
+## 1.0.0 — 2026-08-28
+
+- Rebuilt the repository-local Amicro design notes as a cross-framework Library-mode Skill.
+- Added scoped design tokens, primitive components, motion utilities, and machine-readable tokens.
+- Added migration guidance for vanilla, React/Next, Vue/Nuxt, Svelte/SvelteKit, Astro, Tailwind, CSS Modules, Sass, and CSS-in-JS.
+- Added deterministic frontend inspection, safe asset installation, and static style verification scripts.
+- Added runnable preview, framework examples, trigger cases, output cases, tests, attribution, and initial validation artifacts.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amicro Universal Frontend Style contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# Amicro Universal Frontend Style Skill v1.1.0
+
+一个可复用、跨框架的 Agent Skill，用于把 **Amicro 的视觉语言与微交互语法**迁移到任意前端页面，而不是强制复制上游的 React、Tailwind 或 Motion 技术栈。
+
+## 能力
+
+- 识别 React、Next.js、Vue、Nuxt、Svelte、Astro、Tailwind、CSS Modules、CSS-in-JS 与现有动效工具。
+- 将页面、表面、舞台、文字、边框、品牌强调色等角色映射为作用域 Token。
+- 提供卡片、按钮、导航、表单、切换、提示、文本/图标交换、光泽和页面转场配方。
+- 默认使用目标项目已有技术栈，不自动安装依赖，不联网，不修改 `package.json`。
+- 检查键盘焦点、主题、对比度、移动端溢出风险、危险动效和 reduced-motion。
+
+## 安装 Skill
+
+将运行版 ZIP 解压到宿主支持的 Skills 目录。常见项目级位置：
+
+```text
+.agents/skills/amicro-universal-frontend-style/
+```
+
+显式调用：
+
+```text
+$amicro-universal-frontend-style 把 src/pages/pricing.tsx 改成 Amicro 风格，保留现有品牌色、文案、组件 API 和业务逻辑。
+```
+
+自然语言能否自动触发取决于宿主的语义路由；显式 `$amicro-universal-frontend-style` 最可靠。
+
+## 检查目标项目
+
+```bash
+python3 scripts/inspect_frontend.py /path/to/project --format markdown
+```
+
+报告只能写到目标项目内部：
+
+```bash
+python3 scripts/inspect_frontend.py /path/to/project \
+  --format json \
+  --output reports/amicro-inventory.json
+```
+
+绝对路径、`../` 逃逸和符号链接逃逸都会被拒绝。
+
+## 安装样式层
+
+默认仅 dry-run：
+
+```bash
+python3 scripts/install_style_layer.py /path/to/project \
+  --destination src/styles/amicro
+```
+
+显式安装：
+
+```bash
+python3 scripts/install_style_layer.py /path/to/project \
+  --destination src/styles/amicro \
+  --apply
+```
+
+默认管理：
+
+- `amicro-tokens.css`
+- `amicro-primitives.css`
+- `amicro-motion.css`
+- `amicro-tokens.json`
+- `amicro-tokens.ts`
+- `.amicro-install.json` 安装清单与文件哈希
+
+需要 TypeScript 动效 helper 时添加 `--include-presets`。
+
+安全更新：
+
+```bash
+python3 scripts/install_style_layer.py /path/to/project \
+  --destination src/styles/amicro \
+  --update --apply
+```
+
+卸载：
+
+```bash
+python3 scripts/install_style_layer.py /path/to/project \
+  --destination src/styles/amicro \
+  --uninstall --apply
+```
+
+被本地修改的受管文件默认不会被更新或删除；只有显式 `--force` 才会覆盖漂移。
+
+## 导入和作用域
+
+```css
+@import "./amicro/amicro-tokens.css";
+@import "./amicro/amicro-primitives.css";
+@import "./amicro/amicro-motion.css";
+```
+
+```html
+<main class="amicro" data-amicro-root data-amicro-theme="auto">
+  <!-- existing product UI -->
+</main>
+```
+
+Token 的权威源是 `assets/amicro-tokens.json`。检查生成物一致性：
+
+```bash
+python3 scripts/generate_token_assets.py .
+```
+
+维护者需要重新生成 CSS/TypeScript 时使用 `--write`。
+
+## 静态验证
+
+```bash
+python3 scripts/verify_amicro_style.py /path/to/project --strict
+```
+
+写入目标内部报告：
+
+```bash
+python3 scripts/verify_amicro_style.py /path/to/project \
+  --strict --format json \
+  --output reports/amicro-verification.json
+```
+
+静态扫描不能证明视觉正确。真实验收至少应覆盖 320、360、768、1440px，明暗主题、键盘、触摸、唯一可访问名称、RTL（适用时）、reduced-motion、控制台错误和横向溢出。
+
+## 源码验证
+
+从源码仓库运行标准库测试：
+
+```bash
+python3 -m unittest discover -s tests -p 'test_*.py'
+python3 scripts/generate_token_assets.py .
+python3 scripts/verify_amicro_style.py . --strict
+```
+
+测试覆盖路径约束、前端探测、Token 生成一致性、静态验证，以及样式层
+dry-run/install/update/drift/uninstall 生命周期。npm runtime 包不包含测试与评测
+夹具；它们保留在源码仓库中供维护和发布验证。
+
+真实浏览器验收仍需在具体目标项目上完成，不能由静态测试替代。
+
+## 分发边界
+
+- **npm runtime 包**：实际安装使用，不包含测试、评测和生成报告。
+- **Git 源码**：包含测试、触发与输出评测，以及维护元数据。
+- 宿主适配声明只描述目录与元数据兼容性，不代表所有宿主都完成在线实机认证。
+
+独立人类盲审与生产采用 telemetry 仍是 `missing evidence`，因此不作
+“world-class”或生产采用声明。
+
+## 来源与许可
+
+本 Skill 基于 Amicro 公开 MIT 仓库进行框架中立化整理。归属与边界见 `THIRD_PARTY_NOTICES.md` 和 `references/source-notes.md`。

package/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: amicro-universal-frontend-style
+description: Apply or port the Amicro-inspired visual language, scoped design tokens, component surfaces, and restrained micro-transitions to an existing frontend. Use for React, Next.js, Vue, Nuxt, Svelte, Astro, Tailwind, CSS Modules, CSS-in-JS, or vanilla HTML/CSS/JS when the user asks for Amicro styling, tactile motion, a style migration, or an implementation audit. Preserve product behavior, content, component APIs, accessibility, branding, and the target stack. Exclude backend work, generic brand identity design, install-only support, visual critique without implementation, and verbatim cloning of Amicro product content.
+---
+
+# Amicro Universal Frontend Style
+
+Apply Amicro as an adaptable style grammar, not a product clone.
+
+## Contract
+
+- Preserve behavior, semantics, content, component APIs, and brand constraints unless explicitly changed.
+- Reuse the target stack and existing design system. New dependencies require approval.
+- Scope all tokens and styles; inspect before writing and patch narrowly.
+- Keep essential behavior available to keyboard, pointer, and touch users without relying on hover.
+- Put non-essential animation inside `prefers-reduced-motion: no-preference`.
+- Never claim visual verification from static scanning.
+
+## Exclusions
+
+Do not use this Skill for backend work, installation-only support, generic visual critique, general accessibility audits that do not request Amicro adaptation, broad brand identity work, one-off animation snippets, summaries, or verbatim product cloning.
+
+## Workflow
+
+1. Identify the target slice, framework, style entrypoint, theme model, existing motion library, checks, and contracts to preserve.
+2. Inventory the target before editing:
+   ```bash
+   python3 scripts/inspect_frontend.py <target> --format markdown
+   ```
+3. Read `references/design-language.md` and `references/migration-workflow.md`. Add motion or framework references only when needed.
+4. Pilot the smallest useful layer: token roles, surfaces, geometry, focus, component states, then optional motion.
+5. Run the target project's format, type, lint, test, and build commands, followed by:
+   ```bash
+   python3 scripts/verify_amicro_style.py <target> --strict
+   ```
+6. Render relevant states at 320, 360, 768, and 1440px. Check focus, touch, exact accessible names, themes, reduced motion, clipping, overflow, RTL when relevant, and runtime errors.
+7. Report changed files, preserved contracts, checks actually run, rendered states actually inspected, and unresolved caveats.
+
+## Optional Style Layer
+
+Dry-run is the default. Writes require `--apply` and remain inside the explicit target:
+
+```bash
+python3 scripts/install_style_layer.py <target> --destination src/styles/amicro
+python3 scripts/install_style_layer.py <target> --destination src/styles/amicro --apply
+python3 scripts/install_style_layer.py <target> --destination src/styles/amicro --update --apply
+python3 scripts/install_style_layer.py <target> --destination src/styles/amicro --uninstall --apply
+```
+
+## Output Contract
+
+Return working target-native files, a concise compatibility summary, commands actually run, rendered evidence actually inspected, and explicit remaining risks. The bundled `assets/` are optional seeds, not mandatory global CSS.
+
+Routing evidence and packaging expectations live in `evals/`; they are maintenance inputs, not runtime instructions.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,39 @@
+# Third-Party Notices
+
+## Amicro — Micro-transitions
+
+This Skill derives design-system observations, token roles, interaction patterns, and implementation guidance from the public Amicro repository:
+
+- Project: `@subhanhq/amicro`
+- Repository: <https://github.com/Subhan-code/Amicro--Micro-transitions->
+- Creator: Syed Subhan
+- Upstream license: MIT
+- Upstream copyright: `Copyright (c) 2026 SYED SUBHAN UDDIN`
+
+The upstream MIT notice follows:
+
+```text
+MIT License
+
+Copyright (c) 2026 SYED SUBHAN UDDIN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+This package does not redistribute the Amicro logo, product copy, screenshots, or a wholesale copy of the upstream component library. The bundled CSS and examples are framework-neutral adaptations written for this Skill.

package/VERSION

@@ -0,0 +1 @@
+1.1.0

package/agents/interface.yaml

@@ -0,0 +1,29 @@
+interface:
+  display_name: "Amicro Universal Frontend Style"
+  short_description: "Port scoped Amicro-inspired styling and motion into an existing frontend"
+  default_prompt: "Use $amicro-universal-frontend-style to inspect the target, preserve its contracts, implement the smallest scoped Amicro-inspired layer in the existing stack, verify project checks and rendered states, and report only evidence actually collected."
+compatibility:
+  canonical_format: "agent-skills"
+  adapter_targets:
+    - "openai"
+    - "claude"
+    - "generic"
+    - "agent-skills-compatible"
+    - "vscode"
+  activation:
+    mode: "manual"
+    semantic_routing: "host-dependent"
+    explicit_invocation: "$amicro-universal-frontend-style"
+  execution:
+    context: "inline"
+    shell: "bash"
+  trust:
+    source_tier: "local"
+    remote_inline_execution: "forbid"
+    remote_metadata_policy: "allow-metadata-only"
+  degradation:
+    openai: "metadata-adapter"
+    claude: "neutral-source-plus-adapter"
+    generic: "neutral-source"
+    agent-skills-compatible: "neutral-source"
+    vscode: "agent-skills-source-with-vscode-notes"

package/assets/README.md

@@ -0,0 +1,38 @@
+# Bundled Style Assets
+
+These files are opt-in implementation seeds. They are scoped, install no dependency, import no font, perform no global reset, and make no network request.
+
+## Canonical source
+
+`amicro-tokens.json` is the single machine-readable source for all public `--amicro-*` variables. The CSS and TypeScript files are generated from it.
+
+```bash
+python3 scripts/generate_token_assets.py .          # read-only parity check
+python3 scripts/generate_token_assets.py . --write  # maintainer regeneration
+```
+
+## Files
+
+- `amicro-tokens.json` — canonical light/dark/auto token data.
+- `amicro-tokens.css` — generated variables under `.amicro`, `[data-amicro-scope]`, or `[data-amicro-root]`.
+- `amicro-tokens.ts` — generated dependency-free TypeScript token maps.
+- `amicro-primitives.css` — layout, card, stage, button, navigation, form, switch, toast, and metric primitives.
+- `amicro-motion.css` — gated hover/press, entrance, icon/text swap, glare, pulse, shake, success, skeleton, and route utilities.
+- `amicro-motion-presets.ts` — optional dependency-free timing, easing, spring, reduced-motion, and magnetic-offset helpers.
+
+## Minimal use
+
+```html
+<link rel="stylesheet" href="amicro-tokens.css">
+<link rel="stylesheet" href="amicro-primitives.css">
+<link rel="stylesheet" href="amicro-motion.css">
+
+<main class="amicro" data-amicro-root data-amicro-theme="auto">
+  <article class="amicro-card amicro-hover-lift" data-interactive="true">
+    <div class="amicro-card__stage">...</div>
+    <footer class="amicro-card__footer">...</footer>
+  </article>
+</main>
+```
+
+Override variables at the scope root to preserve the target product's brand.

package/assets/amicro-motion-presets.ts

@@ -0,0 +1,39 @@
+/** Framework-neutral Amicro motion constants and small helpers. No runtime dependency. */
+export const AMICRO_EASE = [0.16, 1, 0.3, 1] as const;
+export const AMICRO_CURTAIN_EASE = [0.83, 0, 0.17, 1] as const;
+
+export const AMICRO_DURATION = {
+  instant: 0.12,
+  fast: 0.18,
+  control: 0.24,
+  card: 0.32,
+  section: 0.48,
+  route: 0.65,
+} as const;
+
+export const AMICRO_SPRING = {
+  crisp: { stiffness: 600, damping: 25 },
+  layout: { stiffness: 500, damping: 25 },
+  gentle: { stiffness: 400, damping: 25 },
+  ring: { stiffness: 600, damping: 15 },
+} as const;
+
+export function prefersReducedMotion(): boolean {
+  return typeof window !== "undefined" &&
+    window.matchMedia?.("(prefers-reduced-motion: reduce)").matches === true;
+}
+
+export type MagneticOffset = { x: number; y: number };
+
+export function magneticOffset(
+  event: Pick<PointerEvent, "clientX" | "clientY">,
+  element: Element,
+  strength = 0.25,
+  maxDistance = 12,
+): MagneticOffset {
+  const rect = element.getBoundingClientRect();
+  const x = (event.clientX - (rect.left + rect.width / 2)) * strength;
+  const y = (event.clientY - (rect.top + rect.height / 2)) * strength;
+  const clamp = (value: number) => Math.max(-maxDistance, Math.min(maxDistance, value));
+  return { x: clamp(x), y: clamp(y) };
+}