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 <noreply@paperclip.ing>
This commit is contained in:
Dotta
GitHub
parent
ccfd52bd24
commit
32ef854771
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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 | <degrees>
|
||||
- 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.
|
||||
|
|
@ -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",
|
||||
|
|
|
|||
Loading…
Reference in New Issue