@yargote/artifacts-cli 0.1.0-beta.1 → 0.1.0-beta.11

package/skills/artifacts-design/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,155 @@
+# Third-party notices
+
+These notices apply to the named adapted references and bundled fonts. They do not set a license
+for the Artifacts application or the original Artifacts skill instructions.
+
+## Emil Kowalski skills
+
+Adapted in [references/interface-checks.md](references/interface-checks.md). [Upstream license](https://raw.githubusercontent.com/emilkowalski/skills/refs/heads/main/LICENSE).
+
+```text
+MIT License
+
+Copyright (c) 2026 Emil Kowalski
+
+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.
+```
+
+## Vercel Web Interface Guidelines
+
+Adapted in [references/interface-checks.md](references/interface-checks.md). [Upstream license](https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/refs/heads/main/LICENSE).
+
+```text
+MIT License
+
+Copyright (c) 2025 Vercel Labs
+
+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.
+```
+
+## Catppuccin palette
+
+Adapted in [references/catppuccin.md](references/catppuccin.md). [Upstream license](https://raw.githubusercontent.com/catppuccin/palette/refs/heads/main/LICENSE).
+
+```text
+MIT License
+
+Copyright (c) 2021 Catppuccin
+
+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.
+```
+
+## Vercel Agent Skills
+
+Adapted in [interface guidelines](references/interface-checks.md).
+[Upstream repository](https://github.com/vercel-labs/agent-skills).
+This notice is retained from the reviewed Packy Web Pack.
+
+```text
+Vercel Agent Skills
+
+The upstream repository declares these skills licensed under the MIT License.
+
+Copyright (c) Vercel
+
+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.
+```
+
+## Hallmark
+
+The composition guidance in [SKILL.md](SKILL.md) and the review categories in
+[references/interface-checks.md](references/interface-checks.md) adapt ideas from
+[Hallmark](https://github.com/Nutlope/hallmark), reviewed on 2026-10-24.
+[Upstream license](https://github.com/Nutlope/hallmark/blob/main/LICENSE).
+
+```text
+MIT License
+
+Copyright (c) 2026 Hallmark 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.
+```
+
+## Bundled fonts
+
+The files in [fonts](fonts) are the Latin subsets of Bricolage Grotesque, Public Sans, JetBrains Mono, and Newsreader, as served by Google Fonts on 2026-10-17. Each is licensed under the SIL Open Font License, Version 1.1. The copyright lines and the complete license text are in [fonts/OFL.txt](fonts/OFL.txt).

package/skills/artifacts-design/fonts/OFL.txt

@@ -0,0 +1,96 @@
+Copyright 2022 The Bricolage Grotesque Project Authors (https://github.com/ateliertriay/bricolage)
+Copyright 2015 The Public Sans Project Authors (https://github.com/uswds/public-sans)
+Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)
+Copyright 2020 The Newsreader Project Authors (http://github.com/productiontype/Newsreader)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/skills/artifacts-design/references/canvas.md

@@ -0,0 +1,100 @@
+# Author a design canvas
+
+Create a retained `design` snapshot when several HTML boards belong in one canvas. Each board is a complete self-contained HTML document. The canvas supplies placement, page selection, notes, pan, zoom, and a focus view. The calling MCP or CLI skill owns saving and publication.
+
+## Compose the boards
+
+1. Choose a frame size for each board. Common starting sizes are 1440 by 900 for desktop, 390 by 844 for a phone, and 768 by 1024 for a tablet. These are authoring conventions, not schema limits.
+2. Place boards in a row with 80 px between their edges. Start another row 120 px below the tallest board in the preceding row. Coordinates are canvas pixels, and boards can use different sizes.
+3. Write each board under `boards/` as one UTF-8 `.html` file. Inline its styles, scripts, images, and fonts. Files retained beside a board are downloads, not relative executable assets.
+4. Apply this skill's typography and Catppuccin tokens inside each board. The canvas ground follows the viewer's light or dark theme independently.
+5. Define `canvas.json` with the exact index below. Keep snapshot metadata outside the index.
+
+```json
+{
+	"v": 1,
+	"boards": {
+		"boards/Desktop.html": { "x": 0, "y": 0, "w": 1440, "h": 900, "title": "Desktop", "page": "overview" },
+		"boards/Phone.html": { "x": 1520, "y": 0, "w": 390, "h": 844, "title": "Phone", "page": "overview" },
+		"boards/Detail.html": { "x": 0, "y": 0, "w": 1440, "h": 900, "title": "Detail", "page": "detail" },
+		"boards/DetailPhone.html": { "x": 1520, "y": 0, "w": 390, "h": 844, "title": "Detail phone", "page": "detail" }
+	},
+	"order": ["boards/Desktop.html", "boards/Phone.html", "boards/Detail.html", "boards/DetailPhone.html"],
+	"notes": {
+		"review": { "x": 0, "y": 1020, "w": 390, "text": "Review both layouts.", "page": "overview" }
+	},
+	"pages": [
+		{ "id": "overview", "name": "Overview" },
+		{ "id": "detail", "name": "Detail" }
+	]
+}
+```
+
+The first page opens initially. Boards and notes without `page` appear on the first page when pages exist. Without pages, every board and note appears together. A page can reuse the coordinates of another page.
+
+## Index reference
+
+The index and its nested entries reject unknown fields. The complete rules are:
+
+| Field | Rule |
+| --- | --- |
+| `v` | Required integer `1`. |
+| `boards` | Required object with at most 32 entries. Every key matches `^boards/[A-Za-z0-9_][A-Za-z0-9_.-]*\.html$`. Names are case-sensitive and flat. |
+| Board `x`, `y` | Required finite numbers from -1,000,000 to 1,000,000 inclusive. Fractions are accepted. |
+| Board `w`, `h` | Required finite numbers from 40 to 8000 inclusive. Fractions are accepted. |
+| Board `title` | Optional string of 1 to 256 characters. The board path is the display fallback. |
+| Board `page` | Optional ID that names a declared page. |
+| `order` | Required array of 1 to 32 board paths. It names every board exactly once and contains no other path. Its order controls rendering. |
+| `notes` | Optional object with at most 200 entries. Each key is an ID. |
+| Note `x`, `y`, `text` | Coordinates use the board coordinate limits. `text` is a required string rendered as escaped text, not HTML. |
+| Note `w`, `page` | Optional width from 40 to 8000 and an optional declared page ID. |
+| `pages` | Optional array of at most 32 objects with required `id` and `name`. IDs are unique. `name` contains 1 to 256 characters. |
+| ID | 1 to 40 ASCII letters, digits, underscores, or hyphens. `__proto__` is rejected. |
+
+Every indexed board has a matching snapshot file with the same `path`, `mediaType: "text/html"`, `encoding: "utf8"`, and the complete HTML in `data`. A snapshot has at most 32 files total, including other retained downloads. The directory preparer rejects every unindexed entry in `boards/`, missing boards, directories, symbolic links, and invalid UTF-8. The snapshot contract itself permits other unindexed attachments.
+
+## Embed fonts within the shared budget
+
+Run the real font helper once for each board after completing its HTML:
+
+```sh
+node <design-skill-directory>/scripts/embed-fonts.mjs my-canvas/boards/Desktop.html
+node <design-skill-directory>/scripts/embed-fonts.mjs my-canvas/boards/Phone.html
+```
+
+For the CLI, resolve `<design-skill-directory>` with `artifacts skills path artifacts-design`. The helper selects bundled Latin font subsets from actual CSS declarations and embeds `data:` WOFF2 faces. It rewrites the board in place and is safe to rerun.
+
+Use one small, consistent selection of bundled families and styles across boards. Each board needs its own embedded font bytes because each iframe is an independent document. A subset cannot be shared through an attachment URL. Three families add about 135 KB per board, so repeated embedding can exhaust the canvas budget. Prefer one family and only the styles the board uses when many boards share one revision. The helper checks one board's 1 MiB limit. The preparer and server check the combined revision.
+
+The shared limit is 1,048,576 decoded bytes. It includes serialized snapshot metadata, UTF-8 index text, every file path and media type, and every decoded file body. Whitespace in `canvas.json` counts. The 1 MiB limit applies to all boards together, not to each board separately.
+
+## Save the canvas
+
+For MCP, send one complete snapshot to `artifacts_create` or `artifacts_update`:
+
+```js
+{
+	metadata: { title: 'Product layouts', description: 'Desktop and phone review.' },
+	content: { kind: 'design', text: JSON.stringify(index) },
+	files: boardPaths.map((path) => ({ path, mediaType: 'text/html', encoding: 'utf8', data: boardHtml[path] }))
+}
+```
+
+Here `index`, `boardPaths`, and `boardHtml` come from your completed source files. Read the saved revision back through `artifacts_read` before reporting persistence.
+
+For the CLI, keep `canvas.json` and `boards/*.html` in one directory. Run the bundled preparer:
+
+```sh
+node <cli-skill-directory>/scripts/prepare-retained.mjs ./my-canvas > snapshot.json
+artifacts create --snapshot snapshot.json
+```
+
+Resolve `<cli-skill-directory>` with `artifacts skills path artifacts-cli`. Use the script at that returned path so its installed contracts dependency resolves. The preparer preserves the index text and board HTML and sorts snapshot files by path. Canvas rendering still follows `order`. It emits a validated snapshot on stdout, uses the directory basename as `metadata.title`, and sets `metadata.description` to `""`. Edit those metadata fields in the emitted JSON before saving when the task calls for a specific title or description. The directory form accepts exactly one positional argument. The named-option form prepares retained-verification configuration and keeps its separate contract.
+
+## Check the retained canvas
+
+Open the exact saved revision in the authenticated panel. Confirm all boards fit on the initial page, select each page, and open a board through its name button. Focus view shows that board at its declared width and height and enables its controls. **Volver al lienzo** returns to the prior pan and zoom. Escape also returns when a canvas control has keyboard focus. After interacting inside a board, use **Volver al lienzo** to return. For Escape, first use Shift+Tab to move focus back to the canvas controls. Embedded boards remain inert in the overview.
+
+Check publication through the protected URL returned by `artifacts_publish`. In unsupported browsers, the canvas displays an inert listing of board source. Rendering uses nested opaque `srcdoc` iframes with `sandbox="allow-scripts"` and the existing content policy. Board scripts can still consume renderer time or briefly perturb focus. The canvas is not an absolute keyboard isolation boundary.
+
+Export retains the index as `content.json` and boards as `files/boards/*.html`. To recreate a snapshot, use the manifest's `metadata`, preserve `content.json` as `content.text`, and reconstruct each file using its declared encoding. The ZIP manifest sorts files by path, matching the directory preparer. Snapshot digests preserve the original `files` array order, so keep that order from an independent saved read when comparing digests after recreation. A directory preparer also derives new metadata. Restore the manifest metadata and original file order before comparing snapshot digests.

package/skills/artifacts-design/references/catppuccin.md

@@ -0,0 +1,38 @@
+# Catppuccin roles
+
+The starter maps the official [Catppuccin palette](https://github.com/catppuccin/palette/blob/main/palette.json) to semantic tokens. Latte serves the light theme and Mocha the dark theme. Blue is the Artifacts accent.
+
+| Token | Role | Latte (light) | Mocha (dark) |
+| --- | --- | --- | --- |
+| `--page` | Page background | Base `#eff1f5` | Mantle `#181825` |
+| `--surface` | Strip, table, or panel | White `#ffffff` | Base `#1e1e2e` |
+| `--sunken` | Table header, hover, code | Mantle `#e6e9ef` | Crust `#11111b` |
+| `--line` | Hairline divider | Surface 0 `#ccd0da` | Surface 0 `#313244` |
+| `--control` | Input and button boundary | Overlay 1 `#8c8fa1` | Overlay 0 `#6c7086` |
+| `--fg` | Main text | Text `#4c4f69` | Text `#cdd6f4` |
+| `--muted` | Secondary text and labels | Subtext 1 `#5c5f77` | Subtext 0 `#a6adc8` |
+| `--accent` | Focus, selection, primary fill | Blue `#1e66f5` | Blue `#89b4fa` |
+| `--accent-ink` | Links and accent text | `#1957d0` | Blue `#89b4fa` |
+| `--ok` / `--ok-ink` | Success mark / text | Green `#40a02b` / `#307820` | Green `#a6e3a1` |
+| `--warn` / `--warn-ink` | Warning mark / text | Yellow `#df8e1d` / `#915c13` | Yellow `#f9e2af` |
+| `--bad` / `--bad-ink` | Error mark / text | Red `#d20f39` / `#b20d30` | Red `#f38ba8` |
+
+The Latte ink values darken the palette color so pill text reaches 4.5:1 on its soft background. Each `*-soft` token mixes 14 % of its color into `--surface`, so it adapts to both themes without a second definition.
+
+Every text token reaches 4.5:1 on `--page` and `--surface` in both themes. `--control` reaches 3:1 for input boundaries. `--line` is decorative and must not be the only boundary of a control.
+
+## Chart series
+
+Use these in order after Blue. Give each series a direct label or marker as well as a color.
+
+| Series | Latte | Mocha |
+| --- | --- | --- |
+| 1 | Blue `#1e66f5` | Blue `#89b4fa` |
+| 2 | Peach `#fe640b` | Peach `#fab387` |
+| 3 | Teal `#179299` | Teal `#94e2d5` |
+| 4 | Mauve `#8839ef` | Mauve `#cba6f7` |
+| 5 | Yellow `#df8e1d` | Yellow `#f9e2af` |
+
+Mauve is a data color only, never the accent.
+
+The palette's license notice is retained in [third-party notices](../THIRD-PARTY-NOTICES.md).

package/skills/artifacts-design/references/interface-checks.md

@@ -0,0 +1,60 @@
+# Interface checks for HTML artifacts
+
+Use these checks for visual authoring and review. Apply only the checks relevant to the artifact. Keep the requested content and behavior central.
+
+## Accessible, resilient interfaces
+
+- Use semantic headings, buttons, links, and tables. Label controls and icon buttons. Give meaningful images alternative text.
+- Make every action keyboard accessible. Keep focus visible and unobscured. Restore focus after dismissing overlays.
+- Announce asynchronous status changes without interrupting reading. Pair errors with a useful next action.
+- Provide click and keyboard alternatives for gestures. Keep essential information available without hover.
+- Preserve zoom and paste. Associate input labels with their controls. Use suitable input types.
+- Support narrow viewports, empty results, and long content. Let flex children shrink. Wrap text before hiding overflow.
+- Reserve image dimensions. Defer below-fold media. Batch layout reads and writes. Paginate or virtualize long lists when needed.
+- Use tabular numerals for comparisons and `Intl` for localized values. Keep units attached to numbers.
+- Set native controls to the document's color scheme. Keep hover, active, and focus states distinguishable.
+- Avoid motion that blocks interaction. Provide pause controls for extended autoplay and a reduced-motion alternative.
+
+## Motion and interaction detail
+
+Adapt motion to repetition and purpose. Frequent actions should respond immediately. Add animation when it explains a state change or spatial relationship.
+
+Prefer interruptible CSS transitions with named properties. Start around 100 to 160 ms for press feedback and 125 to 250 ms for small overlays. Use an ease-out curve for entry. Anchor popover transforms to their trigger and center modal transforms.
+
+Prefer `transform` and `opacity` for movement. Avoid `transition: all`, large blur effects, and entrance scaling from zero. Keep feedback subtle enough that labels remain readable.
+
+Under `prefers-reduced-motion: reduce`, remove decorative movement and retain immediate state feedback. Gate hover effects with `(hover: hover) and (pointer: fine)`. Do not make content wait for an entrance animation.
+
+## Adapt to the Artifacts sandbox
+
+Keep input-driven calculations in document memory. Use labeled controls without a form submission workflow. Do not imply that an in-document control saves a retained revision or publishes an artifact.
+
+Keep filters and tabs local to the document. Do not depend on host URL synchronization, router packages, persistent storage, network requests, or remote fonts. Embed fonts and other required assets as `data:` URIs within the snapshot budget.
+
+## Required checks
+
+Check content fidelity, sandbox compatibility, and usable behavior regardless of the composition. Preserve supplied facts, units, qualifications, and requested controls. For a visual revision, record the existing content and actions before editing and confirm that they still work afterward.
+
+When browser tools are available, inspect the generated document at a narrow viewport around 375 px and a wide viewport around 1280 px, or the user's requested sizes. Verify that body content fits, labels remain legible, and only intentionally wide tables or code regions scroll locally. Check the artifact itself rather than relying on the surrounding application's appearance.
+
+Exercise every distinct action with keyboard and pointer input. Observe the expected output or state change, including input errors, reset behavior, and empty filter results where applicable. Confirm that focus stays visible and follows opened and dismissed overlays. Check reduced motion when animation is present. Inspect the console for runtime errors and confirm that required content and controls work without external requests.
+
+Finish when each relevant check passes or an unavailable check is identified. Fix observed failures and repeat affected checks. Source inspection establishes markup and script intent; report browser behavior as verified only after observing it.
+
+For a requested audit, identify each issue by element or source location and state its correction. Distinguish source inspection from browser verification. Do not turn ordinary artifact delivery into an unsolicited audit report.
+
+## Visual judgment
+
+Check whether the main visual or result answers the reader's task, whether its labels stay close to what they describe, and whether the reading order is clear at both widths. Read the headings alone and check that they describe this document's content. Remove containers and repeated labels that add no grouping or information.
+
+Choose density, alignment, cards, and section rhythm for the content. A long report, a diagram sequence, and a calculator need different compositions. These choices are defaults to reconsider with a concrete reason, not automatic failures. Keep the user's requested style and content. Do not remove evidence or simplify away a qualification to meet an aesthetic preference.
+
+## Sources
+
+Adapted on 2026-10-14 from [Emil Kowalski's design engineering skill](https://raw.githubusercontent.com/emilkowalski/skills/refs/heads/main/skills/emil-design-eng/SKILL.md) and [Vercel's web design guidelines skill](https://raw.githubusercontent.com/vercel-labs/agent-skills/refs/heads/main/skills/web-design-guidelines/SKILL.md).
+
+The accessibility and interface checks incorporate Vercel's Web Interface Guidelines `command.md` as local guidance. Its remote command workflow and output format are not required. The sandbox adaptations are specific to Artifacts.
+
+The composition workflow and the distinction between required checks and visual judgment draw on [Hallmark](https://github.com/Nutlope/hallmark), reviewed on 2026-10-24. This adaptation retains Artifacts' document types, palette, embedded fonts, and sandbox constraints.
+
+License notices are retained in [Third-party notices](../THIRD-PARTY-NOTICES.md).

package/skills/artifacts-design/references/local-checks.md

@@ -0,0 +1,70 @@
+# Check local HTML before saving
+
+Run the helper after embedding fonts and before the calling skill's create or update operation.
+
+```sh
+design_skill=$(artifacts skills path artifacts-design)
+node "$design_skill/scripts/verify-local.mjs" page.html --evidence ./page-evidence
+```
+
+The helper needs Node 24+, an existing `playwright` or `playwright-core` package, and Chrome or Chromium 152+. It resolves the package from the current project first, then from its own installation. It tries existing Playwright browser binaries and system executables. To select an existing browser explicitly, add `--browser /absolute/path/to/chromium`. An explicit selection does not fall back to another executable.
+
+Missing dependencies, incompatible versions, and launch failures produce actionable diagnostics. The helper never installs software, downloads a browser, disables browser sandboxing, or relaxes document policies.
+
+## Describe controls
+
+Add `--expectations checks.json` to replay actions and assert their results. Each matrix case starts with a fresh document. Steps run in order. A failed step ends that case's sequence because later steps may depend on it. The remaining cases still run.
+
+```json
+{
+  "expectations": [
+    { "kind": "visibleCount", "selector": ".mobile-map, .desktop-map", "count": 1 },
+    { "kind": "visible", "selector": ".mobile-map", "visible": true, "when": { "width": 375 } },
+    { "kind": "visible", "selector": ".desktop-map", "visible": true, "when": { "width": 1280 } },
+    { "kind": "text", "selector": "#total", "text": "5.00" },
+    { "kind": "click", "selector": "#calculate" },
+    { "kind": "text", "selector": "#total", "text": "28.40" },
+    { "kind": "press", "selector": "#reset", "key": "Enter" },
+    { "kind": "text", "selector": "#total", "text": "5.00" }
+  ]
+}
+```
+
+Every step requires `kind` and a Playwright locator `selector`. Optional `when` limits it to `width` of 375 or 1280, `theme` of `light` or `dark`, or both. Unknown fields and malformed values fail configuration validation.
+
+| Kind | Additional fields | Observable result |
+| --- | --- | --- |
+| `text` | `text`, a string | Exact inner text of one element. Add a `visible` check when visibility is required. |
+| `count` | `count`, a nonnegative integer | Number of matching elements. |
+| `visible` | `visible`, a boolean | Visibility of exactly one matching element. A missing element fails. |
+| `visibleCount` | `count`, a nonnegative integer | Number of visible matches. Use one selector matching both responsive variants to assert exclusivity. |
+| `attribute` | `name`, a nonempty string, and `value`, a string or `null` | Exact attribute value. `null` requires absence. |
+| `click` | None. | Real pointer activation. |
+| `press` | `key`, a Playwright key string such as `Enter`, `Space`, or `Tab` | Keyboard input to the selected element. |
+| `fill` | `value`, a string | Input or textarea edit. |
+| `check` | `checked`, a boolean | Checkbox or radio state. |
+| `select` | `values`, an array of strings | Selected option values. |
+
+Assertions poll for their expected result. Actions wait for Playwright's actionability checks. The JSON document accepts at most 100 steps and an optional `timeoutMs` from 100 to 30000. Its default is 3000 ms per expectation. With no expectations file, the helper checks rendering and errors but does not infer the document's intended controls.
+
+Each variant also has a total deadline of `timeoutMs * (step count + 1)`, bounded between 10 and 60 seconds. The deadline includes loading, checks, captures, and final observations. If the renderer stops responding, the helper closes that variant's context, records `deadline.exceeded`, and marks its remaining evidence incomplete. The other variants still run. A deadline failure cannot pass the automatic checks.
+
+## Inspect the evidence
+
+The helper creates a fresh `local-*` subdirectory under `--evidence`. It writes `report.json`, `index.md`, and PNG images. Repeated runs keep separate evidence.
+
+The fixed matrix is 375 and 1280 px wide at 900 px high, each in light and dark. Every case checks document overflow before and after its scenario, runtime exceptions, error console entries, and forbidden resource attempts. CSP violations include resource attempts blocked before a browser request occurs. Initial and final captures scroll the actual iframe in viewport-sized steps. Each phase saves at most 12 tiles. Capture records include actual scroll offsets and mark incomplete coverage in `captureCoverage.truncated`.
+
+The document runs in an opaque-origin iframe with `sandbox="allow-scripts"`. Its response uses the Artifacts preview CSP, `Connection-Allowlist: ()`, and disabled DNS prefetching. Fonts, images, and media must be embedded as `data:` URIs. Network connections, remote scripts, frames, objects, forms, and workers remain blocked. The local server exposes only the generated wrapper and content, without arbitrary filesystem access. Browser request routing also denies other destinations.
+
+The report records the chosen executable, version, user agent, rejected browser candidates, source hashes before and after verification, actual content response policy and hash, per-case checks, errors, and screenshots. It identifies the evidence as **renderizado local** and leaves `authenticatedPublication` as `not-verified`. It does not modify the HTML, save a revision, publish, or contact the Artifacts service. No service credentials are required.
+
+| Exit code | Meaning |
+| --- | --- |
+| 0 | Automatic checks passed. Visual review remains required. |
+| 1 | An automatic check failed. |
+| 2 | Setup or configuration blocked the run. |
+
+A structured blocked report is written when a valid evidence destination is available. The helper prints the report as JSON on standard output.
+
+Read the screenshots and the [interface checks](interface-checks.md) before accepting the design. Check content fidelity, reading order, labels, focus, alignment, density, and both themes. A clean console cannot establish those judgments. Each run observes load, font readiness, its declared interactions, and a short settling period. Delayed behavior beyond the run and content outside captured coverage require further inspection. Verify the retained revision and protected publication separately through the service workflow after saving.

package/skills/artifacts-design/references/visual-explanations.md

@@ -0,0 +1,13 @@
+# Beginner visual explanations
+
+When the user requests a visual HTML explanation for a beginner, assume no prior knowledge. Identify the topic from the conversation. Ask for it only if it is missing or ambiguous.
+
+Build a visual sequence with one idea per scene. Start with a concrete example the reader can recognize, then show how the parts connect or change. Use large illustrations, diagrams, or pictures to carry the explanation. Decorative icons and oversized headings do not replace explanatory images.
+
+Pair each visual with a short heading and a brief caption. Use familiar words and define necessary terms where they first appear. Keep labels close to what they explain. Preserve essential qualifications and the limits of an analogy even when the user asks for few words.
+
+Use inline SVG or CSS for diagrams. Use embedded raster images when the subject benefits from illustrations or photographs. Resize and compress them to fit the snapshot budget while keeping details readable. If image tools are unavailable, use a clear diagram when it can convey the concept faithfully. Report any requested imagery you cannot provide.
+
+Make the main visual dominant and its labels legible on narrow and wide screens. Give meaningful images text alternatives. Add interaction only when it helps the reader understand a relationship or change. Keep the core explanation accessible without operating a control.
+
+Before saving, check that the sequence explains the topic with its pictures and short captions, without a separate essay. Apply the [interface guidelines](interface-checks.md) visual checks and report any checks you could not run.