@yargote/artifacts-cli 0.1.0-beta.2 → 0.1.0-beta.3

package/README.md

@@ -11,9 +11,9 @@ Use Node 24 or later. The beta targets macOS and Linux. Windows has not been ver
 Choose one persistent installation:
 
 ```sh
-npm install --global @yargote/artifacts-cli@0.1.0-beta.2
+npm install --global @yargote/artifacts-cli@0.1.0-beta.3
 # Or, with pnpm and an existing global bin directory on PATH:
-pnpm add --global @yargote/artifacts-cli@0.1.0-beta.2
+pnpm add --global @yargote/artifacts-cli@0.1.0-beta.3
 artifacts --version
 ```
 
@@ -22,8 +22,8 @@ If pnpm reports that no global bin directory exists, run `pnpm setup` and reopen
 For one-off execution, pin the same version:
 
 ```sh
-npx --yes @yargote/artifacts-cli@0.1.0-beta.2 --help
-pnpm dlx @yargote/artifacts-cli@0.1.0-beta.2 --help
+npx --yes @yargote/artifacts-cli@0.1.0-beta.3 --help
+pnpm dlx @yargote/artifacts-cli@0.1.0-beta.3 --help
 ```
 
 `@beta` follows future prereleases. Exact versions remain reproducible. No stable `latest` release is part of this beta. An organization's pnpm minimum release age or trust policy can delay a new release. Follow that policy rather than disabling it globally.
@@ -134,9 +134,9 @@ Global `--server RESOURCE` and `--state-dir DIR` options can appear before or af
 
 Check `artifacts --help` for `skills` support. The published `0.1.0-beta.1` package predates this command group. These commands describe the current source and packages built from it.
 
-`artifacts skills` and `artifacts skills list` print each bundled skill's name and description, separated by a tab. The initial catalog contains `artifacts-cli`. Its complete source directory is bundled with the CLI, so the instructions match the installed version and work offline.
+`artifacts skills` and `artifacts skills list` print each bundled skill's name and description, separated by a tab. The catalog contains `artifacts-cli` and `artifacts-design`, which owns HTML design, bundled fonts, and the font embedding script. Their complete source directories are bundled with the CLI, so the instructions match the installed version and work offline.
 
-`artifacts skills get artifacts-cli` prints the complete `SKILL.md` without headers or changes to its bytes. `--full` includes every bundled reference and template. Each file starts with a catalog-relative marker such as `=== artifacts-cli/references/commands.md ===`. `artifacts skills get --all` prints every `SKILL.md` with these markers. Add `--full` to include every skill's support files.
+`artifacts skills get artifacts-cli` prints the complete `SKILL.md` without headers or changes to its bytes. `--full` includes every bundled reference and template. Binary files such as fonts appear as a marker with their size, for example `=== artifacts-design/fonts/public-sans.woff2 (binary, 26636 bytes) ===`; read them from `artifacts skills path artifacts-design`. Each file starts with a catalog-relative marker such as `=== artifacts-cli/references/commands.md ===`. `artifacts skills get --all` prints every `SKILL.md` with these markers. Add `--full` to include every skill's support files.
 
 `artifacts skills path` prints the absolute bundled catalog directory. Add a skill name to print that skill's directory. These paths belong to the CLI package and do not depend on the current directory.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yargote/artifacts-cli",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.3",
   "private": false,
   "type": "module",
   "description": "Command-line client for the Artifacts REST API.",
