# Critical CSS Strategy

## Objective

Get the first screen styled correctly on the first paint, with no flash of raw markup.

An inlined slice of the app's styles covering the first viewport, with the remainder loaded after paint.

## 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. Identify the entry screens that are painted before the main stylesheet has arrived — the marketing page, the sign-in screen, the authenticated shell — and extract only the rules the first viewport actually uses on each.
2. Derive the critical slice from the same source as the full stylesheet, as a build step, so the two cannot drift apart when a component's styles change.
3. Resolve the user's theme, colour scheme, and any layout preference before the first paint, from a value that can be read synchronously at the top of the document rather than after the app boots.
4. Load the remainder without blocking rendering, and make sure the page reaches a fully styled state even if that request is slow — the inline slice is a head start, not a substitute.
5. Do not hand-write and hand-maintain a separate critical stylesheet. It goes stale the first time a component changes and nobody notices until a page renders wrong in production.

## 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

- The extracted slice and the runtime stylesheet must agree on every rule they share. If a selector is inlined at one specificity and served at another, the page will visibly reflow the moment the full sheet applies.
- An inline payload that grows past a few kilobytes costs more than it saves, because it is re-sent with every document and cannot be cached separately. Set a budget and fail the build when it is exceeded.
- Theme has to be settled before anything paints. A dark-mode user who sees a white flash on every navigation is worse off than one who waited for the stylesheet.
- A strict content security policy will block inline styles outright unless they carry a nonce or hash. Confirm the delivery mechanism works under the policy the app actually ships, not a relaxed development one.
- Cached HTML holds the inline styles that were current when it was generated. After a deploy, a cached document paired with a new stylesheet must still render acceptably rather than half-styled.
- Print styles, reduced-motion rules, and high-contrast overrides are not first-viewport rules and must not be pulled into the inline slice.
- Font loading and font-face declarations belong to the Font Subsetting brief, not this one — keep the two from each inlining the same declarations twice.

## 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

- [ ] Entry screens paint fully styled with no flash of unstyled or wrongly themed content.
- [ ] The critical slice is generated by the build from the same source as the full stylesheet.
- [ ] The inline payload has a documented size budget that the build enforces.
- [ ] The page reaches a complete styled state even when the deferred stylesheet is slow or fails once.
- [ ] Inline styles are delivered in a way the production content security policy permits.
- [ ] Theme and colour scheme are resolved before first paint on every entry point.
- [ ] 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.