# Provider Form Requirements Guidance Design

Date: 2026-08-03

## Summary

The provider experience must explain requirements before submission instead of relying on browser validation or API errors. The approved visual direction is **Option C: guided requirements by step**. It combines a compact form guide, coral required markers, contextual limits, prominent blocking notices, and a dynamic publication checklist.

The system applies to both unauthenticated account flows and every authenticated provider-portal form. It does not change API validation or publication policy. The API remains the source of truth; the web interface communicates those rules earlier and more clearly.

## Problem

Required inputs currently depend mainly on native HTML attributes and API validation. Labels do not consistently identify required fields, optional steps are not always described as optional, and blocking notices such as “Guarda primero la identidad del prestador” use the same low-emphasis presentation as ordinary informational text.

This creates three ambiguities for providers:

1. Which fields are required to save the current form.
2. Which optional fields have format or size constraints when used.
3. Which minimum steps must be completed before submitting the provider for review.

## Goals

- Identify every field required to submit its current form.
- Explain short constraints before validation, including lengths, formats, file count, file type, and file size.
- Distinguish form requirements from publication minimums.
- Make blocking dependencies visually prominent and actionable.
- Clearly label optional steps and conditionally required fields.
- Preserve the MyCode blue primary and coral accent visual language.
- Provide equivalent Spanish and English content.
- Preserve accessible semantics and keyboard behavior.
- Keep API validation and state transitions unchanged.

## Non-goals

- Changing which data the API requires.
- Changing provider publication or verification policy.
- Turning the portal into a new wizard or changing its navigation.
- Automatically saving incomplete forms.
- Replacing server validation with client validation.
- Redesigning the public provider directory or administration panel.

## Terminology

- **Required field:** must be valid to submit the current form.
- **Conditional requirement:** required only after the provider chooses to add or enable an item.
- **Optional field or step:** can be omitted without blocking the current save or publication.
- **Publication minimum:** must exist somewhere in the saved provider data before review submission.
- **Blocking dependency:** an earlier entity or action required before the current section can be used, such as saving provider identity before adding a location.

## Approved Visual System

### Form guide

Every form begins with a compact blue guide that explains what is required to save that form. It must be specific, not generic. Examples:

- “Completa los 3 campos marcados con *.”
- “Adjunta 1 o 2 archivos PDF, JPG o PNG de hasta 10 MB.”
- “Este paso es opcional. Si agregas un horario, completa el día y un modo válido.”

The guide is informative and uses blue, not coral.

### Required markers

Visible required controls use a coral `*` inside the associated label. Each form exposes one accessible explanation equivalent to “* Campo obligatorio.” Existing HTML `required`, `minlength`, `maxlength`, `pattern`, `accept`, numeric ranges, and input types remain authoritative browser hints where applicable.

The marker cannot be the only indication of a requirement. Screen-reader text and the guide provide equivalent wording.

### Optional labels

“Opcional” is shown only where users could reasonably mistake an input or whole step for a requirement. It is not repeated on every optional control in long forms. Optional sections such as media, specialties, features, and schedule exceptions state their optional status in the form guide.

### Blocking notices

Blocking dependencies use a prominent coral notice with:

- an icon;
- a short title such as “Acción requerida”;
- the exact required action;
- `role="alert"` only when introduced after an interaction, otherwise a non-interruptive status region.

The notice replaces low-emphasis raw dependency text. Coral is reserved for blockers and validation errors, not general help.

### Publication checklist

The review screen remains a dynamic checklist. It separates required minimums from optional enhancements and states the exact reason the submit action is unavailable. Required minimums are:

- saved provider identity;
- at least one category and one selected primary category in the portal state;
- an active, location-confirmed branch;
- either a weekly schedule or 24-hour mode on a qualifying branch;
- at least one public contact on that qualifying branch.

Services, media, specialties, features, verification requests, and schedule exceptions remain optional unless the API policy changes later.

## Form Inventory and Guidance

### Account flows

| Form | Required now | Guidance |
|---|---|---|
| Login | Email, password | Password minimum is 6 characters; remember-session is optional. |
| Registration | Name, email, phone, password, confirmation | Name is 2–100 characters; password is at least 6 characters and must match confirmation. |
| Email verification | Email, six-character code | Code length is shown next to the control. |
| Verification resend | Email | Presented as a separate required single-field action. |
| Forgot password | Email | Presented as a required single-field action. |
| Password reset | Email, six-character code, password, confirmation | Password minimum and confirmation requirement remain visible. |
| Two-factor verification | Six-digit code | Temporary token remains internal state. |
| Recovery-code verification | Recovery code | Alternative action remains visually secondary. |

### Provider identity

Required to save:

- provider type;
- display name;
- legal name.

Email, phone, mobile, WhatsApp, website, Instagram, Facebook, and description are optional. Optional contact values still display their format constraints when relevant. Identity is a blocking dependency for provider categories, locations, media, verification, and review actions.

### Categories

The form guide states that 1–20 categories are required and exactly one selected category must be primary. The catalog hierarchy and current visual grouping remain unchanged. The section keeps its blocking notice until provider identity exists.

### Locations

The guide summarizes the visible minimum rather than forcing users to infer it from a long form. Required visible data includes branch name, address line, formatted address, commune, region, two-letter country code, latitude, longitude, and explicit map/location confirmation. Location source is maintained internally. Time zone is validated when sent and keeps its default value.

Optional address detail, description, postal code, service flags, and home-service radius are described contextually. Radius becomes relevant only when home service is enabled.

### Services

