# Component Prop Guardrails

## Objective

Make impossible prop combinations fail at the point of use rather than in production.

Validation on shared component props that rejects contradictory or meaningless combinations as early as the codebase allows.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Go through the shared components and write down which prop combinations are actually supported. Most components have grown two or three arrangements that were never intended and are held together by defensive branches inside the render.
2. Replace piles of independent booleans with a single named variant. A component taking a primary flag, a danger flag, and a ghost flag admits combinations nobody has ever designed, and each one has to be resolved arbitrarily at render time.
3. Express the same rule twice — once in the static type layer so it is caught while editing, and once as a runtime check so it is caught in tests and in development builds. The two must agree; a runtime check that permits something the types forbid is worse than neither.
4. In production the guardrail must report and degrade, never crash. Log the offending combination with the component name and pick a defined fallback rendering rather than throwing inside a render path.
5. Do not tighten a rule silently. Record what changed and what the supported replacement is, and hand removal of the old shape to the process described in Component Deprecation Path rather than deleting the prop in the same change.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- Prefer one discriminated variant prop over several independent booleans, because a set of booleans multiplies into states that were never designed and forces the component to invent a precedence order at render time.
- The runtime validation and the static types must describe exactly the same rule. When they drift, developers trust the editor, tests pass against the looser check, and the invalid combination reaches users.
- A violation in production must warn and fall back rather than crash. A guardrail that throws inside a render turns a cosmetic mistake into a blank screen, which is a worse outcome than the wrong variant.
- Every tightened rule needs to be documented where the component is used, not only in its source, so callers who hit the new error know which shape replaced theirs.
- Warnings must be deduplicated per component and per combination, or a component rendered in a long list floods the console and the real message is lost.
- Props whose values come from server data or user configuration cannot be validated by types alone, so those paths need the runtime check and a defined behaviour for an unrecognised value.
- Validation must not run on every render of a hot component in production; the check belongs in development and test builds, with only cheap assertions left in place.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Contradictory prop combinations are rejected in the type layer and by an equivalent runtime check.
- [ ] Shared components expose named variants rather than overlapping boolean flags.
- [ ] An invalid combination in production logs a warning and renders a defined fallback instead of throwing.
- [ ] Repeated violations from the same component produce one warning, not one per render.
- [ ] Every tightened rule is documented at the point of use with its supported replacement.
- [ ] Props sourced from data outside the codebase have a defined behaviour for unrecognised values.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.