# kawaii-shuffle: guide for AI agents

© 2026 Aesthetic Vulpes (github.com/didvc). Code AGPL-3.0-only; sample pictures CC-BY-4.0.

kawaii-shuffle returns an SVG image badge for GitHub profile READMEs and other Markdown. It is configured only by URL path segments. It has no API keys, no POST endpoints, no uploads and no user data.

## Endpoint

```
GET https://readmes.pages.dev/kawaii-shuffle[/<token>[/<token>...]][.svg]
```

- Response: `image/svg+xml`, self-contained (pictures embedded as data URIs).
- Tokens are case-insensitive and order-independent; at most 16 tokens.
- An unknown token returns HTTP 200 with a small error badge and the header `X-Kawaii-Error: unknown option #N`.
- Methods other than GET and HEAD return 405.

## Tokens

### What to show

| Token | Meaning |
|---|---|
| `random` | A random picture on every load (default). |
| `daily` | One picture per day, changing at 00:00 UTC. Cacheable until then. |
| `cycle` | Animated crossfade slideshow of all pooled pictures, in shuffled order. |
| `miko`, `doujin`, `pale`, `hanten`, `jinbei` | Pick pictures by name. One name always shows it; several names form the pool to shuffle. |
| `speed-N` | Seconds per picture in cycle mode, 2 to 30 (default 4). |

### Shape and size

| Token | Meaning |
|---|---|
| `rounded` | Rounded-corner card (default). |
| `rect` | Square corners. |
| `circle` | Circle avatar; forces the square aspect. |
| `polaroid` | Instant-photo frame with a caption. |
| `wide`, `banner`, `square`, `portrait` | Aspect ratio 16:9 (default), 3:1, 1:1 or 3:4. |
| `size-N` | Width in pixels, 64 to 800 (default 400; 200 for square and portrait). |
| `border-N` | Border width in pixels, 0 to 16 (default 0). |

### Look and feel

| Token | Meaning |
|---|---|
| `auto` | Follow the viewer's light or dark preference (default). |
| `light`, `dark` | Force a theme. |
| `transparent` | No background; frame colors still follow the viewer's preference. |
| `accent-RRGGBB` | Border and sparkle color as 3 or 6 hex digits without #, e.g. accent-e91e63. |
| `label`, `nolabel` | Show or hide the picture name (polaroid shows it by default). |
| `sparkles` | Add twinkling sparkles. |

Aki is a Japanese kitsune who lives near a shrine that Aesthetic Vulpes sometimes stops by. She is the little sister of Aesthetic Vulpes's acquaintance.

Available picture names: `miko` (Aki, a fox-eared young woman with orange hair, in a white and red shrine maiden (miko) outfit); `doujin` (Aki, a fox-eared young woman with orange hair, in a dark green kimono with a yellow obi); `pale` (Aki, a fox-eared young woman with orange hair, in a pale mint kimono on a wooden veranda); `hanten` (Aki, a fox-eared young woman with orange hair, in a cozy brown hanten jacket); `jinbei` (Aki, a fox-eared young woman with orange hair, in a light blue summer jinbei).

## Examples

| Goal | URL |
|---|---|
| Random picture, default card | https://readmes.pages.dev/kawaii-shuffle |
| Circle avatar with ring | https://readmes.pages.dev/kawaii-shuffle/circle/border-6 |
| Slideshow polaroid | https://readmes.pages.dev/kawaii-shuffle/cycle/polaroid |
| Picture of the day, dark | https://readmes.pages.dev/kawaii-shuffle/daily/dark |
| Only two pictures, labelled | https://readmes.pages.dev/kawaii-shuffle/miko/jinbei/label |

Embed in Markdown with alt text, for example:

```markdown
![Aki](https://readmes.pages.dev/kawaii-shuffle/polaroid/sparkles)
```

## Caching

- `random` and `cycle`: `Cache-Control: no-store`.
- `daily`: cacheable until 00:00 UTC.
- Single named picture: cacheable for one day.
- GitHub proxies README images (camo). Prefer `cycle` when the user wants every picture to appear.

## Guidance for agents

- Always include meaningful alt text when embedding.
- Do not invent tokens; use only those listed above. Validate by checking for the `X-Kawaii-Error` header.
- The public demo serves only its built-in samples. To show a user's own images, point them to the template repository and self-hosting steps: https://github.com/profile-readme/kawaii-shuffle
- This is a best-effort free demo without warranty. Do not send automated high-volume traffic.

## More

- Human help page and URL builder: https://readmes.pages.dev/kawaii-shuffle/help
- Site overview for LLMs: https://readmes.pages.dev/llms.txt
- Source, license and disclaimer: https://github.com/profile-readme/kawaii-shuffle