yysun/react-app

React Tailwind Layered Web

Use this skill to keep React + Tailwind apps organized around clear ownership, thin route composition, and one-way imports.

Core Rules

• Inspect the existing project first: routing framework, src/ tree, import aliases, Tailwind setup, component conventions, and test scripts.
• Keep the top-level router thin.
• Keep route files thin; they should mostly compose shell, page, and feature workspaces.
• Keep domain contracts explicit; do not invent browser-only domain behavior when ownership belongs to shared contracts or the backend.
• Prefer the lowest valid layer; do not promote code upward just because it might be reused later.
• Do not create or grow catch-all folders like components or lib when a clearer layer exists.
• Match existing naming, exports, aliases, and test patterns unless they violate the boundaries below.

Layer Map

| Layer | Purpose | Allowed contents | Disallowed contents | |---|---|---|---| | src/foundations/ | Visual foundations | design tokens, Tailwind imports, base styles | React components, domain logic | | src/primitives/ | Generic UI controls | buttons, inputs, cards, form controls | business logic, API calls | | src/patterns/ | Reusable UI compositions | headers, panels, form sections, list shells | business logic, API calls | | src/features/ | Domain UI and behavior | product-specific views, hooks, state, feature composition | generic shared UI that belongs lower | | src/pages/ | Route entry points | page orchestration, route-level assembly | deep feature logic, generic UI libraries | | src/shell/ | App framing | layout chrome, providers, navigation shell | feature-owned domain behavior | | src/shared/ | Sidecar shared code | API clients, schemas, helpers, generic utilities | UI-layer imports |

Placement Rules

Use this decision order for new files and moved code:

1. If it is styles, tokens, or Tailwind/base CSS only, place it in src/foundations/.
2. If it is a generic standalone control, place it in src/primitives/.
3. If it is a reusable UI composition built from primitives, place it in src/patterns/.
4. If it knows about a product domain, workflow, or business state, place it in src/features/.
5. If it only wires routes, page assembly, or app framing, place it in src/pages/ or src/shell/.
6. If it is non-UI shared logic, place it in src/shared/.

When in doubt, keep code in the owning feature first and only extract downward once it is clearly generic.

Import Rules

Keep imports one-way. Higher layers may import lower layers; lower layers must not import higher layers.

foundations <- primitives <- patterns <- features <- pages
foundations <- primitives <- patterns <- features <- shell
shared -> usable by any layer

Enforce these constraints:

• foundations imports from no app UI layer.
• primitives may import foundations and shared.
• patterns may import foundations, primitives, and shared.
• features may import patterns, lower UI layers, and shared.
• pages and shell may compose feature work, but must not own feature logic.
• shared must never import from UI layers.
• No layer may import from pages.
• Avoid lateral imports between unrelated features; use explicit shared contracts or keep the code inside the owning feature.

Follow the host project's existing import style. Do not introduce aliases just for this skill.

React + Tailwind Guidance

• Use function components.
• Prefer Tailwind utilities with className extension points.
• Establish a clear visual direction early and preserve it.
• Use existing primitives and patterns before creating new ones.
• Keep accessibility attributes, focus states, loading states, empty states, and error states with the owning component or feature.
• Keep typography consistent:
  • text-xs: labels, badges, metadata, uppercase markers
  • text-sm: body copy, helper text, inputs, buttons, small headings
  • text-base: section and component titles
  • text-lg: page titles and prominent headings
  • text-2xl: stat values

Working Sequence

For each requested change:

1. Start from the user-facing outcome.
2. Identify the owning route, shell, feature, or shared contract.
3. Place each new file in the lowest valid layer.
4. Extract repeated generic UI downward into primitives or patterns.
5. Keep domain behavior in features and shared contracts in src/shared/ or the backend/service layer.
6. Keep pages and routing code thin.
7. Update nearby barrels/index files only when the host project already uses them.
8. Add the required source-file header block to every source file you create or edit when the host project requires it.
9. Run the narrowest useful UI validation: typecheck, lint, unit tests, component tests, or browser/e2e checks as appropriate.

Done Check

Before finishing:

• New code sits in the correct layer.
• Imports follow the allowed boundaries.
• Router and route files remain thin.
• Domain behavior stays in features or shared/server-owned contracts.
• Styling stays consistent with the chosen visual direction.
• New UI includes necessary loading, empty, error, disabled, and responsive states for the requested workflow.
• Normal UI validation for the host app has been run, or the reason it could not be run is stated.