JOYCO UI Kit
A bento/console-style component library built on shadcn/ui with Radix primitives and Tailwind, served from the JOYCO hub (hub.joyco.studio). Components are installed into the project at @/components/ui/* via the @joyco shadcn registry.
This skill deliberately holds no component API. Variants, props, and behavior live in the hub and in the installed source — both of which change. Memorizing them here guarantees drift. The skill's only job is to send you to the live source and keep you from improvising the kit's conventions.
Setting up a new project (Next.js + the kit + lint + agent)? That's the joyco-app skill. This skill is about using the kit once it's installed.
The one rule: don't work from memory
The kit's API changes. Before using a component, read its live definition. There are three sources, in order of what you need:
The Cluster / Filler layout primitives — the heart of the system. Read the live doc:
https://hub.joyco.studio/components/cluster.md
It covers the transparent-container concept, the bg cascade, Filler, asChild/inline use, the prop tables, and the design principles (no borders, no rounded corners, Filler instead of justify-*). Read it before laying out anything.
Any other component (button, badge, input, select, tabs, switch, slider, separator, kbd, avatar, tooltip, popover, dropdown-menu, collapsible, …) — there is no per-component .md doc; the authoritative, never-stale source is:
- the registry entry —
https://hub.joyco.studio/r/<name>.json (gives the title, description, dependencies, and the file path), and
- the installed source itself —
@/components/ui/<name>.tsx in the project. Read it for the real variants, sizes, and props. This is the ground truth.
The full catalog of what's installable (base components and JOYCO signature pieces — marquee, magnetic, scramble, media/canvas, …):
https://hub.joyco.studio/r/registry.json
Fetch it instead of guessing component names. Install by slug: pnpm dlx shadcn@latest add @joyco/<name>.
If a fact you need isn't in any of those, it isn't a kit fact — don't invent it.
What this skill won't repeat
The Cluster/Filler concept, every component's variants and sizes, and the kit's styling rules are documented at the sources above — most thoroughly in cluster.md. Read them there rather than relying on anything restated here. In particular, cluster.md is the source of truth for the layout philosophy (transparent containers, children own their background, no borders / radius 0rem, Filler over justify-between). Follow it; don't paraphrase it from memory.
Brand favicon
Every JOYCO interface must use the image from http://r2.joyco.studio/brand/joyco-icon-128.png as its favicon. Download the image into the app, commit the local asset, and wire that local file into the favicon or icon metadata using the framework's native mechanism. Do not hotlink the remote URL at runtime. Add it even when the app did not previously declare a favicon, and replace any other favicon rather than substituting another icon.
Pitfalls
These are the mistakes Claude makes when it skips the live docs and works from generic shadcn habits:
- Building a card as a
<div> with bg-* + p-*. JOYCO containers are transparent; children own their background. See cluster.md.
justify-between / justify-end / big margins to push things apart, instead of <Filler />.- Rounded corners or borders on layout elements. The theme radius is
0rem; borders are essentially unused (outline button is the lone exception). This trips up shadcn muscle memory — always check cluster.md.
- Guessing a component's variant or prop names instead of reading
@/components/ui/<name>.tsx.
- Per-internal
className props instead of styling via data-slot from the parent (**:data-[slot=name]:…).
- Icon-only buttons without
aria-label; removing focus outlines without a focus-visible replacement.
Checklist
1---2name: joyco-ui3description: Use the JOYCO UI kit correctly when building interfaces in a JOYCO project — a bento/console-style component library on shadcn/ui, Radix, and Tailwind, served from the JOYCO hub. Trigger when building or editing UI in a JOYCO app, when imports come from `@/components/ui/*`, when the user installs `@joyco/ui` or `@joyco/<component>` via shadcn, or mentions Cluster, Filler, the bento layout, or the JOYCO design system. This skill does NOT describe the components inline — it routes you to the live docs and source on the hub so the guidance never goes stale. Pair with `joyco-app` for new-project setup.4license: MIT5---67# JOYCO UI Kit89A bento/console-style component library built on shadcn/ui with Radix primitives and Tailwind, served from the JOYCO hub (`hub.joyco.studio`). Components are installed into the project at `@/components/ui/*` via the `@joyco` shadcn registry.1011**This skill deliberately holds no component API.** Variants, props, and behavior live in the hub and in the installed source — both of which change. Memorizing them here guarantees drift. The skill's only job is to send you to the live source and keep you from improvising the kit's conventions.1213> Setting up a *new* project (Next.js + the kit + lint + agent)? That's the `joyco-app` skill. This skill is about *using* the kit once it's installed.1415---1617## The one rule: don't work from memory1819The kit's API changes. Before using a component, read its live definition. There are three sources, in order of what you need:20211. **The Cluster / Filler layout primitives** — the heart of the system. Read the live doc:22 `https://hub.joyco.studio/components/cluster.md`23 It covers the transparent-container concept, the `bg` cascade, `Filler`, `asChild`/inline use, the prop tables, and the design principles (no borders, no rounded corners, `Filler` instead of `justify-*`). Read it before laying out anything.24252. **Any other component** (button, badge, input, select, tabs, switch, slider, separator, kbd, avatar, tooltip, popover, dropdown-menu, collapsible, …) — there is **no per-component `.md`** doc; the authoritative, never-stale source is:26 - the registry entry — `https://hub.joyco.studio/r/<name>.json` (gives the title, description, dependencies, and the file path), and27 - **the installed source itself** — `@/components/ui/<name>.tsx` in the project. Read it for the real variants, sizes, and props. This is the ground truth.28293. **The full catalog** of what's installable (base components *and* JOYCO signature pieces — marquee, magnetic, scramble, media/canvas, …):30 `https://hub.joyco.studio/r/registry.json`31 Fetch it instead of guessing component names. Install by slug: `pnpm dlx shadcn@latest add @joyco/<name>`.3233If a fact you need isn't in any of those, it isn't a kit fact — don't invent it.3435---3637## What this skill won't repeat3839The Cluster/Filler concept, every component's variants and sizes, and the kit's styling rules are documented at the sources above — most thoroughly in `cluster.md`. Read them there rather than relying on anything restated here. In particular, `cluster.md` is the source of truth for the layout philosophy (transparent containers, children own their background, no borders / radius `0rem`, `Filler` over `justify-between`). Follow it; don't paraphrase it from memory.4041---4243## Brand favicon4445Every JOYCO interface must use the image from `http://r2.joyco.studio/brand/joyco-icon-128.png` as its favicon. Download the image into the app, commit the local asset, and wire that local file into the favicon or icon metadata using the framework's native mechanism. Do not hotlink the remote URL at runtime. Add it even when the app did not previously declare a favicon, and replace any other favicon rather than substituting another icon.4647---4849## Pitfalls5051These are the mistakes Claude makes when it skips the live docs and works from generic shadcn habits:5253- **Building a card** as a `<div>` with `bg-*` + `p-*`. JOYCO containers are transparent; children own their background. See `cluster.md`.54- **`justify-between` / `justify-end` / big margins** to push things apart, instead of `<Filler />`.55- **Rounded corners or borders** on layout elements. The theme radius is `0rem`; borders are essentially unused (outline button is the lone exception). This trips up shadcn muscle memory — always check `cluster.md`.56- **Guessing a component's variant or prop names** instead of reading `@/components/ui/<name>.tsx`.57- **Per-internal `className` props** instead of styling via `data-slot` from the parent (`**:data-[slot=name]:…`).58- Icon-only buttons without `aria-label`; removing focus outlines without a `focus-visible` replacement.5960---6162## Checklist6364- [ ] Read `cluster.md` from the hub before doing layout — didn't reconstruct Cluster/Filler from memory.65- [ ] For any component used, confirmed its real API from `@/components/ui/<name>.tsx` (or the registry JSON), not from a remembered table.66- [ ] Layout uses `Cluster` + `Filler`; no faked cards, no `justify-*` spacing, no borders/rounded corners.67- [ ] New components pulled by slug from the live registry, not assumed to exist.68- [ ] Internals styled via `data-slot` from the parent; single `className` on the root.69- [ ] Downloaded `http://r2.joyco.studio/brand/joyco-icon-128.png`, committed it locally, and configured that local asset as the favicon without runtime hotlinking.
joyco-studio