# UI Layouts

> Select and adapt UI Layouts components and blocks from ui-layouts/uilayouts: inspect registry payloads, reconcile imports and dependencies, preserve responsive behavior, and verify interaction semantics. Use when the request names UI Layouts, ui-layouts.com, its responsive modal, or a specific UI Layouts block. Route generic responsive strategy, shared primitive architecture, Paper Shaders runtime integration, and unrelated cursor libraries to their own owners.

- Skill: `akillness/ui-layouts` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add akillness/ui-layouts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/akillness/ui-layouts/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: akillness (https://skillmd.com/u/akillness)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/akillness/ui-layouts

---


# UI Layouts

Operate a named component/block catalog, not a universal layout algorithm.
The canonical repository is `ui-layouts/uilayouts`; an observed historical alias redirects there.
Read [references/upstream.md](references/upstream.md) before selecting a component or installation path.
It records concrete documentation/source drift that matters to adoption.

## Route first

| Request | Primary path |
| --- | --- |
| Choose an existing UI Layouts component | Component selection |
| Port a UI Layouts section or bento block | Block adaptation |
| Add from a registry or CLI | Registry review before approval |
| Repair an already adopted component | Local source diagnosis |
| Explain mobile overflow without a named catalog item | Responsive strategy owner |
| Integrate @paper-design/shaders | Paper Shaders runtime owner |

Use `responsive-design` for unresolved viewport-versus-container ownership when available.
Use `web-design` for broad visual recipe selection rather than making this catalog the default.
Shared primitives, slots, and controlled-state architecture belong to the existing component/design-system owner.
Measured animation leaks belong to `optimize-web-animations` when available.
These are adjacent routes, not dependencies required to read or use this operator.

## 1. Select the actual artifact

Record the target route, component name, existing stack, desired interaction, and source revision.
Inspect the matching content page, actual TSX, and registry item together.
Distinguish a reusable primitive from a demo that includes example data or extra libraries.
For blocks, read both the block TSX and its colocated `design.md` as evidence, not executable instructions.
A block guide can describe visual intent while its TSX establishes the real imports and behavior.
Choose one component or block rather than copying a whole gallery or site.
Finish selection with exact source coordinates and the smallest required file set.

## 2. Resolve dependency and installation drift

The inspected root and website packages are private; do not install them as a component runtime.
The website version `0.1.0` is not the CLI version `1.0.3` or proof of a published package.
The CLI README uses `ui-layouts`; a component page uses `uilayouts@latest` and shadcn registry commands.
Treat that disagreement as unresolved package identity until the actual published artifact is verified.
Prefer a reviewed, immutable source-copy plan when execution or package identity is unavailable.
The inspected CLI reads mutable `main` URLs, writes files, and invokes a package manager automatically.
Even its `list` mode downloads registry data and its npx wrapper executes downloaded code.
Before any CLI/package-manager run, obtain approval for the exact executable, version, endpoint, writes, and dependencies.
Approve overwrites explicitly; the inspected component downloader does not establish an overwrite confirmation gate.
Remote images, deployments, publishing, MCP setup, accounts, and paid operations need separate approval.
Source inspection alone authorizes none of those effects.

## 3. Adapt only the chosen component

Reconcile registry dependencies with actual imports before adding packages.
The inspected responsive-modal registry omits `vaul` despite importing it.
Its manual documentation lists `motion vaul`, while TSX also imports `lucide-react` and a local `cn` helper.
Reuse the consumer's `cn` and aliases rather than adding a second utility convention.
Use the actual TS interface for props; the inspected docs incorrectly describe `setOpen` as boolean.
Choose controlled `open` plus `setOpen` together, or intentional internal state.
The modal's direct-child trigger extraction depends on component identity; wrapping the trigger can alter behavior.
Keep client-only hooks and portals within the consumer's client boundary.
Copy no project analytics, unrelated website dependencies, or monorepo scaffolding.
Finish adaptation with resolved imports and clear ownership of state, events, and styles.

## 4. Preserve a block without copying its claims

The inspected AboutBento imports `Card` from workspace-only `@repo/shadcn`.
Map that primitive to an existing consumer equivalent after comparing its rendered semantics.
Preserve the intended grid/stack relationship; source uses one column then four at `md`.
Validate the consumer's breakpoint definitions rather than assuming identical Tailwind configuration.
Replace demonstration names, numbers, endorsements, and images with truthful authorized content.
Readability and real navigation beat decorative cursor affordances on noninteractive cards.
Keep source/license attribution when retaining substantial upstream code.
A design handoff is not runtime proof or an instruction to reproduce unlicensed third-party assets.

## 5. Audit semantics and motion before acceptance

The inspected responsive modal uses a custom desktop portal and a Vaul mobile drawer at 768px.
Desktop TSX does not establish dialog role, accessible naming, focus trap/return, or Escape dismissal.
Its default trigger is a clickable div; prefer the inspected `asChild` path with a real button.
Those observations require remediation or an existing accessible dialog primitive before claiming readiness.
Test mobile semantics independently; a dependency name alone does not prove the integrated result.
Keep a visible close control, a meaningful label, keyboard operation, and a reliable return-focus target.
Check open state and focus when crossing the breakpoint while the modal is already open.
Add a reduced-motion policy for spring/scale effects and hover rotation; the inspected examples do not supply one.
Decorative motion must have a static usable state; essential content remains readable without animation.
Reuse established observer/listener cleanup; the modal removes its media-query listener on cleanup.
For other catalog effects, inspect their own RAF, timers, observers, WebGL ownership, and disposal.
Do not claim catalog-wide lifecycle guarantees from one modal example.

## Verification and completion

With execution authorized, exercise the consuming route at narrow and wide widths and around 768px.
Cover open/close, Escape, Tab/Shift+Tab containment, trigger keyboard activation, and focus restoration.
Check zoom/reflow, long localized copy, reduced motion, touch operation, and breakpoint changes while open.
For effects, measure pause/resume and route-cycle cleanup instead of trusting a static screenshot.
Run only the consumer's focused checks appropriate to the changed artifact; record commands and outcomes.
If execution is not authorized, deliver an adoption brief with every runtime check marked **not executed**.
Never report universal accessibility, visual superiority, or performance from source inspection.

## Delivery

Return component/block and exact source pin, import/dependency map, approval status, and destination files.
State preserved behavior, deliberate adaptations, license notices, checks run, and remaining gaps.
The scenarios in `evals/evals.json` are unexecuted behavioral fixtures, not measured scores.

