ADR-008 — React style guidelines + thin-app architecture

:::note Contenido en inglés Esta página del wiki se sincroniza desde la base de conocimiento en inglés y todavía no está traducida. :::

reference · frontend · updated 2026-06-23 · source

• Status: Accepted
• Date: 2026-06-23
• Owner: Frontend
• Related issue: #715 (depends on #716, Next 16 upgrade)

Context

• React/Next code style + architecture was governed by scattered guardrails (frontend-guardrails.md, admin-ui-conventions.md, grid-system.md) with no single contract for component architecture, data patterns, composition, or where reusable UI lives.
• We now run Next 16 / React 19 / Turborepo (#716) across three Next apps (admin, console, comprender) that share @tedos/admin-ui (+ the neutral @tedos/ui foundation).
• José wants a performant, solid, antipattern-free codebase where the apps are thin and the reusable React lives in the UI packages — plus a swarm refactor to enforce it.
• Needs an ADR now because it ratifies an architecture decision (thin apps), not just style.

Decision

Adopt a single citable React style + architecture contract — .claude/rules/react-style-guidelines.md — grounded in Vercel's official guidance, with aggressive thin-app architecture.

• Thin apps (A1–A5): apps own only routing, RSC data-fetching seams, auth (proxy.ts), env, and thin page shells. All presentational/reusable UI lives in @tedos/admin-ui (admin skin) or @tedos/ui (neutral foundation). apps/*/src/components/** trends to empty.
• Server-first (RSC default, client only at interactive leaves), waterfall elimination (Promise.all, Suspense, React.cache), bundle discipline (subpath imports, next/dynamic), composition over boolean props (compound components, explicit variants, children), React 19 idioms (no forwardRef, use()), and re-render hygiene.
• A 12-item antipattern table (AP1–AP12) is the swarm's fix-list.
• Sources cited per section — vercel-react-best-practices, vercel-composition-patterns, next-best-practices, turborepo — the rule is the local digest; the skills are the canonical explanation.
• Scope boundary: this governs React code style + architecture. Visual tokens/brand stay with the Designer + admin-ui-conventions.md / color-scope.md / grid-system.md. It does not change tokens, brand, or the design system.

Consequences

Positive

• One bible for every React contribution (human or agent); reviews cite a rule ID.
• Maximal reuse: a component is written once, in a package, consumed by all apps.
• Performance + a11y are contractual, not aspirational; antipatterns are a review blocker.

Negative / trade-offs

• Aggressive extraction is a large, prod-facing refactor (separate effort) — real blast radius; mitigated by a read-only audit pass before the fix swarm, and per-app verification.
• The @tedos/admin-ui barrel vs. tree-shaking tension forces subpath-export discipline (D1).
• Some app-specific components legitimately stay in the app; "thin" is a strong default, not absolute.

Follow-ups required

• .claude/rules/react-style-guidelines.md (new) + this ADR + knowledge/INDEX.md row.
• A separate refactor effort (audit → one PR) to bring admin/console/comprender into line.
• Pair with playwright-best-practices (testable) + web-design-guidelines/axe (accessible) — not covered by the perf/composition skills.

Alternatives considered

Option	Why not
Keep guardrails scattered	No single contract; the swarm has no bible to enforce against.
Rules only, no thin-app architecture	Misses José's core ask — apps purely compose package components.
Per-app component libraries	Violates monorepo "one workspace per concern"; defeats reuse across the app fleet.

References

• .claude/rules/react-style-guidelines.md (the enforced rule)
• Skills: vercel-react-best-practices, vercel-composition-patterns, next-best-practices, turborepo
• Next 16 upgrade: https://nextjs.org/docs/app/guides/upgrading/version-16 (#716)
• Sibling rules: admin-ui-conventions.md, frontend-guardrails.md, monorepo-turbo.md, color-scope.md