The react-decor reference

Top-level declaration decorators evaluate in module scope only — there is no props channel into their arguments. Return-position, in-tree, and (forbidden) local placements evaluate inside the function, so hooks and props are available there.

• Wrappers are childless — self-closing or an empty pair; the decorated target becomes their children (AT002).
• Wrappers and decorated declarations are capitalized component references (AT003, AT004).
• The top decorator of a stack is the outermost wrapper — reading top-down matches the emitted nesting.

In JSX text, the two-character directive opener would be parsed as syntax — render literal text through an expression instead:

// a literal "@(" in JSX copy must be an expression, or it parses
// as a directive (AT001 flags the malformed remainder)
<p>{'Use @( to open a JSX-form directive.'}</p>

// tiles at module scope — stable identity across re-renders
@StaggerItem({ className: 'flex h-full flex-col gap-3 rounded-xl border p-5' })
const FeatureTile = ({ item }: { item: (typeof FEATURES)[number] }) => {
  const { t } = useTranslation()
  return (
    <>
      <h3>{t(`home.why.items.${item.key}.title`)}</h3>
      <p>{t(`home.why.items.${item.key}.body`)}</p>
    </>
  )
}

// the mapped grid rides a decl-@Stagger Body atom; key on the callsite
@Stagger({ className: 'mt-12 grid gap-5 sm:grid-cols-2 lg:grid-cols-4' })
const WhyStripBody = () => FEATURES.map((item) => <FeatureTile key={item.key} item={item} />)

// the section is pure composition
@SectionShell({ bare: true, id: 'why' })
export function WhyStrip() {
  const { t } = useTranslation()
  return (
    <>
      <SectionHeading eyebrow={t('…')} title={t('…')} />
      <WhyStripBody />
    </>
  )
}

At section scale this becomes the full-strip shape: module-scope tiles (stable identity), the mapped grid on a decl-@Stagger Body atom, and the section reduced to pure composition. One wrapper per atom with the decl form maximized — a return-position directive carries only what genuinely reads hooks or props, riding the consuming component's own return.

// no props channel into decl args — specialize statically instead
@Link({ to: '/work', viewTransition: true, className: BACK_LINK })
export const WorkBackLink = () => <BackLinkLabel />

@Link({ to: '/insights', viewTransition: true, className: BACK_LINK })
export const InsightsBackLink = () => <BackLinkLabel />

// every callsite paired SectionHeading with @(<Reveal />) — bake it
// into the declaration once and delete the per-callsite directives
@Reveal
export function SectionHeading(props: SectionHeadingProps) {
  return <HeadingBlock {...props} />
}

// ✗ the tiles would remount on EVERY parent render — counters reset
export function IdentityDemo() {
  @Button({ variant: 'outline' })          // react-decor/no-local-atom
  const ClickTile = ({ id }: { id: string }) => <TileBody id={id} />
  return TILE_IDS.map((id) => <ClickTile key={id} id={id} />)
}

A decorated atom compiles to a wrapper around <Name_base {...props} />. Put an asChild wrapper on the declaration and Slot clones the _base element — the injected props land on the label instead of the wrapper. It compiles green and renders broken, which is why no-aschild-decl-decorator exists (proven by a preserved RED fixture in the library's test suite).

// ✗ compiles green, renders broken: Slot clones <CtaLink_base />, so
// the Button's className/handlers land on the LABEL, not the wrapper
@(<Button asChild size="lg" />)          // react-decor/no-aschild-decl-decorator
const CtaLink = () => <Link to="/docs">{'Read the docs'}</Link>

// ✓ the pair stays in one return — the Link remains Slot's literal child
const DocsCta = () => {
  const { t } = useTranslation()
  @(<Button asChild size="lg" />)
  return <Link to="/docs">{t('cta.docs')}</Link>
}

The asChild wrapper itself may be a directive — only its direct child must remain literal. One escape exists: an atom that spreads its props onto its root element forwards the injection through, so the innermost decl-position asChild is allowed there (the lint rule detects the spread). Zero-prop atoms keep the return-position pair.

// raw source               what the type-checker sees   (same length, same spans)
@Labeled({ text })          !Labeled({ text })           // call: props type-checked
@Card                       ;Card                        // bare
@(<Badge tone="new" />)     ;(<Badge tone="new" />)      // JSX form
  @(<TintCard />)             { <TintCard />}            // inside a tree

Declarations and returns become expression statements: @ becomes ; — or ! for the call form, which type-checks the props object against the component while keeping ReactNode-returning call results out of no-floating-promises. Inside trees, the opener/closer pair becomes an expression container (the sample above shows the exact swap). Because every swap preserves length, positions in diagnostics map 1:1 back to your raw text. Three shims apply exactly that swap:

This repo's config additionally bans disabling react/jsx-key outright (eslint-comments/no-restricted-disable), and every other disable comment requires a written reason.