---
description: Component authoring rules for <DESIGN SYSTEM NAME>. Use when creating or editing components.
applyTo: "src/components/**/*.{ts,tsx}"
---

<!--
  Destination: .github/instructions/components.instructions.md

  applyTo is a glob relative to the workspace root. Use "**" to apply
  everywhere. Because these files are concatenated with no guaranteed
  ordering, each rule below is written to stand alone.

  Every rule here carries its reason. A rule an agent understands the reason
  for generalises to cases you did not enumerate; a bare prohibition does not.
-->

# Component authoring

## Prop APIs

Type every prop as a union of literals, never as `string`.

```ts
// Wrong — the agent will invent 'huge', 'xlg', 'massive'
size?: string

// Right — the compiler rejects everything else
size?: 'sm' | 'md' | 'lg'
```

An open prop type is the single largest source of design-system drift in
agent-written code. Each invented value that survives review becomes a sample
the next generation copies.

## Defaults

Every optional prop declares its default in JSDoc. An agent that cannot see
the default will pass one explicitly, and it will pass the wrong one.

## Exports

A component is not shipped until it is exported from the package index and
named in `AGENTS.md`. A component documented under a name the package does
not export is worse than an undocumented one: the agent will read the name,
use it, and produce a build failure that traces back to your own docs.

## Composition

State which components are valid parents and children in JSDoc. Agents nest
wrongly by default because nothing in a type signature says `TabPanel` must
sit inside `Tabs`.

## Before finishing

Run `<pnpm typecheck>`. If the compiler rejects a prop value, the fix is to
use a valid value — not to widen the type.