@@ -27,13 +27,14 @@
     "skills"
   ],
   "dependencies": {
-    "@yargote/artifacts-contracts": "0.1.0-beta.2",
-    "@yargote/artifacts-client": "0.1.0-beta.2",
+    "@yargote/artifacts-contracts": "0.1.0-beta.3",
+    "@yargote/artifacts-client": "0.1.0-beta.3",
     "openid-client": "6.8.8",
     "zod": "4.6.5"
   },
   "artifactsSkills": [
-    "artifacts-cli"
+    "artifacts-cli",
+    "artifacts-design"
   ],
   "publishConfig": {
     "access": "public",

package/skills/artifacts-cli/SKILL.md

@@ -21,7 +21,7 @@ Use self-contained HTML for interactive content. Inline styles and scripts and e
 
 Keep the whole revision within 1 MiB of decoded content, metadata, attachment paths, media types, and attachment bytes. At most 32 attachments are accepted. Base64 changes wire size, not the decoded limit. If required content exceeds a limit, explain the constraint without silently removing it.
 
-Finish requested visual and interaction checks before saving when browser tools are available. A successful CLI write proves persistence, not visual quality or browser compatibility. Interactive HTML follows the server's Chrome policy; do not promise it in every browser.
+Before writing or restyling HTML, run `artifacts skills get artifacts-design --full` and follow it. It owns typography, embedded fonts, color, layout, and the rendered checks. Finish those checks before saving when browser tools are available. A successful CLI write proves persistence, not visual quality or browser compatibility. Interactive HTML follows the server's Chrome policy; do not promise it in every browser.
 
 ## Create or revise
 

package/skills/artifacts-design/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: artifacts-design
+description: Design the HTML document of a retained Artifact with embedded fonts, light and dark Catppuccin tokens, purposeful layout, and rendered checks. Use before writing or restyling HTML for the artifacts or artifacts-cli skills.
+---
+
+# Design HTML artifacts
+
+The calling skill owns the snapshot, size limit, and save workflow. This skill owns how the document looks and behaves. Follow the user's visual direction first. When revising content only, keep an existing artifact's established style. When the user asks to redesign or improve the look, start from these defaults.
+
+The document renders in a sandbox that blocks every network request. Fonts, images, and icons load only as `data:` URIs. External stylesheets, Google Fonts links, and CDN scripts silently fail. Inline all CSS and JavaScript.
+
+## Start from the starter
+
+Copy the `<style>` block of [the starter](templates/starter.html) into the new document. It defines the color, font, and spacing tokens and the shared primitives: eyebrow and label, lede, summary strip, pills, expandable rows, panel, note, table, filter bar, and footer. Delete primitives the page does not use. Derive every new color and type decision from its tokens.
+
+The starter supplies a vocabulary, not a layout. Compose the body for the reader's task:
+
+| Purpose | Composition |
+| --- | --- |
+| Report or guide | A conclusion first, a reading column near 68 characters, and evidence beside the claim it supports. |
+| Inventory, ledger, or status | A summary strip, a filter bar with a live count, then one `.row` per record. Its summary shows the identifier, title, and state; its detail holds everything else. Set `--cols` on `.rows` to match the summary cells. Rows stack to one column below 720 px. |
+| Compare options | Aligned criteria in a table, consistent scales, and the tradeoff stated in words. |
+| Explore data | A dominant chart or table sized to carry the page, with filters beside it. |
+| Calculate or simulate | Labeled inputs beside the result they change, with units and a realistic starting example. |
+| Explain a concept | A sequence of large diagrams with short captions; read [visual explanations](references/visual-explanations.md). |
+
+Open in a complete state with the user's real data. Never ship an empty shell or placeholder text.
+
+## Typography
+
+Use the bundled faces through the starter's tokens:
+
+- `--f-display` is Bricolage Grotesque. Use it for `h1` to `h3` and large figures only.
+- `--f-body` is Public Sans for running text and controls.
+- `--f-mono` is JetBrains Mono for code, identifiers, table headers, eyebrows, and labels.
+- Newsreader is an optional reading face. For a long essay or editorial guide, set `--f-body` to `"Newsreader",Charter,Georgia,serif` and keep Public Sans for controls.
+
+Keep the starter's scale: `h1` at `clamp(28px,4vw,40px)`, body at 15 to 16 px with a 1.55 line height, uppercase mono labels at 11 to 12 px with `.06em` tracking, and `text-wrap: balance` on headings. Use `font-variant-numeric: tabular-nums` wherever digits align.
+
+After the HTML file is complete, embed the fonts it names:
+
+```sh
+node <skill-directory>/scripts/embed-fonts.mjs page.html
+```
+
+For the CLI, `<skill-directory>` is the output of `artifacts skills path artifacts-design`. The script rewrites the file in place and is safe to rerun after edits. It embeds only the families the page names and adds italic faces only for `font-style: italic`, `<em>`, `<i>`, or `<cite>`. It refuses to write a page above 1 MiB. Three families add about 135 KB. Newsreader adds about 80 to 165 KB. Do not name another family unless you embed its `woff2` yourself, because an unembedded face silently falls back. Without Node, keep the fallback stacks and report that the fonts were not embedded.
+
+## Color
+
+The starter follows the viewer's system theme. Light uses Catppuccin Latte and dark uses Mocha, with Blue as the only accent. [Catppuccin roles](references/catppuccin.md) lists every token and the extra chart colors.
+
+- Define each color once as a token on bare `:root` and redefine only the tokens in both dark blocks. Never write a literal color in a component rule.
+- Keep `body` on `var(--page)`. Use `--surface` for the objects you set apart, and `--sunken` for table headers and hover.
+- Show state with soft pills: a `*-soft` background and `*-ink` text. Do not fill badges with saturated pastels. Map every state to neutral, accent, ok, warn, or bad. Do not add a hue for an extra state; distinguish it with its label.
+- Use the accent for links, focus, the selected state, and one primary action. Status colors carry meaning only.
+- When the user names a single dark look, set the Mocha values on bare `:root`, keep `color-scheme: dark`, and drop the media blocks.
+
+## Layout and components
+
+- Center one `.wrap` column at `--width` with `max(16px, env(safe-area-inset-*))` side gutters. Space siblings with grid or flex `gap`.
+- Use borders and fills by role. A summary strip, a table, and one panel can each earn a surface. Running text and headings sit on the page.
+- Mark structure that is true: an eyebrow names the source or scope, a label names a field, and numbering appears only for real sequences.
+- Encode attention in form. A row that needs action gets a pill or a muted closed state, not only a different word.
+- Put wide code and diagrams in their own `overflow-x: auto` container. Use a `<table>` only for short records that stay readable when scrolled; use expandable rows for records with long text. The page itself never scrolls sideways at 375 px.
+- Draw diagrams in inline SVG with token colors and labels inside the view box. For icons, use inline Tabler outline SVGs with `currentColor`.
+- Respect `prefers-reduced-motion`. Use motion only to explain a change of state.
+
+## Copy
+
+Give the `<title>` a specific name of two to four words, or the name the user already uses for the document. Write labels from the reader's side, in the user's language. State units next to numbers. Put the source and date of the data in the footer.
+
+## Check the rendered page
+
+Run the [interface checks](references/interface-checks.md) when browser tools are available. Render at 375 px and 1280 px in both light and dark. Confirm that the fonts loaded, nothing overflows, and every control changes something visible. Fix what you see once, then save. Report checks you could not run.
+
+The license notices for bundled fonts and adapted guidance are in [third-party notices](THIRD-PARTY-NOTICES.md).

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

@@ -0,0 +1,124 @@
+# 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.
+```
+
+## 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/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,50 @@
+# 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.
+
+## Check the result
+
+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.
+
+## 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.
+
+License notices are retained in [Third-party notices](../THIRD-PARTY-NOTICES.md).

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.

package/skills/artifacts-design/scripts/embed-fonts.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const fonts = join(dirname(fileURLToPath(import.meta.url)), '../fonts');
+const latin = 'U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD';
+const faces = [
+  { family: 'Bricolage Grotesque', style: 'normal', weight: '500 800', file: 'bricolage-grotesque.woff2' },
+  { family: 'Public Sans', style: 'normal', weight: '400 700', file: 'public-sans.woff2' },
+  { family: 'Public Sans', style: 'italic', weight: '400 700', file: 'public-sans-italic.woff2' },
+  { family: 'JetBrains Mono', style: 'normal', weight: '400 700', file: 'jetbrains-mono.woff2' },
+  { family: 'Newsreader', style: 'normal', weight: '400 700', file: 'newsreader.woff2' },
+  { family: 'Newsreader', style: 'italic', weight: '400 700', file: 'newsreader-italic.woff2' },
+];
+const limit = 1024 * 1024;
+const embedded = /<style data-artifacts-fonts>[\s\S]*?<\/style>\n?/;
+
+const paths = process.argv.slice(2);
+if (paths.length !== 1) {
+  process.stderr.write('Usage: node embed-fonts.mjs PAGE.html\nEmbeds the bundled font faces that PAGE.html names, in place.\n');
+  process.exit(2);
+}
+const [path] = paths;
+const page = (await readFile(path, 'utf8')).replace(embedded, '');
+const italic = /font-style\s*:\s*italic|<(em|i|cite)[\s>]/i.test(page);
+const used = faces.filter((face) => page.includes(face.family) && (face.style === 'normal' || italic));
+const rules = await Promise.all(used.map(async (face) => {
+  const data = (await readFile(join(fonts, face.file))).toString('base64');
+  return `@font-face{font-family:"${face.family}";font-style:${face.style};font-weight:${face.weight};font-display:swap;src:url(data:font/woff2;base64,${data}) format("woff2");unicode-range:${latin}}`;
+}));
+const block = rules.length ? `<style data-artifacts-fonts>${rules.join('')}</style>\n` : '';
+
+const anchor = page.search(/<style[\s>]/i);
+const head = /<head[^>]*>\n?/i.exec(page) ?? /<!doctype[^>]*>\n?/i.exec(page);
+const at = anchor >= 0 ? anchor : head ? head.index + head[0].length : 0;
+const output = page.slice(0, at) + block + page.slice(at);
+const bytes = Buffer.byteLength(output);
+if (bytes > limit) {
+  process.stderr.write(`Not written. ${path} would be ${bytes} bytes, above the 1 MiB revision limit. Drop a family or the italic faces, or shrink the content.\n`);
+  process.exit(1);
+}
+await writeFile(path, output);
+const names = used.map((face) => `${face.family}${face.style === 'italic' ? ' italic' : ''}`);
+process.stdout.write(`${names.length ? `Embedded ${names.join(', ')}` : 'No bundled family named; nothing embedded'}. ${path} is ${bytes} bytes.\n`);

package/skills/artifacts-design/templates/starter.html

@@ -0,0 +1,170 @@
+<!doctype html>
+<html lang="es">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Artifact starter</title>
+<style>
+/* Layout: one centered column; summary before detail, then the dominant table, chart, or diagram. */
+:root{
+  --page:#eff1f5; --surface:#ffffff; --sunken:#e6e9ef; --line:#ccd0da; --control:#8c8fa1;
+  --fg:#4c4f69; --muted:#5c5f77; --accent:#1e66f5; --on-accent:#ffffff; --accent-ink:#1957d0;
+  --ok:#40a02b; --ok-ink:#307820; --warn:#df8e1d; --warn-ink:#915c13; --bad:#d20f39; --bad-ink:#b20d30;
+  --neutral-soft:color-mix(in srgb,var(--fg) 9%,var(--surface));
+  --accent-soft:color-mix(in srgb,var(--accent) 14%,var(--surface));
+  --ok-soft:color-mix(in srgb,var(--ok) 14%,var(--surface));
+  --warn-soft:color-mix(in srgb,var(--warn) 14%,var(--surface));
+  --bad-soft:color-mix(in srgb,var(--bad) 14%,var(--surface));
+  --f-display:"Bricolage Grotesque","Avenir Next",system-ui,sans-serif;
+  --f-body:"Public Sans","Segoe UI",system-ui,sans-serif;
+  --f-mono:"JetBrains Mono",ui-monospace,"SF Mono",Menlo,Consolas,monospace;
+  --radius:10px; --width:1120px;
+  color-scheme:light;
+}
+@media (prefers-color-scheme:dark){:root:not([data-theme="light"]){
+  --page:#181825; --surface:#1e1e2e; --sunken:#11111b; --line:#313244; --control:#6c7086;
+  --fg:#cdd6f4; --muted:#a6adc8; --accent:#89b4fa; --on-accent:#11111b; --accent-ink:#89b4fa;
+  --ok:#a6e3a1; --ok-ink:#a6e3a1; --warn:#f9e2af; --warn-ink:#f9e2af; --bad:#f38ba8; --bad-ink:#f38ba8;
+  color-scheme:dark}}
+:root[data-theme="dark"]{
+  --page:#181825; --surface:#1e1e2e; --sunken:#11111b; --line:#313244; --control:#6c7086;
+  --fg:#cdd6f4; --muted:#a6adc8; --accent:#89b4fa; --on-accent:#11111b; --accent-ink:#89b4fa;
+  --ok:#a6e3a1; --ok-ink:#a6e3a1; --warn:#f9e2af; --warn-ink:#f9e2af; --bad:#f38ba8; --bad-ink:#f38ba8;
+  color-scheme:dark}
+
+*{box-sizing:border-box}
+html{background:var(--page)}
+body{margin:0;background:var(--page);color:var(--fg);font:15px/1.55 var(--f-body);-webkit-font-smoothing:antialiased}
+.wrap{max-width:var(--width);margin:0 auto;padding-left:max(16px,env(safe-area-inset-left,0px));padding-right:max(16px,env(safe-area-inset-right,0px));padding-block:32px 64px;display:grid;gap:24px}
+.wrap>*{min-width:0}
+h1,h2,h3{font-family:var(--f-display);margin:0;text-wrap:balance;letter-spacing:-.01em}
+h1{font-size:clamp(28px,4vw,40px);line-height:1.05;font-weight:700}
+h2{font-size:clamp(20px,2.4vw,24px);line-height:1.2;font-weight:700}
+h3{font-size:17px;line-height:1.3;font-weight:600}
+p{margin:0}
+a{color:var(--accent-ink);text-underline-offset:3px}
+code,kbd,pre{font-family:var(--f-mono);font-size:.86em}
+pre{margin:0;padding:14px 16px;background:var(--sunken);border-radius:8px;overflow-x:auto;line-height:1.5}
+:focus-visible{outline:2px solid var(--accent);outline-offset:2px}
+
+.eyebrow,.label{font:600 11.5px/1.2 var(--f-mono);letter-spacing:.06em;text-transform:uppercase;color:var(--muted)}
+header{display:grid;gap:8px}
+.lede{color:var(--muted);max-width:68ch;font-size:16px}
+.prose{display:grid;gap:12px;max-width:68ch}
+section{display:grid;gap:14px}
+
+.strip{display:flex;flex-wrap:wrap;gap:1px;background:var(--line);border:1px solid var(--line);border-radius:var(--radius);overflow:hidden}
+.stat{flex:1 1 150px;display:grid;gap:2px;padding:14px 16px;background:var(--surface)}
+.stat b{font:700 26px/1.1 var(--f-display);font-variant-numeric:tabular-nums}
+.stat span{font-size:13px;color:var(--muted)}
+
+.pill{display:inline-flex;align-items:center;gap:6px;font:600 11.5px/1.25 var(--f-body);padding:3px 8px;border-radius:5px;background:var(--neutral-soft);color:var(--muted)}
+.pills{display:flex;flex-wrap:wrap;gap:5px}
+.pill.accent{background:var(--accent-soft);color:var(--accent-ink)}
+.pill.ok{background:var(--ok-soft);color:var(--ok-ink)}
+.pill.warn{background:var(--warn-soft);color:var(--warn-ink)}
+.pill.bad{background:var(--bad-soft);color:var(--bad-ink)}
+
+.panel{background:var(--surface);border:1px solid var(--line);border-radius:var(--radius);padding:16px 18px;display:grid;gap:10px}
+.note{border-left:3px solid var(--accent);padding:2px 0 2px 14px;display:grid;gap:4px;max-width:72ch}
+.note.warn{border-color:var(--warn)}
+
+.table{background:var(--surface);border:1px solid var(--line);border-radius:var(--radius);overflow-x:auto}
+table{width:100%;border-collapse:collapse;font-size:14px}
+th{font:600 11px/1.2 var(--f-mono);letter-spacing:.06em;text-transform:uppercase;color:var(--muted);text-align:left;padding:10px 14px;background:var(--sunken);border-bottom:1px solid var(--line);white-space:nowrap}
+td{padding:11px 14px;border-bottom:1px solid var(--line);vertical-align:top;font-variant-numeric:tabular-nums}
+tr:last-child td{border-bottom:0}
+td.num,th.num{text-align:right;white-space:nowrap}
+
+.rows{background:var(--surface);border:1px solid var(--line);border-radius:var(--radius);overflow:hidden}
+.rows-head,.row>summary{display:grid;grid-template-columns:var(--cols,88px minmax(0,2fr) minmax(0,1fr) minmax(0,1.4fr));gap:16px;padding:12px 16px;align-items:start}
+.rows-head{font:600 11px/1.2 var(--f-mono);letter-spacing:.06em;text-transform:uppercase;color:var(--muted);background:var(--sunken);border-bottom:1px solid var(--line)}
+.row{border-bottom:1px solid var(--line)}
+.row:last-child{border-bottom:0}
+.row>summary{cursor:pointer;list-style:none}
+.row>summary::-webkit-details-marker{display:none}
+.row>summary>*{min-width:0}
+.row>summary>:first-child::before{content:"▸";display:inline-block;margin-right:6px;color:var(--muted);font-size:11px;transition:transform .15s}
+.row[open]>summary>:first-child::before{transform:rotate(90deg)}
+.row-detail{padding:4px 16px 18px;display:grid;grid-template-columns:repeat(auto-fit,minmax(min(260px,100%),1fr));gap:14px 28px}
+.row-detail dl{margin:0;display:grid;gap:10px;align-content:start}
+.row-detail dd{margin:2px 0 0;font-size:13.5px;overflow-wrap:anywhere}
+.row.closed>summary{color:var(--muted)}
+
+.bar{display:flex;flex-wrap:wrap;gap:10px;align-items:center}
+input,select,button{font:inherit;font-size:14px;color:var(--fg);background:var(--surface);border:1px solid var(--control);border-radius:8px;padding:8px 10px;min-width:0}
+button{cursor:pointer}
+button.primary{background:var(--accent);border-color:var(--accent);color:var(--on-accent);font-weight:600}
+.chip{border:1px solid var(--line);border-radius:999px;padding:5px 11px;font-size:13px;font-weight:500}
+.chip[aria-pressed="true"]{background:var(--accent-soft);border-color:var(--accent);color:var(--accent-ink)}
+.count{margin-left:auto;font:13px var(--f-mono);color:var(--muted)}
+
+footer{font-size:12.5px;color:var(--muted);display:grid;gap:4px;border-top:1px solid var(--line);padding-top:16px}
+
+@media (max-width:720px){.rows-head{display:none}.row>summary{grid-template-columns:minmax(0,1fr);gap:6px}}
+@media (hover:hover) and (pointer:fine){tbody tr:hover td,.row>summary:hover{background:var(--sunken)}button:hover{border-color:var(--accent)}}
+@media (prefers-reduced-motion:reduce){*{transition:none!important;animation:none!important}}
+</style>
+</head>
+<body>
+<main class="wrap">
+  <header>
+    <div class="eyebrow">Specimen · artifacts-design</div>
+    <h1>Starter primitives</h1>
+    <p class="lede">Replace this body with the artifact's own composition. Keep the tokens and the primitives the page needs, and delete the rest.</p>
+  </header>
+
+  <section class="strip" aria-label="Summary">
+    <div class="stat"><b>34</b><span>Records</span></div>
+    <div class="stat"><b>23</b><span>Open</span></div>
+    <div class="stat"><b>4</b><span>Need attention</span></div>
+  </section>
+
+  <section>
+    <h2>Status and data</h2>
+    <div class="bar">
+      <input id="q" type="search" placeholder="Search" aria-label="Search">
+      <button class="chip" aria-pressed="true">All</button>
+      <button class="chip" aria-pressed="false">Open</button>
+      <span class="count">3 of 34</span>
+    </div>
+    <div class="table">
+      <table>
+        <thead><tr><th>Item</th><th>State</th><th class="num">Value</th></tr></thead>
+        <tbody>
+          <tr><td>Accent</td><td><span class="pill accent">In review</span></td><td class="num">1,204</td></tr>
+          <tr><td>Success</td><td><span class="pill ok">Passed</span></td><td class="num">98.6 %</td></tr>
+          <tr><td>Warning and error</td><td><span class="pill warn">Pending</span> <span class="pill bad">Failed</span></td><td class="num">−12</td></tr>
+        </tbody>
+      </table>
+    </div>
+  </section>
+
+  <section>
+    <h2>Expandable records</h2>
+    <div class="rows">
+      <div class="rows-head" aria-hidden="true"><span>ID</span><span>Title</span><span>Group</span><span>State</span></div>
+      <details class="row">
+        <summary><b>#2088</b><span>Parallelize search and listing data fetching</span><span>Performance</span><span class="pills"><span class="pill">Draft</span><span class="pill ok">Build passed</span></span></summary>
+        <div class="row-detail">
+          <dl><dt class="label">Next step</dt><dd>Keep separate and wait for team review.</dd></dl>
+          <dl><dt class="label">Branch</dt><dd><code>refactor/search-plp-parallel-fetch</code></dd></dl>
+        </div>
+      </details>
+      <details class="row closed">
+        <summary><b>#2086</b><span>Temporary workspace configuration</span><span>Temporary</span><span class="pills"><span class="pill">Closed</span></span></summary>
+        <div class="row-detail"><dl><dt class="label">Reason</dt><dd>Closed without merge by the owner.</dd></dl></div>
+      </details>
+    </div>
+  </section>
+
+  <section class="prose">
+    <h2>Reading text</h2>
+    <p>Body copy stays near 68 characters per line. Use <code>code</code> for identifiers and the <span class="label">label</span> style for metadata.</p>
+    <div class="note"><b>Note.</b><p>A note marks one consequential statement. It is not a container for ordinary paragraphs.</p></div>
+  </section>
+
+  <footer><span>Source and date of the data go here.</span></footer>
+</main>
+</body>
+</html>

package/src/skills.js

@@ -67,12 +67,27 @@ async function fullFiles(directory, prefix = '') {
     }
     return files;
 }
+function isText(content) {
+    if (content.includes(0))
+        return false;
+    try {
+        new TextDecoder('utf-8', { fatal: true }).decode(content);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function labeledContent(skills, full) {
     const chunks = [];
     for (const skill of skills) {
         const files = full ? ['SKILL.md', ...(await fullFiles(skill.directory)).filter((path) => path !== 'SKILL.md')] : ['SKILL.md'];
         for (const path of files) {
             const content = path === 'SKILL.md' ? skill.skillText : await readFile(join(skill.directory, path));
+            if (!isText(content)) {
+                chunks.push(Buffer.from(`=== ${skill.name}/${path} (binary, ${content.length} bytes) ===\n`));
+                continue;
+            }
             chunks.push(Buffer.from(`=== ${skill.name}/${path} ===\n`), content);
             if (content.at(-1) !== 10)
                 chunks.push(Buffer.from('\n'));