Skip to content

LiorCohen/sdd / plugin/fullstack-typescript/skills/components/frontend/frontend-standards

frontend-standards

Verified

MVVM architecture standards for React/TypeScript frontends with TanStack ecosystem, TailwindCSS, and Shadcn UI.

FileKindSize
SKILL.mdskill md12.4 KB
resources/mvvm-patterns.mdmarkdown5.4 KB
resources/shadcn.mdmarkdown6.2 KB
resources/tailwind.mdmarkdown4.0 KB
resources/tanstack.mdmarkdown3.8 KB

resources/shadcn.md

View on GitHub
# Shadcn UI

Shadcn UI provides copy-paste React components built on Radix UI primitives, styled with TailwindCSS and `cva`. Components live in `src/components/ui/` and are owned by the project (not an npm dependency).

---

## Component Hierarchy (D6)

When building UI, follow this decision order:

1. **Use Shadcn component if it exists** — check `components/ui/` first
2. **Build on a Radix primitive following Shadcn patterns** — if Shadcn doesn't have it but Radix does
3. **Fully custom component** — only when no Radix primitive applies

Never re-implement what Shadcn or Radix already provides.

---

## Component Anatomy

Every `components/ui/` file follows this structure:

```typescript
import * as React from 'react';
import * as DialogPrimitive from '@radix-ui/react-dialog';
import { cn } from '@/lib';

const Dialog = DialogPrimitive.Root;
const DialogTrigger = DialogPrimitive.Trigger;

const DialogContent = React.forwardRef<
  React.ComponentRef<typeof DialogPrimitive.Content>,
  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>
>(({ className, children, ...props }, ref) => (
  <DialogPrimitive.Portal>
    <DialogPrimitive.Overlay className="fixed inset-0 z-50 bg-black/80" />
    <DialogPrimitive.Content
      ref={ref}
      className={cn(
        'fixed left-1/2 top-1/2 z-50 -translate-x-1/2 -translate-y-1/2',
        'w-full max-w-lg rounded-lg bg-background p-6 shadow-lg',
        className,
      )}
      {...props}
    >
      {children}
    </DialogPrimitive.Content>
  </DialogPrimitive.Portal>
));
DialogContent.displayName = DialogPrimitive.Content.displayName;

export { Dialog, DialogTrigger, DialogContent };
```

### Key patterns

- **`forwardRef`** — all components forward refs for composition
- **`className` prop** — always accepted, always merged via `cn()`
- **Spread `...props`** — remaining props passed through to the primitive
- **`displayName`** — set for DevTools (mirrors the primitive name)
- **`cn()` merging** — base styles + external `className` merged with tailwind-merge

---

## TS Standards Exceptions for `components/ui/` (D24)

The following patterns are **allowed only in `components/ui/` files** and forbidden elsewhere:

| Pattern | Why allowed in `ui/` |
|---------|----------------------|
| `React.forwardRef` | Required by Radix composition model |
| `ComponentName.displayName = ...` | Required for DevTools with forwardRef |
| `import * as React from 'react'` | Needed for `React.forwardRef`, `React.ComponentRef` etc. |

Outside `components/ui/`, these patterns remain forbidden per TypeScript standards.

---

## `cva` for Variants

Use `cva` (class-variance-authority) to define variant styles. This is the standard pattern for Shadcn-style components.

```typescript
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib';

const badgeVariants = cva(
  'inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold transition-colors',
  {
    variants: {
      variant: {
        default: 'border-transparent bg-primary text-primary-foreground',
        secondary: 'border-transparent bg-secondary text-secondary-foreground',
        destructive: 'border-transparent bg-destructive text-destructive-foreground',
        outline: 'text-foreground',
      },
    },
    defaultVariants: {
      variant: 'default',
    },
  },
);

type BadgeProps = React.HTMLAttributes<HTMLDivElement> &
  VariantProps<typeof badgeVariants>;

export const Badge = ({ className, variant, ...props }: BadgeProps) => (
  <div className={cn(badgeVariants({ variant }), className)} {...props} />
);
```

### `cva` rules

- Define a `*Variants` const with `cva(baseClasses, { variants, defaultVariants })`
- Derive the props type with `VariantProps<typeof *Variants>`
- Always merge with `cn(variantsFn({ ...variantProps }), className)`
- Export the variants const if consumers need to reuse the styles (e.g., `buttonVariants` for link-styled buttons)

---

## `components/ui/` Structure

Shadcn components live in a **flat** directory — no subdirectories:

```text
src/components/ui/
├── index.ts          # Barrel: re-exports all ui components
├── button.tsx
├── card.tsx
├── dialog.tsx
├── dropdown_menu.tsx
├── input.tsx
├── label.tsx
├── select.tsx
├── sheet.tsx
├── table.tsx
└── tooltip.tsx
```

- File names use `lowercase_with_underscores` (e.g., `dropdown_menu.tsx`, not `dropdown-menu.tsx`)
- One component family per file (a file may export multiple related parts like `Dialog`, `DialogContent`, `DialogTrigger`)
- The `index.ts` barrel re-exports everything so consumers import from `@/components` (the top-level barrel re-exports `./ui`)

---

## Radix vs Shadcn vs Custom Decision Tree

```text
Need a UI element?
│
├─ Does Shadcn have it? (check components/ui/)
│  └─ YES → Use it directly. Customize via className/variants.
│
├─ Does Radix have a primitive? (e.g., Popover, Tooltip, Accordion)
│  └─ YES → Build a Shadcn-style wrapper:
│           - forwardRef
│           - className + cn() merging
│           - cva if multiple variants
│           - Place in components/ui/
│
└─ Neither?
   └─ Build a fully custom component.
      - Still use forwardRef + className + cn() if it's a ui/ primitive.
      - If it's a domain component, put it in components/<name>/ instead.
```

---

## Usage in Application Components

Application components consume Shadcn primitives from the barrel:

```typescript
// src/pages/settings/settings_page.tsx
import { Button, Card } from '@/components';
import { useSettingsViewModel } from './use_settings_view_model';

export const SettingsPage = () => {
  const { settings, handleSave, isSaving } = useSettingsViewModel();

  return (
    <Card className="max-w-2xl mx-auto mt-8 p-6">
      <h1 className="text-2xl font-bold mb-4">Settings</h1>
      {/* ... form fields ... */}
      <Button onClick={handleSave} disabled={isSaving}>
        {isSaving ? 'Saving...' : 'Save Changes'}
      </Button>
    </Card>
  );
};
```

---

## Living Examples

The scaffold's `components/ui/` files are the canonical reference for Shadcn patterns. When in doubt about anatomy, naming, or style conventions, refer to those files directly rather than external documentation.
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: 322kUpdated 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: 198kUpdated 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: 198kUpdated 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: 198kUpdated Claude CodeCodexVerifiedInstall