agentleFS
notum-cznotum-cz/strapi-next-monorepo-starter/.claude/skills/add-ui-component/SKILL.md

add-ui-component

Skill316 starsChanged 5 months agoMITView on GitHub

Use when adding a generic UI primitive, elementary block, or form field in `apps/ui` — e.g. "new ui component", "add component", "create react component", "new shadcn component", "add form field". Not for Strapi page-builder sections; use `create-content-component`.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 0 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Default to elementary/ for app reusables, ui/ only for true primitives.

    line 36
  2. Very specific:

    Default to a server component.

    line 40
  3. Very specific:

    Keep "use client" on interactive primitives.

    line 55
  4. Very specific:

    If the file already exists in components/ui/, diff and merge — don't overwrite.

    line 56
  5. Very specific:

    Add a section wrapper at apps/ui/src/app/[locale]/dev/showcase/components/sections/<Name>Section.tsx rendering the component's …

    line 125
  6. Very specific:

    Add an entry in apps/ui/src/app/[locale]/dev/showcase/showcaseItems.tsx with kind: "atomic", an id, label, and description.

    line 126

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Add a UI Component

Scaffold a React component in apps/ui/src/components/ to the starter's conventions. shadcn/ui is configured in apps/ui/components.json (new-york, slate, RSC, lucide, cn() from @/lib/styles). Background: apps/docs/docs/ui/project-structure.md, apps/docs/docs/design-system/overview.md.

Phase 1 — Pick the category

CategoryWhenFile name
ui/shadcn primitives (Button, Input, Dialog) — prefer the CLIkebab-case.tsx
elementary/app-specific reusable blocks (Container, Breadcrumbs, AppLink)PascalCase.tsx
forms/react-hook-form fields, App* prefix, built on ui/formPascalCase.tsx
typography/Heading, Paragraph, LeadPascalCase.tsx
helpers/server/client boundary shimsPascalCase.tsx
layouts/page shells composing sectionsPascalCase.tsx
providers/context / SDK wrappersPascalCase.tsx
page-builder/Strapi sections — stop, use create-content-component—

Default to elementary/ for app reusables, ui/ only for true primitives. Ask if unclear. Match the closest sibling's export style.

Phase 2 — Server vs client

Default to a server component. Add "use client" only for hooks, event handlers, browser APIs, or client-only libraries (react-hook-form, Framer Motion). Form fields are always client; layout shells usually server.

Phase 3 — Scaffold

ui/ primitive — prefer the CLI:

pnpm --filter @repo/ui exec shadcn@latest add <name>

Post-install fixup (review generated files):

  1. cn() import must be @/lib/styles, not the upstream default @/lib/utils — the most common breakage on upgrades.
  2. Radix: both the unified radix-ui and scoped @radix-ui/react-* packages coexist here — match the sibling, don't force-convert.
  3. Tokens: CSS vars live in apps/ui/src/styles/globals.css + packages/design-system/src/theme.css; prefer them over shadcn defaults. No tailwind.config.js — never create one.
  4. Keep "use client" on interactive primitives.
  5. If the file already exists in components/ui/, diff and merge — don't overwrite.

Hand-rolling a ui/ primitive: follow an existing one in apps/ui/src/components/ui/ (forwardRef + cva variants + cn()).

elementary/:

import { cn } from "@/lib/styles"

export function ComponentName({
  children,
  className,
}: {
  readonly children: React.ReactNode
  readonly className?: string
}) {
  return <div className={cn("base-classes", className)}>{children}</div>
}

Ref: Container.tsx, Breadcrumbs.tsx.

forms/ field — App prefix, useFormContext, built on @/components/ui/form:

"use client"

import { useFormContext } from "react-hook-form"

import {
  FormControl,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from "@/components/ui/form"

export function AppFieldName({ name, label }: { name: string; label: string }) {
  const { control } = useFormContext()

  return (
    <FormField
      control={control}
      name={name}
      render={({ field }) => (
        <FormItem>
          <FormLabel>{label}</FormLabel>
          <FormControl>{/* input */}</FormControl>
          <FormMessage />
        </FormItem>
      )}
    />
  )
}

Provider / layout / helper — no fixed template; match the closest sibling.

Phase 4 — Conventions

  • cn() from @/lib/styles for all class merging; @/ alias = apps/ui/src/ (no deep relative imports, no barrel files).
  • Design tokens only (text-primary, bg-secondary, border-input) — no hex. Tailwind v4 (CSS-first config). Lucide icons. Mobile-first (sm:/md:/lg:).
  • forwardRef only for ui/ primitives that need it (Radix composition) — not elsewhere.
  • Wrap full-bleed sections in <Container> from @/components/elementary/Container.

Phase 5 — Showcase (elementary / atomic only)

The starter has no Storybook — the in-app /dev/showcase gallery is its lightweight equivalent (see apps/docs/docs/ui/built-in-pages/showcase.md). When the component is a reusable elementary/atomic primitive, register it there:

  1. Add a section wrapper at apps/ui/src/app/[locale]/dev/showcase/components/sections/<Name>Section.tsx rendering the component's variants/states.
  2. Add an entry in apps/ui/src/app/[locale]/dev/showcase/showcaseItems.tsx with kind: "atomic", an id, label, and description.

(Page-builder sections appear in the same showcase with kind: "component" — handled by create-content-component.)

Phase 6 — Verify

  1. pnpm --filter @repo/ui lint
  2. pnpm --filter @repo/ui exec tsc --noEmit
  3. pnpm --filter @repo/ui dev → render the consumer (or /dev/showcase) → confirm visual output.
  4. Pure logic or a utility hook? Add a *.test.ts next to it — use write-tests.

Notes

  • Page-builder sections live elsewhere — components rendered from Strapi dynamic zones use a different scaffold; switch to create-content-component.
  • shadcn upgrades — re-run the CLI rather than hand-editing, to keep diffs reviewable against upstream. Official refs: docs, components, Tailwind v4, LLM docs.
  • React / Next.js standards — apply the vendored vercel-react-best-practices, next-best-practices, and frontend-design skills (in .agents/skills/) for performance, RSC boundaries, and visual design.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.