The services step is optional for publication. The form guide explains that each added row requires a catalog service. Price range, currency, appointment requirement, availability, and notes are optional or conditional. If prices are supplied, values must be non-negative and the final price cannot be lower than the initial price.

### Specialties and features

Both steps are optional. Selecting a specialty makes its identifier required. Adding a feature makes its catalog identifier and a value compatible with the feature type required. Integer, decimal, boolean, and text constraints remain adjacent to the generated control.

### Schedules and exceptions

Weekly schedules can be empty while editing, but a qualifying active location must have at least one schedule or be marked as open 24 hours before review submission. Each schedule block requires a day and one valid mode:

- closed with no times;
- open 24 hours with no times;
- different opening and closing times.

Schedule exceptions are optional. When added, their date and mode become required.

### Contacts

Each contact requires type and value. Labels and primary designation are optional. Phone, email, and URL guidance changes with contact type. Contacts created by this portal are public; the review guide explains that at least one public contact must exist on a qualifying active location.

### Provider and location media

Logo, cover, and gallery media are optional steps. When an upload form is submitted, its file becomes required. Limits remain visible before selection:

- logo: JPG, PNG, or WebP, up to 4 MB;
- cover: JPG, PNG, or WebP, up to 8 MB;
- location image: JPG, PNG, or WebP, up to 8 MB.

Image type is required for location media. Alternative text and sort order are optional, with their existing limits.

### Verification requests

The step is optional for publication. Once started, a request requires:

- one owner-submittable verification type;
- one or two evidence files;
- PDF, JPG, or PNG format;
- no more than 10 MB per file.

Metadata key and value remain optional as a pair. The UI explains that entering one requires entering the other.

### Review submission

The confirmation checkbox is required at submission. The submit button remains disabled until the web completion model confirms the same minimum structure used by the API. A disabled button must always be accompanied by a visible explanation and checklist; it cannot be the only indication that progress is blocked.

## Component and Data Flow

The implementation uses a small reusable presentation vocabulary rather than independent custom markup for each section:

- a Blade-accessible required marker and form legend;
- a guide component with informational, blocking, success, and error tones;
- helper text identifiers wired through `aria-describedby`;
- dynamic JavaScript rendering for dependency notices and the review checklist;
- shared CSS tokens and classes in the provider portal stylesheets;
- localized strings in the existing Spanish and English provider language files and safe client translation catalog.

Static Blade forms declare known requirements in markup. Dynamic rows attach markers and helper relationships when JavaScript creates their controls. The JavaScript store continues to carry provider and location state; no requirement state is persisted as business data.

The API remains authoritative. The web may prevalidate for immediate feedback, but API field errors continue through the existing safe field-error mapper.

## Error and State Behavior

- Client and API validation errors appear next to their associated control.
- The first invalid control receives focus after a rejected submission.
- Invalid controls expose `aria-invalid="true"` and reference their error text.
- A form guide changes to error tone and summarizes the action without duplicating every message.
- Dependency notices update when provider or location state changes.
- Busy forms retain their disabled state and cannot be resubmitted.
- Read-only provider statuses use the same prominent notice structure without being styled as validation errors.
- Success feedback does not remove persistent requirement guidance.
- Loading, empty, blocked, error, and success states use distinct text, icons, and semantics.

## Localization

All new content must exist in Spanish and English. The current page locale selects the language automatically, and the existing locale switch changes the full form guidance consistently. No new user-facing Spanish literals may be left untranslated in generated JavaScript.

## Accessibility

- Labels remain programmatically associated with controls.
- Required markers include screen-reader-equivalent text.
- Helper and error text use stable IDs referenced by `aria-describedby`.
- Color is always paired with iconography and wording.
- Informational guides do not interrupt assistive technology.
- Interaction-introduced blockers and submission errors use appropriate live regions.
- Focus order and keyboard operation remain unchanged.
- Disabled actions retain nearby human-readable explanations.

## Testing Strategy

### Feature tests

- Assert guides and accessible required legends on every account and portal form.
- Assert Spanish and English translations for all new requirement content.
- Assert prominent dependency notice containers on categories, locations, media, verification, and review screens.
- Assert versioned CSS and JavaScript assets remain present.

### JavaScript tests

- Test guide rendering for informational, blocking, and error tones.
- Test dynamic required markers and helper relationships on generated controls.
- Test provider-identity and location dependency transitions.
- Test review checklist labels, required versus optional classification, and exact blocker summaries.
- Retain existing payload, upload, duplicate-submission, localization, and safe-rendering tests.

### Regression verification

- Run the provider JavaScript suite.
- Run focused provider feature tests.
- Run the complete PHPUnit suite.
- Run the strict architecture audit.
- Build production assets.
- Run whitespace and generated-bundle consistency checks.
- Perform desktop and mobile visual review in Spanish and English.

## Versioning

This is a backward-compatible user-interface improvement. The web project receives a patch-version increment after reviewing the version-hook dialogue. The API requires no version change because its validation and response contracts remain unchanged.

## Acceptance Criteria

1. Every provider-facing form explains its current required fields before submission.
2. Every visible required field has accessible, coral required marking.
3. File, count, format, and length constraints are visible before validation where relevant.
4. Optional steps are explicitly distinguished from publication minimums.
5. Blocking dependency messages are prominent and state the required action.
6. The review checklist accurately reflects saved provider and location state.
7. Disabled submission actions always include a nearby explanation.
8. Spanish and English experiences contain equivalent guidance.
9. Existing payloads, API validation, state transitions, and public behavior remain unchanged.
10. Automated and visual verification pass on desktop and mobile.