From 32ef854771c3c2ca21a3d7d979fa49cae9ce7e78 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Fri, 26 Jun 2026 13:45:57 -0500 Subject: [PATCH] docs: expand capsule identicon prototyper guidance (#8665) Reviewed by CTO for PAP-12039. Documentation/catalog-only change with regenerated manifest; focused catalog verification, CI, security scans, and Greptile are green. Co-Authored-By: Paperclip --- .../product/paperclip-capsules/SKILL.md | 5 +- .../references/generator-workflows.md | 39 +--- .../references/identicon-prototyper.md | 213 ++++++++++++++++++ .../skills-catalog/generated/catalog.json | 18 +- 4 files changed, 232 insertions(+), 43 deletions(-) create mode 100644 packages/skills-catalog/catalog/bundled/product/paperclip-capsules/references/identicon-prototyper.md diff --git a/packages/skills-catalog/catalog/bundled/product/paperclip-capsules/SKILL.md b/packages/skills-catalog/catalog/bundled/product/paperclip-capsules/SKILL.md index de2596c12c..059eec505f 100644 --- a/packages/skills-catalog/catalog/bundled/product/paperclip-capsules/SKILL.md +++ b/packages/skills-catalog/catalog/bundled/product/paperclip-capsules/SKILL.md @@ -56,7 +56,7 @@ Use the **hero capsule bank** only for brand hero imagery, feature-video hero sc Use **graphic-generator layouts** when the task asks for capsule graphics such as blend rows, chains, grids, icon marks, or hero compositions. Prefer seeded tools and exportable workflows; read `references/generator-workflows.md`. -Use **seeded identicons/profile pills** when an agent needs a reproducible personal capsule mark. Keep the seed/config with the output. +Use **seeded identicons/profile pills** when an agent needs a reproducible personal capsule mark. Read `references/identicon-prototyper.md` before choosing variants, color schemes, dither algorithms, density, sheen, aurora, mesh, motion, or exports. ## Implementation Workflow @@ -95,4 +95,5 @@ For code changes, include targeted checks that exercise the edited surface. For - `references/individual-status-capsules.md` - product app capsules, heartbeat status capsules, palette caveats, and reduced-motion rules. - `references/hero-capsule-bank.md` - canonical hero-bank geometry, palette, grain, wave, crop, and rendering checklist. -- `references/generator-workflows.md` - website generator, external graphic-generator, and seeded identicon/profile-pill workflows. +- `references/generator-workflows.md` - website generator and external graphic-generator workflows. +- `references/identicon-prototyper.md` - deterministic profile-pill variants, color schemes, dither algorithms, density behavior, motion, export/share controls, and recommended combinations. diff --git a/packages/skills-catalog/catalog/bundled/product/paperclip-capsules/references/generator-workflows.md b/packages/skills-catalog/catalog/bundled/product/paperclip-capsules/references/generator-workflows.md index 958b6bc62f..4a366c6f48 100644 --- a/packages/skills-catalog/catalog/bundled/product/paperclip-capsules/references/generator-workflows.md +++ b/packages/skills-catalog/catalog/bundled/product/paperclip-capsules/references/generator-workflows.md @@ -21,7 +21,7 @@ The mirrored contract below was source-mined from the external prototype at comm | Need | Preferred workflow | | --- | --- | | Canonical hero brand image | Hero capsule bank reference | -| One agent's profile mark | Seeded identicon/profile-pill prototype | +| One agent's profile mark | Seeded identicon/profile-pill prototype; read `identicon-prototyper.md` | | Repeatable marketing motif | External graphic-generator with explicit seed | | Quick public-doc example | Website embedded generator | | Product UI state | Existing `AgentCapsule` and status helpers | @@ -88,40 +88,7 @@ Palette caution: ## Deterministic Identicon / Profile Pill -Use this when generating a reproducible capsule identity for one agent. - -Determinism key: - -```txt -seed + variant + density + theme -``` - -Variant families: - -- Gradient: `Smooth`, `Soft Sheen`, `Mesh`, `Aurora` -- Dither: `Floyd-Steinberg`, `Atkinson`, `Jarvis-Judice-Ninke`, `Bayer 4x4`, `Bayer 8x8`, `Blue Noise` - -Color spaces and themes: - -- Color spaces: `hsl`, `oklch` -- Themes: `charcoal`, `paper`, `ink` -- Gradient angle can be seeded or manually overridden. - -Export/share affordances: - -- SVG -- PNG -- data URI -- React snippet -- standalone card view -- URL hash restore -- clipboard sharing - -Smoke checks to perform when using the prototype: - -- Same seed/config produces the same output. -- Changing the seed visibly changes the output. -- SVG or PNG export is non-empty and inspectable. +Use `identicon-prototyper.md` when generating a reproducible capsule identity for one agent. That reference carries the detailed variant ids, HSL/OKLCH color schemes, dither algorithms, density/tone behavior, motion, share/export controls, and recommended combinations from the PAP-11825 prototype. ## Artifact Record Template @@ -136,7 +103,9 @@ Capsule artifact - Seed: - Template / variant: - Palette / theme: +- Color space / color scheme: - Density / count / dimensions: +- Motion / gradient angle: - Output: SVG | PNG | HTML | MP4 | WebM - Divergence from canonical Paperclip rendering: ``` diff --git a/packages/skills-catalog/catalog/bundled/product/paperclip-capsules/references/identicon-prototyper.md b/packages/skills-catalog/catalog/bundled/product/paperclip-capsules/references/identicon-prototyper.md new file mode 100644 index 0000000000..c2dbba29d9 --- /dev/null +++ b/packages/skills-catalog/catalog/bundled/product/paperclip-capsules/references/identicon-prototyper.md @@ -0,0 +1,213 @@ +# Identicon Prototyper + +Use this reference when generating or reviewing deterministic Paperclip capsule identicons/profile pills. Prototype source paths, when the Paperclip content repository is available: + +- `paperclip-content/design/PAP-11825/paperclip-capsule-identicon-prototyper/README.md` +- `paperclip-content/design/PAP-11825/paperclip-capsule-identicon-prototyper/src/identicon.ts` +- `paperclip-content/design/PAP-11825/paperclip-capsule-identicon-prototyper/src/App.tsx` + +These are individual agent marks. They do not replace product UI status capsules or the canonical hero capsule bank. + +## Determinism Contract + +The renderer scopes deterministic output by: + +```txt +normalized seed + variant + density + theme +``` + +Additional options such as color space, color scheme, motion, and manual angle affect the rendered SVG and must still be recorded for reproducibility. + +Default app state: + +- Seed: `paperclip capsule bank` +- Variant: `gradient-smooth` +- Size control: `48` in the UI; renderer often uses `512` for the primary preview and `256` for samples. +- Density: `56` +- Theme: `charcoal` +- Color space/scheme: `oklch` / `Golden` +- Angle: seeded auto angle unless manually set. +- Motion: on. + +Geometry: + +- SVG viewBox: `0 0 120 292` +- Capsule body: `x=18`, `y=16`, `w=84`, `h=248`, `rx=42` +- Output width is approximately `size * 0.43`; output height is `size`. +- Capsule SVG includes `data-capsule="individual"` and an agent-oriented aria label. + +## Variants + +Gradient variants use smooth color only, not dot or stripe patterns: + +| Variant id | UI label | Use | +| --- | --- | --- | +| `gradient-smooth` | Smooth | Clean two-tone linear gradient. | +| `gradient-soft` | Sheen | Linear gradient plus a soft radial white highlight near the top. | +| `gradient-mesh` | Mesh | Base gradient plus overlapping seeded radial color blobs. | +| `gradient-aurora` | Aurora | Multi-stop diagonal ribbon using three hues plus a broad soft band. | + +Dither variants quantize the gradient ramp and emit one SVG path per tone level: + +| Variant id | UI label | Algorithm | +| --- | --- | --- | +| `dither-floyd` | Floyd | Floyd-Steinberg error diffusion; compact classic grain. | +| `dither-atkinson` | Atkinson | Atkinson error diffusion; crisp Mac-era contrast. | +| `dither-jjn` | JJN | Jarvis-Judice-Ninke wide-kernel diffusion; smoother photographic grain. | +| `dither-bayer4` | Bayer 4 | Ordered dithering with a 4x4 Bayer matrix. | +| `dither-bayer8` | Bayer 8 | Ordered dithering with a recursively built 8x8 Bayer matrix. | +| `dither-bluenoise` | Blue Noise | Hash-based void-and-cluster-style threshold mask; avoids visible grid structure. | + +## Color Systems + +Supported color spaces: + +- `hsl` +- `oklch` + +HSL color schemes: + +- `Triadic` +- `Complement` +- `Analogous` +- `Mono` +- `Split` +- `Tetrad` + +OKLCH color schemes: + +- `Mono` +- `Triadic` +- `Golden` +- `Complement` +- `Analogous` +- `Split` +- `Tetrad` +- `Warm-Cool` +- `Vivid` +- `Pastel` +- `Cinema` +- `Sunset` +- `Earth` + +Scheme behavior: + +- HSL defaults to `Triadic`. +- OKLCH defaults to `Golden`. +- OKLCH `Pastel` lowers chroma and raises lightness. +- OKLCH `Earth` uses lower chroma. +- OKLCH `Vivid` uses higher chroma. +- OKLCH `Cinema`, `Sunset`, and `Earth` intentionally bias lightness/hue for more authored looks. +- Manual angle is `0..360`; auto angle is seeded and normally falls in a diagonal range. + +## Density And Dither Behavior + +UI density presets are `32`, `56`, and `80`, but the renderer accepts numeric density. + +Dither tone levels: + +- Density `< 45`: 2 tones +- Density `45..67`: 3 tones +- Density `>= 68`: 4 tones + +Dither grid: + +- Column count is clamped from roughly `size / 8`, with a minimum of `14` and maximum of `34`. +- Row count follows capsule height/cell width so the cells stay proportional. +- Error diffusion kernels: + - Floyd-Steinberg divisor `16` + - Atkinson divisor `8` + - Jarvis-Judice-Ninke divisor `48` +- Ordered dithers shift the target ramp by threshold before rounding to the nearest tone. + +Use lower density for bolder two-tone marks, mid density for readable profile icons, and high density for richer dither studies. Avoid using dither algorithms for product status indicators; those are a different capsule family. + +## Recommended Combinations + +The prototype's study sections provide known-good pairings: + +- Smooth gradient + OKLCH `Golden` +- Soft sheen + OKLCH `Sunset` +- Mesh gradient + OKLCH `Vivid` +- Aurora gradient + OKLCH `Cinema` +- Gradient mix + HSL `Triadic` +- Floyd-Steinberg + OKLCH `Golden` +- Atkinson + OKLCH `Sunset` +- JJN + OKLCH `Earth` +- Bayer 4 or Bayer 8 + HSL `Complement` +- Blue noise + OKLCH `Vivid` +- Dither mix + OKLCH `Cinema` + +Use these combinations first when a prompt asks for sophisticated capsule marks. Explore other schemes only when the request is explicitly exploratory. + +## Themes, Motion, And Randomization + +Themes: + +- `charcoal`: dark brand lab setting with parchment ink. +- `paper`: white/paper setting with black ink. +- `ink`: near-black setting with white ink. + +Motion: + +- Motion adds a subtle vertical SVG `animateTransform` translate wave: `0 -3; 0 3; 0 -3` over `4s`, repeating indefinitely. +- Turn motion off for static exports, grid previews, and reduced-motion contexts. +- Keyboard `Space` replays motion in the prototype. + +Randomize behavior: + +- Randomizes style, color space/scheme, gradient angle, density, motion, and seed. +- Keeps Size and Theme stable. +- Seed words include `atlas`, `budget`, `capsule`, `delta`, `forge`, `governance`, `hermes`, `ledger`, `signal`, and `thread`. + +## Export And Share + +Supported actions: + +- Copy SVG +- Download SVG +- Download PNG +- Copy data URI +- Copy React snippet +- Share standalone card URL +- Restore settings from URL hash + +URL hash fields: + +- `s`: seed +- `v`: variant id +- `z`: UI size +- `d`: density +- `t`: theme +- `c`: color space +- `p`: color scheme +- `a`: manual angle, omitted for seeded auto angle +- `m`: motion, `1` or `0` + +When attaching an identicon artifact, record at least: + +```md +Capsule identicon + +- Seed: +- Variant id: +- Theme: +- Color space / scheme: +- Density: +- Size / output dimensions: +- Motion: +- Angle: seeded auto | +- Export: SVG | PNG | data URI | React snippet | card URL +- Source: PAP-11825 identicon prototyper +``` + +## Smoke Checks + +Before treating an identicon artifact as complete: + +- Same seed and settings produce the same SVG. +- Changing the seed changes the SVG. +- All selected variant ids render nonblank SVG. +- SVG and PNG exports are non-empty and inspectable. +- Shared URL hash restores the intended seed, variant, density, theme, color space, color scheme, angle, and motion. +- Motion can be turned off for static/reduced-motion delivery. diff --git a/packages/skills-catalog/generated/catalog.json b/packages/skills-catalog/generated/catalog.json index aaf0e7aa65..7acb6fca6d 100644 --- a/packages/skills-catalog/generated/catalog.json +++ b/packages/skills-catalog/generated/catalog.json @@ -2,7 +2,7 @@ "schemaVersion": 1, "packageName": "@paperclipai/skills-catalog", "packageVersion": "0.3.1", - "generatedAt": "2026-06-26T10:57:05.518Z", + "generatedAt": "2026-06-26T18:26:43.763Z", "skills": [ { "id": "paperclipai:bundled:docs:doc-maintenance", @@ -140,14 +140,14 @@ { "path": "SKILL.md", "kind": "skill", - "sizeBytes": 5657, - "sha256": "fdc53ec7e35fc49d6c9f909a4a5c5a6da1563c6d2ab0b1e1a15c524bd890211b" + "sizeBytes": 5930, + "sha256": "eda40e8f29cae07c2ce8ad1cef3406eae243dbbf52069a85cfb56fe7999a25ff" }, { "path": "references/generator-workflows.md", "kind": "reference", - "sizeBytes": 4753, - "sha256": "26f2eb9b58187351cc064f9af02c2e75f9c9512d0f5f5b80c8a9079019a48ec7" + "sizeBytes": 4356, + "sha256": "b5f72e5b6683e8f93f2d852e84c2cc19e6ab438b250bf777dfb2480dd4f6e1b6" }, { "path": "references/hero-capsule-bank.md", @@ -155,6 +155,12 @@ "sizeBytes": 5981, "sha256": "ec3d34113aa7bb527560d1eb4d8ab7667c73e18284c85a2019122743a767525a" }, + { + "path": "references/identicon-prototyper.md", + "kind": "reference", + "sizeBytes": 6669, + "sha256": "0b19419efa1396a402097decabe24ea9ae649678569449c8ce855e0678df6bfe" + }, { "path": "references/individual-status-capsules.md", "kind": "reference", @@ -162,7 +168,7 @@ "sha256": "be1f2eccf96b4d2deefe45b3bc1dd0a3597278472c2ffedadc43c57161e9103d" } ], - "contentHash": "sha256:1a573063759019928d591f29ad1c32029939058ec652880c7f41c58c7ebe0f4e" + "contentHash": "sha256:e8f502f9556103bd575bb664a9d21b1004869990802e639a188a720012116909" }, { "id": "paperclipai:bundled:product:wireframe",