Skip to content

ChronicStone/nuxt-ui-tools / .agents/skills/nuxt-ui-tools-playground

nuxt-ui-tools-playground

Verified

Use this skill when adding, restructuring, or validating the nuxt-ui-tools playground examples, shell, navigation, or route-level composition demos.

nuxt-ui-tools Playground

The playground is a maintainer-facing inspection surface. It should make one runtime abstraction or one composition variant easy to find, run, compare, and extend without making the shell part of the behavior under test.

Architecture

The app has three intentionally separate layers:

  • playground/app/layouts/default.vue and empty.vue both mount the shared PlaygroundShell; page layouts no longer invent their own navigation chrome.
  • playground/app/components/playground/ owns reusable shell primitives: PlaygroundShell.vue, PlaygroundPageHeader.vue, PlaygroundSidebar.vue, the recursive tree node, and PlaygroundContent.vue.
  • playground/app/pages/ owns example code, runtime fixtures, runtime controls, and route-level composition decisions. A page must not reimplement playground navigation or testing chrome.

playground/app/app.config.ts contains only the canonical Nuxt UI color baseline. Keep it neutral and monochrome (primary: 'neutral' and neutral: 'zinc'). main.css owns the small canonical token adjustment that makes primary fills true black in light mode and near-white in dark mode; neutral gray remains the secondary surface. Component ui props belong in an example only when the example is explicitly demonstrating a package composition or slot contract; never use app config as a global visual patch.

Navigation registry

The playground is organized as abstraction families with a persistent, collapsible tree navigator:

  • /form/* owns field labs plus form workflows.
  • /table/* owns data-source examples and the nested composition family.
  • /spreadsheet/* owns core flow, reference, and stress/validation groups.

usePlaygroundNavigation.ts is the single hierarchy registry. Each abstraction owns a navigation tree made of group nodes and route nodes. Route nodes declare a stable id, exact path, concise label, useful description, and content mode; group nodes declare children. The shared sidebar renders that tree and expands only the branch relevant to the current route, so large families remain scannable without flattening every example into one dropdown.

Keep variants as separate routes when behavior, schema, or content mode differs. For example, table offset remote, cursor remote, filter rail, staged finance, selection operations, and people directory are independent modules rather than one schema behind a variant toggle. Legacy aliases may redirect to a canonical route when the redirect is explicit and cheap.

Table size is playground testing chrome, not example UI. Every rendered table example binds its root size to usePlaygroundShell().tableSize; the shared page header owns the desktop XS/SM/MD/LG/XL selector and the mobile navigation drawer owns the mobile copy. All table examples default to md. Do not add local size selectors or make an example's concept be "small table" versus "large table". Granular size overrides are appropriate only when the example is explicitly testing that override.

Keep the table canvas edge-aligned inside one NutDataListContent boundary; do not add decorative nested table shells. Selection actions belong in the schema and render through NutDataListSelectionActions, while filter-rail examples use their explicit rail controls.

Page shell and content modes

Wrap normal pages in PlaygroundContent and choose the mode that owns their scroll contract:

<PlaygroundContent mode="document">
  <!-- normal page: this shell content region scrolls -->
</PlaygroundContent>

<PlaygroundContent mode="fixed">
  <!-- full-height composition: the child runtime owns its viewport -->
</PlaygroundContent>

<PlaygroundContent mode="scroll">
  <!-- full-height route with one internal vertical scroll boundary -->
</PlaygroundContent>

<PlaygroundContent mode="canvas">
  <!-- free-form canvas or custom viewport ownership -->
</PlaygroundContent>

document is for forms, indexes, and narrative examples and owns the shell's vertical content scroll. fixed is for table compositions whose runtime owns the available viewport. scroll is for bounded examples such as assembled DataList recipes that intentionally scroll as one page region. canvas is for an example that deliberately manages its own free layout. The browser body must remain fixed to the shell; do not combine a mode with negative margins, a second viewport-sized wrapper, or an implicit 100vh height.

Spreadsheet fullscreen scenarios may keep definePageMeta({ layout: 'empty' }) for route intent, but both playground layouts mount the same PlaygroundShell. The spreadsheet canvas owns the remaining shell viewport (h-full), never the entire browser viewport, so navigation stays consistent across abstractions.

Recipe for a new sample

  1. Choose the owning runtime abstraction and decide whether the sample is a document, fixed, scroll-contained, or canvas route.
  2. Add a focused page module under playground/app/pages/; split variants into separate files when comparing behavior would otherwise require a toggle.
  3. Keep the demonstrated schema, fixture, and runtime calls in the page or an adjacent feature folder under playground/app/components/. Extract shared data only when it makes the example easier to compare, not when it hides the API being assessed.
  4. Add navigation metadata to the relevant abstraction in usePlaygroundNavigation.ts, a concise row to that abstraction's index.vue, and only a high-level abstraction row to pages/index.vue.
  5. Add loading, empty, error, disabled, focus, keyboard, responsive, overflow, and reduced-motion handling when the example exercises those states.
  6. Validate the route in the configured browser at desktop and mobile widths, then run the focused playground typecheck and formatter.

Validation matrix

Before handoff, verify the following for each changed route:

SurfaceDesktopMobile
document pageone document scroll, heading visible, no horizontal overflowreadable line lengths, controls wrap, no clipped labels
fixed compositionshell header plus one runtime viewport, no body scrollcontrols wrap or stack, runtime viewport remains usable
scroll-contained pageexactly one internal scroll boundarytouch scrolling stays inside the intended region
canvas/fullscreenone deliberate canvas boundaryclose/back action remains reachable
navigationactive tree branch, collapse control, keyboard focusdrawer remains reachable; active hierarchy is preserved
color modeneutral contrast in light and darkcontrols retain visible focus and disabled states

Focused commands from the repository root are:

cd playground && bun run typecheck
bunx oxfmt --check playground/app playground/nuxt.config.ts

Use the repository-configured browser skill for visible acceptance. Source inspection or an HTTP 200 response does not prove a route's rendered layout.

Anti-patterns

  • Do not add page-specific playground navigation, duplicate sidebars, or local example switchers; the shared collapsible tree is the navigation chrome.
  • Do not add global ui slot overrides, gradients, broad shadows, or a theme control panel to compensate for a page-level layout problem.
  • Do not use negative viewport margins, nested h-screen/overflow-auto wrappers, or a body scroll plus an unrelated page scroll.
  • Do not wrap every section in UCard, nest bordered cards, or generate generic equal-card grids for route navigation.
  • Do not hide a variant behind a toggle when separate route modules make the behavior easier to assess.
  • Do not move runtime feature code into the shell or a generic playground helper where the example's API usage becomes hard to see.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 321kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall